If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/MarkEdit-app/MarkEdit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit today
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 92% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live MarkEdit-app/MarkEdit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/MarkEdit-app/MarkEdit.

What it runs against: a local clone of MarkEdit-app/MarkEdit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in MarkEdit-app/MarkEdit | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of MarkEdit-app/MarkEdit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/MarkEdit-app/MarkEdit.git
#   cd MarkEdit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of MarkEdit-app/MarkEdit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "MarkEdit-app/MarkEdit(\\.git)?\\b" \\
  && ok "origin remote is MarkEdit-app/MarkEdit" \\
  || miss "origin remote is not MarkEdit-app/MarkEdit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "CoreEditor/src/core.ts" \\
  && ok "CoreEditor/src/core.ts" \\
  || miss "missing critical file: CoreEditor/src/core.ts"
test -f "CoreEditor/src/bridge/nativeModule.ts" \\
  && ok "CoreEditor/src/bridge/nativeModule.ts" \\
  || miss "missing critical file: CoreEditor/src/bridge/nativeModule.ts"
test -f "CoreEditor/src/bridge/webModule.ts" \\
  && ok "CoreEditor/src/bridge/webModule.ts" \\
  || miss "missing critical file: CoreEditor/src/bridge/webModule.ts"
test -f "CoreEditor/src/modules/commands/index.ts" \\
  && ok "CoreEditor/src/modules/commands/index.ts" \\
  || miss "missing critical file: CoreEditor/src/modules/commands/index.ts"
test -f "CoreEditor/package.json" \\
  && ok "CoreEditor/package.json" \\
  || miss "missing critical file: CoreEditor/package.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/MarkEdit-app/MarkEdit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

MarkEdit is a native macOS Markdown editor built in Swift (~640K lines) with a web-based editor core in TypeScript (~388K lines) powered by CodeMirror 6. It solves the problem of editing large Markdown files (10 MB+) with full GFM compliance, native macOS integration, and exceptional performance in a 4 MB app footprint—no Electron bloat, no regex-based parsing correctness issues. Hybrid monorepo structure: the main Swift app (Xcode project root) wraps a self-contained TypeScript/Node editor engine in ./CoreEditor/, which builds to HTML/JS/CSS bundles embedded in the macOS app. CoreEditor uses Vite for dev/build, Jest for tests, and a custom @codegen system (ts-gyb) to generate Swift bridge types from TypeScript definitions. The ./src/@vendor/ directory vendorizes dependencies like CodeMirror language definitions and Joplin's Markdown math parser.

macOS users and developers who write Markdown extensively and need a lightweight, privacy-focused editor with native feel; technical writers, developers, and note-takers who work with large documents and want single-app simplicity without subscription licensing or data collection.

Production-ready and actively developed. The project has reached v1.0.0 maturity with comprehensive CI/CD via GitHub Actions (.github/workflows/build-and-test.yml), SwiftLint configuration for code quality, and a clear philosophy around correctness and performance. The architecture shows thoughtful separation between native Swift UI and a TypeScript/CodeMirror editing engine, suggesting stable design decisions.

Low risk from dependency perspective—the web-based CoreEditor uses well-maintained CodeMirror 6 packages and Lezer parser libraries. However, it is primarily maintained by a small team (single-organization), so contributor velocity depends on libremac.github.io maintainers. The macOS 15.0+ requirement (Sonoma/Sequoia) limits backward compatibility, which could be a concern for enterprise adoption.

Actively maintained with recent CI/CD refinements and extension ecosystem maturation. The repo shows focus on the MarkEdit-api ecosystem (referenced in package.json as v0.22.0), enabling third-party extensions like MarkEdit-preview, MarkEdit-theming, and MarkEdit-ai-writer (Apple Intelligence integration). The @codegen system suggests ongoing tooling to keep Swift/TypeScript type contracts in sync.

# Clone the repo
git clone https://github.com/MarkEdit-app/MarkEdit.git
cd MarkEdit

# Install web editor dependencies (uses Yarn 4.14.1)
cd CoreEditor
yarn install

# Return to root and open Xcode project
cd ..
open MarkEdit.xcworkspace

# Or run the web editor in dev mode
cd CoreEditor && yarn dev

Daily commands:

cd CoreEditor
yarn dev          # Starts Vite dev server on localhost (live reload)

# Or for building:
yarn build        # Runs: lint → codegen → vite build (main + light variant)
yarn lint         # Runs ESLint
yarn test         # Runs Jest
yarn codegen      # Runs ts-gyb to generate Swift types

• CoreEditor/src/core.ts — Main editor initialization and orchestration; entry point for CodeMirror integration and module setup
• CoreEditor/src/bridge/nativeModule.ts — Bridge layer connecting native Swift code to JavaScript; critical for macOS integration and IPC
• CoreEditor/src/bridge/webModule.ts — Web-based module bridge; handles communication between web-based editor and native layers
• CoreEditor/src/modules/commands/index.ts — Command execution system; handles all Markdown editing commands and text transformations
• CoreEditor/package.json — Build pipeline and dependency management; defines CodeMirror, Vite, and testing infrastructure
• CoreEditor/index.ts — Web entry point; initializes the editor instance and exposes public API to native code
• CoreEditor/src/modules/config/index.ts — Configuration management; centralizes editor settings and preferences

Add a new Markdown formatting command

1. Create a new command file in the commands module, extending the base command interface (CoreEditor/src/modules/commands/myNewCommand.ts)
2. Export and register the command in the commands index (CoreEditor/src/modules/commands/index.ts)
3. Implement the command handler to manipulate text selections using CodeMirror transactions (CoreEditor/src/modules/commands/myNewCommand.ts)
4. Wire the command to the bridge API so native code can invoke it (CoreEditor/src/bridge/native/api.ts)

Add a new editor feature module

1. Create a new subdirectory under CoreEditor/src/modules/ with an index.ts file (CoreEditor/src/modules/myFeature/index.ts)
2. Implement the feature logic, hooking into editor events and state (CoreEditor/src/modules/myFeature/index.ts)
3. Register the module in core.ts to initialize on editor startup (CoreEditor/src/core.ts)
4. Expose feature methods via the public API if needed (CoreEditor/src/api/editor.ts)

Extend the native bridge with a new capability

1. Define the new method signature in the native bridge API definitions (CoreEditor/src/bridge/native/api.ts)
2. Implement the handler in the appropriate native module (e.g., core.ts, preview.ts) (CoreEditor/src/bridge/native/core.ts)
3. Create a web fallback/stub in the corresponding web bridge module (CoreEditor/src/bridge/web/core.ts)
4. Call the new method from editor code via the webModule or nativeModule bridge layer (CoreEditor/src/bridge/webModule.ts)

• CodeMirror 6 — Modern, composable text editor with excellent Markdown support, fine-grained reactivity, and minimal footprint
• TypeScript + Vite — Type safety and rapid iteration during development; Vite provides fast hot-reload and small production bundles
• Native bridge (nativeModule.ts) — Enables seamless macOS integration while keeping editor logic portable; allows asset access and platform-specific features
• Lezer + @codemirror/language — Robust incremental parsing for Markdown with minimal memory overhead, enabling fast syntax highlighting even in large files
• Jest + ESLint — Standard testing and linting; ensures code quality and correctness of Markdown transformations

• Web-based editor (HTML/TS) instead of native Cocoa UI

  • Why: Easier to maintain, cross-platform testable, faster iteration, mature ecosystem
  • Consequence: Introduces a JavaScript runtime in a native app; slight latency on input, but negligible for typical typing speeds

• CodeMirror over custom editor implementation

  • Why: Battle-tested, active ecosystem, built-in plugins for search, history, language modes
  • Consequence: Binary size ~1–2 MB; less fine-grained control over rendering, but acceptable trade-off for 4 MB total app size

• Synchronous bridge calls instead of async IPC

  • Why: Simpler API surface, lower latency for frequent operations (e.g., syntax checking, file I/O)
  • Consequence: Native code must complete operations quickly; blocking on I/O could freeze UI if not careful

• Multi-module architecture (commands, completion, config, events) vs. monolithic editor

  • Why: Better separation of concerns, testability, and feature independence
  • Consequence: Slight complexity in dependency injection and initialization order (managed in core.ts)

• Cloud sync or collaboration (local-only editing)
• Plugin system for third-party extensions
• Real-time preview rendering (separate preview service)
• Linux or Windows support (macOS-only as stated in README)

1. Code generation cycle: Running yarn build automatically runs yarn codegen; if you modify TypeScript types in CoreEditor/src/@types/ or CoreEditor/src/@codegen/config.json, the corresponding Swift files must be regenerated and committed. Mismatch causes runtime crashes at the native–web boundary. 2. Two build targets: yarn build produces both main and light (simplified) editor variants via separate Vite configs; the light variant uses src/@light/vite.config.mts and may have different behavior. 3. macOS 15.0+ requirement: Build and runtime target Safari 18+; testing on older macOS versions will fail silently or produce incorrect behavior. 4. Yarn 4 workspace lock: The repo uses Yarn 4.14.1 (not npm); yarn.lock changes must be committed, and node_modules is not used (zero-install via Yarn PnP or similar).

• Incremental Parsing (Lezer) — MarkEdit uses Lezer's incremental parser to re-parse only changed regions of the document; this is the key to handling 10 MB files without UI lag, unlike regex-based editors that re-scan the whole file on every keystroke.
• GitHub Flavored Markdown (GFM) Spec Compliance — MarkEdit's core design decision is strict GFM compliance (not custom syntax); understanding the spec at https://github.github.com/gfm/ is essential for feature requests, parser bugs, and maintaining correctness.
• Native–Web Bridge (WKWebKit / JSON-RPC) — The architecture passes messages between Swift native code and a TypeScript/JavaScript editor engine embedded in a WebView; understanding message serialization, error handling, and the type contract is critical for debugging cross-layer issues.
• Code Generation (ts-gyb + Mustache) — MarkEdit uses ts-gyb to auto-generate Swift types from TypeScript definitions; this keeps the native bridge type-safe without manual duplication, reducing sync bugs between layers.
• WebAssembly / Syntax Highlighting Caching — CodeMirror 6 + Lezer use highlight tokens cached at parse tree nodes; understanding tokenization (not detailed in repo but fundamental to CM6) helps optimize custom syntax rules or theme debugging.
• macOS Privacy & Sandbox Constraints — The app is privacy-focused and runs on modern macOS (15.0+); understanding sandbox restrictions, file access entitlements, and macOS Sequoia APIs (like Writing Tools integration mentioned in README) is essential for native feature work.
• Vite Build Bundling & Single-File Output — CoreEditor uses Vite + vite-plugin-singlefile to bundle the entire editor (HTML/JS/CSS) into a single file for embedding in the native app; understanding this build step is critical for debugging asset loading or bundle size issues.

• github/cmark-gfm — Reference implementation of GitHub Flavored Markdown spec that MarkEdit strictly follows; understanding this parser ensures GFM compliance in edge cases.
• codemirror/codemirror5 — Predecessor to CodeMirror 6 (which MarkEdit uses); helpful for understanding architectural decisions and migration path if version bumps occur.
• MarkEdit-app/MarkEdit-preview — Official companion extension providing Markdown preview pane; shows the extension API pattern and how third parties hook into MarkEdit's editor.
• MarkEdit-app/MarkEdit-theming — Official theming extension demonstrating CSS/JavaScript customization surface; reference for users wanting custom syntax highlighting or UI themes.
• MarkEdit-app/MarkEdit-api — Published npm package (v0.22.0) defining the public extension API; essential reading for understanding what capabilities are exposed to third-party developers.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for CoreEditor bridge modules (native.ts, web.ts)

The CoreEditor/src/bridge directory contains critical native-to-web communication code (native/api.ts, native/core.ts, web/api.ts) but there are no corresponding .test.ts or .spec.ts files visible in the repo. Given the complexity of bidirectional bridge communication and the presence of jest.config.js, adding comprehensive tests would prevent regressions in the native/web boundary—a high-risk area.

• [ ] Create CoreEditor/src/bridge/native/tests/api.test.ts covering message passing and API method invocation
• [ ] Create CoreEditor/src/bridge/web/tests/api.test.ts covering web-side message handling
• [ ] Add tests for CoreEditor/src/bridge/native/tokenizer.ts since it handles language model integration
• [ ] Run 'yarn test' and verify all tests pass in CI workflow

Add GitHub Actions workflow for CodeMirror/Lezer dependency security audits

The project heavily depends on CodeMirror 6 packages (@codemirror/, @lezer/) for core editing functionality, but .github/workflows only shows build-and-test.yml. A dedicated workflow to audit these dependencies for vulnerabilities and check for outdated versions would catch security issues early, especially important for a code editor handling user files.

• [ ] Create .github/workflows/dependency-audit.yml with 'yarn audit' and 'yarn outdated' checks
• [ ] Add npm/yarn vulnerability scanning (e.g., using npm audit or Snyk) for @codemirror and @lezer packages
• [ ] Configure the workflow to run on push to main and on a weekly schedule
• [ ] Set up alerts to fail the workflow if critical vulnerabilities are found

Add integration tests for CoreEditor API modules (editor.ts, files.ts, languageModel.ts)

CoreEditor/src/api contains multiple API surface modules (editor.ts, files.ts, pasteboard.ts, languageModel.ts, translation.ts, ui.ts) but no visible integration tests. These modules are the public contract between the native app and the web editor, making them critical for stability. Current test coverage appears minimal based on the file structure.

• [ ] Create CoreEditor/src/api/tests/editor.test.ts covering editor initialization, content manipulation, and selection
• [ ] Create CoreEditor/src/api/tests/files.test.ts covering file read/write operations across the native bridge
• [ ] Create CoreEditor/src/api/tests/languageModel.test.ts to verify LLM integration flow
• [ ] Add mock implementations for native bridge calls in jest.setup.js or use jest.mock() patterns

• Add Jest unit tests for CoreEditor/src/@vendor/joplin/markdownMathParser.ts—this vendorized math parser currently has no test coverage visible in the repo; writing tests would improve reliability for LaTeX/MathML rendering in Markdown.: Medium: Prevents math rendering regressions and documents expected parsing behavior.
• Document the code generation workflow: create a CoreEditor/src/@codegen/README.md explaining how to add a new TypeScript type and have it auto-generate Swift equivalents. Currently only a generic README exists; contributors are left guessing at the ts-gyb + Mustache template flow.: Easy: Onboarding friction for native extension developers; documentation pays dividends for the extension ecosystem.
• Expand ESLint configuration in CoreEditor/eslint.config.mjs to enforce stricter typing rules (e.g., no implicit any, require explicit return types) in the editor core. Current config exists but appears minimal; stricter linting would catch type-safety bugs before they reach native bridge.: Easy–Medium: Improves code correctness at the Swift–TypeScript boundary where bugs are hardest to debug.

• High · Direct GitHub Dependency Reference Without Version Pinning — package.json - devDependencies.markedit-api. The markedit-api package is installed directly from a GitHub repository with a version tag (v0.22.0) in devDependencies. While the version is pinned, this dependency mechanism bypasses npm registry security checks and makes the package vulnerable to repository compromise. If the GitHub account or repository is compromised, malicious code could be injected into the build. Fix: 1) If possible, publish markedit-api to npm registry and use standard npm dependency syntax. 2) Implement GitHub branch protection rules, require code reviews, and enable signed commits on the MarkEdit-api repository. 3) Consider using git commit hash pinning instead of version tags for additional verification. 4) Monitor the dependency repository for suspicious activity.
• Medium · Overly Permissive Browserslist Configuration — package.json - browserslist. The browserslist is configured to support 'safari >= 18', which includes development and edge versions. While Safari 18 is relatively recent, supporting very new browser versions may expose users to unpatched security vulnerabilities in the browser itself. The application handles markdown editing which could involve sensitive content. Fix: Consider a more conservative browserslist targeting stable, widely-adopted Safari versions (e.g., 'safari >= 17.4'). Document the minimum supported version requirements and update documentation accordingly.
• Medium · Missing Content Security Policy Configuration — CoreEditor/index.html and general configuration. No Content Security Policy (CSP) headers are visible in the codebase. The application is a markdown editor with native bridge functionality and file handling capabilities. Without CSP, the application is more vulnerable to XSS attacks, especially given the nature of markdown parsing and potential user-supplied content rendering. Fix: Implement a strict Content Security Policy. Define directives for: script-src (restrict inline scripts), style-src (restrict inline styles), img-src, font-src, connect-src. Consider using nonces for inline scripts if necessary. Test the policy thoroughly to ensure it doesn't break functionality.
• Medium · Potential XSS Risk in Markdown Parsing Pipeline — CoreEditor/src/@vendor/lang-markdown/, CoreEditor/src/api/. The codebase includes markdown parsing functionality (@vendor/lang-markdown, @vendor/joplin/markdownMathParser.ts) and custom markdown implementation. Markdown can be a vector for XSS if user-supplied markdown content is rendered with inadequate sanitization. The bridge to native code suggests untrusted content may be processed. Fix: 1) Ensure all markdown output is properly sanitized before rendering. 2) Use a well-maintained HTML sanitization library (e.g., DOMPurify) to strip malicious HTML/scripts from rendered markdown. 3) Implement strict output encoding. 4) Add security-focused unit tests for markdown parsing with XSS payloads. 5) Use Content Security Policy to provide defense-in-depth.
• Medium · Yarn Lock File Integrity Not Explicitly Verified — .github/workflows/build-and-test.yml and build configuration. While the project uses Yarn with a lock file (yarn@4.14.1), the build configuration doesn't show explicit verification of lock file integrity. This could allow dependency confusion or MITM attacks during CI/CD if not properly configured. Fix: 1) In CI/CD workflows, use 'yarn --immutable' or 'yarn --immutable-cache' to ensure lock file integrity. 2) Verify the yarn version and lock file hash before running builds. 3) Consider using npm audit or yarn audit in the CI pipeline to detect known vulnerabilities. 4) Pin the yarn version in .yarnrc.yml and document security expectations.
• Low · Missing Subresource Integrity (SRI) Checks — CoreEditor/src/@res/ and CoreEditor/index.html. The codebase includes font files (SF-Mono-Bold.woff2, SF-Mono-Regular.woff2) and the index.html references external resources, but no visible SRI (Subresource Integrity) attributes are documented. This could allow MITM attacks on font files or external resources. Fix: 1) Add SRI hashes to all external resource references in HTML files. 2) Generate SRI hashes for font files served locally. 3) Document the SRI generation process in the build pipeline. 4) Test that resources with incorrect hashes are properly rejected

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.