// ZPWR-MODAL-EDITOR — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zpwr-modal-editor is the shared Vim / Emacs modal-editing editor of the MenkeTechnologies app stack — one TypeScript source of truth for the vim and emacs editing modes, vendored from monaco-vim and monaco-emacs and adapted so we own them outright. The source lives in src/ and each consuming app bundles it with its own monaco-editor dependency.

The design turns on a surface adapter: the vim engine talks only to a CodeMirror-shaped adapter, so the same ~7.1k-line engine drives either surface unchanged. Both adapters now ship — monaco_adapter over a Monaco editor, and dom_adapter over a plain contenteditable element with no Monaco at all — and the bundler emits a bundle for each. Both are esbuild IIFE (ES2020, minified) and both expose a single window.ZModal facade: create / attachVim / attachEmacs on the Monaco build, attach / attachVim / snippets on the DOM build. A consumer loads one or the other, never both.

Counts derived from the repo: src/**/*.ts = 17 files / 12,030 lines; vim engine engine/vim/keymap_vim.ts = 7,135; adapters/monaco_adapter.ts = 1,119 and adapters/dom_adapter.ts = 1,089 (both over the shared 232-line adapters/cm_core.ts); engine/emacs/*.ts = 1,329; modal engines = vim + emacs; surface adapters = monaco + dom; window.ZModal methods = create + attachVim + attachEmacs (Monaco build) / attach + attachVim + snippets (DOM build); runtime deps = 0 (lodash replaced by a local util).

~ARCHITECTURE

One engine source, built per consumer, behind a swappable surface adapter. There are two entries: src/index.ts wires the Monaco theme + worker and the Monaco facade, src/index-dom.ts the Monaco-free one. The vim engine is bolted onto whichever adapter class it imports — the DOM build aliases its ../../adapters/monaco_adapter import to dom_adapter.ts at bundle time, so the vendored 7k-line engine is reused byte-for-byte and the bundle never pulls in Monaco. The bundler runs inside each app to resolve its own Monaco dep and emit vendored IIFE artifacts.

&FACADE SURFACE

Both bundles expose one global, window.ZModal — a consumer loads whichever it needs, never both.

Monaco build (modal-editor.bundle.js): create is the convenience mount (news up a Monaco editor and applies a mode); attachVim / attachEmacs are the primitives it is built on, for hosts that already own a Monaco editor and must not bundle a second one.

DOM build (modal-editor-dom.bundle.js): vim only, over a contenteditable element, with no Monaco anywhere in the bundle.

*INSERT-MODE COMPLETION & SNIPPETS

The DOM editor grows a completion popup in INSERT mode: it takes the word before the caret and queries a per-field source, merged with any matching snippet triggers. The source is supplied either as attach({ completion }) or per element as host.zmodalCompletion (read at query time), so a generic mount can attach fields whose candidate lists it does not know. CompletionConfig also carries separators (token terminators), minChars (default 1) and maxItems (default 8). With no source configured the popup never opens and every key — Tab included — reaches the Vim engine unchanged.

Snippets are { trigger, body } pairs persisted in localStorage per app WebView, created and edited through the built-in manager (snippets.openManager()) so the feature is self-contained in the editor. Bodies resolve $DATE, $TIME, $DATETIME, $DATE_ISO and $YEAR at insertion time. A snippet flagged stryke is a stryke script rather than literal text: on expansion its body is run through an evaluator the host registers once with snippets.setEvaluator(fn) (e.g. wired to a run_stryke_hook Tauri command) and the script's output is what lands in the document. Stryke candidates resolve asynchronously on accept; with no evaluator registered they insert the empty string.

!INTEGRATION — ONE MONACO PER PAGE

The Monaco build bundles its own Monaco. If a host page also loads another Monaco bundle (e.g. zpwr-hooks-editor), a WebKit / WKWebView content process can crash on the second full Monaco — the window renders fully blank (the content process is gone). Chromium tolerates two Monacos on one page; WebKit does not. This is an integration constraint, not a bug in the engine. Three supported patterns:

/BUNDLER & RESOLVE FIXES

scripts/build-modal-editor.mjs emits three artifacts — modal-editor.bundle.js (+ .css), modal-editor.worker.js and modal-editor-dom.bundle.js — and carries esbuild resolve overrides so the vendored engines and Monaco resolve to ESM rather than AMD define() builds that throw in the WebView. Bare monaco-editor imports (the vendored monaco-emacs require()s it) are pinned to esm/vs/editor/edcore.main.js — the same lean ESM instance the entry uses — instead of the AMD min build. Deep monaco-editor/esm/* subpaths without a file extension get .js appended and resolve to the package dir directly (the package exports map only resolves extensioned paths). The build defaults its output to <cwd>/frontend/lib and honors MODAL_EDITOR_OUT. Because the vim/emacs engines are vendored, the consumer needs only esbuild + monaco-editor in devDependencies — no monaco-vim / monaco-emacs.

The DOM bundle is built by a second, tiny plugin rather than a second copy of the engine: vim-dom-adapter-alias rewrites the engine's hard adapters/monaco_adapter import to adapters/dom_adapter.ts. It uses no monaco-resolve-fix, so nothing in that bundle can reach Monaco. Setting MODAL_EDITOR_DOM_ONLY=1 emits only that bundle and skips the monaco-editor presence check — a DOM-only consumer needs no monaco-editor dependency at all. Otherwise the bundler fails fast with the resolved path when node_modules/monaco-editor is missing, rather than producing a broken artifact.

$CI GATES

This is a non-Rust (frontend / TypeScript) submodule, so it is exempt from the meta repo's cargo gates (fmt / clippy / doc / cargo test). The umbrella MenkeTechnologiesMeta repo enforces the documentation and brand gates on docs/:

#PROJECT METADATA