Build MindNode

0%0 of 16 items done

Saved on this device only. Tick prerequisites first, then work the phases in order · do not start one until the checks above it pass.

A mind mapping tool where the value is thinking speed rather than diagramming: nodes are created and rearranged from the keyboard without pauses, the layout resolves itself without overlaps, and the same structure is editable as an outline when a tree is the wrong view.

estimated effort multi-daythe files for this build are in the project pack

ModelA tree with optional cross-links, kept separateLayoutAutomatic radial or lateral placement with collision resolutionInputKeyboard-first with every action bound, no modal dialogsDualityThe same document editable as a map or an outlineRuntimeA local application with file-based documents

Before step 1

Everything below is assumed from the first step. Tick each one when you actually have it, not when you plan to.

installfree
Why Runs the local application.
Get it nodejs.org, or nvm install 22. open ↗
Verify node --version prints v22 or higher
installfree
Why Collision resolution and subtree balancing are the difference between a usable map at a hundred nodes and an unusable one, and it is a solved problem worth reading rather than inventing.
Get it Read a published tree drawing algorithm and implement it, or use a maintained library.
Verify A hundred node tree lays out without overlaps
have readyfree
Why Layout quality, reflow smoothness and export size are all uninteresting below fifty nodes and become the whole problem above a hundred.
Get it Build one from real thinking rather than generating a balanced tree, since real maps are lopsided.
Verify A hundred node lopsided map exists with several cross-links
decidefree
Why Everything is keyboard bound and retrofitting a scheme after building the interface means rebuilding the interface.
Get it Decide the bindings for creation, navigation, collapsing and view switching before writing phase one.
Verify A written scheme covers every planned action

Data model

Create these before the first phase that stores anything. Changing a table later is the expensive kind of change.

- documents(id, title, layout_kind, theme, updated_at)
- nodes(id, document_id, parent_id, ordinal, text, note, collapsed, style_json, manual_position)
- links(from_node_id, to_node_id, label) · cross-links outside the tree, drawn differently
- layout_cache(document_id, computed_at, positions_json) · derived, discarded when the tree changes
- focus_state(document_id, node_id, at) · so reopening returns you where you were thinking
- attachments(node_id, kind, ref) · images and file references, bounded
- A node records whether its position was set manually, so automatic layout never discards a placement someone made deliberately.

Environment variables

These go in a .env file the app reads at startup. The pack's .env.example is this table as a file · copy it, never commit the filled-in version.

Variable	Needed	Example	Where the value comes from
`DOCUMENTS_DIR`	required	`~/Documents/maps`	Map files. A mind map is a document and should behave like one.
`LAYOUT_KIND`	required	`radial`	Radial or lateral. Both need collision resolution.
`REFLOW_ANIMATION_MS`	required	`180`	Long enough to follow, short enough not to feel slow while typing.
`LAYOUT_BUDGET_MS`	required	`16`	Layout runs while typing. Beyond this it must degrade rather than stutter.
`UNDO_DEPTH`	required	`50`	Fast entry produces mistakes and they should all be cheap.
`MAX_NODES_WARNING`	required	`1000`	Where layout quality starts to degrade, made explicit rather than discovered.

The build, in order

1
Typing a map without pausing
Fifty nodes can be entered in a couple of minutes without a mouse.
1. Sibling, child, parent, move. All single keystrokes.
  Files src/keys.ts
2. A dialog is a pause and a pause costs the thought.
  Files src/editing.ts
3. Fast entry produces mistakes and they must be cheap.
  Files src/undo.ts
done when · tick each as it passes
watch out
- Any modal dialog or mouse reach in the creation loop breaks the rhythm, and a mind map is used precisely when someone is thinking quickly, so a pause costs the idea rather than a second. Bind everything, edit in place, and time a realistic session rather than assuming.
next phase
2
A layout that resolves itself
A hundred nodes arrange without overlapping or crossing badly.
1. Overlapping nodes at a hundred is where people abandon the layout.
  Files src/layout.tssrc/layout.test.ts
2. A canvas jumping while you type is disorienting.
  Files src/reflow.ts
3. A deliberate placement should survive the next node.
  Files src/layout.ts
done when · tick each as it passes
watch out
- Reflowing the whole map on every keystroke makes the canvas jump around while someone is typing, which is disorienting enough that they stop using automatic layout entirely. Animate the reflow, keep the focused node stationary, and move everything else around it.
next phase
3
The same document as an outline
Switching between map and outline edits one structure, not two.
1. Two representations drift and the drift loses a branch.
  Files src/outline.ts
2. A branch collapsed in one view should not reappear in the other.
  Files src/tree.ts
3. They have no natural place in an outline and dropping them loses information.
  Files src/outline.ts
done when · tick each as it passes
watch out
- Implementing the outline as a separate representation that syncs to the map produces two structures that drift, and the drift is discovered when one view is missing a branch. Render both from one tree, so there is nothing to synchronise.
next phase
4
Links that are not the tree
A connection between distant branches exists without breaking the layout.
1. Trying to satisfy them as tree edges produces a tangle.
  Files src/links.ts
2. A reader must be able to tell structure from association.
  Files src/render.ts
3. A stated rule rather than a dangling reference.
  Files src/links.ts
done when · tick each as it passes
watch out
- Treating a cross-link as another parent edge makes the layout algorithm try to satisfy an impossible tree and produces a tangle, which is why many mind mappers refuse cross-links entirely. Keep them out of the layout computation and draw them as an overlay.
5
Getting the thinking outproduct builder
A map becomes text, an image or something another tool can read.
1. The map usually becomes a document. An image cannot.
  Files src/export.ts
2. Export, import, compare. It is the guarantee that matters.
  Files tests/roundtrip.test.ts
3. So it is searchable and readable by assistive tools.
  Files src/export-svg.ts
done when · tick each as it passes
watch out
- Exporting only as an image loses the structure entirely, and a mind map's value is usually that it becomes a document, an outline or a plan afterwards. Export the text structure first and treat the image as secondary.

what this build does not replace

Real-time collaboration.
Presentation and walkthrough modes.
Task management with dates and dependencies.
Automatic map generation from a document.
high-fidelity import and export
presentation and enterprise controls
multiplayer cursors and comments
large template libraries

after v1, if you want it

Focus mode showing one subtree, which is how large maps stay usable
Node styling driven by depth or tag rather than set by hand
Merging two maps, which is harder than it sounds once cross-links exist

Need the files? The project pack on the verdict page hands your agent the whole brief · more diagrams.