Skip to content

Design ​

These pages explain why jsMind V2 is structured the way it is, and how the layers work together. They are not a getting-started guide. For usage, see the Guide.

Related design articles:

  • Layout system — coordinate system, box model, layout pipeline, and spacing
  • Theme system — data-driven themes, tones, the override chain, and shadow merging
  • Hybrid edge system — tree relationships use direct fields; extra relationships use edges

jsMind v2 is organized in six layers, from the bottom up: model → serialization → arranger → view → application → CLI.

1. Layers ​

CLI         jsMind command entry point, argument parsing, exit codes, headless browser wrapper
application JsMind facade, JmMindChangeCoordinator (passive observation), JmCommander (active commands)
view        Rendering: Shadow DOM isolation, nodes / connections / expanders, theme variables, image export
arranger    Pure layout calculation: feed in node sizes → compute coordinates. Zero DOM dependency
serialization JSON/FreeMind read and write, validator (22 error codes)
model       JmMind / JmNode / JmEdge / JmNodeContent / style / theme type system

2. Data flow ​

Agent path (file → command line) ​

JSON file → serialization.deserialize → JmMind
    → CLI command (add-child / set-text / ...) operates on the JmMind API
    → serialization.serialize → JSON file
    → validate → roll back if validation fails

Human interaction path (browser) ​

User action → JmMind API (moveNode / addChildNode / ...)
    → JmMindChangeCoordinator.onNodeMoved / onNodeAdded / ...
    → view.settle (relayout + redraw)

Export path ​

JmCommander.exportImage() → JmViewHandle.capture()
    → captureShadowContent: clone the DOM → SVG foreignObject → canvas → Blob

3. Dual channels ​

The application layer has two channels into the view. The test is whether the operation changes the model:

Caller → JmCommander → JmViewHandle → JmView      (commands: export, pan/zoom)
Model change → JmMindChangeCoordinator → JmView    (reactions: node add / remove / edit)

Operations that change the model must use the second channel. Folding, moving, changing text, changing style — the data is the source of truth, and the view is a projection. Putting model changes through Commander would create a second write path, and that path would diverge from the one agents take through the CLI.

Operations that do not change the model use the first channel. Pan, zoom, and export only change how the map is observed; they do not change any node. JmViewHandle is the narrow interface the view exposes to the application layer (currently only capture(); pan / zoom / centerOn may be added later).

4. Key decisions ​

DecisionReason
Flat table for the on-disk formatClean diffs, O(1) incremental lookup, isomorphic with edges, no deep recursion
Nested tree for LLM interactionOutlines and directory trees are a natural form in LLM training data
SVG + foreignObject for renderingLossless vector scaling, natural Bézier support, typography left to the browser
Shadow DOM enabled unconditionallyStyle isolation is a hard requirement: a self-contained HTML document may be embedded in any page
CSS custom properties for styleGeometry can inherit once from the host; color can be overridden on a single node
Arranger has zero DOM dependencyLayout tests run in Node, with no browser required
Validator is independent of the serializerThe CLI can validate without loading a complete mind
Leave the v1 adapter until lastWait until the schema is frozen; writing a converter against a still-moving model is wasted work

5. File index ​

LayerCore files
modelsrc/model/mind.ts, src/model/data/node.ts, src/model/data/edge.ts, src/model/data/node-content.ts, src/model/data/style.ts
serializationsrc/serialization/json.ts, src/serialization/freemind.ts, src/serialization/serializer.ts, src/serialization/validation.ts, src/serialization/serializer-factory.ts
arrangersrc/arranger/mindmap.ts
viewsrc/view/index.ts, src/view/node.ts, src/view/edge.ts, src/view/shadow.ts, src/view/export.ts, src/view/handle.ts
applicationsrc/application/jsmind.ts, src/application/mind-change-coordinator.ts, src/application/commander.ts
CLIsrc/cli/index.ts, src/cli/io.ts, src/cli/browser.ts, src/cli/commands/*.ts

本文档由 AI 协助生成 / This documentation was prepared with AI assistance