Ask-AI Widget Development¶

📁 Project Structure¶

docs/sphinx_doc/source/_static/
├── ask-ai-modules/              # Modularized source code
│   ├── ask-ai-i18n.js          # Internationalization configuration
│   ├── ask-ai-api.js           # API communication layer
│   ├── ask-ai-ui.js            # UI rendering and interaction
│   └── ask-ai-widget.js        # Main controller
├── ask-ai-widget.js            # Bundled single file (for production)
├── ask-ai-widget.css           # Widget styles (follows light/dark theme)
├── package.json                # Node.js dependency configuration
└── rollup.config.js            # Rollup bundling configuration

This document lives at docs/ask_ai_widget.md (rendered in the built site), not inside _static/.

The widget is only loaded when JUICER_API_URL is configured (see docs/sphinx_doc/source/conf.py).

🚀 Quick Start¶

1. Install Dependencies¶

Run the following command in the docs/sphinx_doc/source/_static/ directory:

npm install

2. Build and Bundle¶

npm run build

This will:

Read all modules in the ask-ai-modules/ directory
Bundle them into a single file using Rollup
Output to ask-ai-widget.js (overwriting the original file)

3. Development Mode (Watch for File Changes)¶

npm run watch

In development mode, any modifications to files in ask-ai-modules/ will automatically trigger a rebuild.

📝 Module Descriptions¶

ask-ai-i18n.js¶

Purpose: Internationalization configuration
Exports: I18N object and detectLanguage() function
Size: ~2KB

ask-ai-api.js¶

Purpose: API communication layer
Exports: AskAIApi class
Responsibilities:
- API connection verification
- Session history loading
- Streaming response handling
- Session clearing
Size: ~8KB

ask-ai-ui.js¶

Purpose: UI rendering and interaction
Exports: AskAIUI class
Responsibilities:
- DOM creation and management (floating input bar, select-to-ask tooltip, resizable side panel)
- Event binding
- Message rendering (streaming replies, thinking blocks, tool calls, feedback buttons)
- Theme switching
- Markdown rendering
Size: ~12KB

🔧 Modifying Code¶

Modification Workflow¶

Edit Module Files: Modify the corresponding module in the ask-ai-modules/ directory
Rebuild: Run npm run build
Test: Test the bundled file in your browser

Adding New Features¶

If you need to add new functionality:

Determine which module the feature belongs to (I18N, API, UI, or main controller)
Add code to the corresponding module
If cross-module calls are needed, implement them through export/import mechanisms
Rebuild and test

📦 Bundling Information¶

Bundling Configuration Explanation¶

rollup.config.js configuration:

{
  input: 'ask-ai-modules/ask-ai-widget.js',  // Entry file
  output: {
    file: 'ask-ai-widget.js',                 // Output file
    format: 'iife',                           // Immediately Invoked Function Expression
    name: 'AskAIWidget',                      // Global variable name
    globals: { marked: 'marked' }             // External dependency mapping
  },
  external: ['marked']                        // Don't bundle marked library
}

🔍 Troubleshooting¶

Build Failures¶

If the build fails, check:

Whether Node.js version is >= 18 (Rollup 4 requires it; a system Node 12 will fail with syntax errors)
Whether dependencies are correctly installed (npm install)
Whether there are syntax errors in the module files

Function Anomalies¶

If functionality is abnormal after bundling:

Check the browser console for errors
Verify that marked.js is correctly loaded