1  # Liminal Web Layout Feature
 2  
 3  **Purpose**: Manages spatial positioning and relationship visualization for DreamNodes in 3D space using a hexagonal ring-based layout system.
 4  
 5  ## Directory Structure
 6  
 7  ```
 8  liminal-web-layout/
 9  ├── store/
10  │   └── slice.ts              # Zustand slice for selected node and navigation history
11  ├── docs/
12  │   ├── ring-layout.md        # Algorithm documentation with mathematical foundations
13  │   └── ring-layout-visualizer.html  # Interactive algorithm demo
14  ├── RingLayout.ts             # Core 3D positioning algorithm (hexagonal rings)
15  ├── relationship-graph.ts     # In-memory graph database for relationship queries
16  ├── commands.ts               # Command palette commands for relationship maintenance
17  ├── index.ts                  # Barrel export
18  └── README.md
19  ```
20  
21  ## Algorithm Documentation
22  
23  **[📐 Ring Layout Algorithm](./docs/ring-layout.md)** - Detailed documentation including:
24  - Mathematical foundations (golden ratio, hexagonal geometry)
25  - Interactive visualizer for the 42-coordinate system
26  - Boolean mask patterns for node positioning
27  
28  ## Main Exports
29  
30  ```typescript
31  // Store (state management)
32  export { createLiminalWebSlice, LiminalWebSlice } from './store/slice';
33  export type { NavigationHistoryEntry, NavigationHistoryState } from './store/slice';
34  
35  // Layout algorithms
36  export { calculateRingLayoutPositions, calculateRingLayoutPositionsForSearch } from './RingLayout';
37  export { DEFAULT_RING_CONFIG } from './RingLayout';
38  export type { RingLayoutConfig, RingLayoutPositions } from './RingLayout';
39  
40  // Relationship graph
41  export { buildRelationshipGraph, getRelationshipStats } from './relationship-graph';
42  export type { RelationshipGraph } from './relationship-graph';
43  
44  // Commands
45  export { registerRelationshipCommands } from './commands';
46  ```
47  
48  ## Ownership
49  
50  **Liminal-web-layout owns** the ring layout algorithm (`RingLayout.ts`), navigation history state, and selected node tracking. Used by SpatialOrchestrator for liminal-web, search, edit, and copilot spatial modes.
51  
52  ## Key Components
53  
54  ### `store/slice.ts` - State Management
55  Zustand slice managing:
56  - **selectedNode**: Currently focused DreamNode in liminal web view
57  - **navigationHistory**: Undo/redo stack (150 max entries) with flip state
58  - **setSelectedNode()**: Updates selection and triggers lazy media loading for node neighborhood
59  - **performUndo()**, **performRedo()**: Navigate through history
60  - **restoreVisualState()**: Restores flip state from history entry
61  
62  ### `RingLayout.ts` - Positioning Algorithm
63  Calculates 3D positions for up to 36 nodes in hexagonal rings:
64  - **Center**: Focused/selected node
65  - **Ring 1**: 6 nodes (inner ring)
66  - **Ring 2**: 12 nodes (middle ring)
67  - **Ring 3**: 18 nodes (outer ring)
68  
69  Uses boolean masking for precise node placement and priority mapping to position related nodes in inner rings.
70  
71  ### `relationship-graph.ts` - Graph Database
72  Fast in-memory relationship traversal:
73  - `buildRelationshipGraph()`: Constructs graph from DreamNode array
74  - `getConnections()`: First-degree connections
75  - `getOppositeTypeConnections()`: Dreams ↔ Dreamers only
76  - `getSecondDegreeConnections()`: Connections of connections
77  
78  ### `commands.ts` - Maintenance Commands
79  - **Clean Dangling Relationships**: Removes references to non-existent nodes from liminal-web.json files
80  
81  ## Integration Points
82  
83  - Used by `DreamspaceCanvas` component for 3D node positioning
84  - Integrated with semantic search for prioritizing related nodes
85  - Connects to media loading service for lazy loading node neighborhoods
86  - Commands registered in plugin's `main.ts`
87  
88  ## Technical Notes
89  
90  - **Coordinate system**: Y-axis is negated to convert from HTML canvas (Y-down) to 3D (Y-up)
91  - **36-node capacity**: Maximum layout capacity across all rings (6+12+18)
92  - **Priority mapping**: Related nodes always get inner ring positions
93  - **Lazy loading**: Selecting a node triggers media loading for its 2-degree neighborhood