### Install SpaceGraph ZUI Library
Source: https://github.com/automenta/spacegraphjs/blob/main/README.md
Instructions for installing the SpaceGraph ZUI library using npm or yarn package managers.
```bash
npm install spacegraph-zui
```
```bash
yarn add spacegraph-zui
```
--------------------------------
### Install SpaceGraph ZUI Peer Dependencies
Source: https://github.com/automenta/spacegraphjs/blob/main/README.md
Instructions for installing the required peer dependencies (three, gsap, and postprocessing) for SpaceGraph ZUI using npm or yarn.
```bash
npm install three gsap postprocessing
```
```bash
yarn add three gsap postprocessing
```
--------------------------------
### Initialize SpaceGraph.js and Create Nodes/Edges
Source: https://github.com/automenta/spacegraphjs/blob/main/README.md
This JavaScript code demonstrates how to initialize the SpaceGraph.js library within a web page. It selects a container element, configures basic options like layout, creates two 'ShapeNode' instances, adds an edge between them, and starts the rendering loop. Error handling for initialization is also included.
```javascript
import { SpaceGraph } from 'spacegraph-zui';
// For CommonJS: const { SpaceGraph } = require('spacegraph-zui');
document.addEventListener('DOMContentLoaded', async () => {
const container = document.getElementById('graph-container');
if (!container) {
console.error('Graph container not found!');
return;
}
// Basic options (see documentation for more)
const options = {
// Example: configure default layout
layout: {
type: 'ForceLayout', // Default, can be omitted
settings: {
// Force layout specific settings
},
},
// Example: UI plugin options (if using default UI elements)
// ui: {
// contextMenuElement: document.getElementById('my-custom-context-menu'),
// confirmDialogElement: document.getElementById('my-custom-confirm-dialog')
// }
};
const sg = new SpaceGraph(container, options);
try {
await sg.init(); // Initialize plugins and renderer
// Add some nodes
const node1 = sg.createNode({
id: 'node-1',
type: 'ShapeNode', // Default node type, can be 'HtmlNode', 'ImageNode' etc.
data: { label: 'Hello' },
position: { x: -50, y: 0, z: 0 }, // Optional initial position
});
const node2 = sg.createNode({
id: 'node-2',
type: 'ShapeNode',
data: { label: 'World' },
position: { x: 50, y: 0, z: 0 },
});
// Add an edge between them
if (node1 && node2) {
sg.addEdge(node1, node2, { label: 'connects to' });
}
// If your layout requires manual starting or if you want to ensure rendering loop
sg.animate(); // Starts the rendering loop if not auto-started by plugins
// Center view on content or specific node
sg.centerView();
} catch (error) {
console.error('Failed to initialize SpaceGraph:', error);
}
// Make it accessible for debugging
window.mySpaceGraph = sg;
});
```
--------------------------------
### Start Initialization on DOM Ready
Source: https://github.com/automenta/spacegraphjs/blob/main/enhanced-index.html
Ensures the `initializeDemo` function is called once the DOM is fully loaded. This prevents script execution before necessary HTML elements are available, which is crucial for functions that interact with the document structure.
```JavaScript
if (documen
```
--------------------------------
### HTML Setup for SpaceGraph.js Container
Source: https://github.com/automenta/spacegraphjs/blob/main/README.md
This HTML snippet provides the basic structure for a web page, including a 'div' element with the ID 'graph-container' which serves as the rendering target for the SpaceGraph.js library. It also includes minimal CSS to ensure the container fills the viewport and imports the main application JavaScript file.
```html
My SpaceGraph App
```
--------------------------------
### Initialize Demo on DOMContentLoaded
Source: https://github.com/automenta/spacegraphjs/blob/main/enhanced-index.html
This snippet checks if the DOM is already loaded (e.g., `readyState` is not 'loading') or waits for the 'DOMContentLoaded' event before executing the `initializeDemo` function. This pattern ensures that the demo's setup logic runs only after the HTML structure is fully parsed and available.
```javascript
t.readyState === 'loading') { document.addEventListener('DOMContentLoaded', initializeDemo); } else { initializeDemo(); }
```
--------------------------------
### Initialize SpaceGraphJS Demo System
Source: https://github.com/automenta/spacegraphjs/blob/main/enhanced-index.html
Asynchronously initializes the SpaceGraphJS demo. It first performs browser feature and performance detection, updates loading messages based on performance, then dynamically imports the main demo module. The function includes robust error handling, displaying user-friendly messages if initialization fails due to compatibility or network issues.
```JavaScript
async function initializeDemo() {
try {
const detection = detectFeatures();
console.log('Feature detection:', detection);
if (!showFeatureWarnings(detection)) {
return;
}
const performance = detectPerformance();
console.log('Performance tier:', performance);
document.querySelector('.loading-subtitle').textContent = `Loading enhanced demo system... (${performance.message})`;
const module = await import('./src/examples/enhanced-demo-main.js');
setTimeout(() => {
document.getElementById('loading-screen').style.display = 'none';
}, 1000);
} catch (error) {
console.error('Failed to initialize demo system:', error);
document.getElementById('loading-screen').innerHTML = `
❌ Initialization Failed
There was an error loading the SpaceGraphJS demo system:
Error: ${error.message}
This might be due to network issues or browser compatibility problems.
`;
}
}
```
--------------------------------
### API for UI Framework and Theming in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API describes the core UI elements like toolbars and context menus, and an advanced theming system based on CSS Custom Properties for deep customization.
```APIDOC
UI Framework and Theming API:
Core UI Elements:
- Toolbar for common actions.
- Context Menus for node, edge, and canvas interactions.
Advanced Theming System:
- Implemented based on CSS Custom Properties for deep, non-intrusive customization (e.g., --spacegraph-node-bg, --spacegraph-accent-color).
```
--------------------------------
### API for Layout System Management in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API outlines the system for managing and transitioning between various graph layout algorithms, including a robust force-directed layout with collision detection and smooth animations.
```APIDOC
Layout System API:
Layout Manager:
- System to register and switch between different layout algorithms.
Force-Directed Layout:
- Robust implementation with collision detection and clustering.
Layout Transitions:
- Uses GSAP for smooth, animated transitions when layouts change or graph is modified.
```
--------------------------------
### CSS Base Styles and Loading Screen for SpaceGraphJS Demo
Source: https://github.com/automenta/spacegraphjs/blob/main/enhanced-index.html
This CSS defines global body styles and a full-screen loading overlay. It includes animations for a pulsating logo and a progress bar, providing visual feedback during initial page load.
```CSS
body { margin: 0; padding: 0; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; background: #f8f9fa; }
#loading-screen { position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; display: flex; flex-direction: column; align-items: center; justify-content: center; z-index: 9999; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; }
.loading-logo { font-size: 64px; margin-bottom: 20px; animation: pulse 2s infinite; }
.loading-title { font-size: 24px; font-weight: 300; margin-bottom: 10px; }
.loading-subtitle { font-size: 14px; opacity: 0.8; margin-bottom: 30px; }
.loading-progress { width: 300px; height: 4px; background: rgba(255, 255, 255, 0.2); border-radius: 2px; overflow: hidden; }
.loading-bar { height: 100%; background: rgba(255, 255, 255, 0.8); border-radius: 2px; animation: loading 3s ease-in-out infinite; }
@keyframes pulse { 0%, 100% { transform: scale(1); } 50% { transform: scale(1.1); } }
@keyframes loading { 0% { width: 0%; } 50% { width: 70%; } 100% { width: 100%; } }
```
--------------------------------
### SpaceGraph.js API Documentation Reference
Source: https://github.com/automenta/spacegraphjs/blob/main/README.md
This entry indicates the availability of detailed API documentation for SpaceGraph.js, covering classes, methods, options, and plugin development. Users are directed to an external site for comprehensive API specifications.
```APIDOC
For detailed API documentation, including all classes, methods, options, and plugin development, please visit [our documentation site](PLACEHOLDER_API_DOCS_LINK).
```
--------------------------------
### API for Expanded Content and Layouts (Plugins) in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API describes the plugin system for advanced node types (e.g., Image, Video, Group, Data, IFrame) and additional layout algorithms (e.g., Grid, Circular, Hierarchical), with progress noted on specific enhancements.
```APIDOC
Expanded Content and Layouts (Plugins) API:
Advanced Node Types:
- ImageNode
- VideoNode
- GroupNode (collapsible container)
- DataNode (for charts)
- IFrameNode (for embedding web content)
- Progress: AudioNode, DocumentNode, and ChartNode enhanced beyond basic stubs.
Additional Layouts:
- GridLayout (2D/3D)
- CircularLayout/SphericalLayout
- HierarchicalLayout (for tree-like structures)
- Progress: TreeMapLayout and RadialLayout enhanced beyond basic stubs.
```
--------------------------------
### API for Interaction Model in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API defines user interaction capabilities, including 3D node dragging with depth adjustment, flexible selection models (single, multi, group), and the ability to pin nodes.
```APIDOC
Interaction Model API:
3D Dragging:
- Implements node dragging in 3D space.
- Supports modifier keys for depth adjustment.
Selection Model:
- Supports single-select.
- Supports multi-select (e.g., with Shift+Click).
- Supports group dragging.
Node Pinning:
- Allows users to pin nodes to fix their position during layout calculations.
```
--------------------------------
### Handle Unhandled Promise Rejections
Source: https://github.com/automenta/spacegraphjs/blob/main/enhanced-index.html
Sets up a global event listener to catch any promise rejections that are not explicitly handled by a `.catch()` block. This is crucial for debugging asynchronous operations, as it logs the reason for the unhandled rejection to the console, helping developers identify and fix potential issues in promise chains.
```javascript
window.addEventListener('unhandledrejection', function(e) { console.error('Unhandled promise rejection:', e.reason); });
```
--------------------------------
### Define Import Map for SpaceGraphJS Dependencies
Source: https://github.com/automenta/spacegraphjs/blob/main/enhanced-index.html
Configures import maps for SpaceGraphJS, mapping module names like 'three' and 'gsap' to their CDN URLs. This allows modern browsers to load these dependencies directly via their module names, simplifying development and deployment.
```JavaScript
{ "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.177.0/build/three.module.js", "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.177.0/examples/jsm/", "gsap": "https://cdn.jsdelivr.net/npm/gsap@3.12.5/index.js" } }
```
--------------------------------
### API for Performance Optimization in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API details strategies for optimizing performance, including instanced rendering for high object counts, Level of Detail (LOD) for complex geometries, and parallelization of heavy calculations.
```APIDOC
Performance Optimization API:
Instanced Rendering:
- Implemented for nodes and edges to efficiently render thousands of objects.
Level of Detail (LOD):
- Uses LODs for complex node geometries and text labels to maintain high frame rates.
Parallelization:
- Offloads heavy layout calculations to Web Workers.
```
--------------------------------
### API for Advanced Camera and View Management in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API covers advanced camera modes, the ability to save and restore camera states, and the implementation of an optional minimap for navigating large graphs.
```APIDOC
Advanced Camera and View Management API:
Camera Modes:
- FreeCamera (FPS-style)
- AutoCamera (auto-frame/follow)
View Management:
- API to save and restore camera states ("Named Views").
Minimap:
- Implements an optional minimap for navigating large graphs.
```
--------------------------------
### API for Mature Node and Edge Systems in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API defines the structure for creating and managing different node types via a NodeFactory, including HTML and shape-based nodes, and extends edge capabilities with new types and styling options.
```APIDOC
Node and Edge Systems API:
NodeFactory:
- Supports registering and creating different node types.
Core Node Types:
- HtmlNode: For displaying rich HTML/CSS content.
- ShapeNode: For basic 3D shapes (Sphere, Box), with support for GLTF model imports.
Edge System Enhancements:
- Edge Types:
- CurvedEdge (Bezier/Spline)
- LabeledEdge
- Styling:
- Dashed lines
- Color gradients
- Arrowheads
```
--------------------------------
### API for Advanced Rendering and Visuals in Spacegraph.js
Source: https://github.com/automenta/spacegraphjs/blob/main/TODO.md
This API section details enhancements for visual quality, including improved edge rendering, post-processing effects, and comprehensive lighting controls to enhance depth and realism.
```APIDOC
Rendering and Visuals API:
Edges:
- Replaces THREE.Line with Line2 for variable thickness and superior visual quality.
Post-Processing:
- Integrates Postprocessing effects:
- Bloom
- Screen Space Ambient Occlusion (SSAO)
- Outline effect (on selection/hover)
Lighting Control:
- Provides developer API to configure scene lighting:
- Ambient Light
- Directional Light
- Point Light
- Enables shadows for improved depth perception.
```
--------------------------------
### Define JavaScript Module Imports with Import Map
Source: https://github.com/automenta/spacegraphjs/blob/main/dist-demo/index.html
This snippet defines an import map, a standard way to control the behavior of JavaScript module imports. It maps module specifiers like 'three' and 'gsap' to their respective CDN URLs, allowing direct import in browser environments without a build step. This configuration is typically placed in a