PyVizAST Prerelease 1.0.0-beta

LLM AI Refactoring & Bug Fixes

LLM Explanation Panel Refactoring:

• Redesigned AI explanation panel with premium black/white minimalist theme
• Added unavailable state UI with helpful messages when LLM not configured
• Added fullscreen modal for detailed reading
• Improved loading states and error handling
• Auto-retry on failure (up to 2 times)

Backend LLM Service Refactoring:

• Improved prompt templates with clearer JSON output format requirements
• Multi-strategy JSON parsing with fallback mechanisms
• Thread-safe caching with TTL for explanation caching
• Case-insensitive model name matching (codeLlama:7b vs codellama:7b)
• Separated error handling for availability check and model listing
• Added shorter timeouts to avoid UI hanging

Frontend LLM Integration Improvements:

• Added custom event system (llmConfigChanged) for cross-component communication
• Fixed React Hooks order issue (useMemo before early return)
• Fixed incorrect default status value ('ready' → 'unavailable')
• Improved SSE parsing with type annotations
• Better error feedback and loading states

Files Added:

• frontend/src/components/LLMExplanationPanel.js - AI explanation panel component
• frontend/src/components/LLMExplanationPanel.css - Black/white minimalist styles

Files Modified:

• backend/llm/prompts.py - Improved prompt templates
• backend/llm/service.py - Multi-strategy parsing, caching, status handling
• backend/llm/ollama_client.py - Shorter timeouts
• backend/routers/llm.py - Unified error responses, detailed logging
• frontend/src/api.js - SSE parsing, shorter timeouts
• frontend/src/components/LLMSettings.js - Event dispatching, improved status handling
• frontend/src/components/ASTVisualizer.js - Event listeners, fixed default status
• frontend/src/components/ASTVisualizer3D.js - Event listeners, fixed default status
• frontend/src/components/components.css - LLM explanation panel styles

Bug Fixes:

• Fixed model not loading when clicking Load button
• Fixed UI stuck at loading state (timeout optimization)
• Fixed false "loaded" display when model not actually loaded
• Fixed React Hooks error (useMemo called after early return)
• Fixed model name case sensitivity matching

PyVizAST Prerelease 1.0.0-alpha

Major Release - LLM AI Integration

New Features:

LLM Service Module (backend/llm/):

• models.py: Data models for LLM configuration, status, and responses
• ollama_client.py: Ollama API client for local LLM communication
• prompts.py: Prompt templates for node explanations, challenges, and hints
• service.py: Core LLM service with explanation/challenge/hint generation
• downloader.py: Ollama auto-install and model download with aria2 acceleration

LLM API Endpoints (backend/routers/llm.py):

• GET /api/llm/status - Get LLM service status
• GET/POST /api/llm/config - LLM configuration management
• GET /api/llm/models - List installed models
• POST /api/llm/models/pull - Download model with progress streaming
• DELETE /api/llm/models/{name} - Delete model
• GET /api/llm/ollama/status - Get Ollama installation status
• POST /api/llm/ollama/install - Auto-install Ollama
• POST /api/llm/ollama/start - Start Ollama server
• POST /api/llm/generate/explanation - Generate node explanation
• POST /api/llm/generate/challenge - Generate coding challenge
• POST /api/llm/generate/hint - Generate contextual hint

Frontend Components:

• LLMSettings.js: Settings panel with model management and configuration
• LLMDownloader.js: Quick setup wizard for Ollama installation
• LLMSettings.css: Black/white minimalist design styles

AI Node Explanations (2D & 3D):

• AI explanations display in node detail panel when LLM is enabled
• Code context snippet shown with explanations
• Fullscreen modal for detailed reading
• Auto-retry on failure (up to 2 times)
• Error display with manual retry button

Model Management:

• Recommended models: CodeLlama 7B/13B, Llama 3.2 3B, Mistral 7B, DeepSeek Coder, Qwen 2.5 Coder
• One-click download with progress tracking
• Auto-select best model for code analysis
• "Use" button for installed models, "In Use" indicator for current model

Ollama Auto-Install:

• Automatic platform detection (Windows/macOS/Linux)
• One-click Ollama installation
• Automatic server startup
• Status monitoring (installed/running)

Configuration Options:

• Enable/disable LLM features
• Toggle AI explanations, challenges, hints separately
• Temperature and max tokens settings
• Model selection with "Load" button

Bug Fixes:

• Fixed model name case sensitivity matching (codeLlama:7b vs codellama:7b)
• Fixed async state update issue in Load button
• Fixed LLM explanation status checks
• Fixed pullModel API to use POST with streaming

Dependencies Added:

• httpx>=0.27.0 for LLM API calls

Files Added:

• backend/llm/__init__.py
• backend/llm/models.py
• backend/llm/ollama_client.py
• backend/llm/prompts.py
• backend/llm/service.py
• backend/llm/downloader.py
• backend/routers/llm.py
• frontend/src/components/LLMSettings.js
• frontend/src/components/LLMDownloader.js
• frontend/src/components/LLMSettings.css

Files Modified:

• backend/config.py - Version bump
• backend/main.py - LLM router registration
• backend/routers/__init__.py - Export LLM router
• backend/routers/learning.py - LLM-enhanced explanations
• backend/routers/challenges.py - LLM challenge generation
• frontend/src/App.js - LLM settings modal
• frontend/src/api.js - LLM API functions
• frontend/src/components/Header.js - AI button
• frontend/src/components/ASTVisualizer.js - AI explanations
• frontend/src/components/ASTVisualizer3D.js - AI explanations
• frontend/src/components/components.css - LLM explanation styles
• frontend/src/components/LearnChallenge.css - LLM toggle styles
• requirements.txt - Added httpx

PyVizAST Release 0.7.2

The development of Version 1.0.0 started

Bug Fixes & Security Improvements

Python Version Requirement:

• Updated minimum Python version from 3.8 to 3.9 (required for ast.unparse())

Security Improvements:

• Added ZIP compression bomb detection:
  • Maximum uncompressed size limit (500MB)
  • Maximum compression ratio check (100x)
  • Individual file size limit (5MB)
• Simplified error messages to avoid exposing internal implementation details

Code Quality:

• Added logging for exceptions in node_builder.py
• Added user feedback for keyboard interrupt in run.py
• Locked dependency versions in requirements.txt (fastapi, pydantic, uvicorn, etc.)
• Added Node.js/npm version requirements in package.json (Node.js >= 18, npm >= 9)

UI Improvements:

• Refactored Social Card Generator to black/white minimalist design
• Simplified card visual effects with clean geometric AST visualization
• Improved consistency with project's overall monochrome theme

Verification:

• Confirmed all Map.get() calls in ASTVisualizer3D.js have proper null checks
• Confirmed ModuleInfo dataclass has correct default values

Files Modified:

• run.py - Python version check, keyboard interrupt handling
• backend/ast_parser/node_builder.py - Exception logging
• backend/project_analyzer/scanner.py - ZIP bomb detection
• backend/main.py - Simplified error messages
• requirements.txt - Version constraints
• frontend/package.json - Node.js version requirements, version bump
• backend/config.py - Version bump
• frontend/src/components/SocialCardGenerator.js - Refactored to black/white minimalist design
• frontend/src/App.css - Updated social card styles to match project theme
• README.md - Version badge, Python requirement, changelog

PyVizAST Release 0.7.1

Social Card Generator & UI Improvements

New Features:

• Social Card Generator: Generate shareable image cards from the Share dropdown
  • Brand card with AST visualization, logo, and feature highlights
  • 2D Preview card with captured AST visualization
  • 3D Preview card with captured 3D AST visualization
  • Black/white theme adaptation
  • PNG download (1200x630px standard social share size)

Toast System Improvements:

• Toast position moved to top-right of screen
• Simplified vertical stacking (removed complex stacking logic)
• Increased maximum toast limit from 5 to 15
• Increased border-radius from 16px to 24px for rounder corners

UI Enhancements:

• Share button now shows dropdown menu with "Share Code" and "Social Card" options
• Visualizer components expose captureScreenshot method for card generation
• Improved card preview modal with style selector

Known Issues:

• Social Card export may be unstable in certain browsers/conditions
• 3D visualization capture requires the 3D view to be fully rendered

Files Modified:

• frontend/src/components/SocialCardGenerator.js - New social card generator component
• frontend/src/components/Header.js - Share dropdown menu
• frontend/src/components/Toast.js - Simplified toast system
• frontend/src/components/ToastContext.js - Increased toast limit
• frontend/src/App.js - Screenshot capture handlers
• frontend/src/App.css - Social card styles, toast improvements
• frontend/src/components/ASTVisualizer.js - Screenshot capture method
• frontend/src/components/ASTVisualizer3D.js - Screenshot capture method

PyVizAST Release 0.7.0

v0.7.0 (2026-03-14) - Stable Release

Major Updates

Dependency Upgrades

Package Name	Old Version	New Version
react	18.x	19.2.4
react-dom	18.x	19.2.4
@react-three/fiber	8.x	9.5.0
@react-three/drei	9.x	10.7.7
framer-motion	11.x	12.36.0
three	0.160.x	0.183.2
cytoscape-react	3.x	4.0.0

3D Gesture Control

• Implemented pointing gesture functionality for 3D AST visualization
• Virtual cursor components: dot, ring, progress ring, snap indicator
• Used Three.js camera for 3D to screen coordinate projection
• Node snap animation (smooth interpolation)
• Hover progress auto-selection (800ms dwell time)
• Camera auto-focus on node selection

Virtual Cursor System

• Unified state management: single cursorStateRef object
• Smooth position interpolation: cursor 0.25, snap 0.35
• GPU-accelerated transform positioning
• Theme-aware CSS variables (--cursor-bg, --cursor-border, etc.)
• Separate CSS classes for 2D and 3D (cursor-snap vs cursor-snap-3d)

Light Mode Fixes

• Fixed white transparency issue in .detail-tag.scope and .detail-tag.callable
• Fixed theme compatibility for .relationship-tag.inheritance/derived/method
• Fixed .highlighted-line background color
• Fixed .warning-dismiss:hover background
• Fixed @keyframes searchPulse to use theme-aware --pulse-color variable

Bug Fixes

• Fixed cursor dot/ring centering issue (offset calculation: 10px→-5, 44px→-22)
• Fixed conflict between CSS animations and JS transform positioning
• Fixed 3D node projection coordinate system issue
• Fixed cursor positioning error caused by container reference binding

PyVizAST Prerelease 0.7.0-rc3

Bug Fixes & Performance Optimizations

Backend Fixes:

• Fixed async sync blocking in projects.py: Added run_in_executor for file I/O and AST parsing operations
• Fixed incomplete exception handling in parser.py: Added MemoryError catch with smart truncation
• Fixed redundant AST traversal in node_builder.py: Combined 3 separate ast.walk calls into single pass for 3x performance improvement
• Fixed lint errors (F541, F821, F401) across multiple files

Frontend Improvements:

• Enhanced CodeEditor.js for large file performance:
  • Disabled minimap for files > 3000 lines
  • Disabled folding for files > 5000 lines
  • Added performance warning banner for large files
  • Improved memory management for very large files
• Confirmed proper cleanup in useResizeObserver.js, GestureService.js, and ASTVisualizer3D.js

Performance:

• node_builder.py: _count_code_elements() now does single traversal instead of 3
• Reduced memory usage for large file editing
• Better error handling for edge cases

Files Modified:

• backend/routers/projects.py - Async file operations
• backend/ast_parser/parser.py - MemoryError handling
• backend/ast_parser/node_builder.py - Performance optimization
• frontend/src/components/CodeEditor.js - Large file handling
• frontend/src/components/components.css - Performance warning styles

PyVizAST Prerelease 0.7.0-rc2

Virtual Cursor System Rewrite

Complete Refactor:

• Unified state management: Single cursorStateRef object instead of multiple states
• Smooth position interpolation with CURSOR_SMOOTH and SNAP_SMOOTH factors
• CSS variables for theme support (--cursor-bg, --cursor-border, etc.)
• Cleaner class naming: cursor-dot, cursor-ring, cursor-progress, cursor-snap

Snap Animation:

• Smooth snap indicator following with separate smooth factor (0.2)
• First snap initializes position immediately to avoid delay
• Snap indicator now correctly follows node center position

Performance Optimizations:

• CSS transform instead of left/top for GPU acceleration
• Use node.renderedPosition() for accurate screen coordinates
• opacity transitions instead of display for smoother animations
• CSS will-change for optimized rendering

Bug Fixes:

• Fixed CSS animation conflicting with JS position (use margin centering)
• Fixed snap position using renderedPosition() instead of manual calculation
• Fixed snap selecting wrong node (distance squared comparison bug)
• Added validation for renderedPosition() return values

Files Modified:

• frontend/src/components/ASTVisualizer.js - Complete cursor system rewrite
• frontend/src/components/components.css - CSS variables, simplified animations
• frontend/src/App.js - Removed unused GestureType import

PyVizAST Prerelease 0.7.0-rc1

Code Quality & Bug Fixes

Logging Improvements:

• Upgraded debug logs to warning level for error conditions in project analyzer
• scanner.py: File read failures now logged at warning level
• unused_exports.py: Module analysis failures now logged at warning level
• cycle_detector.py: Improved SCC cycle extraction with better error handling

Frontend Improvements:

• ASTVisualizer.js: Added removeAllListeners() before destroy to prevent memory leaks
• Changed debug logs to warning logs for Cytoscape cleanup errors
• useResizeObserver.js: Changed console.debug to console.warn for better error visibility

Files Modified:

• backend/project_analyzer/cycle_detector.py - Improved cycle detection logging
• backend/project_analyzer/scanner.py - Upgraded log levels
• backend/project_analyzer/unused_exports.py - Upgraded log levels
• frontend/src/components/ASTVisualizer.js - Memory leak prevention
• frontend/src/hooks/useResizeObserver.js - Improved error handling

PyVizAST Prerelease 0.7.0.2

Gesture Control Improvements

Stability Enhancements:

• Added gesture stability filter: requires 5 consecutive frames with same gesture
• Raised confidence threshold from 0.5 to 0.7
• Added 300ms cooldown period between gesture changes
• Fast reset when hand leaves frame (immediate instead of waiting 5 frames)
• Position tracking continues during cooldown for smooth UX

Simplified Gesture Set (4 core gestures + pinch):

• Thumb Up: Zoom in
• Thumb Down: Zoom out
• Closed Fist: Pan mode
• Open Palm: Reset view
• Victory (V sign): Select node
• Pointing Up: Point-to-select with hover progress
• Two Hands Pinch: Pinch to zoom

Point-to-Select Feature:

• Virtual cursor appears on AST graph when pointing
• Hover over a node for 2 seconds to auto-select
• Progress ring animation shows selection countdown
• X-axis mirrored to match video preview

Bug Fixes:

• Fixed undefined GestureType references (POINTING_UP, VICTORY)
• Fixed callback cleanup on component unmount
• Fixed cooldown visual feedback timing

Files Modified:

• frontend/src/utils/GestureService.js - Stability filtering, cooldown, pointing direction
• frontend/src/components/GestureControl.js - Removed unused icons, added pointing callback
• frontend/src/components/GestureControl.css - Cooldown styling
• frontend/src/utils/logger.js - Browser safety checks
• frontend/src/components/ASTVisualizer.js - Pointing cursor, hover detection, progress ring
• frontend/src/components/components.css - Pointing cursor styling
• frontend/src/App.js - Pointing direction handling
• backend/analyzers/security.py - Expanded secret detection (25+ patterns)
• backend/project_analyzer/scanner.py - ZIP path validation
• frontend/public/index.html - Title updated to "PyVisAST"

PyVizAST Prerelease 0.7.0

New Feature: Webcam Gesture Control

Hand gesture recognition for 2D/3D AST visualization control using MediaPipe.

Supported Gestures:

• Thumb Up: Zoom in
• Thumb Down: Zoom out
• Closed Fist: Pan mode (grab and drag)
• Open Palm: Quick tap = select, Hold = reset view
• Pointing Up: Select node
• Victory (V sign): Rotate mode
• Two Hands Pinch: Pinch to zoom, move both hands to pan

Components:

• GestureService.js: Core gesture recognition service using MediaPipe GestureRecognizer
• GestureControl.js: UI component with camera preview, status indicator, gesture guide
• GestureControl.css: Styling for gesture control overlay

Features:

• Toggle button in header (default OFF)
• Real-time camera preview with gesture overlay
• Status indicator (loading/ready/running/error/stopped)
• Visual gesture guide with action mappings
• Support for both 2D (Cytoscape) and 3D (Three.js) visualizations

Dependencies:

• Added @mediapipe/tasks-vision for gesture recognition

Known Issues:

• Gesture recognition may be unstable in certain lighting conditions
• Future improvements planned: stability filtering, confidence threshold adjustment, gesture cooldown

Files Added:

• frontend/src/utils/GestureService.js
• frontend/src/components/GestureControl.js
• frontend/src/components/GestureControl.css

Files Modified:

• frontend/src/components/Header.js - Added gesture toggle button
• frontend/src/App.js - Added gesture state management
• frontend/src/components/ASTVisualizer.js - Added gesture handling for 2D
• frontend/src/components/ASTVisualizer3D.js - Added gesture handling for 3D
• frontend/package.json - Added MediaPipe dependency