holosphere 1.1.12 → 1.1.14

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "holosphere",
-  "version": "1.1.12",
+  "version": "1.1.14",
   "description": "Holonic Geospatial Communication Infrastructure",
   "main": "holosphere.js",
   "types": "holosphere.d.ts",
   "type": "module",
   "scripts": {
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
-    "build": "",
-    "prepare": "npm run build"
+    "build": "npm run build:browser",
+    "prepare": "npm run build",
+    "build:browser": "node build.js",
+    "build:bundle": "node build.js",
+    "prepublishOnly": "npm run build",
+    "publish:cdn": "npm publish && echo 'Package published to npm and will be available on CDNs within minutes'",
+    "publish:force": "npm publish --force && echo 'Package force published to npm and will be available on CDNs within minutes'",
+    "prepublish:skip-tests": "npm run build"
   },
   "author": "Roberto Valenti",
   "license": "GPL-3.0-or-later",
@@ -19,11 +25,80 @@
     "openai": "^4.85.1"
   },
   "devDependencies": {
+    "esbuild": "^0.25.5",
     "jest": "^29.7.0",
     "jest-environment-node": "^29.7.0"
   },
   "jest": {
     "testEnvironment": "node",
     "transform": {}
+  },
+    "browser": "holosphere-bundle.js",
+  "unpkg": "holosphere-bundle.js", 
+  "jsdelivr": "holosphere-bundle.js",
+  "cdn": "holosphere-bundle.js",
+  "files": [
+    "holosphere.js",
+    "holosphere-bundle.js",
+    "holosphere-bundle.min.js", 
+    "holosphere-bundle.esm.js",
+    "holosphere.d.ts",
+    "federation.js",
+    "schema.js",
+    "content.js",
+    "node.js",
+    "global.js",
+    "hologram.js",
+    "compute.js",
+    "utils.js",
+    "hexlib.js",
+    "README.md",
+    "LICENSE",
+    "FEDERATION.md"
+  ],
+  "exports": {
+    ".": {
+      "browser": "./holosphere-bundle.js",
+      "import": "./holosphere.js",
+      "require": "./holosphere.js",
+      "default": "./holosphere.js"
+    },
+    "./bundle": "./holosphere-bundle.js",
+    "./bundle/esm": "./holosphere-bundle.esm.js",
+    "./bundle/min": "./holosphere-bundle.min.js",
+    "./browser": "./holosphere-bundle.js",
+    "./node": "./holosphere.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rvalenti/holosphere.git"
+  },
+  "keywords": [
+    "holonic",
+    "geospatial",
+    "h3",
+    "hexagon",
+    "p2p",
+    "decentralized",
+    "gun",
+    "spatial",
+    "mapping",
+    "cdn",
+    "browser",
+    "realtime",
+    "webrtc"
+  ],
+  "bugs": {
+    "url": "https://github.com/rvalenti/holosphere/issues"
+  },
+  "homepage": "https://github.com/rvalenti/holosphere#readme",
+  "peerDependencies": {
+    "gun": "^0.2020.1240",
+    "h3-js": "^4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    }
   }
 }

package/.cursor/rules/futura.mdc

@@ -1,55 +0,0 @@
----
-description: 
-globs: 
-alwaysApply: true
----
-## 1. Collaboration with PRD Development
-- Do not start coding until the PRD is provided.
-- Once I send the completed PRD, use it as the definitive guide for all tasks, referring to it before starting any work.
-- Treat the PRD as a living document that may evolve; check for updates before each task and adjust plans accordingly.
-- Reference the PRD’s user stories, acceptance criteria, and priority levels (Must-have, Should-have, Could-have, Won’t-have) to guide coding and testing decisions.
-- Never use React, libraries are outdated and gives too many problems of compatibility and stability, go for Python in doubt
-- Do not build frontend and backend in separate folders and instaces as it seems that you will have a lot of trouble in managing the connections between the 2 sides
-
-## 2. Project Setup and Tracking
-- After receiving the PRD, create a README.md file with:
-  - A section listing all patterns and technologies used in the project (e.g., frameworks, libraries, tools).
-  - A brief project overview based on the PRD.
-- Create a checklist.md file with:
-  - A task list derived from the PRD, broken into actionable steps (e.g., "Implement login endpoint", "Write tests for user authentication").
-  - A status column (e.g., "Not Started", "In Progress", "Completed") to track progress.
-- Update checklist.md after completing each task by marking it as "Completed" and noting the git commit hash.
-- Incorporate the PRD’s feature breakdown table into checklist.md, including Priority and Dependencies columns to sequence tasks logically.
-- If the PRD includes a release plan (e.g., MVP, v1.1), group tasks by release milestones in checklist.md.
-
-## 3. Task Execution Workflow
-### Step 1: Identify the Next Task
-- Grep the codebase, review the PRD, and check checklist.md to determine the next task in sequence.
-- Focus only on the code areas relevant to the current task.
-- Use the PRD’s priority levels and technical dependencies to select the next task, starting with Must-haves and respecting dependency order.
-
-### Step 2: Write the Code
-- Iterate on existing code if possible, avoiding new solutions unless necessary.
-- Follow naming conventions and keep files under 500-700 lines, refactoring if needed.
-- Add comments for complex logic.
-- Avoid duplication by checking for similar functionality elsewhere in the codebase.
-- Ensure code meets the PRD’s acceptance criteria for the task’s feature or user story.
-- Adhere to non-functional requirements (e.g., performance, scalability) from the PRD when applicable.
-
-### Step 3: Write Tests
-- Write unit tests for individual functions and integration tests for workflows.
-- Name tests clearly (e.g., testLoginSuccess, testUserCreationWorkflow).
-- Ensure tests cover major functionality and edge cases outlined in the PRD.
-- Make tests specific, measurable, and traceable to the PRD’s acceptance criteria (e.g., "User can log in with email/password" passes if the API returns a 200 status).
-- Include tests for edge cases and error states documented in the PRD’s User Flows or AI-generated insights.
-
-### Step 4: Run the Server and Tests
-- Run all tests and verify they pass.
-
-### Step 5: Handle Test Failures
-- If tests fail, first review the test for accuracy (e.g., correct assertions, realistic mocks). Edit the test if it’s incorrect.
-- If the test is valid and still fails, debug the code:
-  - Add logs/console messages to trace the issue.
-  - Fix the underlying problem rather than masking it.
-  - Re-run the server and tests after each change.
-- Repeat until all tests pass. For persistent issues, check the fixes folder for prior solutions or use firecrawl to research fixes.

package/examples/federation.js

@@ -1,162 +0,0 @@
-/**
- * Organization Federation Example for HoloSphere (Updated API)
- * 
- * This example demonstrates a real-world use case where a tech team creates tasks
- * that are automatically federated to the parent organization for visibility using
- * the latest HoloSphere federation features.
- */
-
-import HoloSphere from '../holosphere.js';
-
-async function organizationFederationExample() {
-  const holoSphere = new HoloSphere('organization-example-updated');
-  
-  try {
-    console.log('Starting Organization Federation Example (Updated API)...');
-    
-    // Define unique names for this run to avoid conflicts
-    const runId = Date.now();
-    const orgHolon = `acme-org-${runId}`;
-    const techTeamHolon = `acme-tech-${runId}`;
-    
-    // Step 1: Create federation relationship (bidirectional by default)
-    console.log('\nStep 1: Creating federation relationship...');
-    // The `federate` method automatically sets up bidirectional notifications when `bidirectional` is true (default).
-    const federateResult = await holoSphere.federate(techTeamHolon, orgHolon); 
-    if (!federateResult) {
-        throw new Error('Federation setup failed.');
-    }
-    console.log(`Federation created between ${techTeamHolon} and ${orgHolon}`);
-    
-    // Allow a moment for GunDB propagation of federation settings
-    await new Promise(resolve => setTimeout(resolve, 1500)); 
-
-    // Step 2: Verify federation is set up properly
-    console.log('\nStep 2: Verifying federation setup...');
-    const techTeamFedInfo = await holoSphere.getFederation(techTeamHolon);
-    console.log(`Tech team (${techTeamHolon}) federation info:`, techTeamFedInfo);
-    if (!techTeamFedInfo?.federation?.includes(orgHolon)) {
-        console.warn('Warning: Organization holon not found in tech team federation list.');
-    }
-    
-    const orgFedInfo = await holoSphere.getFederation(orgHolon);
-    console.log(`Organization (${orgHolon}) federation info:`, orgFedInfo);
-    if (!orgFedInfo?.notify?.includes(techTeamHolon)) {
-        console.warn('Warning: Tech team holon not found in organization notify list.');
-    }
-
-    // Step 3: Create a task in the tech team holon
-    // The `put` method automatically propagates data to federated holons by default (`autoPropagate: true`).
-    console.log('\nStep 3: Creating a task in the tech team holon (will auto-propagate)...');
-    
-    const task = {
-      id: `task-${runId}-123`,
-      title: 'Implement new authentication system',
-      description: 'Replace the current auth system with OAuth2',
-      assignee: 'dev@example.com',
-      status: 'in_progress',
-      priority: 'high',
-      dueDate: '2024-12-31',
-      createdAt: new Date().toISOString(),
-      tags: ['security', 'infrastructure']
-    };
-    
-    // Store the task - it will be automatically propagated to orgHolon due to federation
-    const putResult = await holoSphere.put(techTeamHolon, 'tasks', task);
-    console.log(`Task created in ${techTeamHolon}: ${task.id}. Propagation result:`, putResult.propagationResult);
-    if (putResult.propagationResult?.errors > 0) {
-      console.warn('Warning: Auto-propagation reported errors.');
-    }
-
-    // Step 4: Allow time for propagation via put
-    console.log('\nStep 4: Waiting for auto-propagation to complete...');
-    await new Promise(resolve => setTimeout(resolve, 1500)); 
-    
-    // Step 5: Verify task in both holons
-    console.log('\nStep 5: Verifying task is in both holons...');
-    
-    // Check tech team holon directly (original data)
-    const techTeamTask = await holoSphere.get(techTeamHolon, 'tasks', task.id);
-    console.log(`Task in tech team holon (${techTeamHolon}):`, techTeamTask ? 'Found' : 'Not found');
-    if (techTeamTask) console.log('Tech team task status:', techTeamTask.status);
-    
-    // Check organization holon directly (should have a resolved reference)
-    const orgTask = await holoSphere.get(orgHolon, 'tasks', task.id);
-    console.log(`Task in organization holon (${orgHolon}):`, orgTask ? 'Found' : 'Not found');
-    if (orgTask) {
-      console.log('Organization task status:', orgTask.status);
-      // Check if it's a resolved reference
-      console.log('Is resolved reference:', !!orgTask._federation?.resolved); 
-    } else {
-      console.warn(`Task ${task.id} not found in organization holon ${orgHolon}. Propagation might have failed or is slow.`);
-    }
-    
-    // Step 6: Use getFederated to view all tasks from the organization's perspective
-    console.log('\nStep 6: Using getFederated to view all tasks...');
-    
-    const allOrgTasks = await holoSphere.getFederated(orgHolon, 'tasks');
-    console.log(`Organization holon (${orgHolon}) has access to ${allOrgTasks.length} tasks (via getFederated):`);
-    // console.log(allOrgTasks); // Uncomment to see the full list
-    
-    const allTechTasks = await holoSphere.getFederated(techTeamHolon, 'tasks');
-    console.log(`Tech team holon (${techTeamHolon}) has access to ${allTechTasks.length} tasks (via getFederated):`);
-    // console.log(allTechTasks); // Uncomment to see the full list
-
-    // Step 7: Update the task in tech team holon (will also auto-propagate)
-    console.log('\nStep 7: Updating task in tech team holon (will auto-propagate)...');
-    
-    const updatedTask = {
-      ...task,
-      status: 'completed',
-      completedAt: new Date().toISOString()
-    };
-    
-    // Update the task - the change will be automatically propagated
-    const updateResult = await holoSphere.put(techTeamHolon, 'tasks', updatedTask);
-    console.log(`Task updated in ${techTeamHolon}. Propagation result:`, updateResult.propagationResult);
-    if (updateResult.propagationResult?.errors > 0) {
-      console.warn('Warning: Auto-propagation of update reported errors.');
-    }
-    
-    // Step 8: Allow time for update propagation
-    console.log('\nStep 8: Waiting for update propagation...');
-    await new Promise(resolve => setTimeout(resolve, 1500)); 
-    
-    // Step 9: Verify updates in both holons
-    console.log('\nStep 9: Verifying updated task in both holons...');
-    
-    const updatedTechTeamTask = await holoSphere.get(techTeamHolon, 'tasks', task.id);
-    console.log(`Updated task status in tech team holon (${techTeamHolon}):`, updatedTechTeamTask?.status);
-    
-    // Get the potentially updated reference in the organization holon
-    const updatedOrgTask = await holoSphere.get(orgHolon, 'tasks', task.id); 
-    console.log(`Updated task status in organization holon (${orgHolon}):`, updatedOrgTask?.status);
-    if (!updatedOrgTask || updatedOrgTask.status !== 'completed') {
-        console.warn(`Updated task status not reflected in organization holon ${orgHolon}. Propagation might have failed or is slow.`);
-    }
-
-    // Step 10: Clean up - remove federation
-    console.log('\nStep 10: Cleaning up - removing federation...');
-    await holoSphere.unfederate(techTeamHolon, orgHolon);
-    console.log(`Federation removed between ${techTeamHolon} and ${orgHolon}`);
-    
-    // Optional: Clean up data (can be slow and sometimes unreliable in Gun)
-    // console.log('Cleaning up task data...');
-    // await holoSphere.delete(techTeamHolon, 'tasks', task.id);
-    // await holoSphere.delete(orgHolon, 'tasks', task.id); // Delete the reference
-    // await holoSphere.deleteGlobal('federation', techTeamHolon);
-    // await holoSphere.deleteGlobal('federation', orgHolon);
-    
-    console.log('\nOrganization federation example completed successfully!');
-    
-  } catch (error) {
-    console.error('Error in organization federation example:', error);
-  } finally {
-    // Always close the HoloSphere instance
-    await holoSphere.close();
-    console.log('HoloSphere instance closed');
-  }
-}
-
-// Run the example
-organizationFederationExample().catch(console.error); 

package/examples/hologram-updates-example.js

@@ -1,106 +0,0 @@
-// hologram-updates-example.js
-// Example showing how to use the returned list of updated holograms from put()
-
-import HoloSphere from '../holosphere.js';
-
-async function exampleUsage() {
-    const holosphere = new HoloSphere('example-app', false);
-    
-    try {
-        // 1. Create some original data
-        const originalData = { 
-            id: 'product-123', 
-            name: 'Widget', 
-            price: 19.99,
-            inventory: 100 
-        };
-        
-        console.log('Step 1: Storing original data...');
-        await holosphere.put('store', 'products', originalData);
-        
-        // 2. Create holograms in different locations (maybe for different displays/views)
-        console.log('Step 2: Creating holograms...');
-        const hologram1 = holosphere.createHologram('store', 'products', originalData);
-        const hologram2 = holosphere.createHologram('store', 'products', originalData);
-        
-        await holosphere.put('storefront', 'display', { id: 'featured-product', soul: hologram1.soul });
-        await holosphere.put('warehouse', 'inventory', { id: 'stock-item', soul: hologram2.soul });
-        
-        // Wait for Gun to propagate
-        await new Promise(resolve => setTimeout(resolve, 500));
-        
-        // 3. Update the original data and get the list of updated holograms
-        console.log('Step 3: Updating original data...');
-        const updatedData = { 
-            ...originalData, 
-            price: 17.99,  // Price reduction!
-            inventory: 95, // Some sold
-            lastUpdated: Date.now()
-        };
-        
-        const result = await holosphere.put('store', 'products', updatedData);
-        
-        console.log('PUT Result:', {
-            success: result.success,
-            pathInfo: {
-                holon: result.pathHolon,
-                lens: result.pathLens,
-                key: result.pathKey
-            },
-            updatedHologramsCount: result.updatedHolograms.length
-        });
-        
-        // 4. Process the updated holograms
-        console.log('Step 4: Processing updated holograms...');
-        if (result.updatedHolograms.length > 0) {
-            console.log(`Updated ${result.updatedHolograms.length} holograms:`);
-            
-            for (const hologram of result.updatedHolograms) {
-                console.log(`  - Hologram at ${hologram.holon}/${hologram.lens}/${hologram.key}`);
-                console.log(`    Soul: ${hologram.soul}`);
-                console.log(`    Updated at: ${new Date(hologram.timestamp).toISOString()}`);
-                
-                // Example post-processing: 
-                // You could trigger UI updates, send notifications, update caches, etc.
-                
-                if (hologram.holon === 'storefront') {
-                    console.log('    -> Triggering storefront display refresh');
-                    // triggerStorefrontRefresh(hologram.key);
-                }
-                
-                if (hologram.holon === 'warehouse') {
-                    console.log('    -> Updating warehouse inventory system');
-                    // updateWarehouseInventory(hologram.key);
-                }
-            }
-        } else {
-            console.log('No holograms were updated.');
-        }
-        
-        // 5. Verify the holograms have the updated timestamp
-        console.log('Step 5: Verifying hologram updates...');
-        const storefrontHologram = await holosphere.get('storefront', 'display', 'featured-product', null, { resolveHolograms: false });
-        const warehouseHologram = await holosphere.get('warehouse', 'inventory', 'stock-item', null, { resolveHolograms: false });
-        
-        console.log('Storefront hologram updated field:', storefrontHologram?.updated);
-        console.log('Warehouse hologram updated field:', warehouseHologram?.updated);
-        
-    } catch (error) {
-        console.error('Error in example:', error);
-    } finally {
-        await holosphere.close();
-    }
-}
-
-// Example usage scenarios:
-console.log('=== Hologram Updates Return Value Example ===');
-console.log('This example demonstrates how to use the updatedHolograms return value from put()');
-console.log('to perform post-processing tasks when original data changes.\n');
-
-exampleUsage().then(() => {
-    console.log('\n=== Example completed ===');
-    process.exit(0);
-}).catch(error => {
-    console.error('Example failed:', error);
-    process.exit(1);
-}); 

package/examples/holograms.js

@@ -1,175 +0,0 @@
-import HoloSphere from '../holosphere.js';
-
-async function testHologramFederation() {
-    console.log('Starting hologram federation test...');
-    const holoSphere = new HoloSphere('test-holograms');
-    
-    try {
-        const space1 = 'holo-test-space1';
-        const space2 = 'holo-test-space2';
-        
-        // Step 1: Create federation with bidirectional notify settings
-        console.log('Step 1: Creating federation between spaces...');
-        await holoSphere.federate(space1, space2);
-        
-        // Also federate from space2 to space1 for testing getFederated
-        await holoSphere.federate(space2, space1);
-        
-        // Step 2: Verify federation is set up properly
-        const fedInfo = await holoSphere.getFederation(space1);
-        console.log('Federation info for space1:', fedInfo);
-        
-        const fedInfo2 = await holoSphere.getFederation(space2);
-        console.log('Federation info for space2:', fedInfo2);
-        
-        // Step 3: Create test data
-        console.log('Step 3: Creating test data...');
-        const testData = {
-            id: 'holo-test-item',
-            title: 'Hologram Test',
-            value: 200,
-            tags: ['test', 'hologram']
-        };
-        
-        // Store data in space1
-        await holoSphere.put(space1, 'items', testData);
-        
-        // Step 4: Propagate using holograms
-        console.log('Step 4: Propagating with soul holograms...');
-        const propResult = await holoSphere.propagate(space1, 'items', testData, {
-            useHolograms: true
-        });
-        console.log('Propagation result:', propResult);
-        
-        // Allow time for propagation
-        console.log('Waiting for propagation...');
-        await new Promise(resolve => setTimeout(resolve, 1000));
-        
-        // Step 5: Verify that the data in space2 is a soul hologram
-        console.log('Step 5: Verifying soul hologram was created...');
-        const rawHolo = await holoSphere.get(space2, 'items', 'holo-test-item', null, {
-            resolveHolograms: false
-        });
-        
-        console.log('Raw hologram data:', rawHolo);
-        console.log('Is soul hologram:', holoSphere.isHologram(rawHolo));
-        
-        if (rawHolo?.soul) {
-            const soulParts = rawHolo.soul.split('/');
-            console.log('Soul parts:', soulParts);
-            console.log('Soul refers to:', {
-                app: soulParts[0], 
-                holon: soulParts[1], 
-                lens: soulParts[2], 
-                key: soulParts[3]
-            });
-        }
-        
-        // Step 6: Verify hologram resolution works
-        console.log('Step 6: Verifying hologram resolution...');
-        const resolvedData = await holoSphere.get(space2, 'items', 'holo-test-item');
-        console.log('Resolved data:', resolvedData);
-        
-        // Step 7: Update the original data
-        console.log('Step 7: Updating original data...');
-        const updatedData = {
-            ...testData,
-            value: 300,
-            updated: true
-        };
-        
-        await holoSphere.put(space1, 'items', updatedData);
-        
-        // Allow time for update to propagate
-        console.log('Waiting for update...');
-        await new Promise(resolve => setTimeout(resolve, 500));
-        
-        // Step 8: Verify update is reflected through the hologram
-        console.log('Step 8: Verifying update is reflected in hologram...');
-        const reResolvedData = await holoSphere.get(space2, 'items', 'holo-test-item');
-        console.log('Re-resolved data after update:', reResolvedData);
-        
-        // Step 9: Update directly through origin holon
-        console.log('Step 9: Updating through the origin holon...');
-        const originData = await holoSphere.get(space1, 'items', 'holo-test-item');
-        
-        const finalUpdate = {
-            ...originData,
-            value: 400,
-            finalUpdate: true
-        };
-        
-        await holoSphere.put(space1, 'items', finalUpdate);
-        
-        // Allow time for update to propagate
-        console.log('Waiting for final update...');
-        await new Promise(resolve => setTimeout(resolve, 500));
-        
-        // Step 10: Verify final update through the hologram in space2
-        console.log('Step 10: Verifying final update is reflected...');
-        const finalResolvedData = await holoSphere.get(space2, 'items', 'holo-test-item');
-        console.log('Final resolved data:', finalResolvedData);
-        
-        // Step 11: Test manual soul hologram resolution
-        console.log('Step 11: Testing manual soul hologram resolution...');
-        
-        // Check what getAll returns
-        console.log('Raw holograms from getAll in space2:');
-        const allItems = await holoSphere.getAll(space2, 'items');
-        console.log('getAll results:', allItems);
-        
-        if (allItems.length > 0 && allItems[0].soul) {
-            console.log('Found a soul hologram, resolving it manually:');
-            const soulParts = allItems[0].soul.split('/');
-            
-            const originHolon = soulParts[1];
-            const originLens = soulParts[2];
-            const originKey = soulParts[3];
-            
-            console.log(`Soul path components: holon=${originHolon}, lens=${originLens}, key=${originKey}`);
-            
-            const originalData = await holoSphere.get(
-                originHolon,
-                originLens,
-                originKey,
-                null,
-                { resolveHolograms: false }
-            );
-            console.log('Manually resolved hologram data:', originalData);
-        }
-        
-        // Test getFederated with holograms
-        console.log('\nTesting getFederated with holograms:');
-        const federatedData = await holoSphere.getFederated(space2, 'items', {
-            resolveHolograms: true,
-            idField: 'id'
-        });
-        
-        console.log('getFederated results length:', federatedData.length);
-        
-        // Find the item by ID
-        const federatedItem = federatedData.find(item => item.id === 'holo-test-item');
-        console.log('Found federated item by ID:', federatedItem);
-        
-        // Check if federated data correctly resolves soul holograms
-        if (federatedItem && federatedItem.value === 400 && federatedItem.finalUpdate) {
-            console.log('SUCCESS: getFederated correctly resolved the soul hologram!');
-        } else {
-            console.log('WARNING: getFederated may not be resolving soul holograms properly');
-        }
-        
-        // Step 12: Clean up
-        console.log('Step 12: Cleaning up...');
-        await holoSphere.unfederate(space1, space2);
-        await holoSphere.unfederate(space2, space1);
-        
-        console.log('Hologram federation test completed successfully!');
-    } catch (error) {
-        console.error('Hologram federation test failed:', error);
-    } finally {
-        await holoSphere.close();
-        console.log('HoloSphere connection closed.');
-    }
-}
-
-testHologramFederation();