Onboarding: wanglin2/mind-map

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

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/wanglin2/mind-map 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.

Verdict

WAIT — Single-maintainer risk — review before adopting

• Last commit today
• 3 active contributors
• MIT licensed
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

Verify before trusting

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

What it runs against: a local clone of wanglin2/mind-map — 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 wanglin2/mind-map | 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 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>wanglin2/mind-map</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wanglin2/mind-map. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wanglin2/mind-map.git
#   cd mind-map
#
# 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 wanglin2/mind-map and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wanglin2/mind-map(\\.git)?\\b" \\
  && ok "origin remote is wanglin2/mind-map" \\
  || miss "origin remote is not wanglin2/mind-map (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"

# 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/wanglin2/mind-map"
  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).

</details>

TL;DR

SimpleMindMap is a framework-agnostic JavaScript library + Vue2/ElementUI web application for building and visualizing mind maps in the browser using SVG via @svgdotjs/svg.js. It solves the problem of creating feature-rich mind mapping tools without vendor lock-in—the core library has zero framework dependencies, while the included web client demonstrates deployment as a progressive PWA-like application. The library supports multiple diagram types (mindmap, logic charts, timelines, fishbone), rich node content (images, formulas, tags, links), and multi-format import/export (XMind, FreeMind, Markdown, PDF, PNG). Dual-architecture: (1) npm package at root with src/ containing the core library organized by plugins (see dependencies on Yjs, SVG.js), compiled to dist/simpleMindMap.umd.min.js; (2) Vue2 web application in top-level directories using ElementUI, served from dist/ with assets/ containing client UI screenshots and embedding examples. The library uses an event-driven plugin system (EventEmitter3) for extensibility, with state managed via Yjs for CRDT-based collaboration.

Who it's for

Frontend developers building mind mapping features into web applications (who want a lightweight, framework-agnostic library), and end users running the bundled Vue2 web application or Electron-based desktop client. Secondary users: Obsidian and uTools plugin developers extending the ecosystem, and teams needing self-hosted collaborative diagramming without SaaS dependencies.

Maturity & risk

Low maintenance—the library is functional and feature-complete but explicitly noted as 'low maintenance status' in the README. The project has significant GitHub stars (visible from badges in README) and is 3+ years old. The desktop client and plugins are actively developed in closed-source form, but the open-source web library receives only critical fixes. Production-ready for embedding but not actively enhanced.

Moderate risk: single maintainer (街角小林), 11 production dependencies including Yjs+y-webrtc (CRDT complexity), pdf-lib, and KaTeX which expand the attack surface. The 'low maintenance' status means bug fixes may be slow; community pull requests are the primary contribution path. Breaking changes are possible in minor versions given the pre-1.0 versioning (currently 0.14.0-fix.2). No visible CI/CD pipeline in file list (no .github/workflows/).

Active areas of work

The closed-source desktop client is actively developed (latest releases on GitHub and Microsoft Store). The open-source web library is in maintenance mode with occasional bug fixes (version 0.14.0-fix.2 suggests recent patches). No visible active PR/issue work in the provided data; focus has shifted to the proprietary client distribution across Windows, Mac, Linux, and Obsidian/uTools integrations.

Get running

git clone https://github.com/wanglin2/mind-map.git
cd mind-map
npm install
npm run wsServe        # Start WebSocket server for collaboration features
npm run lint           # Verify code style
npm run types          # Generate TypeScript definitions

Then open dist/index.html in a browser (requires a build step first; check for build script in package.json not shown here).

Daily commands:

npm install
npm run wsServe          # WebSocket server on default port (for collaboration)
# Then in another terminal or open dist/ in browser
# No explicit 'npm start' in package.json; likely requires building dist/ first
npm run format           # Code formatting via Prettier

The web app is served from dist/ folder; check for build scripts in the full package.json.

Map of the codebase

• index.js: The entry point for the npm package; exports the SimpleMindMap library interface
• types/index.d.ts: TypeScript definitions generated by npm run types; documents the public API for IDE autocompletion
• package.json: Defines all 11 production dependencies (Yjs, SVG.js, pdf-lib, KaTeX, etc.) and build scripts; the source of truth for environment setup
• dist/simpleMindMap.umd.min.js: The compiled UMD bundle for npm distribution and browser <script> inclusion; generated from src/ via build process
• dist/index.html: The entry point for the bundled Vue2 web application; demonstrates the library in action
• .eslintrc: Linting configuration (if present) ensures code quality for contributions
• bin/createPluginsTypeFiles.js: Helper script run during npm run types to generate plugin-specific TypeScript definitions
• bin/wsServer.mjs: WebSocket server implementation for real-time CRDT synchronization via Yjs

How to make changes

For library changes: src/ contains the core library organized by feature (plugins). Modify individual plugin files (e.g., node rendering, export formats), then run npm run types to regenerate TypeScript definitions in types/index.d.ts. For web app UI: Modify Vue components in the root-level directories (exact structure not shown; check for src/ with .vue files). For formats: Edit XML/PDF/PNG export logic in relevant plugin files. Always run npm run lint and npm run format before committing.

Traps & gotchas

Plugin registration: The library uses a plugin event system (EventEmitter3); new diagram types or export formats require both plugin code and event registration, not documented in provided files. CRDT complexity: Yjs state sync can conflict with local Vue2 reactivity if not properly isolated; the wsServer.mjs implies a separate Node.js process must run for multi-user editing, which may not be obvious from the web-only distribution. Build artifact confusion: dist/ contains pre-built artifacts; modifying src/ requires a build step (likely webpack/rollup) not shown in package.json scripts. Element UI version lock: The project is frozen on ElementUI (Vue 2 only) and cannot upgrade to Vue 3 without a complete rewrite.

Concepts to learn

• CRDT (Conflict-free Replicated Data Type) — SimpleMindMap uses Yjs (a CRDT library) for real-time multi-user collaboration; understanding CRDTs is critical to extending collaborative features without race conditions
• SVG Vector Graphics & SVG.js Library — The entire mind map visualization is rendered as SVG via @svgdotjs/svg.js, not Canvas or DOM; all visual customization and performance optimization depends on SVG concepts
• Plugin Event System & EventEmitter Pattern — SimpleMindMap extends functionality through an event-driven plugin architecture (EventEmitter3); adding exporters, diagram types, or tools requires understanding the event subscription model
• Multi-Format Serialization (XMind, FreeMind, Markdown) — The library must parse and emit multiple diagram formats; understanding the AST (Abstract Syntax Tree) transformation pipeline between formats is essential for fixing import/export bugs
• WebSocket Real-Time Sync via y-webrtc — The wsServer.mjs process syncs Yjs state across browsers using WebRTC; understanding signaling, peer discovery, and fallback transports is needed for debugging collaboration issues
• UMD (Universal Module Definition) Bundle Format — SimpleMindMap is distributed as both npm module and a UMD bundle (dist/simpleMindMap.umd.min.js) for browser <script> inclusion; understanding how the build process creates both is necessary for publishing changes
• Vue 2 Reactivity & ElementUI Component Library — The bundled web application is Vue 2 + ElementUI; the library itself is framework-agnostic, but the demo app uses Vue2's reactivity system to bind mind map state to UI controls

Related repos

• mermaid-js/mermaid — Alternative Markdown-based diagram rendering (supports mindmap syntax); SimpleMindMap is more interactive but Mermaid integrates better into documentation pipelines
• fengari-lua/fengari — Not directly related, but SimpleMindMap's CRDT-based collaboration via Yjs is similar in spirit to Fengari's event-driven architecture
• yjs/yjs — SimpleMindMap depends on Yjs for CRDT state; understanding Yjs's Y.Map and Y.Array is essential for extending collaborative features
• svgdotjs/svg.js — SimpleMindMap's entire rendering engine is built on SVG.js; contributing to diagram visual features requires understanding this library's API

PR ideas

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 core SVG rendering and node manipulation in src/

The repo has eslint and prettier configured but no visible test suite. Given this is a mind-map library built on @svgdotjs/svg.js with complex node manipulation, rendering, and layout logic, adding Jest or Vitest tests for core modules would catch regressions early and improve contributor confidence. The package.json has no 'test' script despite having devDependencies configured.

• [ ] Add Jest or Vitest config to package.json with test script
• [ ] Create test files for src/modules/Node.ts and src/modules/Render.ts (core rendering logic)
• [ ] Add tests for src/utils/ utility functions used across the library
• [ ] Document test patterns in CONTRIBUTING.md or similar

Add GitHub Actions workflow for automated type checking and linting on PR

The repo has a 'types' script and eslint/prettier configured but no CI pipeline visible. With TypeScript definitions exported (types/index.d.ts) and a growing npm package (0.14.0), automated type validation and linting on pull requests would catch quality issues before merge and reduce maintainer burden.

• [ ] Create .github/workflows/lint-and-types.yml
• [ ] Run 'npm run lint' and 'npm run types' on PR with node 16+ versions
• [ ] Add status check requirement in branch protection settings
• [ ] Document CI expectations in CONTRIBUTING.md

Create API documentation pages for undocumented plugins and modules

The package.json lists multiple complex dependencies (yjs, y-webrtc, pdf-lib, quill, katex) suggesting rich plugin ecosystem, but the README only references external docs at https://wanglin2.github.io/mind-map-docs/. The src/ directory likely contains plugin implementations (export feature, collaboration, rich text) with no inline JSDoc or local docs. Adding TSDoc comments and a docs/PLUGINS.md file would improve discoverability for contributors.

• [ ] Audit src/ for plugin directories (e.g., export, collaboration, rich-text) and missing JSDoc
• [ ] Add TSDoc comments to main plugin entry points with @param, @returns, @example tags
• [ ] Create docs/PLUGINS.md documenting each plugin API with usage examples
• [ ] Link PLUGINS.md from README.md and README_EN.md

Good first issues

• Add TypeScript definitions for the plugin system: the types/index.d.ts file is generated but the plugin architecture (EventEmitter3 event names, hook signatures) lacks inline JSDoc. Document the exact event names and payloads for common hooks like nodeClick, nodeCreate, export:start.
• Write unit tests for export adapters: there are no .test.js or .spec.js files visible in the file list. Start with the XML export logic for FreeMind/XMind format; add tests in src/__tests__/exporters/xml.spec.js covering node hierarchy serialization and attribute preservation.
• Create example integrations directory: add examples/react-integration/ and examples/vanilla-js/ showing how to instantiate SimpleMindMap in non-Vue contexts, similar to how the web app uses it. This would reduce questions in issues about embedding the library.

Top contributors

• @wanglin2 — 98 commits
• @cuikaipeng — 1 commits
• @googlesky — 1 commits

Recent commits

• 645febb — 'update' (wanglin2)
• fc4f93a — update (wanglin2)
• eb776d1 — update (wanglin2)
• 7b288a3 — update (wanglin2)
• 1c5a243 — update readme (wanglin2)
• 3541b7d — update (wanglin2)
• 9eab537 — Merge pull request #1254 from cuikaipeng/readme (wanglin2)
• 31d71db — Merge branch 'main' into readme (wanglin2)
• cfe07aa — update (wanglin2)
• b8ac079 — update (wanglin2)

Security observations

• High · Outdated Dependencies with Known Vulnerabilities — package.json - dependencies section. The project uses several outdated dependencies that likely contain known security vulnerabilities. Notable examples: @svgdotjs/svg.js 3.2.0 (released 2021), quill 2.0.3, tern 0.24.3, and ws 7.5.9. These versions are significantly behind current releases and may contain unpatched CVEs. Fix: Update all dependencies to their latest stable versions. Run 'npm audit' to identify specific vulnerabilities. Implement automated dependency scanning in CI/CD pipeline using tools like Snyk or OWASP Dependency-Check.
• High · WebSocket (ws) Library with Potential Security Issues — package.json - ws dependency, wsServe script in bin/wsServer.mjs. The project uses ws 7.5.9, a WebSocket library that has had multiple security vulnerabilities in older versions. Combined with y-webrtc for collaborative features, this could expose data in transit to attacks. Fix: Upgrade ws to version 8.x or later. Implement TLS/WSS (WebSocket Secure) for all WebSocket connections. Add authentication and authorization checks for WebSocket connections.
• Medium · Missing Security Headers in Nginx Configuration — Dockerfile and /etc/nginx/nginx.conf. The Dockerfile references an nginx.conf but the configuration file is not provided in the repository listing. Without visibility, it's unclear if security headers (X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, etc.) are properly configured. Fix: Ensure nginx.conf includes security headers: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: appropriate policy, Strict-Transport-Security: max-age=31536000. Implement rate limiting and disable server token exposure.
• Medium · Potential XSS Vulnerabilities in SVG Handling — Dependencies: @svgdotjs/svg.js, dist/img/ SVG files. The project heavily uses @svgdotjs/svg.js for SVG manipulation (based on dist/img content and architecture). SVG files can contain malicious scripts. There's no evidence of sanitization in the file structure provided. Fix: Implement input validation and sanitization for all SVG content using libraries like DOMPurify. Apply Content Security Policy (CSP) headers to prevent inline script execution. Validate SVG sources and avoid loading SVGs from untrusted sources.
• Medium · Exposed Nginx Container Without Resource Limits — Dockerfile. The Dockerfile uses a plain nginx image without specifying version tag, security scan, or resource constraints. No USER directive specified, so container may run as root. Fix: Specify explicit nginx version (e.g., 'FROM nginx:1.25-alpine'). Use Alpine Linux base image for smaller attack surface. Add 'USER nginx' directive to avoid running as root. Implement health checks and resource limits (memory, CPU). Use multi-stage builds if applicable.
• Medium · Missing CORS Configuration Documentation — nginx.conf (not provided), WebSocket server configuration. With WebSocket and client-server architecture, CORS configuration is critical but not visible in provided files. This could enable unauthorized cross-origin requests. Fix: Implement strict CORS policies in nginx and WebSocket server. Only allow requests from trusted origins. Set appropriate headers: Access-Control-Allow-Origin, Access-Control-Allow-Methods, Access-Control-Allow-Credentials.
• Low · No Security Policy or Vulnerability Disclosure Process — Repository root. The repository does not show evidence of SECURITY.md or vulnerability disclosure policy, making it difficult for security researchers to report issues responsibly. Fix: Create a SECURITY.md file documenting vulnerability reporting process and responsible disclosure guidelines. Consider implementing a bug bounty program. Add security.txt file at /.well-known/security.txt
• Low · Weak Version Specification Pattern — package.json - dependencies with ^ specifier (deepmerge, eventemitter3, jszip,. Some dependencies use caret (^) version specifiers which allow breaking changes. For security-sensitive libraries, this could introduce vulnerabilities in minor updates. Fix: undefined

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

Where to read next

• 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.