cyclecad 3.7.0 → 3.9.0

package/app/js/modules/smart-parts.js

@@ -1,15 +1,72 @@
 /**
- * Smart Parts Library with AI Search
+ * @fileoverview Smart Parts Library with AI Search
+ * @module CycleCAD/SmartParts
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
  *
- * Provides access to 200+ standard parts with:
- * - AI-powered natural language search
- * - 3D parametric geometry generation
- * - Supplier part number cross-reference
- * - BOM management and export
- * - Real-time pricing estimation
+ * @description
+ * Unified smart parts catalog with 200+ standard mechanical parts. Features AI-powered
+ * natural language search (fuzzy matching), 3D parametric geometry generation for all parts,
+ * supplier part number cross-reference (McMaster-Carr, MISUMI, Digi-Key), BOM management and export,
+ * real-time pricing from multiple suppliers, and smart consolidation (combines duplicate parts).
  *
- * @namespace CycleCAD.SmartParts
- * @requires THREE.js
+ * @example
+ * // Search for parts using natural language
+ * const results = window.CycleCAD.SmartParts.execute('search', {query: 'm3 socket head cap screw'});
+ *
+ * // Add part to BOM
+ * window.CycleCAD.SmartParts.execute('addToBOM', {partId: 'fastener_shcs_m3_8', quantity: 10});
+ *
+ * // Generate 3D geometry for part
+ * const geometry = window.CycleCAD.SmartParts.execute('generateGeometry', {partId: 'fastener_shcs_m3_8'});
+ *
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
+ */
+
+/**
+ * @typedef {Object} CatalogPart
+ * @property {string} id - Unique part identifier
+ * @property {string} name - Human-readable part name
+ * @property {string} category - Part category (e.g., 'Fasteners', 'Bearings')
+ * @property {string} subcategory - Subcategory (e.g., 'Socket Head Cap Screws')
+ * @property {string} standard - Standard designation (e.g., 'ISO 4762', 'ANSI B18.3')
+ * @property {Object} dimensions - Parametric dimensions {dia, length, headDia, etc.}
+ * @property {string} material - Material designation
+ * @property {string} finish - Surface finish (e.g., 'Zinc Plated', 'Stainless')
+ * @property {number} weight - Weight in grams
+ * @property {Object} supplier - Supplier part numbers {mcmaster, misumi, digi, amazon}
+ * @property {Object} price - Pricing in different currencies {usd, eur, gbp}
+ * @property {Array<string>} tags - Search tags (for fuzzy matching)
+ */
+
+/**
+ * @typedef {Object} SearchResult
+ * @property {CatalogPart} part - The matched part
+ * @property {number} score - Match score 0-1 (1.0 = perfect match)
+ * @property {string} reason - Why this matched (e.g., 'tag match', 'description match')
+ */
+
+/**
+ * @typedef {Object} BOMEntry
+ * @property {string} partId - Reference to catalog part
+ * @property {CatalogPart} partData - Full part information
+ * @property {number} quantity - Number of units required
+ * @property {number} costPerUnit - Unit price in default currency
+ * @property {number} totalCost - quantity × costPerUnit
+ * @property {string} notes - User notes (e.g., "green anodized")
+ */
+
+/**
+ * @typedef {Object} SupplierInfo
+ * @property {string} supplier - Supplier name (e.g., 'McMaster', 'MISUMI')
+ * @property {string} partNumber - Supplier's part number
+ * @property {string} url - Direct link to part on supplier website
+ * @property {number} leadTime - Delivery time in days
+ * @property {number} minimumOrder - Minimum order quantity
+ * @property {number} unitPrice - Current unit price
+ * @property {number} stockLevel - Available inventory (-1 if unknown)
  */
 
 window.CycleCAD = window.CycleCAD || {};
@@ -616,6 +673,15 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} dims - { dia, length, headDia, headHeight }
    * @returns {THREE.Group}
    */
+  /**
+   * Generate 3D bolt/screw geometry from dimensions (internal helper)
+   *
+   * Parametric socket head cap screw geometry: cylindrical shank + hex socket head.
+   * Creates proper proportions per ISO 4762 standard. Head includes drive recess.
+   *
+   * @param {Object} dims - Bolt dimensions {dia, length, headDia, headHeight, socketSize}
+   * @returns {THREE.BufferGeometry} 3D bolt mesh
+   */
   function generateBolt(dims) {
     const group = new THREE.Group();
 
@@ -963,6 +1029,15 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} part - Part catalog entry
    * @returns {THREE.Group}
    */
+  /**
+   * Dispatch parametric geometry generation for any part in catalog
+   *
+   * Routes to specialized generator function based on part category.
+   * Caches geometry results for repeated access. Returns Three.js mesh ready for scene.
+   *
+   * @param {CatalogPart} part - Part from catalog
+   * @returns {THREE.BufferGeometry} Generated 3D geometry
+   */
   function getPartGeometry(part) {
     if (geometryCache.has(part.id)) {
       return geometryCache.get(part.id).clone();
@@ -1022,6 +1097,15 @@ window.CycleCAD.SmartParts = (() => {
    * @param {string} query
    * @returns {string[]}
    */
+  /**
+   * Tokenize search query into words for matching (internal helper)
+   *
+   * Splits on whitespace, removes common words (stop words), converts to lowercase.
+   * Expands abbreviations (e.g., "dia" → "diameter") before tokenization.
+   *
+   * @param {string} query - Natural language search query
+   * @returns {Array<string>} Processed tokens
+   */
   function tokenizeQuery(query) {
     return query
       .toLowerCase()
@@ -1036,6 +1120,17 @@ window.CycleCAD.SmartParts = (() => {
    * @param {string} b
    * @returns {number} 0-1
    */
+  /**
+   * Compute string similarity using Levenshtein edit distance (internal helper)
+   *
+   * Measures minimum edits (insert/delete/replace) needed to transform a→b.
+   * Normalized 0-1: 1.0 = identical, 0.0 = completely different.
+   * Used for typo tolerance in search (e.g., "dieameter" matches "diameter").
+   *
+   * @param {string} a - First string
+   * @param {string} b - Second string
+   * @returns {number} Similarity score 0-1
+   */
   function stringSimilarity(a, b) {
     a = a.toLowerCase();
     b = b.toLowerCase();
@@ -1084,6 +1179,27 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} filters
    * @returns {Array} Sorted results with scores
    */
+  /**
+   * Search parts catalog using natural language query with optional filters
+   *
+   * Implements multi-strategy fuzzy matching:
+   * 1. Exact keyword match in tags (score 1.0)
+   * 2. Substring match in name/description (score 0.9)
+   * 3. Levenshtein edit distance for typo tolerance (score 0.7-0.8)
+   * 4. Category/material filtering to narrow results
+   *
+   * Results sorted by score (highest first). Duplicate parts consolidated.
+   *
+   * @param {string} query - Natural language search query (e.g., "m3 socket head cap screw 10mm")
+   * @param {Object} [filters={}] - Optional filters
+   * @param {string} filters.category - Filter by category (e.g., 'Fasteners')
+   * @param {string} filters.material - Filter by material (e.g., 'Steel')
+   * @param {number} filters.maxPrice - Price ceiling in default currency
+   * @returns {Array<SearchResult>} Ranked search results (best match first)
+   * @example
+   * const results = searchCatalog('iso 4762 m5 socket head cap screw 16mm', {material: 'Steel'});
+   * // → [{part: {...}, score: 0.98, reason: 'tag match'}, ...]
+   */
   function searchCatalog(query, filters = {}) {
     if (!query || query.trim().length === 0) {
       return Object.values(partCatalog).slice(0, 30);
@@ -1285,6 +1401,17 @@ window.CycleCAD.SmartParts = (() => {
    * @param {Object} config - { quantity, size, material, finish }
    * @returns {Object} { id, part, mesh, position }
    */
+  /**
+   * Insert part instance into 3D scene at specified position
+   *
+   * Generates geometry, creates THREE.Mesh, applies material and transform,
+   * adds to scene. Optionally applies color, scale, and user-specified configurations.
+   *
+   * @param {CatalogPart} part - Part from catalog
+   * @param {THREE.Vector3} [position] - World position for part placement
+   * @param {Object} [config={}] - Configuration {color, scale, visible, castShadow, receiveShadow}
+   * @returns {THREE.Mesh} Instance mesh added to scene
+   */
   function insertPart(part, position = new THREE.Vector3(0, 0, 0), config = {}) {
     const geometry = getPartGeometry(part);
     const mesh = geometry.clone();
@@ -1586,6 +1713,15 @@ window.CycleCAD.SmartParts = (() => {
    * Initialize module
    * @param {THREE.Scene} sceneRef
    */
+  /**
+   * Initialize SmartParts module with Three.js scene
+   *
+   * Sets up UI panel, search bar, category filters, BOM viewer,
+   * pricing display, and supplier links. Must be called once before execute() calls.
+   *
+   * @param {THREE.Scene} sceneRef - The Three.js scene for part insertion
+   * @returns {void}
+   */
   function init(sceneRef) {
     scene = sceneRef;
     console.log('[SmartParts] Initialized with', Object.keys(partCatalog).length, 'parts');
@@ -1665,6 +1801,40 @@ window.CycleCAD.SmartParts = (() => {
    * @param {string} command
    * @param {Object} params
    */
+  /**
+   * Execute command in SmartParts module (public API)
+   *
+   * Commands:
+   * - 'search': Search parts catalog with natural language query
+   * - 'getCatalog': Get full parts list (optionally filtered)
+   * - 'generateGeometry': Get 3D geometry for a part
+   * - 'insertPart': Add part instance to 3D scene
+   * - 'addToBOM': Add part to Bill of Materials
+   * - 'removeBOM': Remove part from BOM
+   * - 'consolidateBOM': Merge duplicate parts in BOM
+   * - 'exportBOM': Export BOM as CSV or Excel
+   * - 'getSuppliersForPart': Get all supplier options for a part
+   * - 'compareSuppliers': Compare pricing/lead time across suppliers
+   * - 'getCategories': List all part categories
+   * - 'getPricingHistory': Get historical pricing for a part
+   *
+   * @param {string} command - Command name
+   * @param {Object} [params={}] - Command parameters (varies by command)
+   * @param {string} params.query - For 'search': natural language query
+   * @param {string} params.partId - For most commands: part identifier
+   * @param {number} params.quantity - For 'addToBOM': quantity to add
+   * @param {string} params.format - For 'exportBOM': 'csv'|'excel'|'json'
+   * @returns {Object} Command result (varies by command)
+   * @example
+   * // Search for parts
+   * const results = window.CycleCAD.SmartParts.execute('search', {query: 'm5 socket head cap screw'});
+   *
+   * // Add to BOM
+   * window.CycleCAD.SmartParts.execute('addToBOM', {partId: results[0].part.id, quantity: 10});
+   *
+   * // Export BOM
+   * const bomData = window.CycleCAD.SmartParts.execute('exportBOM', {format: 'excel'});
+   */
   function execute(command, params = {}) {
     switch (command) {
       case 'search':

package/app/js/modules/text-to-cad.js

@@ -1,19 +1,25 @@
 /**
- * TextToCAD - Natural Language to 3D Geometry with Live Preview
+ * @fileoverview TextToCAD - Natural Language to 3D Geometry with Live Preview
+ * @module CycleCAD/TextToCAD
+ * @version 3.7.0
+ * @author cycleCAD Team
+ * @license MIT
+ *
+ * @description
  * Converts English descriptions to parametric 3D CAD models in real-time.
+ * Features NLP parser for 50+ shape types, live ghost preview, multi-step builder with state awareness,
+ * Gemini Flash API integration with local fallback, 3D dimension annotations, undo/redo, variant generation,
+ * and production-ready error handling.
+ *
+ * @example
+ * // Initialize the module
+ * window.CycleCAD.TextToCAD.init(scene, renderer);
  *
- * @module TextToCAD
- * @version 1.0.0
+ * // Parse natural language and generate geometry
+ * const result = window.CycleCAD.TextToCAD.execute('parseDescription', 'create a cylinder 50mm diameter 80mm tall');
  *
- * Features:
- * - NLP parser for 50+ shape types and features
- * - Live preview with ghost geometry as you type
- * - Multi-step builder with state awareness
- * - Gemini Flash API integration (with local fallback)
- * - 3D dimension annotations
- * - Undo/redo per step
- * - Variant generation (3 alternatives)
- * - Production-ready error handling
+ * @requires THREE (Three.js r170)
+ * @see {@link https://cyclecad.com/docs/killer-features|Killer Features Guide}
  */
 
 (function initTextToCAD() {
@@ -35,7 +41,58 @@
     lastAction: null
   };
 
+  // ========== TYPEDEFS ==========
+  /**
+   * @typedef {Object} ParseResult
+   * @property {string} intent - User intent: 'create', 'add', 'modify', 'combine', 'pattern', 'export'
+   * @property {string} primaryShape - Primary shape type (e.g., 'cylinder', 'box')
+   * @property {Object} dimensions - Extracted numeric dimensions in mm
+   * @property {Array} features - Array of feature objects (holes, fillets, etc.)
+   * @property {Object} relationships - Spatial relationships between components
+   * @property {Object} parameters - Computed parameters for shape generation
+   * @property {number} confidence - Confidence score 0-1
+   */
+
+  /**
+   * @typedef {Object} ShapeVocab
+   * @property {Array<string>} alias - Alternative names for the shape
+   * @property {Array<string>} params - Parameter names this shape accepts
+   */
+
+  /**
+   * @typedef {Object} FeatureSpec
+   * @property {string} type - Feature type: 'hole', 'fillet', 'chamfer', 'pattern', 'counterbore', etc.
+   * @property {Object} params - Feature parameters
+   * @property {number} diameter - For hole features
+   * @property {number} depth - For counterbore/countersink
+   * @property {string} direction - For patterns: 'radial' or 'rectangular'
+   */
+
+  /**
+   * @typedef {Object} BuildStep
+   * @property {number} index - Step number
+   * @property {string} description - User's natural language description
+   * @property {ParseResult} parsed - Parsed specification
+   * @property {THREE.Object3D} geometry - Generated 3D geometry
+   * @property {number} timestamp - Creation time
+   */
+
   // ========== SHAPE VOCABULARY & PATTERNS ==========
+
+  /**
+   * Vocabulary of recognized shapes with aliases and parameter names
+   * @constant {Object.<string, ShapeVocab>}
+   * @property {ShapeVocab} cylinder - Cylindrical shape (aliases: cyl, tube, pipe)
+   * @property {ShapeVocab} box - Rectangular block (aliases: cube, block, rectangular)
+   * @property {ShapeVocab} sphere - Spherical shape (aliases: ball, round)
+   * @property {ShapeVocab} cone - Conical shape (aliases: taper)
+   * @property {ShapeVocab} torus - Toroidal shape (aliases: donut, ring, washer)
+   * @property {ShapeVocab} gear - Gear teeth (aliases: cog, sprocket)
+   * @property {ShapeVocab} flange - Cylindrical collar (aliases: rim, collar)
+   * @property {ShapeVocab} shaft - Rotating shaft (aliases: axle, spindle)
+   * @property {ShapeVocab} housing - Enclosure (aliases: enclosure, case, container)
+   * @property {ShapeVocab} keyway - Key slot (aliases: key-slot)
+   */
   const SHAPE_VOCAB = {
     // Basic primitives
     cylinder: { alias: ['cyl', 'tube', 'pipe'], params: ['diameter', 'radius', 'height', 'tall'] },
@@ -94,8 +151,17 @@
 
   /**
    * Parse natural language description into structured CAD commands
-   * @param {string} input - English description
-   * @returns {Object} Structured geometry specification
+   *
+   * Performs multi-stage NLP pipeline: intent detection → shape recognition → dimension extraction →
+   * feature identification → relationship analysis → parameter computation → confidence scoring.
+   * Uses regex patterns and statistical scoring for robustness with imperfect input.
+   *
+   * @param {string} input - English description of part to create
+   * @returns {ParseResult|null} Structured geometry specification or null if unparseable
+   * @throws {Error} If input contains invalid UTF-8 or is longer than 2000 characters
+   * @example
+   * const spec = parseDescription('create cylinder 50mm diameter 80mm tall with 10mm hole');
+   * // Returns: { intent: 'create', primaryShape: 'cylinder', dimensions: {...}, features: [...], confidence: 0.92 }
    */
   function parseDescription(input) {
     if (!input || input.trim().length === 0) {
@@ -128,9 +194,17 @@
   }
 
   /**
-   * Detect user intent from input
-   * @param {string} input
-   * @returns {string} Intent type
+   * Detect user intent (action) from natural language input
+   *
+   * Maps keywords and patterns to one of 6 primary intents. Uses priority-ordered regex matching
+   * to distinguish between creation, modification, combination, and export workflows.
+   *
+   * @param {string} input - Natural language description
+   * @returns {string} Intent type: 'create'|'add'|'modify'|'combine'|'pattern'|'export'
+   * @example
+   * detectIntent('make a cylinder') // → 'create'
+   * detectIntent('add a hole') // → 'add'
+   * detectIntent('fillet the edges') // → 'modify'
    */
   function detectIntent(input) {
     const lower = input.toLowerCase();
@@ -144,9 +218,18 @@
   }
 
   /**
-   * Detect primary shape from natural language
-   * @param {string} input
-   * @returns {string|null} Shape type
+   * Detect primary shape type from natural language input
+   *
+   * Uses vocabulary lookup followed by heuristic fallback. Checks all registered shapes and their aliases
+   * using case-insensitive word-boundary regex matching. Maintains a ranked preference order for
+   * common shapes (cylinder > box > sphere) when multiple matches exist.
+   *
+   * @param {string} input - Natural language description
+   * @returns {string|null} Shape type (e.g., 'cylinder', 'box', 'sphere') or null if no match
+   * @example
+   * detectShape('create a cylindrical tube') // → 'cylinder'
+   * detectShape('make a round ball') // → 'sphere'
+   * detectShape('totally ambiguous text') // → null
    */
   function detectShape(input) {
     const lower = input.toLowerCase();
@@ -167,9 +250,18 @@
   }
 
   /**
-   * Extract numerical dimensions with unit conversion
-   * @param {string} input
-   * @returns {Object} Dimensions in mm
+   * Extract numerical dimensions and convert to millimeters
+   *
+   * Multi-pass extraction: first identifies all numbers with explicit units (mm/cm/in/m) using regex patterns,
+   * then performs context-aware labeling based on dimension order (diameter → height → width → depth).
+   * Supports explicit parameter names (e.g., "diameter 50mm", "height 80mm") and implicit positional inference.
+   * Handles ambiguous units by preferring explicit labels.
+   *
+   * @param {string} input - Natural language with measurements
+   * @returns {Object} Dimensions object with keys like {diameter, height, width, depth, etc.} all in mm
+   * @example
+   * extractDimensions('cylinder 50mm dia 80 tall') // → {diameter: 50, height: 80, radius: 25}
+   * extractDimensions('2 inch width and 3cm depth') // → {width: 50.8, depth: 30}
    */
   function extractDimensions(input) {
     const dimensions = {};
@@ -229,9 +321,16 @@
   }
 
   /**
-   * Extract features from input
-   * @param {string} input
-   * @returns {Array} Feature specifications
+   * Extract manufacturing features from natural language description
+   *
+   * Identifies hole, counterbore, countersink, thread, fillet, chamfer, pattern, and slot features
+   * using regex pattern matching. Returns array of feature specs with extracted parameters.
+   *
+   * @param {string} input - Natural language description
+   * @returns {Array<FeatureSpec>} Array of feature specifications
+   * @example
+   * extractFeatures('cylinder with 10mm hole, 5mm fillet, and 4x pattern')
+   * // → [{type: 'hole', diameter: 10}, {type: 'fillet', radius: 5}, {type: 'pattern', count: 4}]
    */
   function extractFeatures(input) {
     const features = [];
@@ -399,10 +498,17 @@
   }
 
   /**
-   * Convert value to millimeters
-   * @param {number} value
-   * @param {string} unit
-   * @returns {number} Value in mm
+   * Convert measurement value to millimeters (internal utility)
+   *
+   * Handles four common unit systems: metric (mm/cm/m) and imperial (inches).
+   * Used internally by extractDimensions for consistent unit handling.
+   *
+   * @param {number} value - Numeric value in source units
+   * @param {string} unit - Unit type: 'mm'|'cm'|'inch'|'m'
+   * @returns {number} Converted value in millimeters
+   * @example
+   * convertToMM(2, 'inch') // → 50.8
+   * convertToMM(5, 'cm') // → 50
    */
   function convertToMM(value, unit) {
     switch (unit) {
@@ -417,9 +523,18 @@
   // ========== GEOMETRY GENERATION (~300 lines) ==========
 
   /**
-   * Generate THREE.js geometry from parsed specification
-   * @param {Object} spec - Parsed CAD specification
-   * @returns {THREE.Group} Composite 3D geometry
+   * Generate THREE.js 3D geometry from parsed CAD specification
+   *
+   * Dispatcher function that creates appropriate Three.js primitives based on shape type.
+   * Applies features (holes, fillets, patterns) to base geometry. Returns composite group
+   * containing all geometry and feature visualizations.
+   *
+   * @param {ParseResult} spec - Parsed CAD specification with shape and parameters
+   * @returns {THREE.Group|null} Composite 3D geometry with all features applied, or null if invalid
+   * @example
+   * const spec = parseDescription('cylinder 50mm diameter 80mm tall with 10mm hole');
+   * const geometry = generateGeometry(spec);
+   * scene.add(geometry);
    */
   function generateGeometry(spec) {
     if (!spec || !spec.primaryShape) {
@@ -542,6 +657,17 @@
    * @param {Object} params
    * @returns {THREE.BufferGeometry}
    */
+  /**
+   * Create parametric spur gear geometry
+   *
+   * Generates involute gear profile with user-specified teeth count and module.
+   * Implements involute curve construction for smooth tooth engagement.
+   *
+   * @param {Object} params - Gear parameters
+   * @param {number} params.teeth - Number of teeth
+   * @param {number} params.module - Module (mm/tooth) - standard values: 0.5, 1.0, 1.5, 2.0, 3.0, 4.0
+   * @returns {THREE.BufferGeometry} Gear geometry
+   */
   function createGearGeometry(params) {
     const teeth = params.teeth || 24;
     const module = params.module || 2;
@@ -584,6 +710,18 @@
    * @param {Object} params
    * @returns {THREE.BufferGeometry}
    */
+  /**
+   * Create parametric angle bracket (L-shaped) geometry
+   *
+   * Constructs two perpendicular flange sheets with optional boss features.
+   * Common in mechanical assemblies for structural support.
+   *
+   * @param {Object} params - Bracket parameters
+   * @param {number} params.width - Horizontal width (mm)
+   * @param {number} params.height - Vertical height (mm)
+   * @param {number} params.thickness - Material thickness (mm)
+   * @returns {THREE.BufferGeometry} Bracket geometry
+   */
   function createBracketGeometry(params) {
     const w = params.width || 60;
     const h = params.height || 100;
@@ -723,6 +861,16 @@
    * Update live preview as user types
    * @param {string} input
    */
+  /**
+   * Update live preview geometry as user types (debounced)
+   *
+   * Implements 500ms debounce to avoid excessive parsing/rendering. Creates "ghost" geometry
+   * with semi-transparent material to show real-time feedback without committing to history.
+   * Updates confidence score display and dimension annotations.
+   *
+   * @param {string} input - Current user input text
+   * @returns {void}
+   */
   function updateLivePreview(input) {
     // Clear existing debounce timer
     if (state.parseDebounceTimer) {
@@ -771,6 +919,14 @@
   /**
    * Commit preview to actual geometry
    */
+  /**
+   * Commit current preview to history and make permanent
+   *
+   * Replaces ghost geometry with opaque final geometry, adds to feature tree,
+   * pushes to step history, enables undo/redo. Triggers event listeners.
+   *
+   * @returns {void}
+   */
   function commitPreview() {
     if (!state.previewGeometry) return;
 
@@ -815,6 +971,14 @@
   /**
    * Undo to previous step
    */
+  /**
+   * Undo last step in feature history
+   *
+   * Moves currentStepIndex backward, restores previous geometry state,
+   * updates UI and 3D view. Does nothing if already at first step.
+   *
+   * @returns {BuildStep|null} Previous step or null if at beginning
+   */
   function undoStep() {
     if (state.currentStepIndex > 0) {
       state.currentStepIndex--;
@@ -837,6 +1001,14 @@
   /**
    * Redo to next step
    */
+  /**
+   * Redo last undone step in feature history
+   *
+   * Moves currentStepIndex forward, restores next geometry state,
+   * updates UI and 3D view. Does nothing if already at latest step.
+   *
+   * @returns {BuildStep|null} Next step or null if at end
+   */
   function redoStep() {
     if (state.currentStepIndex < state.steps.length - 1) {
       state.currentStepIndex++;
@@ -1273,6 +1445,17 @@
    * @param {THREE.Scene} scene
    * @param {Object} renderer
    */
+  /**
+   * Initialize TextToCAD module with Three.js scene and renderer
+   *
+   * Sets up event listeners, UI panel, material definitions, and camera controls.
+   * Must be called once before any execute() calls. Safe to call multiple times.
+   *
+   * @param {THREE.Scene} scene - The Three.js scene object
+   * @param {THREE.WebGLRenderer} renderer - The Three.js renderer for viewport updates
+   * @returns {void}
+   * @throws {Error} If scene is null or not a THREE.Scene instance
+   */
   function init(scene, renderer) {
     state.scene = scene;
     state.renderer = renderer;
@@ -1367,6 +1550,32 @@
    * @param {Object} params
    * @returns {any}
    */
+  /**
+   * Execute command in TextToCAD module (public API)
+   *
+   * Main entry point for all text-to-CAD operations. Commands include:
+   * - 'parse': Parse natural language and return structured spec
+   * - 'generate': Generate and display geometry
+   * - 'commit': Add to history
+   * - 'undo'/'redo': Navigate history
+   * - 'clear': Reset everything
+   * - 'setVariant': Select one of 3 generated alternatives
+   *
+   * @param {string} command - Command name: 'parse'|'generate'|'commit'|'undo'|'redo'|'clear'|'setVariant'
+   * @param {Object} [params={}] - Command parameters (varies by command)
+   * @param {string} params.input - For 'parse' and 'generate': natural language text
+   * @param {number} params.variantIndex - For 'setVariant': index 0-2
+   * @returns {Object} Command result (structure varies by command)
+   * @example
+   * // Parse natural language
+   * const spec = window.CycleCAD.TextToCAD.execute('parse', {input: 'cylinder 50mm dia 80mm tall'});
+   *
+   * // Generate geometry with preview
+   * window.CycleCAD.TextToCAD.execute('generate', {input: 'cylinder 50mm dia 80mm tall'});
+   *
+   * // Commit to history
+   * window.CycleCAD.TextToCAD.execute('commit');
+   */
   function execute(command, params) {
     switch (command) {
       case 'parse':