// ZPWR-MODAL-EDITOR — SHARED VIM / EMACS MODAL EDITOR

The adapter seam — why it drops in anywhere

The Vim engine talks only to a surface adapter that implements the CodeMirror API it expects. Swap the adapter and the same engine drives a different surface. Both adapters ship — the bundler emits one bundle per surface, and the DOM build aliases the engine's monaco_adapter import to dom_adapter so the vendored engine is reused byte-for-byte with no Monaco in the bundle.

Vim on a rich-text page

The DOM adapter models the host's block-level descendants as "lines": inline nodes (span / a / img) are transparent text, a <br> is a hard break, and a column is a character offset into a line's concatenated text. Intra-line edits go through execCommand, so surrounding inline formatting survives and the browser's native undo still works. Multi-line / structural edits rebuild the affected blocks as plain paragraphs — a limitation of driving rich text with a line-based engine, with one deliberate exception:

What it is

⚠ One Monaco per page

The Monaco build bundles its own Monaco. If the host page also loads another Monaco bundle (e.g. zpwr-hooks-editor), a WebKit/WKWebView content process can crash on the second full Monaco — a blank window (Chromium tolerates two; WebKit does not). Three clean integrations:

Load order (consuming app)

The consumer loads one of the two bundles — each defines the same window.ZModal global. For the Monaco build, the CSS link plus the JS bundle; the Monaco base worker is fetched at runtime via MonacoEnvironment.getWorker.

<link rel='stylesheet' href='lib/modal-editor.bundle.css'>
<script src='lib/modal-editor.bundle.js'></script>
<!-- lib/modal-editor.worker.js is fetched at runtime, not script-tagged -->

For the DOM build, one script tag and nothing else — no stylesheet (the block caret, the completion popup and the snippet manager each inject their own <style> on first use), no worker, no Monaco.

<script src='lib/modal-editor-dom.bundle.js'></script>

Mounting an editor

ZModal.create(host, opts) creates a Monaco editor into host, applies the modal mode and returns a handle. setMode swaps the active modal layer live.

const handle = window.ZModal.create(hostEl, {
  doc: 'hello\n',          // initial text
  mode: 'vim',             // 'default' | 'vim' | 'emacs'
  statusBar: vimStatusEl,  // optional element for the vim status/command line
  language: 'plaintext',
  onChange: (text) => save(text),
});

handle.getValue();        // current text
handle.setValue(text);    // replace text
handle.focus();
handle.setMode('emacs');  // switch modal mode at runtime
handle.layout();          // re-layout after the host resizes / becomes visible
handle.destroy();         // dispose the modal layer, editor and model

Attaching to an existing editor

When the host already has a Monaco editor (so a second Monaco must not be bundled), attach a mode directly. These are the Monaco-agnostic primitives create is built on.

const vim = window.ZModal.attachVim(existingMonacoEditor, vimStatusEl);
vim.dispose();   // detach vim

const emacs = window.ZModal.attachEmacs(existingMonacoEditor);
emacs.dispose(); // detach emacs

window.ZModal facade — Monaco build

window.ZModal facade — DOM build

The Monaco-free bundle exposes the same global with a vim-only surface, mounted on an element the app already renders. setMode('default') detaches the engine and hands typing straight back to the browser; setMode('vim') re-engages it live.

const handle = window.ZModal.attach(pageEl, {
  mode: 'vim',                // 'default' | 'vim'  (default: vim)
  statusBar: vimStatusEl,     // optional element for the mode / key-buffer / ex line
  onChange: (text) => save(text),
  readOnly: false,            // true sets contenteditable="false"
  completion: { source: (prefix, fullText) => candidatesFor(prefix) },
});

handle.getValue();   // full text of the surface
handle.focus();
handle.setMode('default');
handle.isVim();      // is the engine currently engaged?
handle.adapter;      // the live vim adapter, or null
handle.destroy();

Insert-mode completion

While typing in INSERT mode the DOM editor takes the word before the caret, queries a per-field source, and shows a popup. The source comes from attach({ completion }) or, per element, from host.zmodalCompletion — read at query time, so a generic mount can attach fields whose candidate lists it does not know. With no source set the popup never opens and every key, Tab included, reaches the Vim engine unchanged.

CompletionConfig also takes separators (characters that terminate the token being completed), minChars (default 1) and maxItems (default 8). A candidate is either a plain string or { label, insert?, detail? }.

Snippets

Snippets are { trigger, body } pairs persisted in localStorage (per app WebView). Type a trigger, the completion popup offers it, Tab inserts the body. Bodies may carry dynamic tokens resolved at insertion time: $DATE, $TIME, $DATETIME, $DATE_ISO, $YEAR. The editor ships its own manager UI, so the feature needs nothing from the host.

A snippet flagged stryke treats its body as a stryke script instead of literal text: on expansion the body is run and its output is inserted. The host registers the runtime once; with no evaluator registered a stryke snippet inserts the empty string.

window.ZModal.snippets.setEvaluator((code) => invoke('run_stryke_hook', { code }));

window.ZModal.snippets.add('sig', '— sent $DATE');         // plain body
window.ZModal.snippets.add('uuid', 'print uuid();', true);  // stryke body
window.ZModal.snippets.list();          // Snippet[]
window.ZModal.snippets.match('si');     // completion candidates for a prefix
window.ZModal.snippets.expand(body);    // resolve dynamic tokens only
window.ZModal.snippets.runStryke(code); // run a body through the evaluator
window.ZModal.snippets.remove('sig');
window.ZModal.snippets.openManager();   // built-in list / add / update / remove UI

Build (build-on-each-consumer)

The editor source lives here in src/, but the bundle is built inside the consuming app so esbuild resolves that app's monaco-editor dep and writes into its frontend/lib/. Each consumer keeps esbuild + the pinned monaco-editor in devDependencies (the vim/emacs engines are vendored here, so no monaco-vim / monaco-emacs deps are needed) and invokes the bundler from its project root:

node <path-to-submodule>/scripts/build-modal-editor.mjs

The output dir defaults to <cwd>/frontend/lib; override with the MODAL_EDITOR_OUT env var. Three artifacts are produced, all build outputs (gitignore them in the consumer):

Set MODAL_EDITOR_DOM_ONLY=1 to emit only the DOM bundle — that build imports no Monaco, so the consumer needs no monaco-editor dependency at all. Otherwise the bundler checks for node_modules/monaco-editor up front and fails with the resolved path if it is absent. The bundler emits IIFE, minified, ES2020, with Monaco's codicon .ttf inlined as a data URL so the single .css artifact is self-contained.

Source layout

The app stack

zpwr-modal-editor is a shared editor component across the MenkeTechnologies apps. Browse the rest via the MenkeTechnologiesMeta umbrella repo:

• zpwr-hooks-editor — the shared Monaco code editor (stryke-LSP); the sibling this repo mirrors
• zgui-core — the shared UI widget toolkit
• zoffice — the desktop office suite (a consumer)