synabun 2.0.0 → 2.0.5

package/neural-interface/public/shared/editor/editor-commands.js

@@ -0,0 +1,212 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Code editor: commands
+// ═══════════════════════════════════════════
+//
+// One list of what the editor can be told to do: an id, the i18n key of its
+// name, the keys that run it, and the function. The keymap is built from it,
+// and so are the shortcuts popover and the command palette. Keys follow
+// VS Code; `Mod` is Cmd on macOS and Ctrl elsewhere.
+//
+// A command's `run` gets `{ cm, view, actions }`: the vendored CodeMirror
+// bundle, the editor view, and what the panel offers (save, find, wrap). It
+// returns true when it did something. No DOM and no imports: loaded by
+// `node --test` as it is.
+
+/**
+ * @typedef {object} EditorCommand
+ * @property {string} id
+ * @property {string} titleKey i18n key of its name
+ * @property {string[]} [keys] CodeMirror key names, the first one is the one shown
+ * @property {string[]} [macKeys] further keys that run it on macOS only
+ * @property {{ code: string | string[], alt?: boolean, shift?: boolean }} [physical] a key matched by its position
+ *   on the keyboard instead of the character it types: Alt with a letter types a symbol on macOS, so its name is
+ *   no use. Several codes: the key sits in another place on some keyboards
+ * @property {string} [gesture] a mouse gesture, for the shortcuts list only
+ * @property {string} [scope] where the keys work: 'editor' (default) or 'editor search-panel'
+ * @property {boolean} [passive] the key is the command's only when it acted: otherwise it does what it always did
+ * @property {boolean} [first] its keys are tried before the keys of commands that are not marked
+ * @property {string} [feature] it belongs to a feature the server may not have ('ai', 'git'): listed only when it does
+ * @property {boolean} [palette] false: not in the command palette (it acts on something a list takes the keyboard from)
+ * @property {(ctx: { cm: object, view: object, actions: object }) => boolean} [run]
+ */
+
+// Tab: accept the open completion, indent the selected lines, or insert one indent unit at the caret.
+function tab({ cm, view }) {
+  const { state } = view;
+  if (state.readOnly) return false;
+  if (cm.completionStatus(state) === 'active') return cm.acceptCompletion(view);
+  if (state.selection.ranges.some((range) => !range.empty)) return cm.indentMore(view);
+  view.dispatch(state.replaceSelection(state.facet(cm.indentUnit)), { scrollIntoView: true, userEvent: 'input' });
+  return true;
+}
+
+/** @type {EditorCommand[]} */
+export const EDITOR_COMMANDS = [
+  // Ctrl-S saves on macOS too, as it did before CodeMirror.
+  { id: 'file.save', titleKey: 'editor.command.save', keys: ['Mod-s'], macKeys: ['Ctrl-s'], scope: 'editor search-panel', run: ({ actions }) => { actions.save(); return true; } },
+
+  { id: 'find.open', titleKey: 'editor.command.find', keys: ['Mod-f'], scope: 'editor search-panel', run: ({ view, actions }) => actions.openFind(view) },
+  { id: 'find.replace', titleKey: 'editor.command.replace', keys: ['Mod-Alt-f', 'Mod-h'], scope: 'editor search-panel', run: ({ view, actions }) => actions.openReplace(view) },
+  { id: 'find.next', titleKey: 'editor.command.findNext', keys: ['F3'], scope: 'editor search-panel', run: ({ view, actions }) => actions.findNext(view) },
+  { id: 'find.previous', titleKey: 'editor.command.findPrevious', keys: ['Shift-F3'], scope: 'editor search-panel', run: ({ view, actions }) => actions.findPrevious(view) },
+  { id: 'goto.line', titleKey: 'editor.command.goToLine', keys: ['Mod-g'], scope: 'editor search-panel', run: ({ view, actions }) => actions.openGoToLine(view) },
+
+  { id: 'edit.undo', titleKey: 'editor.command.undo', keys: ['Mod-z'], run: ({ cm, view }) => cm.undo(view) },
+  { id: 'edit.redo', titleKey: 'editor.command.redo', keys: ['Mod-Shift-z', 'Mod-y'], run: ({ cm, view }) => cm.redo(view) },
+
+  { id: 'select.nextOccurrence', titleKey: 'editor.command.selectNextOccurrence', keys: ['Mod-d'], run: ({ cm, view }) => cm.selectNextOccurrence(view) },
+  { id: 'select.allOccurrences', titleKey: 'editor.command.selectAllOccurrences', keys: ['Mod-Shift-l'], run: ({ cm, view }) => cm.selectSelectionMatches(view) },
+
+  { id: 'line.copyDown', titleKey: 'editor.command.copyLineDown', keys: ['Shift-Alt-ArrowDown'], run: ({ cm, view }) => cm.copyLineDown(view) },
+  { id: 'line.copyUp', titleKey: 'editor.command.copyLineUp', keys: ['Shift-Alt-ArrowUp'], run: ({ cm, view }) => cm.copyLineUp(view) },
+  { id: 'line.moveDown', titleKey: 'editor.command.moveLineDown', keys: ['Alt-ArrowDown'], run: ({ cm, view }) => cm.moveLineDown(view) },
+  { id: 'line.moveUp', titleKey: 'editor.command.moveLineUp', keys: ['Alt-ArrowUp'], run: ({ cm, view }) => cm.moveLineUp(view) },
+  { id: 'line.delete', titleKey: 'editor.command.deleteLine', keys: ['Mod-Shift-k'], run: ({ cm, view }) => cm.deleteLine(view) },
+
+  { id: 'comment.line', titleKey: 'editor.command.toggleLineComment', keys: ['Mod-/'], run: ({ cm, view }) => cm.toggleComment(view) },
+  { id: 'comment.block', titleKey: 'editor.command.toggleBlockComment', keys: ['Shift-Alt-a'], physical: { code: 'KeyA', alt: true, shift: true }, run: ({ cm, view }) => cm.toggleBlockComment(view) },
+
+  { id: 'indent.more', titleKey: 'editor.command.indent', keys: ['Tab', 'Mod-]'], run: (ctx) => (ctx.key === 'Tab' ? tab(ctx) : ctx.cm.indentMore(ctx.view)) },
+  { id: 'indent.less', titleKey: 'editor.command.outdent', keys: ['Shift-Tab', 'Mod-['], run: ({ cm, view }) => cm.indentLess(view) },
+
+  { id: 'cursor.add', titleKey: 'editor.command.addCursor', gesture: 'Alt-Click' },
+  { id: 'cursor.addBelow', titleKey: 'editor.command.addCursorBelow', keys: ['Mod-Alt-ArrowDown'], run: ({ cm, view }) => cm.addCursorBelow(view) },
+  { id: 'cursor.addAbove', titleKey: 'editor.command.addCursorAbove', keys: ['Mod-Alt-ArrowUp'], run: ({ cm, view }) => cm.addCursorAbove(view) },
+  { id: 'select.column', titleKey: 'editor.command.columnSelection', gesture: 'Shift-Alt-Drag' },
+
+  { id: 'fold.fold', titleKey: 'editor.command.fold', keys: ['Mod-Shift-['], run: ({ cm, view }) => cm.foldCode(view) },
+  { id: 'fold.unfold', titleKey: 'editor.command.unfold', keys: ['Mod-Shift-]'], run: ({ cm, view }) => cm.unfoldCode(view) },
+  { id: 'bracket.jump', titleKey: 'editor.command.jumpToBracket', keys: ['Mod-Shift-\\'], run: ({ cm, view }) => cm.cursorMatchingBracket(view) },
+
+  { id: 'view.wordWrap', titleKey: 'editor.command.toggleWordWrap', keys: ['Alt-z'], physical: { code: 'KeyZ', alt: true }, run: ({ actions }) => { actions.toggleWordWrap(); return true; } },
+  // The rest of the View menu: no keys of their own, they are run from the menu or the palette.
+  { id: 'view.minimap', titleKey: 'editor.command.toggleMinimap', run: ({ actions }) => { actions.toggleMinimap?.(); return true; } },
+  { id: 'view.indentGuides', titleKey: 'editor.command.toggleIndentGuides', run: ({ actions }) => { actions.toggleIndentGuides?.(); return true; } },
+  { id: 'view.whitespace', titleKey: 'editor.command.cycleWhitespace', run: ({ actions }) => { actions.cycleWhitespace?.(); return true; } },
+  { id: 'view.fontLarger', titleKey: 'editor.command.fontLarger', run: ({ actions }) => { actions.fontLarger?.(); return true; } },
+  { id: 'view.fontSmaller', titleKey: 'editor.command.fontSmaller', run: ({ actions }) => { actions.fontSmaller?.(); return true; } },
+  { id: 'view.fontReset', titleKey: 'editor.command.fontReset', run: ({ actions }) => { actions.fontReset?.(); return true; } },
+
+  // The palette and go-to-file. Mod-P and Mod-Shift-P are the browser's "print": the editor takes them while it
+  // has the keyboard. F1 is the palette's first key.
+  { id: 'palette.commands', titleKey: 'editor.command.commandPalette', keys: ['F1', 'Mod-Shift-p'], scope: 'editor search-panel', palette: false, run: ({ actions }) => { actions.openPalette?.(); return true; } },
+  { id: 'palette.files', titleKey: 'editor.command.goToFile', keys: ['Mod-p'], scope: 'editor search-panel', run: ({ actions }) => { actions.openGoToFile?.(); return true; } },
+
+  // Problems the editor found in the file (editor-lint.js), and the file against the last commit (editor-git.js).
+  { id: 'lint.next', titleKey: 'editor.command.nextProblem', keys: ['F8'], run: ({ view, actions }) => actions.nextProblem?.(view) === true },
+  { id: 'lint.previous', titleKey: 'editor.command.previousProblem', keys: ['Shift-F8'], run: ({ view, actions }) => actions.previousProblem?.(view) === true },
+  { id: 'git.diff', titleKey: 'editor.command.toggleDiff', feature: 'git', run: ({ actions }) => { actions.toggleDiff?.(); return true; } },
+
+  // Tabs. A browser keeps Mod-W, Mod-T and Ctrl-Tab for its own tabs and never hands them to a page: these are
+  // keys it leaves alone. Matched by position, as Alt with a letter or a sign types another character on macOS.
+  { id: 'tab.next', titleKey: 'editor.command.nextTab', keys: ['Alt-.'], physical: { code: 'Period', alt: true }, run: ({ actions }) => { actions.nextTab?.(); return true; } },
+  { id: 'tab.previous', titleKey: 'editor.command.previousTab', keys: ['Alt-,'], physical: { code: 'Comma', alt: true }, run: ({ actions }) => { actions.previousTab?.(); return true; } },
+  { id: 'tab.close', titleKey: 'editor.command.closeTab', keys: ['Alt-w'], physical: { code: 'KeyW', alt: true }, run: ({ actions }) => { actions.closeTab?.(); return true; } },
+  { id: 'view.dismiss', titleKey: 'editor.command.dismiss', keys: ['Escape'], scope: 'editor search-panel', passive: true, run: ({ view, actions }) => actions.dismiss(view) },
+
+  // AI autocomplete (editor-ai.js). Each key is the suggestion's only while there is one: Tab indents, Mod-→
+  // moves the caret and Esc closes the find bar as always when there is none.
+  { id: 'ai.accept', titleKey: 'editor.command.aiAccept', keys: ['Tab'], feature: 'ai', first: true, passive: true, palette: false, run: ({ view, actions }) => actions.aiAccept?.(view) === true },
+  { id: 'ai.acceptWord', titleKey: 'editor.command.aiAcceptWord', keys: ['Mod-ArrowRight'], feature: 'ai', first: true, passive: true, palette: false, run: ({ view, actions }) => actions.aiAcceptWord?.(view) === true },
+  { id: 'ai.dismiss', titleKey: 'editor.command.aiDismiss', keys: ['Escape'], feature: 'ai', first: true, passive: true, palette: false, run: ({ view, actions }) => actions.aiDismiss?.(view) === true },
+  { id: 'ai.trigger', titleKey: 'editor.command.aiTrigger', keys: ['Alt-\\'], physical: { code: ['Backslash', 'IntlBackslash'], alt: true }, feature: 'ai', passive: true, run: ({ view, actions }) => actions.aiTrigger?.(view) === true },
+];
+
+/**
+ * CodeMirror key bindings for the commands that have keys. Each calls preventDefault whether or not the command
+ * did something, so a key the editor owns never reaches the browser (Mod-S never opens "Save page"). A command
+ * marked `passive` only prevents the default when it acted: Escape is left alone when there is nothing to close.
+ * Commands with a `physical` key are left out: physicalKeyHandler() runs those.
+ * @param {EditorCommand[]} commands
+ * @param {{ cm: object, actions: object }} ctx
+ */
+export function commandKeymap(commands, { cm, actions }) {
+  const bindings = [];
+  // A key that several commands share is tried in this order: the ones marked `first`, then the rest as listed.
+  const ordered = [...commands.filter((command) => command.first), ...commands.filter((command) => !command.first)];
+  for (const command of ordered) {
+    if (!command.run || !command.keys || command.physical) continue;
+    const bind = (key, platform) => {
+      const binding = { [platform]: key, run: (view) => command.run({ cm, view, actions, key }) === true };
+      if (!command.passive) binding.preventDefault = true;
+      if (command.scope) binding.scope = command.scope;
+      bindings.push(binding);
+    };
+    for (const key of command.keys) bind(key, 'key');
+    for (const key of command.macKeys || []) bind(key, 'mac');
+  }
+  return bindings;
+}
+
+/**
+ * A keydown handler for the commands bound to a physical key. Returns true (the event was handled) when one ran;
+ * a `passive` command that did nothing leaves the key to type what it types.
+ * @param {EditorCommand[]} commands
+ * @param {{ cm: object, actions: object }} ctx
+ * @returns {(event: KeyboardEvent, view: object) => boolean}
+ */
+export function physicalKeyHandler(commands, { cm, actions }) {
+  const physical = commands.filter((command) => command.run && command.physical);
+  return (event, view) => {
+    if (event.ctrlKey || event.metaKey) return false;
+    for (const command of physical) {
+      const { code, alt = false, shift = false } = command.physical;
+      if (![].concat(code).includes(event.code) || event.altKey !== alt || event.shiftKey !== shift) continue;
+      const acted = command.run({ cm, view, actions, key: command.keys?.[0] }) === true;
+      if (acted || !command.passive) return true;
+    }
+    return false;
+  };
+}
+
+const MAC_SYMBOLS = { Mod: '⌘', Meta: '⌘', Cmd: '⌘', Ctrl: '⌃', Alt: '⌥', Shift: '⇧' };
+const MAC_ORDER = ['Ctrl', 'Alt', 'Shift', 'Mod', 'Meta', 'Cmd'];
+const PC_NAMES = { Mod: 'Ctrl', Meta: 'Win', Cmd: 'Ctrl' };
+const KEY_NAMES = {
+  ArrowUp: '↑', ArrowDown: '↓', ArrowLeft: '←', ArrowRight: '→',
+  Escape: 'Esc', Enter: 'Enter', Tab: 'Tab', Backspace: 'Backspace', Delete: 'Del', Space: 'Space',
+};
+
+/**
+ * A key the way it is written for the user: `Mod-Shift-k` → `⇧⌘K` on macOS, `Ctrl+Shift+K` elsewhere.
+ * @param {string} key a CodeMirror key name, or a gesture such as `Alt-Click`
+ * @param {boolean} mac
+ * @param {(word: string) => string} [word] translates the last part of a gesture (`Click`, `Drag`)
+ */
+export function formatKey(key, mac, word = (w) => w) {
+  const parts = String(key).split('-');
+  // A trailing "-" is the minus key itself.
+  let last = parts.pop();
+  if (last === '' && parts.length) { parts.pop(); last = '-'; }
+  const name = KEY_NAMES[last] || (last.length === 1 ? last.toUpperCase() : word(last));
+  if (mac) {
+    const mods = parts.sort((a, b) => MAC_ORDER.indexOf(a) - MAC_ORDER.indexOf(b)).map((m) => MAC_SYMBOLS[m] || m);
+    return mods.join('') + name;
+  }
+  return [...parts.map((m) => PC_NAMES[m] || m), name].join('+');
+}
+
+/**
+ * The rows of the shortcuts list: every command that has a key or a gesture, with the first of its keys.
+ * @param {EditorCommand[]} [commands]
+ * @param {{ features?: string[] }} [o] the features this server has: a command of another feature is not listed
+ * @returns {{ id: string, titleKey: string, key: string, gesture: boolean }[]}
+ */
+export function shortcutRows(commands = EDITOR_COMMANDS, { features = [] } = {}) {
+  return commands
+    .filter((command) => !command.feature || features.includes(command.feature))
+    .filter((command) => command.gesture || command.keys?.length)
+    .map((command) => ({ id: command.id, titleKey: command.titleKey, key: command.gesture || command.keys[0], gesture: !!command.gesture }));
+}
+
+/**
+ * Run a command by its id (the palette does). False when there is no such command, or it has nothing to run.
+ * @param {string} id
+ * @param {{ cm: object, view: object, actions: object }} ctx
+ * @param {EditorCommand[]} [commands]
+ */
+export function runCommand(id, ctx, commands = EDITOR_COMMANDS) {
+  const command = commands.find((entry) => entry.id === id && typeof entry.run === 'function');
+  if (!command) return false;
+  return command.run({ ...ctx, key: undefined }) === true;
+}

package/neural-interface/public/shared/editor/editor-compare.js

@@ -0,0 +1,103 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Code editor: comparing with another text
+// ═══════════════════════════════════════════
+//
+// Shows the document against another version of itself, inline: what the other
+// version has and the document does not is drawn above the lines that replaced
+// it, changed lines are marked, long unchanged stretches are folded away, and
+// each difference can be put back to the other version (a button: the mouse
+// and the keyboard both press it). The document stays editable; while it is
+// read-only (a save or a reload is under way) the buttons do nothing, as the
+// keys do. It is CodeMirror's unified merge view (@codemirror/merge, a chunk
+// of the vendored bundle that is fetched the first time a comparison is
+// asked for); its colours are the theme's (--ed-add / --ed-del).
+//
+// The panel compares a buffer with the file on disk; the same extension
+// compares a file with its committed version. Takes the vendored bundle and
+// the strings as arguments: no imports.
+
+/** Lines of unchanged text kept around a difference, and the shortest stretch that is folded away. */
+export const COMPARE_CONTEXT = Object.freeze({ margin: 3, minSize: 6 });
+
+/**
+ * @param {object} cm the vendored CodeMirror bundle (editor-loader.js)
+ * @param {{ t: (key: string, params?: object) => string }} o
+ */
+export function editorCompare(cm, { t }) {
+  let merge = null;   // @codemirror/merge, once loaded
+
+  // The button that puts one difference back to the other version. The merge view also offers to accept a
+  // difference (to stop showing it); that is not a thing a comparison needs, so it gets no button.
+  const control = (label) => (type, action) => {
+    const node = document.createElement(type === 'reject' ? 'button' : 'span');
+    if (type !== 'reject') { node.hidden = true; return node; }
+    node.type = 'button';
+    node.className = 'fe-editor-compare-revert';
+    node.textContent = label;
+    // Pressed with the mouse, the keyboard stays in the text (the button is gone once it has acted).
+    node.addEventListener('mousedown', (event) => event.preventDefault());
+    // A click is what a mouse and a keyboard (Enter, Space) both end in. A document that cannot be edited right
+    // now (it is being saved or reloaded) is not edited through this button either.
+    node.addEventListener('click', (event) => {
+      const root = node.closest('.cm-editor');
+      const view = root ? cm.EditorView.findFromDOM(root) : null;
+      if (!view || view.state.readOnly) { event.preventDefault(); return; }
+      action(event);
+      view.focus();
+    });
+    return node;
+  };
+
+  return {
+    /**
+     * The extension that shows `original` against the document it is added to (the panel puts it in the view's
+     * comparison compartment). Rejects when the merge chunk cannot be loaded.
+     * @param {{ original: string, revertLabel: string, gutter?: boolean }} o `original`: the other version, line
+     *   breaks as "\n"; `revertLabel`: what the button that puts a difference back says; `gutter`: false when
+     *   another column already marks the changed lines (the git markers, for a comparison with the last commit)
+     */
+    async extension({ original, revertLabel, gutter = true }) {
+      if (!merge) merge = await cm.loadMerge();
+      // The lines that are new as a whole: every character of them is changed text. The theme gives those the
+      // line's tint only; a line that was modified keeps the stronger tint on the words that changed.
+      const { Decoration, EditorView, RangeSetBuilder, StateField } = cm;
+      const whole = Decoration.line({ class: 'cm-addedWhole' });
+      const wholeLines = (state) => {
+        const builder = new RangeSetBuilder();
+        for (const chunk of merge.getChunks(state)?.chunks || []) {
+          if (chunk.fromB >= chunk.toB) continue;
+          const end = Math.min(state.doc.length, chunk.endB);
+          for (let pos = chunk.fromB; pos <= end;) {
+            const line = state.doc.lineAt(pos);
+            if (line.length && chunk.changes.some((change) => chunk.fromB + change.fromB <= line.from && chunk.fromB + change.toB >= line.to)) builder.add(line.from, line.from, whole);
+            pos = line.to + 1;
+          }
+        }
+        return builder.finish();
+      };
+      const addedWhole = StateField.define({
+        create: wholeLines,
+        update: (value, tr) => (tr.docChanged || merge.getChunks(tr.state)?.chunks !== merge.getChunks(tr.startState)?.chunks ? wholeLines(tr.state) : value),
+        provide: (field) => EditorView.decorations.from(field),
+      });
+      return [
+        addedWhole,
+        merge.unifiedMergeView({
+          original,
+          highlightChanges: true,
+          gutter,
+          // What the other version had is drawn in the diff's own colour, not as code.
+          syntaxHighlightDeletions: false,
+          mergeControls: control(revertLabel),
+          collapseUnchanged: { ...COMPARE_CONTEXT },
+        }),
+        cm.EditorState.phrases.of({ '$ unchanged lines': t('editor.compare.unchanged', { count: '$' }) }),
+      ];
+    },
+
+    /** How many differences a state that is being compared shows; 0 for one that is not. */
+    differences(state) {
+      return merge?.getChunks(state)?.chunks.length ?? 0;
+    },
+  };
+}

package/neural-interface/public/shared/editor/editor-completion-list.js

@@ -0,0 +1,172 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Code editor: the completion list
+// ═══════════════════════════════════════════
+//
+// What the list under the caret offers (CodeMirror's autocompletion): the
+// completions of the document's language, and the words of the document. Three
+// rules are kept here, on top of what CodeMirror does:
+//
+//   - the list never offers the word that already stands before the caret: an
+//     option that would only write that word again is left out, and the list
+//     closes when nothing else is left to offer;
+//   - no name is listed twice: what the language offers (a variable) is not
+//     repeated as a word of the document, nor by a second source of the language;
+//   - while AI autocomplete is expected to suggest for the document, its words
+//     do not open the list by themselves (`wordsYield`). Asked for (Ctrl-Space),
+//     they are listed; what the language offers opens the list as always.
+//
+// An option that carries more than its label (a snippet, an `apply` of its own)
+// is not "the same word": the two `for` loops of JavaScript stay next to the
+// keyword, also when `for` is typed in full.
+//
+// CodeMirror asks a source once and reuses its answer while the word grows, so
+// each answer is given an `update` of its own here: it is filtered again on
+// every key. Takes the vendored bundle as an argument: no imports. The helpers
+// at the top need no page: `node --test` loads them as they are.
+
+/** How many completion sources a language (and the languages nested in it) is given room for at one position. */
+export const LANGUAGE_SOURCES = 8;
+
+/** An option that would only write its own label: there is nothing else to tell it from another of that label. */
+export function isPlainOption(option) {
+  return !!option && typeof option.label === 'string' && (option.apply == null || option.apply === option.label);
+}
+
+/**
+ * The options of one source as the list shows them.
+ * @param {object[]} options a source's own (CodeMirror completions: `{ label, apply?, type?, detail? }`)
+ * @param {{ typed?: string, taken?: Set<string> | null }} [o] `typed`: the word before the caret, as far as this
+ *   source would replace it; `taken`: the labels another source already offers as plain options
+ * @returns {object[]} in the same order, without the plain option that is the typed word, without a plain option
+ *   whose label is taken, and with one plain option for a label at most
+ */
+export function offeredOptions(options, { typed = '', taken = null } = {}) {
+  const seen = new Set();
+  const out = [];
+  for (const option of Array.isArray(options) ? options : []) {
+    if (!option || typeof option.label !== 'string') continue;
+    if (isPlainOption(option)) {
+      if (option.label === typed || taken?.has(option.label) || seen.has(option.label)) continue;
+      seen.add(option.label);
+    }
+    out.push(option);
+  }
+  return out;
+}
+
+/** The labels of a result's plain options, added to `into`. */
+export function plainLabels(result, into = new Set()) {
+  for (const option of result?.options || []) if (isPlainOption(option)) into.add(option.label);
+  return into;
+}
+
+/**
+ * Whether a source's result still applies to the text between `from` and `to`, by the rule the result came with
+ * (CodeMirror's `validFor`: a function, or an expression the whole text must match). Without a rule it does not.
+ */
+export function stillValid(validFor, state, from, to) {
+  if (!validFor) return false;
+  const text = state.sliceDoc(from, to);
+  if (typeof validFor === 'function') return !!validFor(text, from, to, state);
+  const { source } = validFor;
+  const start = source[0] !== '^';
+  const end = source[source.length - 1] !== '$';
+  const whole = start || end ? new RegExp(`${start ? '^' : ''}(?:${source})${end ? '$' : ''}`, validFor.flags ?? '') : validFor;
+  return whole.test(text);
+}
+
+/**
+ * @param {object} cm the vendored CodeMirror bundle (editor-loader.js)
+ * @param {{ wordsYield?: (context: object) => boolean }} [o] `wordsYield`: suggestions are expected at this caret,
+ *   so the document's words stay out of a list nobody asked for
+ */
+export function editorCompletionList(cm, { wordsYield = () => false } = {}) {
+  // A language may hand over a list of completions in place of a source: one source per list, as CodeMirror keeps them.
+  const fromLists = new WeakMap();
+  const asSource = (source) => {
+    if (typeof source === 'function') return source;
+    if (!Array.isArray(source)) return () => null;
+    if (!fromLists.has(source)) fromLists.set(source, cm.completeFromList(source));
+    return fromLists.get(source);
+  };
+  /** What the language at a position completes with: its own sources, in the order it names them. */
+  const languageSources = (state, pos) => state.languageDataAt('autocomplete', pos).map(asSource);
+
+  const isPromise = (value) => !!value && typeof value.then === 'function';
+
+  /**
+   * A source's result as the list uses it: its options filtered for the word before the caret, and filtered again
+   * each time that word changes.
+   * @param {object} original what the source answered
+   * @param {string} typed the text the result would replace
+   * @param {Set<string>} taken plain labels the sources in front of this one offer
+   */
+  function shape(original, typed, taken) {
+    const shaped = {
+      ...original,
+      options: offeredOptions(original.options, { typed, taken }),
+      // CodeMirror reuses a result while `validFor` holds, without asking anybody: here it asks `update` instead.
+      validFor: undefined,
+      update(current, from, to, context) {
+        const text = context.state.sliceDoc(from, to);
+        if (stillValid(original.validFor, context.state, from, to)) return shape({ ...original, from, to }, text, taken);
+        const renewed = typeof original.update === 'function' ? original.update(original, from, to, context) : null;
+        return renewed ? shape(renewed, context.state.sliceDoc(renewed.from, renewed.to ?? context.pos), taken) : null;
+      },
+    };
+    if (typeof original.map === 'function') {
+      shaped.map = (current, changes) => {
+        const mapped = original.map(original, changes);
+        return mapped ? shape(mapped, typed, taken) : null;
+      };
+    }
+    return shaped;
+  }
+
+  /**
+   * The result of the last of `sources`, shaped: without what the sources before it already offer.
+   * A source before it that fails or answers late is no reason to hold this one back: it offers nothing here.
+   */
+  function resultOf(sources, context) {
+    const last = sources.length - 1;
+    const before = sources.slice(0, last).map((source) => {
+      try {
+        const value = source(context);
+        return isPromise(value) ? value.catch(() => null) : value;
+      } catch { return null; }
+    });
+    let own;
+    try { own = sources[last](context); } catch (error) { return Promise.reject(error); }   // CodeMirror logs it and closes the list
+    const finish = (result, earlier) => {
+      if (!result || !Array.isArray(result.options)) return null;
+      const taken = new Set();
+      for (const other of earlier) plainLabels(other, taken);
+      return shape(result, context.state.sliceDoc(result.from, result.to ?? context.pos), taken);
+    };
+    if (isPromise(own) || before.some(isPromise)) return Promise.all([own, ...before]).then(([result, ...earlier]) => finish(result, earlier));
+    return finish(own, before);
+  }
+
+  // One place for each source the language may have at the caret. CodeMirror keeps a source's answer by the
+  // source's identity: a place is always the same function, whichever source it stands for at a position.
+  const languagePlace = (index) => (context) => {
+    const sources = languageSources(context.state, context.pos);
+    return index < sources.length ? resultOf(sources.slice(0, index + 1), context) : null;
+  };
+
+  /** The words of the document, after everything the language offers. */
+  const words = (context) => {
+    if (!context.explicit && wordsYield(context)) return null;
+    const sources = languageSources(context.state, context.pos).slice(0, LANGUAGE_SOURCES);
+    return resultOf([...sources, cm.completeAnyWord], context);
+  };
+
+  const sources = [...Array.from({ length: LANGUAGE_SOURCES }, (_, index) => languagePlace(index)), words];
+
+  return {
+    /** The list, for the view: CodeMirror's autocompletion over the sources above. */
+    extension: cm.autocompletion({ override: sources }),
+    /** The sources themselves, in the order the list asks them (tests). */
+    sources,
+  };
+}