1. Getting Started

Multi-Map is a spatial mapping ecosystem. Instead of folders and files, you organize information into "Constellations" of interconnected nodes. Every map begins with a Universe Root. From there, you can spawn Hubs, Notes, Portals, and structured Web elements.

2. Navigation & Controls

The Radial Menu & Moons

Selecting a node opens its Radial Menu—a circular array of quick actions (Edit, Link, Add, Delete, Collapse).

Non-Destructive Collapse: When you collapse a node (🌚), its children are hidden from the map and replaced by orbiting "Moons" around the parent. Clicking a Moon instantly expands the branch and focuses the camera on the child.

3. Two-Step Targeted Linking

While "Add" creates strict hierarchical structures (solid lines), you can draw conceptual relationships between any two nodes using the Two-Step Linking workflow (dotted lines).

4. Phase Engines (Views)

Multi-Map separates your raw data from how it is displayed. "Phases" are different lenses through which you can view the exact same Mapstate JSON.

• 🗺️
  Celestial Map

  The default spatial graph. Free-form dragging, physics engine enabled.

• 🔮
  Orbital Focus (Magic Circle)

  A strict hierarchical view. Displays only the selected "Sun" node, its immediate "Planets" (children), and its "Halo" (parent). Clicking planets navigates deep into the tree without visual clutter.

• 🌐
  🌐
  Web Architect & Spatial Browser

  A live HTML compiler. If your map uses web-* nodes, this engine dynamically compiles them into live, rendered HTML/Tailwind inside an iframe.

  Advanced Iframe Integration: If you input a valid URL (e.g. google.com or https://wikipedia.org) into the payload of a web-root node, the engine will automatically mount the live website into the background iframe. Any children attached to that node will physically render beneath the live website. If a site employs X-Frame blocking, an "Open in New Tab" escape hatch appears.

5. Profile & Data Manager

Accessible via the "Profile" icon in the top right corner, the right-side drawer serves as your unified command center for Account settings and the Data Manager. It allows you to log in, manage cloud templates, and export the local library.

6. Submaps and Portals

Maps in Multi-Map have intrinsic Subtype Mapstates (e.g., "Generic", "Web Architecture"). This enforces strict Ontology rules globally across the map.

To link maps together, create a Portal node. Using the Portal Inspector, you can either select an existing map as the destination, or create a New Submap by selecting a Map Type. Creating a "Web Architecture" map will instantly enforce Web-only rules and generate a web-root node in the new space.

6. Core Architecture

The platform relies on a Decoupled State Machine pattern. The DOM never dictates truth.

7. Node & Connection Ontology

Defined in Multi-Map-rules.js, this schema dictates what types of nodes can exist and how they are allowed to connect. Rule Exception: Any node is allowed to have a child of type 'note'.

Connection Types

• Structural (Solid): Strict Parent/Child hierarchy. Acts as a spring in the physics engine. Triggers cascading deletions.
• Association (Dashed): Loose conceptual relation. Ignored by physics springs and orbital views. Created via 2-Step linking.
• Flow (Dotted): Directional sequence logic (reserved for Logic Gates / execution loops).

Web Architect Nodes

8. JSON Schema & Arrays

The JSON standard for importing/exporting mapstates. The v14.9 system can parse a single object OR an array `[{...}, {...}]` of mapstates during upload.

{
  "map_id": "u7b9v2z1x",
  "meta": {
    "title": "Project Master Plan",
    "created": "2026-02-24T12:00:00Z",
    "notes": "System schema reference",
    "shared": false
  },
  "nodes": [
    {
      "id": "abc123xyz",
      "type": "hub",
      "title": "Central Architecture",
      "content": "Description payload here...",
      "data": {
        "x": 145.2,
        "y": -22.4,
        "isCore": true,
        "collapsed": false
      },
      "submaps": [] 
    }
  ],
  "connections": [
    {
      "id": "edge_999",
      "from": "abc123xyz",
      "to": "def456lmn",
      "type": "structural"
    }
  ],
  "submaps": [] // Caches templates or local portal configurations
}

9. Force-Directed Physics

The layout is driven by a custom iterative algorithm found in Kernel.resolveOverlaps(). It applies two simultaneous forces to form organic trees dynamically.

Upon node creation, a fast 40-iteration burst runs to clear space. Clicking the "Arrange" UI button triggers a deep 150-iteration simulation to organically untangle complex webs.

10. Serverless Library Engine

In v14.7, we deprecated fetch() calls to external JSON files to bypass local file:// CORS restrictions. The engine now uses a globally mounted MultiMapLibrary object loaded via multi-map-library.js.