npm - cyclecad - Versions diffs - 0.2.2 → 0.2.3 - Mend

cyclecad 0.2.2 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/API-BUILD-MANIFEST.txt +339 -0
package/API-SERVER.md +535 -0
package/Architecture-Deck.pptx +0 -0
package/CLAUDE.md +172 -11
package/CLI-BUILD-SUMMARY.md +504 -0
package/CLI-INDEX.md +356 -0
package/CLI-README.md +466 -0
package/COLLABORATION-INTEGRATION-GUIDE.md +325 -0
package/CONNECTED_FABS_GUIDE.md +612 -0
package/CONNECTED_FABS_README.md +310 -0
package/DELIVERABLES.md +343 -0
package/DFM-ANALYZER-INTEGRATION.md +368 -0
package/DFM-QUICK-START.js +253 -0
package/Dockerfile +69 -0
package/IMPLEMENTATION.md +327 -0
package/LICENSE +31 -0
package/MARKETPLACE_QUICK_REFERENCE.txt +294 -0
package/MCP-INDEX.md +264 -0
package/QUICKSTART-API.md +388 -0
package/QUICKSTART-CLI.md +211 -0
package/QUICKSTART-MCP.md +196 -0
package/README-MCP.md +208 -0
package/TEST-TOKEN-ENGINE.md +319 -0
package/TOKEN-ENGINE-SUMMARY.md +266 -0
package/TOKENS-README.md +263 -0
package/TOOLS-REFERENCE.md +254 -0
package/app/index.html +168 -3
package/app/js/TOKEN-INTEGRATION.md +391 -0
package/app/js/agent-api.js +3 -3
package/app/js/ai-copilot.js +1435 -0
package/app/js/cam-pipeline.js +840 -0
package/app/js/collaboration-ui.js +995 -0
package/app/js/collaboration.js +1116 -0
package/app/js/connected-fabs-example.js +404 -0
package/app/js/connected-fabs.js +1449 -0
package/app/js/dfm-analyzer.js +1760 -0
package/app/js/marketplace.js +1994 -0
package/app/js/material-library.js +2115 -0
package/app/js/token-dashboard.js +563 -0
package/app/js/token-engine.js +743 -0
package/app/test-agent.html +1801 -0
package/bin/cyclecad-cli.js +662 -0
package/bin/cyclecad-mcp +2 -0
package/bin/server.js +242 -0
package/cycleCAD-Architecture.pptx +0 -0
package/cycleCAD-Investor-Deck.pptx +0 -0
package/demo-mcp.sh +60 -0
package/docs/API-SERVER-SUMMARY.md +375 -0
package/docs/API-SERVER.md +667 -0
package/docs/CAM-EXAMPLES.md +344 -0
package/docs/CAM-INTEGRATION.md +612 -0
package/docs/CAM-QUICK-REFERENCE.md +199 -0
package/docs/CLI-INTEGRATION.md +510 -0
package/docs/CLI.md +872 -0
package/docs/MARKETPLACE-API-SCHEMA.json +564 -0
package/docs/MARKETPLACE-INTEGRATION.md +467 -0
package/docs/MARKETPLACE-SETUP.html +439 -0
package/docs/MCP-SERVER.md +403 -0
package/examples/api-client-example.js +488 -0
package/examples/api-client-example.py +359 -0
package/examples/batch-manufacturing.txt +28 -0
package/examples/batch-simple.txt +26 -0
package/model-marketplace.html +1273 -0
package/package.json +14 -3
package/server/api-server.js +1120 -0
package/server/mcp-server.js +1161 -0
package/test-api-server.js +432 -0
package/test-mcp.js +198 -0
package/~$cycleCAD-Investor-Deck.pptx +0 -0

package/app/index.html CHANGED Viewed

@@ -1276,6 +1276,17 @@
     }
   </style>
+  <!-- Token Engine — Initialize early so window.cycleCAD.tokens is available -->
+  <script src="./js/token-engine.js"></script>
+  <!-- New Architecture Modules -->
+  <script src="./js/material-library.js"></script>
+  <script src="./js/dfm-analyzer.js"></script>
+  <script src="./js/cam-pipeline.js"></script>
+  <script src="./js/connected-fabs.js"></script>
+  <script src="./js/ai-copilot.js"></script>
+  <script src="./js/collaboration.js"></script>
+  <script src="./js/collaboration-ui.js"></script>
 </head>
 <body>
   <div id="app">
@@ -1444,6 +1455,42 @@
         </button>
       </div>
+      <!-- Token Balance Indicator -->
+      <div class="toolbar-group">
+        <button class="toolbar-button" id="btn-token-balance" title="View Token Balance & Billing" style="background: linear-gradient(135deg, rgba(88,166,255,0.1), rgba(63,185,80,0.1)); border: 1px solid rgba(88,166,255,0.3);" onclick="document.querySelector('[data-tab=tokens]')?.click()">
+          <span class="toolbar-icon">💰</span>
+          <span class="toolbar-label" id="token-balance-label">1K Tokens</span>
+        </button>
+      </div>
+      <!-- AI & Analysis -->
+      <div class="toolbar-group">
+        <button class="toolbar-button" id="btn-ai-copilot" title="AI Copilot — Text-to-CAD, Voice Commands" style="background:rgba(139,92,246,0.1);border:1px solid rgba(139,92,246,0.3);">
+          <span class="toolbar-icon">✨</span>
+          <span class="toolbar-label">Copilot</span>
+        </button>
+        <button class="toolbar-button" id="btn-dfm" title="DFM Analyzer — Manufacturability Check" style="background:rgba(248,113,113,0.1);border:1px solid rgba(248,113,113,0.3);">
+          <span class="toolbar-icon">🏭</span>
+          <span class="toolbar-label">DFM</span>
+        </button>
+        <button class="toolbar-button" id="btn-materials" title="Material Library — 40+ PBR Materials" style="background:rgba(34,211,238,0.1);border:1px solid rgba(34,211,238,0.3);">
+          <span class="toolbar-icon">🎨</span>
+          <span class="toolbar-label">Materials</span>
+        </button>
+        <button class="toolbar-button" id="btn-cam" title="CAM Pipeline — Slicer, Toolpath, G-code" style="background:rgba(251,191,36,0.1);border:1px solid rgba(251,191,36,0.3);">
+          <span class="toolbar-icon">⚙</span>
+          <span class="toolbar-label">CAM</span>
+        </button>
+        <button class="toolbar-button" id="btn-fabs" title="Connected Fabs — Send to Fabrication" style="background:rgba(74,222,128,0.1);border:1px solid rgba(74,222,128,0.3);">
+          <span class="toolbar-icon">🏗</span>
+          <span class="toolbar-label">Fabs</span>
+        </button>
+        <button class="toolbar-button" id="btn-collab" title="Collaboration — Multi-User Sessions" style="background:rgba(96,165,250,0.1);border:1px solid rgba(96,165,250,0.3);">
+          <span class="toolbar-icon">👥</span>
+          <span class="toolbar-label">Collab</span>
+        </button>
+      </div>
       <!-- Agent API Panel -->
       <div class="toolbar-group">
         <button class="toolbar-button" id="btn-agent-panel" title="Agent Command Panel (Test API)">
@@ -1551,6 +1598,7 @@
           <button class="properties-tab active" data-tab="properties">Properties</button>
           <button class="properties-tab" data-tab="chat">Chat</button>
           <button class="properties-tab" data-tab="guide">Guide</button>
+          <button class="properties-tab" data-tab="tokens" style="margin-left: auto; background: linear-gradient(135deg, rgba(88,166,255,0.1), rgba(63,185,80,0.1)); border: 1px solid rgba(88,166,255,0.3);" title="Token Balance & Billing">💰 Tokens</button>
         </div>
         <!-- Properties Content -->
@@ -1564,6 +1612,7 @@
           <div id="tab-guide" style="display: none;">
             <!-- Rebuild guide populated by JavaScript -->
           </div>
+          <!-- Tokens tab will be populated by token-dashboard.js -->
         </div>
       </div>
     </div>
@@ -1656,6 +1705,7 @@
     import Assembly from './js/assembly.js';
     import { exportSketchToDXF, exportProjectionToDXF, exportMultiViewDXF, export3DDXF, downloadDXF } from './js/dxf-export.js';
     import { initAgentAPI } from './js/agent-api.js';
+    import { initTokenDashboard } from './js/token-dashboard.js';
     // ========== Application State ==========
     const APP = {
@@ -1713,6 +1763,38 @@
           );
         }
+        // 4b. Initialize Token Dashboard
+        const tokenTab = document.getElementById('tab-tokens');
+        if (tokenTab) {
+          const tokenDashboard = initTokenDashboard();
+          tokenTab.innerHTML = tokenDashboard.html;
+          tokenTab.style.display = 'none';
+          tokenTab.style.overflowY = 'auto';
+          // Initialize the dashboard events
+          tokenDashboard.init();
+          // Update toolbar balance indicator
+          function updateTokenBalanceLabel() {
+            const balance = window.cycleCAD?.tokens?.getBalance?.() || 0;
+            const label = document.getElementById('token-balance-label');
+            if (label) {
+              if (balance >= 1000) {
+                label.textContent = Math.floor(balance / 1000) + 'K Tokens';
+              } else {
+                label.textContent = balance + ' Tokens';
+              }
+            }
+          }
+          updateTokenBalanceLabel();
+          // Update label when tokens change
+          if (window.cycleCAD?.tokens?.on) {
+            window.cycleCAD.tokens.on('token-spent', updateTokenBalanceLabel);
+            window.cycleCAD.tokens.on('token-added', updateTokenBalanceLabel);
+            window.cycleCAD.tokens.on('month-reset', updateTokenBalanceLabel);
+          }
+        }
         // 5. Wire up toolbar buttons
         setupToolbar();
@@ -1889,7 +1971,33 @@
         console.log('[Agent API] Usage: window.cycleCAD.execute({ method: "meta.ping" })');
         console.log('[Agent API] Schema: window.cycleCAD.getSchema()');
-        console.log('cycleCAD initialized successfully');
+        // Initialize new architecture modules
+        if (window.cycleCAD?.materials?.init) {
+          window.cycleCAD.materials.init();
+          console.log('[Materials] Library initialized — ' + (window.cycleCAD.materials.getAll?.()?.length || '40+') + ' materials');
+        }
+        if (window.cycleCAD?.dfm?.init) {
+          window.cycleCAD.dfm.init();
+          console.log('[DFM] Analyzer initialized — 8 manufacturing processes');
+        }
+        if (window.cycleCAD?.cam?.init) {
+          window.cycleCAD.cam.init();
+          console.log('[CAM] Pipeline initialized — slicer, toolpath, G-code');
+        }
+        if (window.cycleCAD?.fabs?.init) {
+          window.cycleCAD.fabs.init();
+          console.log('[Fabs] Connected fabrication network initialized');
+        }
+        if (window.cycleCAD?.copilot?.init) {
+          window.cycleCAD.copilot.init();
+          console.log('[AI Copilot] Initialized — text-to-CAD, voice commands');
+        }
+        if (window.cycleCAD?.collab?.init) {
+          window.cycleCAD.collab.init();
+          console.log('[Collaboration] Session management initialized');
+        }
+        console.log('cycleCAD initialized successfully — all modules loaded');
         updateStatus('Ready');
       } catch (error) {
@@ -2302,6 +2410,14 @@
           document.getElementById('tab-properties').style.display = target === 'properties' ? 'block' : 'none';
           document.getElementById('tab-chat').style.display = target === 'chat' ? 'flex' : 'none';
           document.getElementById('tab-guide').style.display = target === 'guide' ? 'block' : 'none';
+          const tokenTab = document.getElementById('tab-tokens');
+          if (tokenTab) {
+            tokenTab.style.display = target === 'tokens' ? 'block' : 'none';
+            if (target === 'tokens') {
+              // Update token dashboard when switching to it
+              window.cycleCAD?.tokens?.on?.('panel-opened', () => {});
+            }
+          }
         });
       });
     }
@@ -2702,7 +2818,7 @@
       init();
     }
-    window.cycleCAD = { version: '1.0.0', APP, init };
+    window.cycleCAD = Object.assign(window.cycleCAD || {}, { version: '1.0.0', APP, init });
     // ========== Hard Reset (with browser detection) ==========
     const hardResetBtn = document.getElementById('btn-hard-reset');
@@ -3119,6 +3235,55 @@
       }
     });
+    // ========== New Module Toolbar Buttons ==========
+    function toggleModulePanel(moduleKey, panelId) {
+      let panel = document.getElementById(panelId);
+      if (panel) {
+        panel.style.display = panel.style.display === 'none' ? 'flex' : 'none';
+        return;
+      }
+      // Create floating panel
+      panel = document.createElement('div');
+      panel.id = panelId;
+      panel.style.cssText = 'position:fixed;top:60px;right:320px;width:400px;max-height:80vh;overflow-y:auto;background:var(--bg-secondary);border:1px solid var(--border-color);border-radius:8px;z-index:500;display:flex;flex-direction:column;box-shadow:var(--shadow-lg);';
+      const header = document.createElement('div');
+      header.style.cssText = 'display:flex;justify-content:space-between;align-items:center;padding:10px 14px;border-bottom:1px solid var(--border-color);background:var(--bg-tertiary);border-radius:8px 8px 0 0;cursor:move;';
+      const titles = {
+        'copilot-panel': '✨ AI Copilot',
+        'dfm-panel': '🏭 DFM Analyzer',
+        'materials-panel': '🎨 Material Library',
+        'cam-panel': '⚙ CAM Pipeline',
+        'fabs-panel': '🏗 Connected Fabs',
+        'collab-panel': '👥 Collaboration'
+      };
+      header.innerHTML = `<span style="font-weight:600;font-size:13px;">${titles[panelId] || moduleKey}</span><button onclick="document.getElementById('${panelId}').style.display='none'" style="background:none;border:none;color:var(--text-secondary);cursor:pointer;font-size:16px;">✕</button>`;
+      panel.appendChild(header);
+      const body = document.createElement('div');
+      body.style.cssText = 'padding:14px;flex:1;min-height:0;overflow-y:auto;font-size:12px;';
+      const mod = window.cycleCAD?.[moduleKey];
+      if (mod?.getUI) {
+        body.innerHTML = mod.getUI();
+      } else if (mod?.getStatus) {
+        const status = mod.getStatus();
+        body.innerHTML = `<div style="color:var(--text-secondary);line-height:1.8;">${JSON.stringify(status, null, 2).replace(/\n/g, '<br>')}</div>`;
+      } else {
+        body.innerHTML = `<div style="color:var(--accent-green);padding:12px;text-align:center;"><p style="font-weight:600;margin-bottom:8px;">Module Loaded</p><p style="color:var(--text-secondary);">Access via console:<br><code style="background:var(--bg-tertiary);padding:2px 6px;border-radius:3px;">window.cycleCAD.${moduleKey}</code></p></div>`;
+      }
+      panel.appendChild(body);
+      document.body.appendChild(panel);
+    }
+    document.getElementById('btn-ai-copilot')?.addEventListener('click', () => toggleModulePanel('copilot', 'copilot-panel'));
+    document.getElementById('btn-dfm')?.addEventListener('click', () => toggleModulePanel('dfm', 'dfm-panel'));
+    document.getElementById('btn-materials')?.addEventListener('click', () => toggleModulePanel('materials', 'materials-panel'));
+    document.getElementById('btn-cam')?.addEventListener('click', () => toggleModulePanel('cam', 'cam-panel'));
+    document.getElementById('btn-fabs')?.addEventListener('click', () => toggleModulePanel('fabs', 'fabs-panel'));
+    document.getElementById('btn-collab')?.addEventListener('click', () => toggleModulePanel('collab', 'collab-panel'));
   </script>
   <!-- Operation Dialogs -->
@@ -3468,6 +3633,6 @@
     </div>
   </div>
-  <span id="version-badge" style="position:fixed;bottom:10px;left:50%;transform:translateX(-50%);z-index:70;font-size:0.85rem;color:rgba(255,255,255,0.7);letter-spacing:0.1em;white-space:nowrap;padding:5px 14px;user-select:all;pointer-events:auto;font-family:monospace;font-weight:600;background:rgba(0,0,0,0.5);border:1px solid rgba(255,255,255,0.15);border-radius:6px;text-shadow:0 1px 3px rgba(0,0,0,0.5);" title="cycleCAD version">cycleCAD v0.2.0</span>
+  <span id="version-badge" style="position:fixed;bottom:10px;left:50%;transform:translateX(-50%);z-index:70;font-size:0.85rem;color:rgba(255,255,255,0.7);letter-spacing:0.1em;white-space:nowrap;padding:5px 14px;user-select:all;pointer-events:auto;font-family:monospace;font-weight:600;background:rgba(0,0,0,0.5);border:1px solid rgba(255,255,255,0.15);border-radius:6px;text-shadow:0 1px 3px rgba(0,0,0,0.5);" title="cycleCAD version">cycleCAD v0.2.2</span>
 </body>
 </html>

package/app/js/TOKEN-INTEGRATION.md ADDED Viewed

@@ -0,0 +1,391 @@
+# $CYCLE Token Engine Integration Guide
+## Overview
+The `$CYCLE` Token Engine is a per-operation billing system for cycleCAD, inspired by the Claude API token model. Every CAD operation costs tokens, and tokens can be purchased, earned, or generated through cache hits.
+## Files Created
+1. **token-engine.js** (~750 lines)
+   - Core billing engine with balance management
+   - Double-entry ledger (debit buyer, credit creator + platform)
+   - Per-operation pricing (2-100 tokens per operation)
+   - Tier system (FREE/PRO/ENTERPRISE)
+   - Cache discounts (10% repeat access within 24h)
+   - Batch discounts (25% for 10+, 50% for 100+)
+   - Escrow system for manufacturing jobs
+   - Token purchase flow (Stripe placeholder)
+   - Event system for real-time updates
+   - All data persisted to localStorage
+2. **token-dashboard.js** (~600 lines)
+   - Rich UI dashboard for balance, transactions, usage analytics
+   - 4 dialog systems: estimate price, purchase tokens, upgrade tier, view history
+   - Real-time balance indicator in toolbar
+   - Recent activity list
+   - Top operations breakdown
+   - Tier information cards
+3. **index.html** (Modified)
+   - Added token-engine.js `<script>` tag in head
+   - Added import for token-dashboard.js in main script
+   - Added "💰 Tokens" tab to properties panel
+   - Added token balance indicator button to toolbar
+   - Wired tab switching and balance updates
+## API Usage
+### Balance Management
+```javascript
+// Get current balance
+const balance = window.cycleCAD.tokens.getBalance();
+// Get detailed info
+const info = window.cycleCAD.tokens.getBalanceInfo();
+// Returns: { balance, tier, monthlyAllowance, usedThisMonth, remainingThisMonth, tierColor, creatorRoyalty }
+// Add tokens (for purchases/earnings)
+window.cycleCAD.tokens.addTokens(1000, 'stripe_purchase', { purchaseId: '...' });
+// Spend tokens for operations
+try {
+  window.cycleCAD.tokens.spendTokens(10, 'model.export.step', { fileSize: 2.5 });
+} catch (err) {
+  console.error('Insufficient tokens:', err.message);
+}
+```
+### Operation Pricing
+```javascript
+// Get price for an operation (includes cache & batch discounts)
+const price = window.cycleCAD.tokens.getPriceForOperation('model.export.step', {});
+// Estimate cost with optional batch size
+const estimate = window.cycleCAD.tokens.estimateOperation('model.export.step', {
+  batchSize: 10  // 25% discount applied
+});
+// Returns: { operation, basePrice, batchSize, batchDiscount, finalPrice, cached }
+// Charge for operation (returns actual price paid including discounts)
+const charge = window.cycleCAD.tokens.chargeForOperation('model.export.step', {}, {
+  fileSize: 2.5
+});
+// Returns: { price, discount }
+```
+### Transaction History
+```javascript
+// Get transaction history with optional filters
+const history = window.cycleCAD.tokens.getTransactionHistory({
+  type: 'debit',           // 'debit' or 'credit'
+  operation: 'model.export.step',
+  after: '2026-03-25T00:00:00Z',
+  minAmount: 5,
+  limit: 50
+});
+// Get usage by operation (this month)
+const usage = window.cycleCAD.tokens.getUsageByOperation();
+// Returns: { 'model.export.stl': { count: 5, totalTokens: 10 }, ... }
+// Get cost breakdown
+const breakdown = window.cycleCAD.tokens.getCostBreakdown();
+// Returns: [ { operation, count, totalTokens, averagePerOp, costInEuros }, ... ]
+// Get monthly usage
+const used = window.cycleCAD.tokens.getMonthlyUsage();
+```
+### Escrow System (for Manufacturing)
+```javascript
+// Create escrow for a fab job
+const escrow = window.cycleCAD.tokens.createEscrow(500, 'job_123', 'fab_456', {
+  service: 'CNC milling',
+  estimatedCost: 50
+});
+// Returns: { escrowId, amount, status: 'held' }
+// Release tokens to fab when job is delivered
+window.cycleCAD.tokens.releaseEscrow('escrow_1');
+// Cancel escrow and refund tokens
+window.cycleCAD.tokens.cancelEscrow('escrow_1');
+// Check escrow status
+const status = window.cycleCAD.tokens.getEscrowStatus('escrow_1');
+```
+### Tier Management
+```javascript
+// Set user tier
+window.cycleCAD.tokens.setTier('PRO');  // 'FREE', 'PRO', or 'ENTERPRISE'
+// Get tier info
+const tier = window.cycleCAD.tokens.getTier();
+// Returns: { tier, tokensPerMonth, creatorRoyalty, color, balance, monthlyTokens }
+```
+### Token Purchases
+```javascript
+// Initiate token purchase (opens Stripe checkout in real app)
+const session = window.cycleCAD.tokens.purchaseTokens(1000, 'stripe');
+// Returns: { id, type, tokens, euros, method, status, stripeCheckoutUrl, metadata }
+// Crypto purchase
+const cryptoSession = window.cycleCAD.tokens.purchaseWithCrypto(10, 'USDC');
+// Complete purchase after payment confirmation
+window.cycleCAD.tokens.completePurchase('purchase_123', 1000);
+```
+### Events
+```javascript
+// Subscribe to token events
+window.cycleCAD.tokens.on('token-spent', (data) => {
+  console.log('Spent', data.amount, 'tokens on', data.operation);
+});
+window.cycleCAD.tokens.on('token-added', (data) => {
+  console.log('Added', data.amount, 'tokens from', data.source);
+});
+window.cycleCAD.tokens.on('month-reset', (data) => {
+  console.log('Monthly allowance reset:', data.balance, 'tokens');
+});
+window.cycleCAD.tokens.on('tier-changed', (data) => {
+  console.log('Upgraded from', data.oldTier, 'to', data.newTier);
+});
+window.cycleCAD.tokens.on('escrow-created', (data) => {
+  console.log('Escrow created:', data.escrowId);
+});
+// Unsubscribe
+window.cycleCAD.tokens.off('token-spent', listener);
+```
+### Debug & Export
+```javascript
+// Export token data as JSON
+const data = window.cycleCAD.tokens.exportDataAsJSON();
+// Clear all token data (requires confirmation)
+window.cycleCAD.tokens.clearAllData();
+```
+## Operation Pricing Table
+All prices in tokens (100 tokens = €1):
+### Model Operations
+- Export as STL: 2 tokens
+- Export as STEP: 10 tokens
+- Export as glTF: 3 tokens
+- Export as OBJ: 2 tokens
+- Export as JSON: 1 token
+- Export as DXF: 5 tokens
+- Download mesh (read-only): 50 tokens
+- Download parametric: 200 tokens
+- Download with full IP: 1,000 tokens
+### AI Operations
+- Part identifier: 5 tokens
+- Design review: 15 tokens
+- Material suggestion: 3 tokens
+- Fastener suggestion: 4 tokens
+- Generative design: 50 tokens
+### CAM Operations
+- Slice for 3D print: 20 tokens
+- CNC toolpath: 75 tokens
+- Laser path: 30 tokens
+- Foam cutting: 25 tokens
+### Manufacturing
+- Submit fab job (escrow): 100 tokens
+- Request quote: 10 tokens
+- List vendors: 5 tokens
+### Analysis
+- Thermal analysis: 20 tokens
+- Stress analysis: 30 tokens
+- Clearance check: 15 tokens
+- Weight estimation: 2 tokens
+- Cost analysis: 5 tokens
+### Marketplace & Collaboration
+- Publish design: 0 tokens (free)
+- List design: 0 tokens (free)
+- Download design: 25 tokens
+- Share link: 0 tokens (free)
+- Comments: 0 tokens (free)
+- Collaboration workspace: 50 tokens/month
+## Tier System
+### FREE Tier
+- 1,000 tokens/month
+- 70% creator royalty
+- Basic exports
+- Community support
+### PRO Tier (€49/month)
+- 10,000 tokens/month
+- 80% creator royalty
+- STEP import/export
+- AI design review
+- Priority support
+### ENTERPRISE Tier (€299/month)
+- 100,000 tokens/month
+- 90% creator royalty
+- Unlimited STEP
+- Advanced analytics
+- SLA & support
+- Custom integrations
+## Discounts
+### Cache Discount
+- First access: full price
+- Repeat access within 24h: 10% of original price
+- Cached operations tracked in localStorage
+### Batch Discount
+- Single operation: full price
+- Batch of 10+ operations: 25% discount
+- Batch of 100+ operations: 50% discount
+## Double-Entry Ledger
+Every transaction creates entries for:
+1. **Debit**: Charged to the user
+2. **Credit**: Split between creator (70-90%) and platform (10-30%)
+For example, exporting a STEP file (10 tokens):
+- User debited 10 tokens
+- Creator credited 8 tokens (80% on PRO tier)
+- Platform credited 2 tokens (20% fee)
+## localStorage Keys
+- `cyclecad_token_balance` — current token balance
+- `cyclecad_token_ledger` — transaction history (JSON array)
+- `cyclecad_token_cache` — cached operations (JSON object)
+- `cyclecad_token_escrow` — active escrows (JSON object)
+- `cyclecad_user_tier` — current tier ('FREE', 'PRO', 'ENTERPRISE')
+- `cyclecad_month_start` — month start date for allowance reset
+## Integration Checklist
+- [x] token-engine.js created and initialized in head
+- [x] token-dashboard.js created and imported
+- [x] Token tab added to properties panel (right side)
+- [x] Token balance button added to toolbar
+- [x] Token balance indicator updates in real-time
+- [x] All UI dialogs created (estimate, purchase, upgrade, history)
+- [x] Event system wired to dashboard updates
+- [x] localStorage persistence implemented
+- [x] Monthly allowance reset logic
+- [x] Cache discount system
+## Next Steps (Optional Enhancements)
+1. **Stripe Integration**: Connect purchaseTokens() to real Stripe checkout
+2. **Crypto Payments**: Implement purchaseWithCrypto() with Polygon/USDC
+3. **Creator Dashboard**: Show royalty earnings and payout history
+4. **Cost Estimation**: Show cost before operations (prompt before spending)
+5. **Cost Breakdown**: Pie chart showing token spend by operation type
+6. **Invoice Export**: Generate PDF invoices for purchases
+7. **Team Billing**: Support shared team tokens pool
+8. **Usage Alerts**: Notify when approaching monthly limit
+9. **Subscription Management**: Add cancel/pause subscription flows
+10. **Analytics Dashboard**: Historical usage trends and projections
+## Testing
+To test the token engine in browser console:
+```javascript
+// Check balance
+console.log(window.cycleCAD.tokens.getBalance());
+// Spend tokens
+window.cycleCAD.tokens.spendTokens(5, 'test.operation', { test: true });
+// View history
+console.log(window.cycleCAD.tokens.getTransactionHistory({ limit: 10 }));
+// Upgrade tier
+window.cycleCAD.tokens.setTier('PRO');
+// View tier info
+console.log(window.cycleCAD.tokens.getTier());
+```
+## Architecture
+```
+┌─────────────────────────────────────────────────────────────┐
+│  cycleCAD Browser App                                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │  Agent API / User Actions                              │ │
+│  │  (trigger operations)                                  │ │
+│  └─────────────────┬──────────────────────────────────────┘ │
+│                    │                                         │
+│  ┌────────────────▼───────────────────────────────────────┐ │
+│  │  Token Engine (token-engine.js)                         │ │
+│  │  - Balance tracking                                    │ │
+│  │  - Operation pricing                                  │ │
+│  │  - Ledger management                                  │ │
+│  │  - Tier system                                        │ │
+│  │  - Event emissions                                    │ │
+│  └─────────────────┬──────────────────────────────────────┘ │
+│                    │                                         │
+│  ┌────────────────▼───────────────────────────────────────┐ │
+│  │  Token Dashboard UI (token-dashboard.js)                │ │
+│  │  - Balance card                                        │ │
+│  │  - Transaction list                                   │ │
+│  │  - Usage analytics                                    │ │
+│  │  - Purchase dialogs                                   │ │
+│  │  - Tier upgrade flows                                 │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                    │                                         │
+│  ┌────────────────▼───────────────────────────────────────┐ │
+│  │  localStorage (Persistence)                             │ │
+│  │  - cyclecad_token_balance                              │ │
+│  │  - cyclecad_token_ledger                               │ │
+│  │  - cyclecad_token_cache                                │ │
+│  │  - cyclecad_token_escrow                               │ │
+│  │  - cyclecad_user_tier                                  │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+## Files Modified
+1. `/app/index.html`
+   - Added `<script src="./js/token-engine.js"></script>` in head
+   - Added `import { initTokenDashboard } from './js/token-dashboard.js';`
+   - Added "💰 Tokens" tab button to properties panel
+   - Added token balance indicator button to toolbar
+   - Added token dashboard initialization and event wiring
+   - Updated tab switching logic to include tokens tab
+## Questions?
+For API questions, inspect `window.cycleCAD.tokens` directly or check the source in token-engine.js.
+The token system is **opt-in**: if you don't call the API, tokens aren't spent. Only operations that explicitly call `chargeForOperation()` will incur costs.

package/app/js/agent-api.js CHANGED Viewed

@@ -70,8 +70,8 @@ export function initAgentAPI({ viewport, sketch, operations, advancedOps, export
   eventListeners = {};
   console.log(`[Agent API] Initialized. Session: ${sessionId}`);
-  // Expose globally for external agent access
-  window.cycleCAD = {
+  // Expose globally for external agent access (merge, don't overwrite — other modules already registered)
+  window.cycleCAD = Object.assign(window.cycleCAD || {}, {
     execute,
     executeMany,
     executeBatch,
@@ -85,7 +85,7 @@ export function initAgentAPI({ viewport, sketch, operations, advancedOps, export
     canUndo,
     canRedo,
     _debug: { viewport, sketch, operations, advancedOps, exportModule, appState, tree, assembly }
-  };
+  });
   return { sessionId };
 }