@silverbulletmd/silverbullet 2.9.0 → 2.11.0

package/client/plugos/syscalls/editor.ts

@@ -1,11 +1,10 @@
-import type { Client } from "../../client.ts";
+import { copyToClipboard } from "../../clipboard.ts";
 import {
-  foldAll,
-  foldCode,
-  toggleFold,
-  unfoldAll,
-  unfoldCode,
-} from "@codemirror/language";
+  acceptCompletion,
+  closeCompletion,
+  moveCompletionSelection,
+  startCompletion,
+} from "@codemirror/autocomplete";
 import {
   cursorCharLeft,
   cursorCharRight,
@@ -54,773 +53,1570 @@ import {
   transposeChars,
   undo,
 } from "@codemirror/commands";
+import { insertNewlineContinueMarkup } from "@codemirror/lang-markdown";
 import {
-  acceptCompletion,
-  closeCompletion,
-  moveCompletionSelection,
-  startCompletion,
-} from "@codemirror/autocomplete";
+  foldAll,
+  foldCode,
+  toggleFold,
+  unfoldAll,
+  unfoldCode,
+} from "@codemirror/language";
+import { forceLinting } from "@codemirror/lint";
+import { openSearchPanel } from "@codemirror/search";
 import type { Transaction } from "@codemirror/state";
 import { EditorView } from "@codemirror/view";
-import { getVimModule } from "../../vim_loader.ts";
-import type { SysCallMapping } from "../system.ts";
+import {
+  coerceAndValidateRef,
+  type Ref,
+} from "@silverbulletmd/silverbullet/lib/ref";
 import type {
   FilterOption,
   NotificationAction,
   NotificationType,
+  PanelMode,
   UploadFile,
 } from "@silverbulletmd/silverbullet/type/client";
-import { openSearchPanel } from "@codemirror/search";
-import { forceLinting } from "@codemirror/lint";
-import { refreshLintEffect } from "../../codemirror/lint.ts";
-import {
-  isValidPath,
-  parseToRef,
-  type Path,
-  type Ref,
-} from "@silverbulletmd/silverbullet/lib/ref";
-import { insertNewlineContinueMarkup } from "@codemirror/lang-markdown";
 import type { VimConfig } from "@silverbulletmd/silverbullet/type/config";
 import type { PageMeta } from "@silverbulletmd/silverbullet/type/index";
+import { updateBakedSections } from "../../baked_sections/bake.ts";
+import type { Client } from "../../client.ts";
+import { refreshLintEffect } from "../../codemirror/lint.ts";
+import { isMobileDevice, isNarrowScreen } from "../../lib/mobile.ts";
+import { hide as hideNavigatorSlot } from "../../navigator/navigator.ts";
+import type { PanelSlot } from "../../types/ui.ts";
+import { getVimModule } from "../../vim_loader.ts";
+import type { SysCallMapping } from "../system.ts";
 
 export function editorSyscalls(client: Client): SysCallMapping {
   const syscalls: SysCallMapping = {
-    "editor.getCurrentPage": (): string => {
-      return client.currentName();
-    },
-    "editor.getCurrentPageMeta": (): Promise<PageMeta | undefined> => {
-      const name = client.currentName();
-      return client.objectIndex.getObjectByRef(name, "page", name);
-    },
-    "editor.getCurrentPath": (_ctx): string => {
-      return client.currentPath();
-    },
-    "editor.getCurrentEditor": (): string => {
-      return client.contentManager.documentEditor?.name || "page";
-    },
-    "editor.getRecentlyOpenedPages": (): PageMeta[] => {
-      return client.ui.viewState.allPages.sort(
-        (a, b) => (b.lastOpened || 0) - (a.lastOpened || 0),
-      );
-    },
-    "editor.getText": () => {
-      return client.editorView.state.sliceDoc();
-    },
-    "editor.getCurrentLine": (): {
-      from: number;
-      to: number;
-      text: string;
-      textWithCursor: string;
-    } => {
-      const pos = client.editorView.state.selection.main.from;
-      const line = client.editorView.state.doc.lineAt(pos);
-      return {
-        ...line,
-        textWithCursor:
-          line.text.slice(0, pos - line.from) +
-          "|^|" +
-          line.text.slice(pos - line.from),
-      };
-    },
-    "editor.setText": (_ctx, newText: string, shouldIsolateHistory = false) => {
-      client.contentManager.setEditorText(newText, shouldIsolateHistory);
-    },
-    "editor.getCursor": (): number => {
-      return client.editorView.state.selection.main.from;
-    },
-    "editor.getSelection": (): { from: number; to: number; text: string } => {
-      const selection = client.editorView.state.selection.main;
-      const text = client.editorView.state.sliceDoc(
-        selection.from,
-        selection.to,
-      );
-      return {
-        from: selection.from,
-        to: selection.to,
-        text,
-      };
-    },
-    "editor.save": () => {
-      return client.save(true);
-    },
-    "editor.navigate": async (
-      _ctx,
-      ref: Ref | string,
-      replaceState = false,
-      newWindow = false,
-    ) => {
-      if (typeof ref === "string") {
-        const parsedRef = parseToRef(ref);
-        if (!parsedRef) {
-          throw new Error(
-            "Unable to parse string provided to `editor.navigate` as ref",
-          );
-        }
-        ref = parsedRef;
-      }
-
-      if (
-        // @ts-expect-error: Legacy support
-        ref.page !== undefined
-      ) {
-        console.warn(
-          "You are using legacy navigation syntax with `editor.navigate()`, this will be phased out in the future",
+    "editor.getCurrentPage": {
+      callback: (): string => {
+        return client.currentName();
+      },
+      description:
+        "Returns the name of the page or document currently open in the editor.",
+      returns: [{ type: "string", description: "The current page name." }],
+    },
+    "editor.getCurrentPageMeta": {
+      callback: (): Promise<PageMeta | undefined> => {
+        const name = client.currentName();
+        return client.objectIndex.getObjectByRef(name, "page", name);
+      },
+      description:
+        "Returns metadata for the page or document currently open in the editor.",
+      returns: [
+        {
+          type: "PageMeta | undefined",
+          description: "The current page metadata, if indexed.",
+        },
+      ],
+    },
+    "editor.getCurrentPath": {
+      callback: (_ctx): string => {
+        return client.currentPath();
+      },
+      description:
+        "Returns the path of the page or document currently open in the editor.",
+      returns: [{ type: "string", description: "The current page path." }],
+    },
+    "editor.getCurrentEditor": {
+      callback: (): string => {
+        return client.contentManager.documentEditor?.name || "page";
+      },
+      description:
+        "Returns the name of the currently active editor implementation.",
+      returns: [
+        {
+          type: "string",
+          description: "The editor name, or `page` for the page editor.",
+        },
+      ],
+    },
+    "editor.getRecentlyOpenedPages": {
+      callback: (): PageMeta[] => {
+        return client.ui.viewState.allPages.sort(
+          (a, b) => (b.lastOpened || 0) - (a.lastOpened || 0),
         );
-
-        const legacyRef = ref as unknown as {
-          kind: "page" | "document";
-          page: string;
-          pos?: number | { line: number; column: number };
-          header?: string;
-          meta?: boolean;
-        };
-
-        legacyRef.kind ??= "page";
-
-        let details: Ref["details"];
-
-        if (typeof legacyRef.pos === "number") {
-          details = {
-            type: "position",
-            pos: legacyRef.pos,
-          };
-        } else if (legacyRef.pos) {
-          details = {
-            type: "linecolumn",
-            line: legacyRef.pos.line,
-            column: legacyRef.pos.column,
-          };
-        } else if (legacyRef.header) {
-          details = {
-            type: "header",
-            header: legacyRef.header,
-          };
+      },
+      description:
+        "Returns page metadata ordered from most to least recently opened.",
+      returns: [{ type: "PageMeta[]", description: "Recently opened pages." }],
+    },
+    "editor.getLastOpenedMap": {
+      callback: (): Record<string, number> => {
+        const out: Record<string, number> = {};
+        for (const pageMeta of client.ui.viewState.allPages) {
+          if (pageMeta.lastOpened) out[pageMeta.name] = pageMeta.lastOpened;
         }
-
-        ref = {
-          path: (legacyRef.kind === "page"
-            ? `${legacyRef.page}.md`
-            : legacyRef.page) as Path,
-          details,
-          meta: legacyRef.meta,
+        return out;
+      },
+      description: `Returns a map of page name to the time it was last opened (epoch milliseconds), for the pages that have ever been opened on this client. This lives outside the object index.`,
+      returns: [
+        {
+          type: "Record<string, number>",
+          description: "Page name to last-opened timestamp.",
+        },
+      ],
+    },
+    "editor.getViewableExtensions": {
+      callback: (): string[] => {
+        return [
+          ...new Set(
+            Array.from(
+              client.clientSystem.documentEditorHook.documentEditors.values(),
+            ).flatMap(({ extensions }) => extensions),
+          ),
+        ];
+      },
+      description: `Returns the file extensions that have a document editor registered, i.e. the documents this client can actually open. Extensions carry no leading dot. Which editors are loaded depends on the plugs installed, so this is a property of the client rather than of the space.`,
+      returns: [
+        {
+          type: "string[]",
+          description: "Extensions with a registered document editor.",
+        },
+      ],
+    },
+    "editor.getText": {
+      callback: () => {
+        return client.editorView.state.sliceDoc();
+      },
+      description:
+        "Returns the full text of the currently open page or document.",
+      returns: [{ type: "string", description: "The editor contents." }],
+    },
+    "editor.getCurrentLine": {
+      callback: (): {
+        from: number;
+        to: number;
+        text: string;
+        textWithCursor: string;
+      } => {
+        const pos = client.editorView.state.selection.main.from;
+        const line = client.editorView.state.doc.lineAt(pos);
+        return {
+          ...line,
+          textWithCursor:
+            line.text.slice(0, pos - line.from) +
+            "|^|" +
+            line.text.slice(pos - line.from),
         };
-      }
-
-      // This validation code should be connected to the Ref type. Ideally using
-      // some validation library. Didn't want to use jsonschemas here tho.
-      // Ideally this would be moved into a function too
-      if (!isValidPath(ref.path) && ref.path !== "") {
-        throw new Error("Path passed in ref to `editor.navigate` is invalid");
-      } else if (typeof ref.meta !== "boolean" && ref.meta !== undefined) {
-        throw new Error("ref.meta has to be of type `boolean`");
-      } else if (ref.details !== undefined && typeof ref.details !== "object") {
-        throw new Error(
-          "ref.details has to be of type `object` or `undefined`",
+      },
+      description:
+        "Returns the current line's range and text, including a `|^|` cursor marker variant.",
+      returns: [
+        {
+          type: "{ from: number; to: number; text: string; textWithCursor: string }",
+          description: "The line containing the main selection head.",
+        },
+      ],
+    },
+    "editor.setText": {
+      callback: (_ctx, newText: string, shouldIsolateHistory = false) => {
+        client.contentManager.setEditorText(newText, shouldIsolateHistory);
+      },
+      description:
+        "Updates the editor text with a minimal diff while preserving the cursor when possible.",
+      parameters: [
+        {
+          name: "newText",
+          type: "string",
+          description: "The complete replacement text.",
+        },
+        {
+          name: "shouldIsolateHistory",
+          type: "boolean",
+          description: "Whether to isolate the change in undo history.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.getCursor": {
+      callback: (): number => {
+        return client.editorView.state.selection.main.from;
+      },
+      description:
+        "Returns the cursor position as a character offset from the start of the document.",
+      returns: [{ type: "number", description: "The cursor offset." }],
+    },
+    "editor.getSelection": {
+      callback: (): { from: number; to: number; text: string } => {
+        const selection = client.editorView.state.selection.main;
+        const text = client.editorView.state.sliceDoc(
+          selection.from,
+          selection.to,
         );
-      } else if (
-        ref.details &&
-        !["position", "linecolumn", "header", "anchor"].includes(
-          ref.details.type,
-        )
-      ) {
-        throw new Error(
-          "ref.details.type has to be 'position', 'linecolumn', 'header' or 'anchor'",
+        return {
+          from: selection.from,
+          to: selection.to,
+          text,
+        };
+      },
+      description: "Returns the current selection range and selected text.",
+      returns: [
+        {
+          type: "{ from: number; to: number; text: string }",
+          description: "The main editor selection.",
+        },
+      ],
+    },
+    "editor.save": {
+      callback: () => {
+        return client.save(true);
+      },
+      description: "Forces the current page or document to be saved.",
+    },
+    "editor.navigate": {
+      callback: async (
+        _ctx,
+        ref: Ref | string,
+        replaceState = false,
+        newWindow = false,
+      ) => {
+        await client.navigate(
+          coerceAndValidateRef(ref),
+          replaceState,
+          newWindow,
         );
-      }
-
-      if (
-        ref.details?.type === "position" &&
-        typeof ref.details.pos !== "number"
-      ) {
-        throw new Error("ref.details.pos has to be of type `number`");
-      } else if (
-        ref.details?.type === "header" &&
-        typeof ref.details.header !== "string"
-      ) {
-        throw new Error("ref.details.header has to be of type `string`");
-      } else if (
-        ref.details?.type === "linecolumn" &&
-        typeof ref.details.line !== "number" &&
-        typeof ref.details.column !== "number"
-      ) {
-        throw new Error(
-          "ref.details.line and ref.details.column has to be of type `number`",
+      },
+      description:
+        "Navigates to a page reference without restoring its remembered cursor and scroll position.",
+      parameters: [
+        {
+          name: "ref",
+          type: "Ref | string",
+          description: "The page reference to navigate to.",
+        },
+        {
+          name: "replaceState",
+          type: "boolean",
+          description: "Whether to replace the current browser history state.",
+          optional: true,
+        },
+        {
+          name: "newWindow",
+          type: "boolean",
+          description: "Whether to open the reference in a new window.",
+          optional: true,
+        },
+      ],
+      examples: [{ code: 'editor.navigate("CHANGELOG@123")' }],
+    },
+    "editor.open": {
+      callback: async (
+        _ctx,
+        ref: Ref | string,
+        replaceState = false,
+        newWindow = false,
+      ) => {
+        await client.open(coerceAndValidateRef(ref), replaceState, newWindow);
+      },
+      description:
+        "Opens a page reference and restores its remembered cursor and scroll position when possible.",
+      parameters: [
+        {
+          name: "ref",
+          type: "Ref | string",
+          description: "The page reference to open.",
+        },
+        {
+          name: "replaceState",
+          type: "boolean",
+          description: "Whether to replace the current browser history state.",
+          optional: true,
+        },
+        {
+          name: "newWindow",
+          type: "boolean",
+          description: "Whether to open the reference in a new window.",
+          optional: true,
+        },
+      ],
+      examples: [{ code: 'editor.open("CHANGELOG")' }],
+    },
+    "editor.reloadPage": {
+      callback: async () => {
+        await client.reloadEditor();
+      },
+      description: "Force reloads the current page in the editor.",
+    },
+    "editor.forceLint": {
+      callback: () => {
+        // `forceLinting` alone is a no-op on unchanged content after the
+        // linter's internal "scheduled" flag has been cleared; the effect
+        // re-arms it via `needsRefresh`.
+        client.editorView.dispatch({
+          effects: refreshLintEffect.of(null),
+        });
+        forceLinting(client.editorView);
+      },
+      description:
+        "Forces editor linting to run, including when the content has not changed.",
+    },
+    "editor.reloadUI": {
+      callback: () => {
+        location.reload();
+      },
+      description: "Force reloads the browser UI.",
+    },
+    "editor.rebuildEditorState": {
+      callback: () => {
+        client.rebuildEditorState();
+      },
+      description:
+        "Rebuilds the CodeMirror editor state from the current client configuration.",
+    },
+    "editor.reloadConfigAndCommands": {
+      callback: async () => {
+        await client.clientSystem.system.localSyscall("system.loadScripts", []);
+        await client.clientSystem.system.localSyscall(
+          "system.loadSpaceStyles",
+          [],
+        );
+        client.rebuildEditorState();
+      },
+      description:
+        "Reloads space scripts and styles, then rebuilds the editor state.",
+    },
+    "editor.invokeCommand": {
+      callback: (_ctx, name: string, args?: string[]) => {
+        return client.runCommandByName(name, args);
+      },
+      description: "Invokes a client command by name.",
+      parameters: [
+        { name: "name", type: "string", description: "The command name." },
+        {
+          name: "args",
+          type: "string[]",
+          description: "Arguments passed to the command.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.updateBakedSections": {
+      callback: (): Promise<void> => {
+        return updateBakedSections(client);
+      },
+      description:
+        "Re-evaluates every baked section on the current page and replaces each body with its latest output.",
+    },
+    "editor.openUrl": {
+      callback: (_ctx, url: string, existingWindow = false) => {
+        client.openUrl(url, existingWindow);
+      },
+      description: "Opens a URL in the browser.",
+      parameters: [
+        { name: "url", type: "string", description: "The URL to open." },
+        {
+          name: "existingWindow",
+          type: "boolean",
+          description: "Whether to reuse an existing window.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.newWindow": {
+      callback: () => {
+        globalThis.open(
+          location.href,
+          `rnd${Math.random()}`,
+          `width=${globalThis.innerWidth},heigh=${globalThis.innerHeight}`,
         );
-      } else if (
-        ref.details?.type === "anchor" &&
-        typeof ref.details.name !== "string"
-      ) {
-        throw new Error("ref.details.name has to be of type `string`");
-      }
+      },
+      description:
+        "Opens the current SilverBullet URL in a new browser window.",
+    },
+    "editor.goHistory": {
+      callback: (_ctx, delta: number) => {
+        globalThis.history.go(delta);
+      },
+      description: "Moves backward or forward through browser history.",
+      parameters: [
+        {
+          name: "delta",
+          type: "number",
+          description:
+            "The relative history offset; negative moves backward and positive moves forward.",
+        },
+      ],
+    },
+    "editor.downloadFile": {
+      callback: (_ctx, filename: string, dataUrl: string) => {
+        const link = document.createElement("a");
+        link.href = dataUrl;
+        link.download = filename;
+        link.click();
+      },
+      description:
+        "Triggers a browser download of a data URL under the given filename.",
+      parameters: [
+        {
+          name: "filename",
+          type: "string",
+          description: "The downloaded filename.",
+        },
+        {
+          name: "dataUrl",
+          type: "string",
+          description: "The data URL to download.",
+        },
+      ],
+      examples: [
+        {
+          code: 'editor.downloadFile("test.txt", "data:text/plain;base64,SGVsbG8=")',
+        },
+      ],
+    },
+    "editor.uploadFile": {
+      callback: (
+        _ctx,
+        accept?: string,
+        capture?: string,
+      ): Promise<UploadFile> => {
+        return new Promise<UploadFile>((resolve, reject) => {
+          const input = document.createElement("input");
+          input.type = "file";
+          if (accept) {
+            input.accept = accept;
+          }
+          if (capture) {
+            input.capture = capture;
+          }
 
-      await client.navigate(ref, replaceState, newWindow);
-    },
-    "editor.reloadPage": async () => {
-      await client.reloadEditor();
-    },
-    "editor.forceLint": () => {
-      // `forceLinting` alone is a no-op on unchanged content after the
-      // linter's internal "scheduled" flag has been cleared; the effect
-      // re-arms it via `needsRefresh`.
-      client.editorView.dispatch({
-        effects: refreshLintEffect.of(null),
-      });
-      forceLinting(client.editorView);
-    },
-    "editor.reloadUI": () => {
-      location.reload();
-    },
-    "editor.rebuildEditorState": () => {
-      client.rebuildEditorState();
-    },
-    "editor.reloadConfigAndCommands": async () => {
-      await client.clientSystem.system.localSyscall("system.loadScripts", []);
-      await client.clientSystem.system.localSyscall(
-        "system.loadSpaceStyles",
-        [],
-      );
-      client.reconfigureLanguage();
-    },
-    "editor.invokeCommand": (_ctx, name: string, args?: string[]) => {
-      return client.runCommandByName(name, args);
-    },
-    "editor.openUrl": (_ctx, url: string, existingWindow = false) => {
-      client.openUrl(url, existingWindow);
-    },
-    "editor.newWindow": () => {
-      globalThis.open(
-        location.href,
-        `rnd${Math.random()}`,
-        `width=${globalThis.innerWidth},heigh=${globalThis.innerHeight}`,
-      );
-    },
-    "editor.goHistory": (_ctx, delta: number) => {
-      globalThis.history.go(delta);
-    },
-    "editor.downloadFile": (_ctx, filename: string, dataUrl: string) => {
-      const link = document.createElement("a");
-      link.href = dataUrl;
-      link.download = filename;
-      link.click();
-    },
-    "editor.uploadFile": (
-      _ctx,
-      accept?: string,
-      capture?: string,
-    ): Promise<UploadFile> => {
-      return new Promise<UploadFile>((resolve, reject) => {
-        const input = document.createElement("input");
-        input.type = "file";
-        if (accept) {
-          input.accept = accept;
-        }
-        if (capture) {
-          input.capture = capture;
-        }
+          input.onchange = () => {
+            const file = input.files?.item(0);
+            if (!file) {
+              reject(new Error("No file found"));
+            } else {
+              const reader = new FileReader();
+              reader.readAsArrayBuffer(file);
+              reader.onloadend = async (evt) => {
+                if (evt.target?.readyState === FileReader.DONE) {
+                  resolve({
+                    name: file.name,
+                    contentType: file.type,
+                    content: new Uint8Array(await file.arrayBuffer()),
+                  });
+                }
+              };
+              reader.onabort = (e) => {
+                reject(e);
+              };
+              reader.onerror = (e) => {
+                reject(e);
+              };
+            }
+          };
+          input.onabort = (e) => {
+            reject(e);
+          };
 
-        input.onchange = () => {
-          const file = input.files?.item(0);
-          if (!file) {
-            reject(new Error("No file found"));
+          input.style.display = "none";
+          document.body.appendChild(input);
+          input.click();
+          setTimeout(() => document.body.removeChild(input), 1000);
+        });
+      },
+      description:
+        "Opens the browser's native file picker and returns the selected file's bytes and metadata.",
+      parameters: [
+        {
+          name: "accept",
+          type: "string",
+          description: "Accepted file types for the file input.",
+          optional: true,
+        },
+        {
+          name: "capture",
+          type: "string",
+          description: "The media capture mode for the file input.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "UploadFile",
+          description: "The selected file's name, content type, and bytes.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local file = editor.uploadFile(".txt")\nprint(file.name)',
+        },
+      ],
+    },
+    "editor.flashNotification": {
+      callback: (
+        _ctx,
+        message: string,
+        type: NotificationType = "info",
+        options?: { timeout?: number; actions?: NotificationAction[] },
+      ) => {
+        client.ui.flashNotification(message, type, options);
+      },
+      description: "Shows a flash notification in the editor UI.",
+      parameters: [
+        {
+          name: "message",
+          type: "string",
+          description: "The message to display.",
+        },
+        {
+          name: "type",
+          type: "NotificationType",
+          description:
+            'The notification severity: "info", "error", or "warning".',
+          optional: true,
+        },
+        {
+          name: "options",
+          type: "{ timeout?: number; actions?: NotificationAction[] }",
+          description:
+            "Optional timeout and action buttons. A timeout of 0 keeps the notification visible until dismissed.",
+          optional: true,
+        },
+      ],
+      examples: [
+        {
+          code: 'editor.flashNotification("Update available", "warning", {\n  timeout = 0,\n  actions = {{\n    name = "Reload",\n    run = function() editor.reloadUI() end\n  }}\n})',
+        },
+      ],
+    },
+    "editor.filterBox": {
+      callback: (
+        _ctx,
+        label: string,
+        options: FilterOption[],
+        helpText = "",
+        placeHolder = "",
+      ): Promise<FilterOption | undefined> => {
+        return client.ui.filterBox(label, options, helpText, placeHolder);
+      },
+      description:
+        "Shows a filterable option picker similar to the page navigator.",
+      parameters: [
+        {
+          name: "label",
+          type: "string",
+          description: "The label shown beside the filter input.",
+        },
+        {
+          name: "options",
+          type: "FilterOption[]",
+          description: "The available options.",
+        },
+        {
+          name: "helpText",
+          type: "string",
+          description: "Help text shown below the picker.",
+          optional: true,
+        },
+        {
+          name: "placeHolder",
+          type: "string",
+          description: "Placeholder text for the filter input.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "FilterOption | undefined",
+          description: "The selected option, or undefined if dismissed.",
+        },
+      ],
+      examples: [
+        {
+          code: 'local result = editor.filterBox("Select:", {\n  {name = "Option 1", value = "1"},\n  {name = "Option 2", value = "2", description = "More details"}\n})',
+        },
+      ],
+    },
+    "editor.showPanel": {
+      callback: async (
+        _ctx,
+        id: string,
+        mode: PanelMode,
+        html: HTMLElement | HTMLElement[] | string,
+        script: string,
+      ) => {
+        // The other half of the shared-slot arbitration in editor_ui.tsx: a
+        // plug opening one of these slots closes the navigator's occupant.
+        if (id === "modal" || id === "bhs") {
+          await hideNavigatorSlot(id, undefined, {
+            restoreDisplaced: false,
+          });
+        }
+        client.ui.viewDispatch({
+          type: "show-panel",
+          id: id as any,
+          config: { html, script, mode },
+        });
+        setTimeout(() => {
+          // Dummy dispatch to rerender the editor and toggle the panel
+          client.editorView.dispatch({});
+        });
+      },
+      description: "Shows an HTML panel in a specified editor UI location.",
+      parameters: [
+        {
+          name: "id",
+          type: "string",
+          description: "The panel location identifier.",
+        },
+        {
+          name: "mode",
+          type: "number | string",
+          description: "The panel display mode or size.",
+        },
+        {
+          name: "html",
+          type: "HTMLElement | HTMLElement[] | string",
+          description: "The panel content.",
+        },
+        {
+          name: "script",
+          type: "string",
+          description: "A script associated with the panel content.",
+        },
+      ],
+    },
+    "editor.focus": {
+      callback: () => {
+        client.focus();
+      },
+      description: "Returns focus to the main editor.",
+    },
+    "editor.getFocusedPanelSlot": {
+      callback: (): PanelSlot | undefined => {
+        const active = document.activeElement;
+        if (!(active instanceof HTMLIFrameElement)) return undefined;
+        const slot = active.dataset.slot;
+        return slot === "lhs" ||
+          slot === "rhs" ||
+          slot === "bhs" ||
+          slot === "modal"
+          ? slot
+          : undefined;
+      },
+      description:
+        "Returns the slot of the panel (keyed or legacy) whose iframe currently holds focus, or undefined if none does.",
+      returns: [
+        {
+          type: '"lhs" | "rhs" | "bhs" | "modal" | undefined',
+          description:
+            "The focused panel's slot, or undefined if no panel iframe has focus.",
+        },
+      ],
+    },
+    "editor.hidePanel": {
+      callback: async (_ctx, id: string) => {
+        // The navigator owns this slot whenever it is the thing showing
+        // there, so "hide the panel at this location" has to reach it too.
+        await hideNavigatorSlot(id);
+        client.ui.viewDispatch({
+          type: "hide-panel",
+          id: id as any,
+        });
+        setTimeout(() => {
+          // Dummy dispatch to rerender the editor and toggle the panel
+          client.editorView.dispatch({});
+        });
+      },
+      description: "Hides the panel at a specified editor UI location.",
+      parameters: [
+        {
+          name: "id",
+          type: "string",
+          description: "The panel location identifier.",
+        },
+      ],
+    },
+    "editor.showProgress": {
+      callback: (
+        _ctx,
+        progressType: "sync" | "index",
+        progressPercentage?: number,
+      ) => {
+        client.ui.showProgress(progressType, progressPercentage);
+      },
+      description:
+        "Shows, updates, or hides a sync or indexing progress indicator.",
+      parameters: [
+        {
+          name: "progressType",
+          type: "sync | index",
+          description: "The operation represented by the indicator.",
+        },
+        {
+          name: "progressPercentage",
+          type: "number",
+          description:
+            "Completion percentage, or undefined to hide the indicator.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.insertAtPos": {
+      callback: (
+        _ctx,
+        text: string,
+        pos: number,
+        cursorPlaceHolder = false,
+      ) => {
+        let cursorPlaceholderPos = -1;
+        if (cursorPlaceHolder) {
+          cursorPlaceholderPos = text.indexOf("|^|");
+          if (cursorPlaceholderPos !== -1) {
+            text =
+              text.slice(0, cursorPlaceholderPos) +
+              text.slice(cursorPlaceholderPos + 3);
           } else {
-            const reader = new FileReader();
-            reader.readAsArrayBuffer(file);
-            reader.onloadend = async (evt) => {
-              if (evt.target?.readyState === FileReader.DONE) {
-                resolve({
-                  name: file.name,
-                  contentType: file.type,
-                  content: new Uint8Array(await file.arrayBuffer()),
-                });
-              }
-            };
-            reader.onabort = (e) => {
-              reject(e);
-            };
-            reader.onerror = (e) => {
-              reject(e);
-            };
+            cursorPlaceHolder = false;
           }
-        };
-        input.onabort = (e) => {
-          reject(e);
-        };
-
-        input.style.display = "none";
-        document.body.appendChild(input);
-        input.click();
-        setTimeout(() => document.body.removeChild(input), 1000);
-      });
-    },
-    "editor.flashNotification": (
-      _ctx,
-      message: string,
-      type: NotificationType = "info",
-      options?: { timeout?: number; actions?: NotificationAction[] },
-    ) => {
-      client.ui.flashNotification(message, type, options);
-    },
-    "editor.filterBox": (
-      _ctx,
-      label: string,
-      options: FilterOption[],
-      helpText = "",
-      placeHolder = "",
-    ): Promise<FilterOption | undefined> => {
-      return client.ui.filterBox(label, options, helpText, placeHolder);
-    },
-    "editor.showPanel": (
-      _ctx,
-      id: string,
-      mode: number,
-      html: HTMLElement | HTMLElement[] | string,
-      script: string,
-    ) => {
-      client.ui.viewDispatch({
-        type: "show-panel",
-        id: id as any,
-        config: { html, script, mode },
-      });
-      setTimeout(() => {
-        // Dummy dispatch to rerender the editor and toggle the panel
-        client.editorView.dispatch({});
-      });
-    },
-    "editor.focus": () => {
-      client.focus();
-    },
-    "editor.hidePanel": (_ctx, id: string) => {
-      client.ui.viewDispatch({
-        type: "hide-panel",
-        id: id as any,
-      });
-      setTimeout(() => {
-        // Dummy dispatch to rerender the editor and toggle the panel
-        client.editorView.dispatch({});
-      });
-    },
-    "editor.showProgress": (
-      _ctx,
-      progressPercentage?: number,
-      progressType?: "sync" | "index",
-    ) => {
-      client.ui.showProgress(progressPercentage, progressType);
-    },
-    "editor.insertAtPos": (
-      _ctx,
-      text: string,
-      pos: number,
-      cursorPlaceHolder = false,
-    ) => {
-      let cursorPlaceholderPos = -1;
-      if (cursorPlaceHolder) {
-        cursorPlaceholderPos = text.indexOf("|^|");
-        if (cursorPlaceholderPos !== -1) {
+        }
+        client.editorView.dispatch({
+          changes: {
+            insert: text,
+            from: pos,
+          },
+        });
+        if (cursorPlaceHolder) {
+          const cursorPos = pos + cursorPlaceholderPos;
+          client.editorView.dispatch({
+            selection: {
+              anchor: cursorPos,
+            },
+            effects: [EditorView.scrollIntoView(cursorPos)],
+          });
+        }
+      },
+      description:
+        "Inserts text at a character offset, optionally placing the cursor at a `|^|` marker.",
+      parameters: [
+        { name: "text", type: "string", description: "The text to insert." },
+        {
+          name: "pos",
+          type: "number",
+          description: "The character offset at which to insert.",
+        },
+        {
+          name: "cursorPlaceHolder",
+          type: "boolean",
+          description:
+            "Whether to remove `|^|` and move the cursor to its position.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.replaceRange": {
+      callback: (
+        _ctx,
+        from: number,
+        to: number,
+        text: string,
+        cursorPlaceHolder = false,
+      ) => {
+        let cursorPlaceholderPos = -1;
+        if (cursorPlaceHolder) {
+          cursorPlaceholderPos = text.indexOf("|^|");
           text =
             text.slice(0, cursorPlaceholderPos) +
             text.slice(cursorPlaceholderPos + 3);
-        } else {
-          cursorPlaceHolder = false;
         }
-      }
-      client.editorView.dispatch({
-        changes: {
-          insert: text,
-          from: pos,
-        },
-      });
-      if (cursorPlaceHolder) {
-        const cursorPos = pos + cursorPlaceholderPos;
         client.editorView.dispatch({
-          selection: {
-            anchor: cursorPos,
+          changes: {
+            insert: text,
+            from: from,
+            to: to,
           },
-          effects: [EditorView.scrollIntoView(cursorPos)],
         });
-      }
-    },
-    "editor.replaceRange": (
-      _ctx,
-      from: number,
-      to: number,
-      text: string,
-      cursorPlaceHolder = false,
-    ) => {
-      let cursorPlaceholderPos = -1;
-      if (cursorPlaceHolder) {
-        cursorPlaceholderPos = text.indexOf("|^|");
-        text =
-          text.slice(0, cursorPlaceholderPos) +
-          text.slice(cursorPlaceholderPos + 3);
-      }
-      client.editorView.dispatch({
-        changes: {
-          insert: text,
-          from: from,
-          to: to,
-        },
-      });
-      if (cursorPlaceHolder) {
-        const cursorPos = from + cursorPlaceholderPos;
+        if (cursorPlaceHolder) {
+          const cursorPos = from + cursorPlaceholderPos;
+          client.editorView.dispatch({
+            selection: {
+              anchor: cursorPos,
+            },
+            effects: [EditorView.scrollIntoView(cursorPos)],
+          });
+        }
+      },
+      description:
+        "Replaces a text range, optionally placing the cursor at a `|^|` marker in the replacement.",
+      parameters: [
+        {
+          name: "from",
+          type: "number",
+          description: "The start offset of the range.",
+        },
+        {
+          name: "to",
+          type: "number",
+          description: "The end offset of the range.",
+        },
+        {
+          name: "text",
+          type: "string",
+          description: "The replacement text.",
+        },
+        {
+          name: "cursorPlaceHolder",
+          type: "boolean",
+          description:
+            "Whether to remove `|^|` and move the cursor to its position.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.moveCursor": {
+      callback: (_ctx, pos: number, center = false) => {
+        // Always scroll into view so callers don't strand the cursor
+        // off-screen; `nearest` (default) is a no-op when already visible.
+        client.editorView.dispatch({
+          selection: { anchor: pos },
+          effects: [
+            EditorView.scrollIntoView(pos, center ? { y: "center" } : {}),
+          ],
+        });
+        client.editorView.focus();
+      },
+      description:
+        "Moves and focuses the cursor at a character offset, scrolling it into view.",
+      parameters: [
+        {
+          name: "pos",
+          type: "number",
+          description: "The character offset to move to.",
+        },
+        {
+          name: "center",
+          type: "boolean",
+          description: "Whether to vertically center the cursor.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.moveCursorToLine": {
+      callback: (_ctx, line: number, column = 1, center = false) => {
+        const cmLine = client.editorView.state.doc.line(line);
+        const offset = Math.max(0, Math.min(cmLine.length, column - 1));
+        const moveCursor = syscalls["editor.moveCursor"];
+        const moveCursorCallback =
+          typeof moveCursor === "function" ? moveCursor : moveCursor.callback;
+        moveCursorCallback(_ctx, cmLine.from + offset, center);
+      },
+      description:
+        "Moves the cursor to a one-based line and column, clamping the column to the line length.",
+      parameters: [
+        {
+          name: "line",
+          type: "number",
+          description: "The one-based line number.",
+        },
+        {
+          name: "column",
+          type: "number",
+          description: "The one-based column number.",
+          optional: true,
+        },
+        {
+          name: "center",
+          type: "boolean",
+          description: "Whether to vertically center the cursor.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.setSelection": {
+      callback: (_ctx, from: number, to: number) => {
         client.editorView.dispatch({
           selection: {
-            anchor: cursorPos,
+            anchor: from,
+            head: to,
           },
-          effects: [EditorView.scrollIntoView(cursorPos)],
         });
-      }
-    },
-    "editor.moveCursor": (_ctx, pos: number, center = false) => {
-      // Always scroll into view so callers don't strand the cursor
-      // off-screen; `nearest` (default) is a no-op when already visible.
-      client.editorView.dispatch({
-        selection: { anchor: pos },
-        effects: [
-          EditorView.scrollIntoView(pos, center ? { y: "center" } : {}),
-        ],
-      });
-      client.editorView.focus();
-    },
-    "editor.moveCursorToLine": (
-      _ctx,
-      line: number,
-      column = 1,
-      center = false,
-    ) => {
-      // CodeMirror already keeps information about lines
-      const cmLine = client.editorView.state.doc.line(line);
-      // How much to move inside the line, column number starts from 1
-      const offset = Math.max(0, Math.min(cmLine.length, column - 1));
-      // Just reuse the implementation above
-      syscalls["editor.moveCursor"](_ctx, cmLine.from + offset, center);
-    },
-    "editor.setSelection": (_ctx, from: number, to: number) => {
-      client.editorView.dispatch({
-        selection: {
-          anchor: from,
-          head: to,
-        },
-      });
+      },
+      description: "Sets the main editor selection to a character range.",
+      parameters: [
+        {
+          name: "from",
+          type: "number",
+          description: "The selection anchor offset.",
+        },
+        {
+          name: "to",
+          type: "number",
+          description: "The selection head offset.",
+        },
+      ],
     },
 
-    "editor.insertAtCursor": (
-      _ctx,
-      text: string,
-      scrollIntoView = false,
-      cursorPlaceHolder = false,
-    ) => {
-      const editorView = client.editorView;
-      const from = editorView.state.selection.main.from;
-      const cursorPlaceholderPos = text.indexOf("|^|");
-      if (cursorPlaceHolder && cursorPlaceholderPos !== -1) {
-        text =
-          text.slice(0, cursorPlaceholderPos) +
-          text.slice(cursorPlaceholderPos + 3);
-      } else {
-        cursorPlaceHolder = false;
-      }
-      editorView.dispatch({
-        changes: {
-          insert: text,
-          from: from,
-        },
-        selection: {
-          anchor: cursorPlaceHolder
-            ? from + cursorPlaceholderPos
-            : from + text.length,
-        },
-        scrollIntoView,
-      });
-    },
-    "editor.dispatch": (_ctx, change: Transaction) => {
-      client.editorView.dispatch(change);
-    },
-    "editor.prompt": (
-      _ctx,
-      message: string,
-      defaultValue = "",
-    ): Promise<string | undefined> => {
-      return client.ui.prompt(message, defaultValue);
-    },
-    "editor.confirm": (
-      _ctx,
-      message: string,
-      options?: { destructive?: boolean },
-    ): Promise<boolean> => {
-      return client.ui.confirm(message, options);
-    },
-    "editor.alert": (_ctx, message: string) => {
-      alert(message);
-    },
-    "editor.getUiOption": (_ctx, key: string): any => {
-      return (client.ui.viewState.uiOptions as any)[key];
-    },
-    "editor.setUiOption": (_ctx, key: string, value: any) => {
-      client.ui.viewDispatch({
-        type: "set-ui-option",
-        key,
-        value,
-      });
-      void client.reloadEditor();
-    },
-    "editor.vimEx": (_ctx, exCommand: string) => {
-      const vimMod = getVimModule();
-      if (!vimMod) {
-        throw new Error("Vim module not loaded.");
-      }
-      const cm = vimMod.getCM(client.editorView);
-      if (cm?.state.vim) {
-        return vimMod.Vim.handleEx(cm as any, exCommand);
-      } else {
-        throw new Error("Vim mode not active or not initialized.");
-      }
-    },
-    "editor.configureVimMode": () => {
-      const vimMod = getVimModule();
-      if (!vimMod) {
-        throw new Error("Vim module not loaded.");
-      }
-      const { Vim } = vimMod;
-      // Override the default "o" binding to be more intelligent and follow the markdown editor's behavior
-      Vim.mapCommand("o", "action", "newline-continue-markup", {}, {});
-      Vim.mapCommand("O", "action", "back-newline-continue-markup", {}, {});
-      Vim.unmap("<C-q>", undefined as any);
-      Vim.defineAction("newline-continue-markup", (cm) => {
-        // Append at end of line
-        Vim.handleKey(cm, "A", "+input");
-        // Insert newline continuing markup where appropriate
-        insertNewlineContinueMarkup(client.editorView) ||
-          insertNewlineAndIndent(client.editorView);
-      });
-      Vim.defineAction("back-newline-continue-markup", (cm) => {
-        // Determine current line
-        const pos = client.editorView.state.selection.main.from;
-        const line = client.editorView.state.doc.lineAt(pos).number;
-        if (line === 1) {
-          // We're on the top line
-          // Go to 0:0
-          Vim.handleKey(cm, "0", "+input");
-          // Insert a newline
-          insertNewline(client.editorView);
-          // Go up to the new line
-          Vim.handleKey(cm, "k", "+input");
-          // Into insert mode
-          Vim.handleKey(cm, "i", "+input");
+    "editor.insertAtCursor": {
+      callback: (
+        _ctx,
+        text: string,
+        scrollIntoView = false,
+        cursorPlaceHolder = false,
+      ) => {
+        const editorView = client.editorView;
+        const from = editorView.state.selection.main.from;
+        const cursorPlaceholderPos = text.indexOf("|^|");
+        if (cursorPlaceHolder && cursorPlaceholderPos !== -1) {
+          text =
+            text.slice(0, cursorPlaceholderPos) +
+            text.slice(cursorPlaceholderPos + 3);
+        } else {
+          cursorPlaceHolder = false;
+        }
+        editorView.dispatch({
+          changes: {
+            insert: text,
+            from: from,
+          },
+          selection: {
+            anchor: cursorPlaceHolder
+              ? from + cursorPlaceholderPos
+              : from + text.length,
+          },
+          scrollIntoView,
+        });
+      },
+      description:
+        "Inserts text at the cursor and moves the cursor after it or to an optional `|^|` marker.",
+      parameters: [
+        { name: "text", type: "string", description: "The text to insert." },
+        {
+          name: "scrollIntoView",
+          type: "boolean",
+          description: "Whether to scroll the new cursor position into view.",
+          optional: true,
+        },
+        {
+          name: "cursorPlaceHolder",
+          type: "boolean",
+          description:
+            "Whether to remove `|^|` and move the cursor to its position.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.dispatch": {
+      callback: (_ctx, change: Transaction) => {
+        client.editorView.dispatch(change);
+      },
+      description: "Dispatches a CodeMirror transaction to the editor view.",
+      parameters: [
+        {
+          name: "change",
+          type: "Transaction",
+          description: "The CodeMirror transaction to dispatch.",
+        },
+      ],
+    },
+    "editor.prompt": {
+      callback: (
+        _ctx,
+        message: string,
+        defaultValue = "",
+      ): Promise<string | undefined> => {
+        return client.ui.prompt(message, defaultValue);
+      },
+      description: "Prompts the user for text input.",
+      parameters: [
+        {
+          name: "message",
+          type: "string",
+          description: "The prompt message.",
+        },
+        {
+          name: "defaultValue",
+          type: "string",
+          description: "The initial input value.",
+          optional: true,
+        },
+      ],
+      returns: [
+        {
+          type: "string | undefined",
+          description: "The entered text, or undefined if dismissed.",
+        },
+      ],
+    },
+    "editor.confirm": {
+      callback: (
+        _ctx,
+        message: string,
+        options?: { destructive?: boolean },
+      ): Promise<boolean> => {
+        return client.ui.confirm(message, options);
+      },
+      description: "Prompts the user to confirm or cancel an action.",
+      parameters: [
+        {
+          name: "message",
+          type: "string",
+          description: "The confirmation message.",
+        },
+        {
+          name: "options",
+          type: "{ destructive?: boolean }",
+          description: "Optional dialog styling settings.",
+          optional: true,
+        },
+      ],
+      returns: [
+        { type: "boolean", description: "Whether the user confirmed." },
+      ],
+    },
+    "editor.alert": {
+      callback: (_ctx, message: string) => {
+        alert(message);
+      },
+      description: "Shows a browser alert dialog.",
+      parameters: [
+        {
+          name: "message",
+          type: "string",
+          description: "The alert message.",
+        },
+      ],
+    },
+    "editor.getUiOption": {
+      callback: (_ctx, key: string): any => {
+        return (client.ui.viewState.uiOptions as any)[key];
+      },
+      description: "Returns the current value of an editor UI option.",
+      parameters: [
+        { name: "key", type: "string", description: "The UI option key." },
+      ],
+      returns: [{ type: "any", description: "The option value." }],
+    },
+    "editor.setUiOption": {
+      callback: (_ctx, key: string, value: any) => {
+        client.ui.viewDispatch({
+          type: "set-ui-option",
+          key,
+          value,
+        });
+        void client.reloadEditor();
+      },
+      description: "Sets an editor UI option and reloads the editor.",
+      parameters: [
+        { name: "key", type: "string", description: "The UI option key." },
+        { name: "value", type: "any", description: "The option value." },
+      ],
+    },
+    "editor.vimEx": {
+      callback: (_ctx, exCommand: string) => {
+        const vimMod = getVimModule();
+        if (!vimMod) {
+          throw new Error("Vim module not loaded.");
+        }
+        const cm = vimMod.getCM(client.editorView);
+        if (cm?.state.vim) {
+          return vimMod.Vim.handleEx(cm as any, exCommand);
         } else {
-          // We're elsewhere in the document
-          // Go up
-          Vim.handleKey(cm, "k", "+input");
-          // Append mode at the end of the line
+          throw new Error("Vim mode not active or not initialized.");
+        }
+      },
+      description: "Executes a Vim Ex command in the active Vim-mode editor.",
+      parameters: [
+        {
+          name: "exCommand",
+          type: "string",
+          description: "The Ex command to execute.",
+        },
+      ],
+    },
+    "editor.configureVimMode": {
+      callback: () => {
+        const vimMod = getVimModule();
+        if (!vimMod) {
+          throw new Error("Vim module not loaded.");
+        }
+        const { Vim } = vimMod;
+        Vim.mapCommand("o", "action", "newline-continue-markup", {}, {});
+        Vim.mapCommand("O", "action", "back-newline-continue-markup", {}, {});
+        Vim.unmap("<C-q>", undefined as any);
+        Vim.defineAction("newline-continue-markup", (cm) => {
           Vim.handleKey(cm, "A", "+input");
-          // Insert a newline using the continue markup thing
           insertNewlineContinueMarkup(client.editorView) ||
             insertNewlineAndIndent(client.editorView);
-        }
-      });
+        });
+        Vim.defineAction("back-newline-continue-markup", (cm) => {
+          const pos = client.editorView.state.selection.main.from;
+          const line = client.editorView.state.doc.lineAt(pos).number;
+          if (line === 1) {
+            Vim.handleKey(cm, "0", "+input");
+            insertNewline(client.editorView);
+            Vim.handleKey(cm, "k", "+input");
+            Vim.handleKey(cm, "i", "+input");
+          } else {
+            Vim.handleKey(cm, "k", "+input");
+            Vim.handleKey(cm, "A", "+input");
+            insertNewlineContinueMarkup(client.editorView) ||
+              insertNewlineAndIndent(client.editorView);
+          }
+        });
 
-      // Load the config if any
-      const config = client.config.get<VimConfig>("vim", {});
-      if (config) {
-        config.unmap?.forEach((binding) => {
-          if (typeof binding === "string") {
-            console.log(`Unmapping ${binding}`);
-            // @ts-expect-error: unmap expects a string for the mode, this is problematic with Ex mappings which requires undefined or false
-            Vim.unmap(binding, undefined);
-          } else if (binding.key) {
-            console.log(
-              `Unmapping ${binding.key} in ${binding.mode ?? "normal"}`,
+        const config = client.config.get<VimConfig>("vim", {});
+        if (config) {
+          config.unmap?.forEach((binding) => {
+            if (typeof binding === "string") {
+              console.log(`Unmapping ${binding}`);
+              // @ts-expect-error: unmap expects a string for the mode, this is problematic with Ex mappings which requires undefined or false
+              Vim.unmap(binding, undefined);
+            } else if (binding.key) {
+              console.log(
+                `Unmapping ${binding.key} in ${binding.mode ?? "normal"}`,
+              );
+              Vim.unmap(binding.key, binding.mode ?? "normal");
+            }
+          });
+          config.map?.forEach(({ map, to, mode }) => {
+            console.log(`Mapping ${map} to ${to} for ${mode ?? "normal"}`);
+            Vim.map(map, to, mode ?? "normal");
+          });
+          config.noremap?.forEach(({ map, to, mode }) => {
+            console.log(`Noremapping ${map} to ${to} for ${mode ?? "normal"}`);
+            Vim.noremap(map, to, mode ?? "normal");
+          });
+          config.commands?.forEach(({ ex, command }) => {
+            console.log(`Mapping command '${command}' to Ex ${ex}`);
+            Vim.defineEx(ex, "", (_, params) =>
+              client.runCommandByName(command, params.args),
             );
-            Vim.unmap(binding.key, binding.mode ?? "normal");
-          }
+          });
+        } else {
+          console.log("No vim config found");
+        }
+      },
+      description:
+        "Configures CodeMirror Vim mode from the current SilverBullet Vim settings.",
+    },
+    "editor.openPageNavigator": {
+      callback: (_ctx, mode: "page" | "meta" | "document" | "all" = "page") => {
+        void client.startPageNavigate(mode);
+      },
+      description: `Opens the page picker in the requested browsing mode. Each mode maps to a segment of the \`std.pages\` navigator view.`,
+      parameters: [
+        {
+          name: "mode",
+          type: "page | meta | document | all",
+          description: "The navigator mode.",
+          optional: true,
+        },
+      ],
+    },
+    "editor.openCommandPalette": {
+      callback: () => {
+        void client.startCommandPalette();
+      },
+      description: "Opens the command palette.",
+    },
+    "editor.openNavigator": {
+      callback: (
+        _ctx,
+        name: string,
+        opts?: {
+          segment?: string;
+          phrase?: string;
+          dropdown?: unknown;
+          focus?: boolean;
+        },
+      ) => client.openNavigatorView(name, opts),
+      description: `Opens a navigator view, returning whether it opened. False means the view isn't there to open -- typically because it's defined in Space Lua that hasn't been indexed yet -- so a caller can fall back to something else.`,
+      parameters: [
+        { name: "name", type: "string", description: "The view's name." },
+        {
+          name: "opts",
+          type: "table",
+          description:
+            "Optional `segment` (segment label), `phrase`, `dropdown` (dropdown value to select), and `focus` (`false` opens without taking focus).",
+          optional: true,
+        },
+      ],
+      returns: [{ type: "boolean", description: "Whether a view opened." }],
+    },
+    "editor.deleteLine": {
+      callback: () => {
+        deleteLine(client.editorView);
+      },
+      description:
+        "Deletes the current line or the lines touched by the selection.",
+    },
+    "editor.selectAll": {
+      callback: () => {
+        return selectAll({
+          state: client.editorView.state,
+          dispatch: client.editorView.dispatch,
         });
-        config.map?.forEach(({ map, to, mode }) => {
-          console.log(`Mapping ${map} to ${to} for ${mode ?? "normal"}`);
-          Vim.map(map, to, mode ?? "normal");
+      },
+      description: "Selects the entire editor document.",
+    },
+    "editor.indentMore": {
+      callback: () => {
+        return indentMore({
+          state: client.editorView.state,
+          dispatch: client.editorView.dispatch,
         });
-        config.noremap?.forEach(({ map, to, mode }) => {
-          console.log(`Noremapping ${map} to ${to} for ${mode ?? "normal"}`);
-          Vim.noremap(map, to, mode ?? "normal");
+      },
+      description: "Increases indentation for the current line or selection.",
+    },
+    "editor.indentLess": {
+      callback: () => {
+        return indentLess({
+          state: client.editorView.state,
+          dispatch: client.editorView.dispatch,
         });
-        config.commands?.forEach(({ ex, command }) => {
-          console.log(`Mapping command '${command}' to Ex ${ex}`);
-          Vim.defineEx(ex, "", (_, params) =>
-            client.runCommandByName(command, params.args),
-          );
+      },
+      description: "Decreases indentation for the current line or selection.",
+    },
+    "editor.toggleComment": {
+      callback: () => {
+        return toggleComment({
+          state: client.editorView.state,
+          dispatch: client.editorView.dispatch,
         });
-      } else {
-        console.log("No vim config found");
-      }
-    },
-    "editor.openPageNavigator": (
-      _ctx,
-      mode: "page" | "meta" | "document" | "all" = "page",
-    ) => {
-      client.startPageNavigate(mode);
-    },
-    "editor.openCommandPalette": () => {
-      void client.startCommandPalette();
-    },
-    "editor.deleteLine": () => {
-      deleteLine(client.editorView);
-    },
-    "editor.selectAll": () => {
-      return selectAll({
-        state: client.editorView.state,
-        dispatch: client.editorView.dispatch,
-      });
-    },
-    "editor.indentMore": () => {
-      return indentMore({
-        state: client.editorView.state,
-        dispatch: client.editorView.dispatch,
-      });
-    },
-    "editor.indentLess": () => {
-      return indentLess({
-        state: client.editorView.state,
-        dispatch: client.editorView.dispatch,
-      });
-    },
-    "editor.toggleComment": () => {
-      return toggleComment({
-        state: client.editorView.state,
-        dispatch: client.editorView.dispatch,
-      });
-    },
-    "editor.moveLineUp": () => {
-      return moveLineUp({
-        state: client.editorView.state,
-        dispatch: client.editorView.dispatch,
-      });
-    },
-    "editor.moveLineDown": () => {
-      return moveLineDown({
-        state: client.editorView.state,
-        dispatch: client.editorView.dispatch,
-      });
-    },
-    // Folding
-    "editor.fold": () => {
-      foldCode(client.editorView);
-    },
-    "editor.unfold": () => {
-      unfoldCode(client.editorView);
-    },
-    "editor.toggleFold": () => {
-      toggleFold(client.editorView);
-    },
-    "editor.foldAll": () => {
-      foldAll(client.editorView);
-    },
-    "editor.unfoldAll": () => {
-      unfoldAll(client.editorView);
-    },
-    "editor.undo": () => {
-      return undo(client.editorView);
-    },
-    "editor.redo": () => {
-      return redo(client.editorView);
-    },
-    // Cursor motion syscalls
-    "editor.cursorCharLeft": () => cursorCharLeft(client.editorView),
-    "editor.cursorCharRight": () => cursorCharRight(client.editorView),
-    "editor.cursorGroupLeft": () => cursorGroupLeft(client.editorView),
-    "editor.cursorGroupRight": () => cursorGroupRight(client.editorView),
-    "editor.cursorLineBoundaryLeft": () =>
-      cursorLineBoundaryLeft(client.editorView),
-    "editor.cursorLineBoundaryRight": () =>
-      cursorLineBoundaryRight(client.editorView),
-    "editor.cursorLineStart": () => cursorLineStart(client.editorView),
-    "editor.cursorLineEnd": () => cursorLineEnd(client.editorView),
-    "editor.cursorDocStart": () => cursorDocStart(client.editorView),
-    "editor.cursorDocEnd": () => cursorDocEnd(client.editorView),
-    // Cursor motions that also navigate the completion popup if it's open
-    "editor.cursorLineUp": () => {
-      const view = client.editorView;
-      if (moveCompletionSelection(false)(view)) return true;
-      return cursorLineUp(view);
-    },
-    "editor.cursorLineDown": () => {
-      const view = client.editorView;
-      if (moveCompletionSelection(true)(view)) return true;
-      return cursorLineDown(view);
-    },
-    "editor.cursorPageUp": () => {
-      const view = client.editorView;
-      if (moveCompletionSelection(false, "page")(view)) return true;
-      return cursorPageUp(view);
-    },
-    "editor.cursorPageDown": () => {
-      const view = client.editorView;
-      if (moveCompletionSelection(true, "page")(view)) return true;
-      return cursorPageDown(view);
-    },
-    // Selection-extending motions
-    "editor.selectCharLeft": () => selectCharLeft(client.editorView),
-    "editor.selectCharRight": () => selectCharRight(client.editorView),
-    "editor.selectGroupLeft": () => selectGroupLeft(client.editorView),
-    "editor.selectGroupRight": () => selectGroupRight(client.editorView),
-    "editor.selectLineBoundaryLeft": () =>
-      selectLineBoundaryLeft(client.editorView),
-    "editor.selectLineBoundaryRight": () =>
-      selectLineBoundaryRight(client.editorView),
-    "editor.selectLineStart": () => selectLineStart(client.editorView),
-    "editor.selectLineEnd": () => selectLineEnd(client.editorView),
-    "editor.selectDocStart": () => selectDocStart(client.editorView),
-    "editor.selectDocEnd": () => selectDocEnd(client.editorView),
-    "editor.selectLineUp": () => selectLineUp(client.editorView),
-    "editor.selectLineDown": () => selectLineDown(client.editorView),
-    "editor.selectPageUp": () => selectPageUp(client.editorView),
-    "editor.selectPageDown": () => selectPageDown(client.editorView),
-    // Delete
-    "editor.deleteCharBackward": () => deleteCharBackward(client.editorView),
-    "editor.deleteCharForward": () => deleteCharForward(client.editorView),
-    "editor.deleteGroupBackward": () => deleteGroupBackward(client.editorView),
-    "editor.deleteGroupForward": () => deleteGroupForward(client.editorView),
-    "editor.deleteLineBoundaryBackward": () =>
-      deleteLineBoundaryBackward(client.editorView),
-    "editor.deleteLineBoundaryForward": () =>
-      deleteLineBoundaryForward(client.editorView),
-    "editor.transposeChars": () => transposeChars(client.editorView),
-    // Enter: accept completion if popup is open, else newline-and-indent
-    "editor.insertNewline": () => {
-      const view = client.editorView;
-      if (acceptCompletion(view)) return true;
-      return insertNewlineAndIndent(view);
-    },
-    // Completion popup control
-    "editor.acceptCompletion": () => acceptCompletion(client.editorView),
-    "editor.startCompletion": () => startCompletion(client.editorView),
-    "editor.closeCompletion": () => closeCompletion(client.editorView),
-    "editor.openSearchPanel": () => {
-      openSearchPanel(client.editorView);
-    },
-    "editor.copyToClipboard": async (_ctx, data: string | Blob) => {
-      try {
-        if (typeof data === "string") {
-          await navigator.clipboard.writeText(data);
-        } else {
-          await navigator.clipboard.write([
-            new ClipboardItem({ [data.type]: data }),
-          ]);
+      },
+      description: "Comments or uncomments the current line or selection.",
+    },
+    "editor.moveLineUp": {
+      callback: () => {
+        return moveLineUp({
+          state: client.editorView.state,
+          dispatch: client.editorView.dispatch,
+        });
+      },
+      description: "Moves the current line or selected lines upward.",
+    },
+    "editor.moveLineDown": {
+      callback: () => {
+        return moveLineDown({
+          state: client.editorView.state,
+          dispatch: client.editorView.dispatch,
+        });
+      },
+      description: "Moves the current line or selected lines downward.",
+    },
+    "editor.fold": {
+      callback: () => {
+        foldCode(client.editorView);
+      },
+      description: "Folds the code or markup region at the cursor.",
+    },
+    "editor.unfold": {
+      callback: () => {
+        unfoldCode(client.editorView);
+      },
+      description: "Unfolds the folded region at the cursor.",
+    },
+    "editor.toggleFold": {
+      callback: () => {
+        toggleFold(client.editorView);
+      },
+      description: "Toggles folding for the region at the cursor.",
+    },
+    "editor.foldAll": {
+      callback: () => {
+        foldAll(client.editorView);
+      },
+      description: "Folds all foldable regions in the editor.",
+    },
+    "editor.unfoldAll": {
+      callback: () => {
+        unfoldAll(client.editorView);
+      },
+      description: "Unfolds all folded regions in the editor.",
+    },
+    "editor.undo": {
+      callback: () => {
+        return undo(client.editorView);
+      },
+      description: "Undoes the most recent editor change.",
+    },
+    "editor.redo": {
+      callback: () => {
+        return redo(client.editorView);
+      },
+      description: "Redoes the most recently undone editor change.",
+    },
+    "editor.cursorCharLeft": {
+      callback: () => cursorCharLeft(client.editorView),
+      description:
+        "Moves the cursor one character left, respecting bidirectional text.",
+    },
+    "editor.cursorCharRight": {
+      callback: () => cursorCharRight(client.editorView),
+      description:
+        "Moves the cursor one character right, respecting bidirectional text.",
+    },
+    "editor.cursorGroupLeft": {
+      callback: () => cursorGroupLeft(client.editorView),
+      description: "Moves the cursor left by one character group or word.",
+    },
+    "editor.cursorGroupRight": {
+      callback: () => cursorGroupRight(client.editorView),
+      description: "Moves the cursor right by one character group or word.",
+    },
+    "editor.cursorLineBoundaryLeft": {
+      callback: () => cursorLineBoundaryLeft(client.editorView),
+      description:
+        "Moves the cursor to the left visual boundary of the current line.",
+    },
+    "editor.cursorLineBoundaryRight": {
+      callback: () => cursorLineBoundaryRight(client.editorView),
+      description:
+        "Moves the cursor to the right visual boundary of the current line.",
+    },
+    "editor.cursorLineStart": {
+      callback: () => cursorLineStart(client.editorView),
+      description: "Moves the cursor to the start of the current logical line.",
+    },
+    "editor.cursorLineEnd": {
+      callback: () => cursorLineEnd(client.editorView),
+      description: "Moves the cursor to the end of the current logical line.",
+    },
+    "editor.cursorDocStart": {
+      callback: () => cursorDocStart(client.editorView),
+      description: "Moves the cursor to the start of the document.",
+    },
+    "editor.cursorDocEnd": {
+      callback: () => cursorDocEnd(client.editorView),
+      description: "Moves the cursor to the end of the document.",
+    },
+    "editor.cursorLineUp": {
+      callback: () => {
+        const view = client.editorView;
+        if (moveCompletionSelection(false)(view)) return true;
+        return cursorLineUp(view);
+      },
+      description:
+        "Moves completion selection up when open, otherwise moves the cursor up one visual line.",
+    },
+    "editor.cursorLineDown": {
+      callback: () => {
+        const view = client.editorView;
+        if (moveCompletionSelection(true)(view)) return true;
+        return cursorLineDown(view);
+      },
+      description:
+        "Moves completion selection down when open, otherwise moves the cursor down one visual line.",
+    },
+    "editor.cursorPageUp": {
+      callback: () => {
+        const view = client.editorView;
+        if (moveCompletionSelection(false, "page")(view)) return true;
+        return cursorPageUp(view);
+      },
+      description:
+        "Moves completion selection up one page when open, otherwise moves the cursor up one viewport page.",
+    },
+    "editor.cursorPageDown": {
+      callback: () => {
+        const view = client.editorView;
+        if (moveCompletionSelection(true, "page")(view)) return true;
+        return cursorPageDown(view);
+      },
+      description:
+        "Moves completion selection down one page when open, otherwise moves the cursor down one viewport page.",
+    },
+    "editor.selectCharLeft": {
+      callback: () => selectCharLeft(client.editorView),
+      description:
+        "Extends the selection one character left, respecting bidirectional text.",
+    },
+    "editor.selectCharRight": {
+      callback: () => selectCharRight(client.editorView),
+      description:
+        "Extends the selection one character right, respecting bidirectional text.",
+    },
+    "editor.selectGroupLeft": {
+      callback: () => selectGroupLeft(client.editorView),
+      description: "Extends the selection left by one character group or word.",
+    },
+    "editor.selectGroupRight": {
+      callback: () => selectGroupRight(client.editorView),
+      description:
+        "Extends the selection right by one character group or word.",
+    },
+    "editor.selectLineBoundaryLeft": {
+      callback: () => selectLineBoundaryLeft(client.editorView),
+      description:
+        "Extends the selection to the left visual boundary of the current line.",
+    },
+    "editor.selectLineBoundaryRight": {
+      callback: () => selectLineBoundaryRight(client.editorView),
+      description:
+        "Extends the selection to the right visual boundary of the current line.",
+    },
+    "editor.selectLineStart": {
+      callback: () => selectLineStart(client.editorView),
+      description:
+        "Extends the selection to the start of the current logical line.",
+    },
+    "editor.selectLineEnd": {
+      callback: () => selectLineEnd(client.editorView),
+      description:
+        "Extends the selection to the end of the current logical line.",
+    },
+    "editor.selectDocStart": {
+      callback: () => selectDocStart(client.editorView),
+      description: "Extends the selection to the start of the document.",
+    },
+    "editor.selectDocEnd": {
+      callback: () => selectDocEnd(client.editorView),
+      description: "Extends the selection to the end of the document.",
+    },
+    "editor.selectLineUp": {
+      callback: () => selectLineUp(client.editorView),
+      description: "Extends the selection upward by one visual line.",
+    },
+    "editor.selectLineDown": {
+      callback: () => selectLineDown(client.editorView),
+      description: "Extends the selection downward by one visual line.",
+    },
+    "editor.selectPageUp": {
+      callback: () => selectPageUp(client.editorView),
+      description: "Extends the selection upward by one viewport page.",
+    },
+    "editor.selectPageDown": {
+      callback: () => selectPageDown(client.editorView),
+      description: "Extends the selection downward by one viewport page.",
+    },
+    "editor.deleteCharBackward": {
+      callback: () => deleteCharBackward(client.editorView),
+      description: "Deletes the selection or the character before the cursor.",
+    },
+    "editor.deleteCharForward": {
+      callback: () => deleteCharForward(client.editorView),
+      description: "Deletes the selection or the character after the cursor.",
+    },
+    "editor.deleteGroupBackward": {
+      callback: () => deleteGroupBackward(client.editorView),
+      description:
+        "Deletes the selection or the character group before the cursor.",
+    },
+    "editor.deleteGroupForward": {
+      callback: () => deleteGroupForward(client.editorView),
+      description:
+        "Deletes the selection or the character group after the cursor.",
+    },
+    "editor.deleteLineBoundaryBackward": {
+      callback: () => deleteLineBoundaryBackward(client.editorView),
+      description:
+        "Deletes the selection or text back to the current line boundary.",
+    },
+    "editor.deleteLineBoundaryForward": {
+      callback: () => deleteLineBoundaryForward(client.editorView),
+      description:
+        "Deletes the selection or text forward to the current line boundary.",
+    },
+    "editor.transposeChars": {
+      callback: () => transposeChars(client.editorView),
+      description: "Transposes the characters around the cursor.",
+    },
+    "editor.insertNewline": {
+      callback: () => {
+        const view = client.editorView;
+        if (acceptCompletion(view)) return true;
+        return insertNewlineAndIndent(view);
+      },
+      description:
+        "Accepts the active completion, or inserts a newline with appropriate indentation.",
+    },
+    "editor.acceptCompletion": {
+      callback: () => acceptCompletion(client.editorView),
+      description:
+        "Accepts the currently selected completion when the completion popup is active.",
+      returns: [
+        {
+          type: "boolean",
+          description: "Whether an active completion was accepted.",
+        },
+      ],
+    },
+    "editor.startCompletion": {
+      callback: () => startCompletion(client.editorView),
+      description: "Explicitly starts editor completion at the cursor.",
+    },
+    "editor.closeCompletion": {
+      callback: () => closeCompletion(client.editorView),
+      description: "Closes the active editor completion popup.",
+    },
+    "editor.openSearchPanel": {
+      callback: () => {
+        openSearchPanel(client.editorView);
+      },
+      description: "Opens the editor's native search panel.",
+    },
+    "editor.copyToClipboard": {
+      callback: async (_ctx, data: string | Blob) => {
+        try {
+          await copyToClipboard(data);
+        } catch (e) {
+          console.error(e);
+          client.ui.flashNotification(`Could not copy to clipboard: ${e}`);
         }
-      } catch (e) {
-        console.error(e);
-        client.ui.flashNotification(`Could not copy to clipboard: ${e}`);
-      }
+      },
+      description:
+        "Copies text or binary Blob data to the system clipboard. Binary clipboard access requires HTTPS or localhost; text copying also works over HTTP when supported by the browser.",
+      parameters: [
+        {
+          name: "data",
+          type: "string | Blob",
+          description: "The text or Blob to copy.",
+        },
+      ],
+      examples: [{ code: 'editor.copyToClipboard("Copied text")' }],
     },
-    "editor.sendMessage": (_ctx, type: string, data: any) => {
-      if (!client.contentManager.isDocumentEditor()) return;
+    "editor.sendMessage": {
+      callback: (_ctx, type: string, data: any) => {
+        if (!client.contentManager.isDocumentEditor()) return;
 
-      client.contentManager.documentEditor.sendPublicMessage({
-        type,
-        data,
-      });
+        client.contentManager.documentEditor.sendPublicMessage({
+          type,
+          data,
+        });
+      },
+      description:
+        "Sends a public message to the active document editor, if one is open.",
+      parameters: [
+        { name: "type", type: "string", description: "The message type." },
+        {
+          name: "data",
+          type: "any",
+          description: "Data attached to the message.",
+          optional: true,
+        },
+      ],
+    },
+
+    "editor.isMobile": {
+      callback: () => isMobileDevice(),
+      description:
+        "Checks whether the current device lacks a fine pointer and should be treated as mobile.",
+      returns: [
+        {
+          type: "boolean",
+          description:
+            "Whether the editor is running in a mobile-style pointer environment.",
+        },
+      ],
     },
 
-    "editor.isMobile": () => {
-      const mouseDetected = globalThis.matchMedia("(pointer:fine)").matches;
-      return !mouseDetected;
+    // Deliberately separate from `editor.isMobile`: that one answers "what
+    // kind of pointer is this", which is the right question for touch
+    // affordances and the wrong one for layout. A narrow window on a desktop
+    // gets the narrow layout with a mouse attached; a tablet in landscape gets
+    // the wide one without.
+    "editor.isNarrowScreen": {
+      callback: () => isNarrowScreen(),
+      description:
+        "Checks whether the client is currently laid out for a narrow screen, i.e. below the breakpoint where sidebar panels become full-width drawers.",
+      returns: [
+        {
+          type: "boolean",
+          description: "Whether the narrow-screen layout is in effect.",
+        },
+      ],
     },
   };