--- status: current version: v0.5.0 canonical: true audience: ai-agent last_updated: 2026-10-05 --- # EveGlyph Editor — Accepted (Shipped and Verified) Concepts These are the engineered, load-bearing concepts that ARE shipped in EveGlyph Editor v0.5.0. Treat each as present and real. For ideas that are deferred, superseded, or not (yet) shipped, see [./deprecated-concepts.md](./deprecated-concepts.md). For the naming and maturity history behind these concepts, see [./concept-genealogy.md](./concept-genealogy.md). ## Core paradigm - **The 4-stage loop (workspace ↔ agent ↔ diff-review ↔ human)** — a human writes clean Markdown, a local CLI agent edits files on disk with auto-approve, every change surfaces as a reviewable git diff, and the human accepts or rejects it. This loop is EveGlyph Editor's reason for existing. - **Front-stage minimal, back-stage strong** — the visible editor UI stays a plain Markdown editor; the agent, diff-review, computation and workspace- memory machinery live backstage and surface only when invoked. ## EveGlyph-MD frontmatter schema (`EG-MD-2026`) - **`type` / `status` / `tags` fields** (`src/frontmatter.js`) — a lightweight classification layer stamped into a document's frontmatter block. - **Round-trip-safe YAML-subset parser** — edits the raw frontmatter block line-by-line so a human's block scalars, nested maps, and comments survive a rewrite untouched. - **Status-bar chip + popover** — sets a document's class in-editor and warns when a value is out of the configured enum. - **Preview schema badges** — the document's `type` / `status` / `tags` are reflected in the live preview. - **Birth-stamping** — new `.md` files are stamped with the schema at creation. - **Sanitized agent context injection** — the active document's class is handed to the agent as fenced, enum-clamped, sanitized metadata, treated as data and never as instructions. ## PatchMD diff-review - **Pre-run git snapshot** — the workspace is git-snapshotted (initializing a repo if needed) before any agent run. - **Unified per-file-card diff renderer** (`src/diffview.js`) — one shared renderer, used by both the agent panel and workspace replace-all, that groups a real `git diff` into collapsible per-file cards with +/− counts, fully escaped since it renders untrusted agent/git output. - **Accept** — commits the agent's changes with message `agent: `. - **Reject** — runs `git reset --hard HEAD` followed by `git clean -fd`, discarding all agent edits and untracked files. - **Agent modes** — Suggest (advice only), Patch (edit plus diff-review, the default) and Direct (apply immediately, one-click revert). ## Real permission tiers - **Cautious / Standard / Trusted** — the three tiers flow from the frontend to the bridge and map to actual CLI enforcement, not just prompt text (real enforcement since v0.4.0, unchanged in v0.5.0): - Claude Code — `--permission-mode` plus a tool allow-list. - Codex — `exec --full-auto` (sandboxed), or `--dangerously-bypass-approvals-and-sandbox` at the most permissive tier. - Gemini — `--approval-mode` (`--yolo` at the most permissive tier). - Codex and Gemini are coarser than Claude Code below Trusted: their Cautious and Standard tiers share CLI flags and differ by prompt clause. - **Live agent activity panel** — a transient "working…" view streams the agent's output tail while it runs (respecting the quiet setting), replaced by the diff view on completion. ## `.eveglyph/` workspace memory + context compiler - **`rules.md`** — injected verbatim into every agent run with elevated authority ("follow these before anything else"). - **`glossary.md`** and **`memory/pitfalls.md`** / **`memory/recent.md`** — additional per-workspace memory layers assembled into the agent prompt. - **Context compiler** (`src/context.js`) — assembles the `.eveglyph/` files into the agent prompt; the directory is also surfaced in the file tree for in-app editing. - **Monitor tab** (`src/monitorview.js`) — a back-stage log viewer that tail-reads the local diagnostic JSONL stream, with a substring filter and manual/auto refresh. Math diagnostics are logged there too. ## Computable documents — AIMD-C - **Typed values, pure functions, assertions, tables and views** — computed results re-evaluate live as the document is edited. - **Dependency graph** — references (`@id.field`, inline `{{ id.field }}`) form a real graph; wrong types and circular references are reported, never silently ignored. - **Closed-grammar evaluator** (`src/aimdc/evaluator.js`) — no `eval`, no `Function`; an adversarial block can only produce a parse or type error. - **Typeset PDF output** — AIMD-C blocks export to PDF as real typeset content, and inline references resolve there too. - **Evidence ledger** — evaluation returns a dependency-evaluation ledger in addition to results and issues. ## Dynamic Logic - **Claim / evidence / judgment / history blocks** layered on AIMD-C, with a deterministic reducer that tracks each judgment through open → generating → provisionally true/false and reopens it on drift. - **UI-local replay** (`←` / `→` / `Live`) that never rewrites Markdown or touches disk, namespaced per document. - **Event-driven rendering** — autoplay advances one real evidence step per tick, motion fires only on an actual value change, `prefers-reduced-motion` is respected. - **`externalRefs` bridge** — lets AIMD-C `{{ }}` and `aimd-view` syntax read a judgment's values; local ids always win. ## Live preview, math and visuals - **`marked` + KaTeX + `:::` callouts**, sanitized with DOMPurify's default configuration (script / iframe / event-handler attributes stripped). - **Layered math rendering** — KaTeX first, a lazy MathJax retry on failure, Safe Rewrite for recognized syntax aliases, and a diagnostics panel for what still fails. - **Visual IR** — `chart` (bar / line / pie) and `plot` blocks rendered as hand-built SVG in the preview. ## PDF export (Typst) - **Client-side Typst compilation** via a bundled WebAssembly compiler — nothing is uploaded. - **Named themes and layout profiles** selected by frontmatter (`typst_theme`, `typst_layout`). - **Traditional Chinese support** through bundled fonts. ## MCP server - **stdio server** (`mcp-server.js`) and **loopback HTTP server** (`mcp-server-remote.js`, bearer token mandatory) exposing the same eleven tools: `list_files`, `read_file`, `write_file`, `evaluate_aimdc`, `validate_world_ir`, `get_publication_capabilities`, `inspect_document`, `validate_document`, `render_document`, `get_render_artifact`, `get_render_report`. - **Explicit workspace root** — required at startup, never inferred from the current directory; every path is confined to it. - **Non-mutating publication runtime** — `render_document` renders a temporary, expiring PDF artifact (30-minute lifetime, size-capped) without touching the source or workspace, and reports source/artifact SHA-256 hashes. ## Capability sandbox foundation - **`document-only` profile** — AIMD-C computation receives only `document.read.self`, `document.compute` and `ephemeral.output`; no filesystem, network, process, environment or credential authority. - **Deny by default, fail closed** — unknown capabilities and profiles are refused; grants require an exact capability and an exact or single trailing-`*` resource; read does not imply write; `once` grants are consumed. - **Actor-aware audit evidence** — every allow/deny decision records who asked (human principal, client, agent, document, session), the request, the decision and the reason. - **Honest scope** — a control-plane foundation, not an OS/process sandbox, and not yet a user-facing grant flow. ## World IR and World Studio (opt-in) - **Visual views for `kind: state_machine | entity | entity_list` YAML** with an inline validator; the file stays plain YAML. - **Studio AI draft panel** — bounded drafts, validated locally with hard limits; applying changes only the editor buffer until an explicit save. - **Off by default** — Settings → Enable World Studio. ## Encoding-aware save - **Detection** — `jschardet` detects a file's encoding on open. - **Preservation** — `iconv-lite` preserves the detected encoding on save (Big5 / GBK / Shift-JIS / and others). - **Per-file status-bar menu** — for bridge-opened files, lets the user re-read or convert the file's encoding. - **Settings → Default encoding** — the fallback used when detection is uncertain, and the encoding applied to newly created files. ## Localhost-gated bridge - **`vite-agent-bridge.js`** — a Vite plugin declared `apply: 'serve'`, exposing `/api/*` for filesystem I/O, encoding detection, git diff-review, and agent spawning. Vite mounts it under `npm run dev`; the Windows desktop app mounts the same code on a loopback-only server. It is never part of a production web build and is never publicly hosted. - **`isLocalRequest` gate** — every `/api` request is rejected with 403 unless its `Host` is `localhost` / `127.0.0.1` / `::1` and, if present, its `Origin` hostname is also local — blocking CSRF and DNS-rebinding from a malicious web page. The gate is header-based and is not a substitute for network isolation (do not start the dev server with `--host` on an untrusted network). - **Desktop token** — in the desktop app every `/api` request must also carry a random per-launch token (`X-EveGlyph-Desktop`) that only the app's own window adds, closing the gap that the header-based gate accepts any `localhost` origin. - **`resolveInside`** — confines file-read/write target paths to the workspace root; any path that would escape it is rejected. - **`confirmedWorkspace` + `assertWorkspace`** — every workspace-scoped operation (file I/O, the four `/api/git/*` endpoints, and `/api/agent`) is pinned to the single folder the bridge recorded when the user opened it; a request whose working directory isn't that folder or a descendant is rejected before any operation runs. - **Stdin-delivered prompts** — the agent prompt is passed to the spawned CLI over stdin, never as command-line arguments, so prompt text is never interpreted as shell syntax. - **Hard 180-second timeout** — the spawned agent process is killed on timeout, on Stop, or on connection close. ## Windows desktop app - **Electron shell over the same bridge** — `desktop/host.mjs` mounts the bridge and the built frontend on `127.0.0.1`; `desktop/main.mjs` opens the window (`contextIsolation` and `sandbox` on, no Node integration, other sites open in the default browser, only clipboard-write, fullscreen and file-system-access permissions granted). - **Per-user installer and zip, unsigned** — built by `desktop/build.mjs`, which stages only the files and npm packages the Node side imports; published with SHA-256 checksums on GitHub Releases. - **Self-tested** — the build runs the packaged app in a self-test mode (token gate, page render, workspace open, optional MCP child) and an installer test (silent install, self-test of the installed app, uninstall). - **Optional MCP child** — started from the Electron binary with `ELECTRON_RUN_AS_NODE=1`. ## Local-first data handling - **No telemetry** — the diagnostic stream is a local JSONL file only. - **Files stay local** — only content a user sends to a cloud AI provider they configured leaves the machine.