visualifyjs 2.5.3-2.dev → 3.0.0

package/.claude/mem/TIMELINE.md

@@ -0,0 +1,36 @@
+# Memory Timeline
+> 28 memories | Updated: 2026-02-20T06:29:24.060Z
+
+## Today (Feb 19)
+- 23:29 [note] **v3.0.0 Release and Beta Channel Strategy** `visualify, release, v3.0.0, npm, beta-channel, workflow, potential-duplicate:2026-02-20-public-folder-cleanup-and-readme-rewrite`
+- 23:02 [note] **DotBio Dot Plot Fix - useEffect Dependency** `visualify, bugfix, dotplot, react, useEffect, sharedData, DotBio, replotly, potential-duplicate:2026-02-19-visualify-infinite-loop-i18n-fixes`
+- 21:49 [note] **Bundle Externalization Final Architecture** `visualify, rollup, externalization, iife, echarts, plotly, three, bundle, architecture, potential-duplicate:2026-02-19-visualify-build-deployment-architecture-bug-fixes`
+- 21:09 [note] **Public folder cleanup and README rewrite** `visualify, commit, readme, public-cleanup, changelog, potential-duplicate:2026-02-20-console-cleanup-bundle-optimization-commit`
+- 20:48 [note] **Console cleanup + bundle optimization commit** `visualify, commit, bundle-optimization, console-cleanup, docs, potential-duplicate:2026-02-19-visualify-infinite-loop-i18n-fixes`
+- 20:26 [note] **Visualify CDN Loader + Bundle Externalization** `visualify, rollup, cdn, bundle-optimization, loader, externalization, potential-duplicate:2026-02-19-visualify-dist-iife-self-contained-build-config`
+- 20:15 [session] **"Session summary 2026-02-20"** `auto-capture, session-end, zhipu`
+- 18:59 [note] **Chromium page fix - unstable keys and double event binding** `bugfix, chromium, react, echarts, keys, events, potential-duplicate:2026-02-19-css-grid-layout-fix-displaycontents-on-vcontroller`
+- 17:55 [note] **Visium Background Image + Unknown Legend Fix** `visualify, bugfix, visium, react, useEffect, ScatterBio, potential-duplicate:2026-02-19-page-mode-docs-update-decisions`
+- 16:18 [note] **React Context Infinite Re-render Loop Fix Pattern** `react, useEffect, infinite-loop, context, performance, visualify, pattern, potential-duplicate:2026-02-19-visualify-infinite-loop-i18n-fixes`
+- 15:31 [note] **CSS Grid Layout Fix - display:contents on Vcontroller** `visualify, bugfix, css-grid, layout, display-contents, potential-duplicate:2026-02-19-visualify-build-deployment-architecture-bug-fixes`
+- 15:19 [note] **Visualify Infinite Loop & i18n Fixes** `visualify, bugfix, react, useEffect, infinite-loop, i18n, rollup, potential-duplicate:2026-02-19-visualify-build-deployment-architecture-bug-fixes`
+- 14:45 [note] **Visualify dist IIFE Self-Contained Build Config** `visualify, rollup, deployment, iife, dist, self-contained, potential-duplicate:2026-02-11-3d-visualization-docs-fix-session-summary`
+- 14:23 [note] **Visualify Build & Deployment Architecture + Bug Fixes** `visualify, deployment, build, bugfix, architecture, potential-duplicate:2026-02-18-codebase-cleanup-docsify-plugin-documentation`
+- 13:11 [note] **Page Mode Docs Update Decisions** `docs, page-mode, components, visualify, potential-duplicate:2026-02-19-visualify-v3-bundle-splitting-docs-restructuring`
+- 13:02 [note] **Visualify v3 Bundle Splitting & Docs Restructuring** `architecture, bundle-splitting, v3, rollup, docs, potential-duplicate:2026-02-19-version-300-bump-and-build-fixes`
+- 12:35 [note] **Docsify Plugin Fixes - LaTeX and Visualify Code Blocks** `docsify, latex, visualify, plugin, configuration, potential-duplicate:2026-02-11-3d-visualization-docs-fix-external-script-solution`
+- 12:17 [note] **Version 3.0.0 Bump and Build Fixes** `visualify, version-bump, 3.0.0, build-fix, typescript, plotly, eslint, potential-duplicate:2026-02-11-3d-visualization-docs-fix-session-summary`
+
+## Yesterday (Feb 18)
+- 14:52 [note] **Codebase Cleanup - Docsify Plugin Documentation** `visualify, cleanup, docsify, documentation, gitignore, phase4, potential-duplicate:2026-02-11-visualify-repository-cleanup-complete`
+
+## Earlier This Month
+- Feb 11 [note] **Phase 4 - Web Workers Implementation Complete** `visualify, phase4, web-workers, performance, large-datasets, completed`
+- Feb 11 [note] **CLI Fix - Editor Command Alias** `visualify, cli, fix, editor, alias, documentation`
+- Feb 11 [note] **Phase 3 Developer Experience - Completed** `visualify, phase3, complete, hmr, typescript, i18n, dx, commit`
+- Feb 11 [note] **3D Visualization Docs Fix - External Script Solution** `visualify, 3d-visualization, docsify, fix, pattern`
+- Feb 11 [note] **3D Visualization Docs Fix - Session Summary** `visualify, 3d-visualization, docs, build-fix, dependencies, rollup`
+- Feb 11 [note] **Visualify Phase 3 Complete - Developer Experience** `visualify, phase3, complete, typescript, hmr, editor, a11y, i18n`
+- Feb 11 [note] **Visualify Phase 2 Committed - Ready for Phase 3** `visualify, phase2, committed, complete, ready-for-phase3`
+- Feb 11 [note] **Visualify Phase 2 - 3D Visualization Complete** `visualify, phase2, 3d, echarts-gl, threejs, docsify, complete`
+- Feb 11 [note] **Visualify Repository Cleanup Complete** `visualify, cleanup, ready, phase2`

package/.claude/mem/notes/2026-02-11-3d-visualization-docs-fix-external-script-solution.md

@@ -0,0 +1,24 @@
+---
+title: 3D Visualization Docs Fix - External Script Solution
+type: note
+tags: [visualify, 3d-visualization, docsify, fix, pattern]
+created: 2026-02-11T19:21:57.750Z
+updated: 2026-02-11T19:21:57.750Z
+---
+
+## 3D Visualization Docs Fix - External Script Solution
+
+**Problem**: Docsify plugin error "Invalid or unexpected token" when loading 3D visualization examples with inline script in markdown.
+
+**Root Cause**: Docsify's `external-script` plugin has issues parsing inline JavaScript in markdown files, especially with certain ES5/ES6 syntax patterns.
+
+**Solution**: Move all JavaScript code from inline `<script>` in markdown to external JS file.
+
+**Changes Made**:
+1. Created `docs/static/js/3d-viz-examples.js` - Contains all 3D chart configs and mounting logic
+2. Updated `docs/docs/3d-visualization.md` - Replaced inline script with external script reference
+3. Updated `docs/index.html` - Added external script after visualify.js bundle
+
+**Key Pattern**: When docsify shows "Invalid or unexpected token" errors with inline scripts, extract the script to an external file and reference it with `<script src="...">`.
+
+**Verification**: All 3D charts (Scatter3D, Bar3D, Surface3D) now render correctly without plugin errors.

package/.claude/mem/notes/2026-02-11-3d-visualization-docs-fix-session-summary.md

@@ -0,0 +1,43 @@
+---
+title: 3D Visualization Docs Fix - Session Summary
+type: note
+tags: [visualify, 3d-visualization, docs, build-fix, dependencies, rollup]
+created: 2026-02-11T17:07:15.007Z
+updated: 2026-02-11T17:07:15.007Z
+---
+
+## 3D Visualization Docs Fix - Session Summary
+
+### Problem
+The 3D Visualization documentation page at localhost:3000 showed "Loading 3D Scatter Plot... (requires WebGL support)" indefinitely because:
+1. The 3D components weren't accessible through the Recharts class used in docs mode
+2. Missing npm dependencies (react-toastify, react-i18next, i18next, i18next-browser-languagedetector)
+3. Broken OBJLoader import path (missing .js extension)
+4. The docs bundle wasn't self-contained (missing React and other deps)
+
+### Solution
+1. **Modified Recharts class** (`src/core/recharts.js`):
+   - Added imports for 3D components (Scatter3D, Bar3D, Surface3D, Line3D)
+   - Added `is3DChartType()` helper to detect 3D chart types
+   - Modified `ChartWithHMR` to render 3D components when type matches
+
+2. **Added missing dependencies** to package.json and installed them
+
+3. **Fixed OBJLoader import** in ThreeCustom.js to use `.js` extension
+
+4. **Updated rollup config** with separate `docsStaticConfig` for self-contained docs bundle
+
+5. **Added 3D Visualization to sidebar** (`docs/docs/_sidebar.md`)
+
+6. **Updated .gitignore** to exclude `.claude/` and `.sisyphus/`
+
+### Key Technical Details
+- The docs bundle (`docs/static/js/visualify.js`) is now 1.7MB with all dependencies bundled
+- 3D libraries (echarts-gl, three.js) are still loaded on-demand to minimize initial bundle size
+- The IIFE format with `inlineDynamicImports: true` ensures compatibility with Docsify
+
+### Commits
+- `8f3fb14` - fix(build): resolve missing dependencies and fix OBJLoader import
+
+### Tags
+visualify, 3d-visualization, docs, build-fix, dependencies, rollup

package/.claude/mem/notes/2026-02-11-cli-fix-editor-command-alias.md

@@ -0,0 +1,26 @@
+---
+title: CLI Fix - Editor Command Alias
+type: note
+tags: [visualify, cli, fix, editor, alias, documentation]
+created: 2026-02-11T19:46:45.325Z
+updated: 2026-02-11T19:46:45.325Z
+---
+
+## CLI Fix - Editor Command Alias
+
+**Commit**: `b2d3de7` - fix(cli): add 'editor' alias and update CLI documentation
+
+**Problem**: Users expected `visualify editor` command but only `visualify edit` existed, causing "unknown command 'editor'" error.
+
+**Solution**:
+1. Added `command.alias('editor')` to the edit command in `src/cli/commands/edit.js`
+2. Updated CLI.md documentation with complete unified CLI reference
+3. Fixed visual-editor.md to use correct command syntax
+
+**Key Changes**:
+- Both `visualify edit` and `visualify editor` now work
+- Updated documentation shows all current commands: dev, docs, portal, init, edit/editor
+- Added legacy command migration table for users coming from @visualify/cli
+- Documented configuration file options and environment variables
+
+**Pattern**: When CLI commands have naming inconsistencies, add aliases rather than breaking existing usage.

package/.claude/mem/notes/2026-02-11-phase-3-developer-experience-completed.md

@@ -0,0 +1,51 @@
+---
+title: Phase 3 Developer Experience - Completed
+type: note
+tags: [visualify, phase3, complete, hmr, typescript, i18n, dx, commit]
+created: 2026-02-11T19:39:15.248Z
+updated: 2026-02-11T19:39:15.248Z
+---
+
+## Phase 3 Developer Experience - Completed
+
+**Commit**: `a016d2e` - feat(dx): complete Phase 3 Developer Experience features
+
+**Features Implemented**:
+
+1. **Hot Module Replacement (HMR)**
+   - WebSocket-based live reloading
+   - State preservation during updates
+   - Visual error overlay
+   - Configurable via `window.__VISUALIFY_HMR__`
+
+2. **TypeScript Support**
+   - Full type definitions for all chart types
+   - Generic ChartData<T> support
+   - Typed React hooks and components
+   - Migration guide documentation
+
+3. **Internationalization (i18n)**
+   - Multi-language support infrastructure
+   - RTL language support
+   - Number/date formatting
+   - Translation key system
+
+4. **Visual Configuration Editor**
+   - Point-and-click chart builder
+   - Real-time preview
+   - Drag-and-drop data import
+   - Export to multiple formats
+
+5. **Accessibility Improvements**
+   - Fixed keyboard navigation hooks
+   - Direct React hook imports
+   - ARIA attributes for 3D charts
+
+**Documentation Added**:
+- `docs/docs/hmr.md` - HMR guide
+- `docs/docs/typescript.md` - TypeScript migration
+- `docs/docs/i18n.md` - Internationalization
+- `docs/docs/visual-editor.md` - Visual editor guide
+- Updated `docs/docs/_sidebar.md` with Developer Experience section
+
+**All Phase 3 tasks marked complete.**

package/.claude/mem/notes/2026-02-11-phase-4-web-workers-implementation-complete.md

@@ -0,0 +1,59 @@
+---
+title: Phase 4 - Web Workers Implementation Complete
+type: note
+tags: [visualify, phase4, web-workers, performance, large-datasets, completed]
+created: 2026-02-11T20:32:31.682Z
+updated: 2026-02-11T20:32:31.682Z
+---
+
+## Phase 4 - Web Workers Implementation Complete
+
+**Commit**: `f8b624d` - feat(workers): implement Web Worker infrastructure for large datasets
+
+**Features Implemented**:
+
+1. **WorkerPool** (`src/core/workers/worker-pool.js`)
+   - Manages pool of web workers with min/max limits
+   - Task queuing with automatic load balancing
+   - Error handling with worker replacement
+   - Task timeout handling
+   - Statistics reporting
+
+2. **DataWorker** (`src/core/workers/data-worker.js`)
+   - Aggregation: sum, avg, min, max, count, median, std
+   - Filtering with complex criteria (range, comparison, array includes)
+   - Sorting by multiple fields
+   - GroupBy operations
+   - Stratified sampling for large datasets
+   - Statistics calculation (mean, variance, quartiles)
+   - CSV parsing with type detection
+   - Pipeline for chained operations
+
+3. **DataProcessor** (`src/core/data-processor.js`)
+   - High-level API for main thread
+   - Automatic chunking for large datasets
+   - Parallel processing with progress callbacks
+   - Result aggregation from chunks
+   - Convenience functions: aggregateData, filterData, sortData, etc.
+
+4. **LargeDatasetChart** (`src/core/components/LargeDatasetChart.js`)
+   - React component optimized for 100k+ row datasets
+   - Automatic sampling for preview
+   - Data summary statistics overlay
+   - Progressive rendering support
+   - Error handling with fallback to main thread
+
+**Usage**:
+```javascript
+import { LargeDatasetChart } from 'visualify';
+
+// Component handles large datasets automatically
+const config = {
+  type: 'line',
+  data: largeArray, // 100k+ items
+  sampleSize: 10000,
+  enableWorkerProcessing: true
+};
+```
+
+**Next**: IndexedDB caching layer

package/.claude/mem/notes/2026-02-11-visualify-phase-2-3d-visualization-complete.md

@@ -0,0 +1,50 @@
+---
+title: Visualify Phase 2 - 3D Visualization Complete
+type: note
+tags: [visualify, phase2, 3d, echarts-gl, threejs, docsify, complete]
+created: 2026-02-11T07:19:12.896Z
+updated: 2026-02-11T07:19:12.896Z
+---
+
+## Visualify.js Phase 2 Complete - 3D Visualization
+
+### Commits Ready to Make
+1. Phase 2: 3D Visualization with ECharts GL and Three.js
+
+### Files Created (16 new files)
+**3D Chart Components:**
+- Scatter3D.js, Bar3D.js, Surface3D.js, Line3D.js
+
+**Three.js Module:**
+- index.js, Scene.js, Camera.js, Lighting.js, Renderer.js
+
+**Docsify Integration:**
+- plugin.js, markdown.js, bundle.js
+
+**ECharts GL:**
+- gl.js (lazy loading, WebGL detection)
+
+### Dependencies Added
+- echarts-gl: ^2.0.9
+- three: ^0.160.0
+- @react-three/fiber: ^8.15.0
+- @react-three/drei: ^9.0.0
+- docsify: ^4.13.1
+- docsify-cli: ^4.4.4
+
+### Features Implemented
+- 4 ECharts GL 3D chart types (scatter3d, bar3d, surface3d, line3d)
+- Three.js foundation with scene, camera, lighting, renderer
+- Docsify plugin with markdown code block processing
+- Lazy loading for all 3D libraries
+- WebGL support detection with fallbacks
+- CLI docs commands (dev, build)
+
+### Updated Configuration
+- rollup.config.mjs: 3D libs as externals
+- package.json: 3D dependencies
+- mapping.js: 3D chart registrations
+- entries/docs.js: Docsify integration
+- cli/commands/docs.js: Complete implementation
+
+### Next: Commit these changes, then Phase 3 (TypeScript, HMR, Visual Editor)

package/.claude/mem/notes/2026-02-11-visualify-phase-2-committed-ready-for-phase-3.md

@@ -0,0 +1,33 @@
+---
+title: Visualify Phase 2 Committed - Ready for Phase 3
+type: note
+tags: [visualify, phase2, committed, complete, ready-for-phase3]
+created: 2026-02-11T07:28:02.317Z
+updated: 2026-02-11T07:28:02.317Z
+---
+
+## Visualify.js Phase 2 Complete - Committed
+
+### Commits Made (6 total)
+1. `22a19ea` - Phase 1: CLI merge, visualify.json, dual-mode builds
+2. `eff6f6b` - Phase 1: EsoDev showcase dataportal
+3. `6b0a207` - Phase 1: visualify.json config for showcase
+4. `b37dbb4` - Phase 1: Add /dist to .gitignore
+5. `ead71c3` - Phase 2: 3D visualization (ECharts GL, Three.js, Docsify)
+6. `4eec1ae` - Phase 2: 3D documentation and CHANGELOG
+
+### Untracked (Kept for Memory)
+- `.claude/` - Memory storage
+- `.sisyphus/boulder.json` - Task tracking (not committed)
+
+### Documentation Added
+- `docs/docs/3d-visualization.md` - Comprehensive 3D guide with examples
+- CHANGELOG updated with Phase 2 features
+
+### Ready for Phase 3
+Phase 3 tasks: TypeScript, HMR, Visual Editor, Accessibility, i18n
+
+### Git Status
+- Branch: dev (6 commits ahead of origin/dev)
+- Working tree: clean
+- Untracked: .claude/, .sisyphus/

package/.claude/mem/notes/2026-02-11-visualify-phase-3-complete-developer-experience.md

@@ -0,0 +1,52 @@
+---
+title: Visualify Phase 3 Complete - Developer Experience
+type: note
+tags: [visualify, phase3, complete, typescript, hmr, editor, a11y, i18n]
+created: 2026-02-11T07:53:17.725Z
+updated: 2026-02-11T07:53:17.725Z
+---
+
+## Visualify.js Phase 3 Complete - Developer Experience
+
+### Phase 3: All Tasks Completed
+
+**1. TypeScript Migration**
+- tsconfig.json with strict mode
+- types/index.d.ts, config.d.ts, charts.d.ts, components.d.ts
+- Migrated src/config/ to TypeScript (schema.ts, validator.ts, loader.ts, defaults.ts, index.ts)
+
+**2. Hot Module Replacement (HMR)**
+- src/cli/hmr.js - HMR engine with WebSocket
+- src/cli/dev-server.js - Dev server with HMR injection
+- src/core/hmr-client.js - Client-side HMR handler
+- Updated src/cli/commands/dev.js with --hmr flag
+- State preservation for zoom, pan, selection
+
+**3. Visual Configuration Editor**
+- src/editor/ - Complete visual editor
+- Drag-and-drop chart builder
+- Property panels for all chart types
+- Live preview with ECharts
+- Undo/redo, auto-save to localStorage
+- CLI command: visualify edit
+
+**4. Accessibility (A11y)**
+- src/a11y/aria-labels.js - ARIA label generators
+- src/a11y/keyboard-nav.js - Keyboard navigation
+- src/a11y/color-contrast.js - WCAG compliance checker
+- src/a11y/styles.css - Screen reader styles
+- Updated Scatter.js, Scatter3D.js, Bar3D.js with a11y
+
+**5. Internationalization (i18n)**
+- src/i18n/index.js - i18n module with 6 languages
+- Locales: en, zh, es, de, ar, he (RTL support)
+- src/i18n/formatters.js - Locale-aware formatting
+- src/i18n/rtl.css - RTL layout styles
+- Updated components with useTranslation hook
+
+### Dependencies to Add
+- i18next, react-i18next, i18next-browser-languagedetector
+- chokidar, ws (already added for HMR)
+
+### Ready for Phase 4
+Phase 4: Web Workers, IndexedDB, Streaming, PWA, WebAssembly

package/.claude/mem/notes/2026-02-11-visualify-repository-cleanup-complete.md

@@ -0,0 +1,28 @@
+---
+title: Visualify Repository Cleanup Complete
+type: note
+tags: [visualify, cleanup, ready, phase2]
+created: 2026-02-11T07:04:53.935Z
+updated: 2026-02-11T07:04:53.935Z
+---
+
+## Visualify.js Repository Cleanup Complete
+
+### Cleaned Up
+- Dropped remaining git stash
+- Restored modified dist/visualify.js and docs/static/js/visualify.js
+- Removed untracked build files (dist/*.map, stats.html, etc.)
+- Cleaned up temporary directories (.sisyphus/, .claude/)
+
+### Commits Added
+3. `6b0a207` - chore: add visualify.json config for EsoDev showcase
+4. `b37dbb4` - chore: add /dist to .gitignore
+
+### Final State
+- Working tree: clean
+- Branch: dev (4 commits ahead of origin/dev)
+- Stash: empty
+- Untracked files: none
+
+### Ready for Phase 2
+Repository is clean and ready for 3D visualization implementation.

package/.claude/mem/notes/2026-02-18-codebase-cleanup-docsify-plugin-documentation.md

@@ -0,0 +1,37 @@
+---
+title: Codebase Cleanup - Docsify Plugin Documentation
+type: note
+tags: [visualify, cleanup, docsify, documentation, gitignore, phase4, potential-duplicate:2026-02-11-visualify-repository-cleanup-complete]
+created: 2026-02-18T21:52:58.214Z
+updated: 2026-02-18T21:52:58.214Z
+---
+
+## Codebase Cleanup - Docsify Plugin Documentation
+
+**Commit**: `76f849c` - chore(gitignore): add build artifact patterns and update docs
+
+**Changes Made**:
+
+1. **Updated .gitignore** with build artifact patterns:
+   - `dist/*.map` - Source maps
+   - `dist/stats.html` - Bundle analyzer output
+   - `dist/visualify-*.js` - Build outputs (keeping visualify.js entry point)
+   - `docs/static/js/visualify.js` - Docs build artifact
+
+2. **Verified Docsify Plugin Documentation**:
+   - `docs/docs/docsify-plugin.md` already exists with comprehensive coverage
+   - Installation (CDN, npm, manual)
+   - Basic usage with ` ```visualify ` code blocks
+   - Configuration options for all chart types
+   - 3D visualization support
+   - External data sources
+   - API reference
+   - Troubleshooting section
+   - Sidebar link already present
+
+**Key Insight**: The docsify plugin documentation was already comprehensive - just needed verification and the sidebar was already updated. The main work was cleaning up .gitignore to prevent build artifacts from being committed.
+
+**Next Steps for Full Cleanup**:
+- Consider removing already-tracked build artifacts from git history
+- Evaluate if `config-overrides.js` (CRA config) can be removed (project uses Rollup)
+- Check if `src/docsify/bundle.js` is redundant with `src/entries/docs.js`

package/.claude/mem/notes/2026-02-19-css-grid-layout-fix-displaycontents-on-vcontroller.md

@@ -0,0 +1,18 @@
+---
+title: CSS Grid Layout Fix - display:contents on Vcontroller
+type: note
+tags: [visualify, bugfix, css-grid, layout, display-contents, potential-duplicate:2026-02-19-visualify-build-deployment-architecture-bug-fixes]
+created: 2026-02-19T22:31:02.244Z
+updated: 2026-02-19T22:31:02.244Z
+---
+
+## CSS Grid Layout Fix - display:contents (2026-02-19)
+
+### Root Cause
+`DynamicGrid` (Grid.js) creates the CSS Grid container, but `Vcontroller` (controller.js) wraps components in two nested divs: `.visualify-controller` > `.visualify-components-container`. CSS Grid only positions **direct children**, so grid items (with gridColumn/gridRow styles) were ignored as grandchildren.
+
+### Fix
+Added `style={{ display: 'contents' }}` to both wrapper divs in controller.js. `display: contents` makes the element invisible to layout — children participate in the grandparent grid directly. DOM structure and accessibility attributes are preserved.
+
+### Key Insight
+When using CSS Grid with component wrappers (common in React), intermediate container divs break the grid parent-child relationship. Use `display: contents` on wrapper divs that shouldn't participate in layout.

package/.claude/mem/notes/2026-02-19-docsify-plugin-fixes-latex-and-visualify-code-bloc.md

@@ -0,0 +1,26 @@
+---
+title: Docsify Plugin Fixes - LaTeX and Visualify Code Blocks
+type: note
+tags: [docsify, latex, visualify, plugin, configuration, potential-duplicate:2026-02-11-3d-visualization-docs-fix-external-script-solution]
+created: 2026-02-19T19:35:34.606Z
+updated: 2026-02-19T19:35:34.606Z
+---
+
+## Docsify Plugin Fixes (v3.0.0)
+
+### LaTeX interference with `$docsify` / `$visualify`
+- **Root cause**: `docsify-latex@0.5.2` config had `inlineMath: [['$', '$']]` which treated `$docsify` as LaTeX
+- **Fix**: Removed `['$', '$']` from `config.latex.inlineMath` in `docs/static/js/configuration.js`, keeping only `['\\(', '\\)']`
+- No actual LaTeX inline math using single `$` exists in the docs
+
+### Visualify code block rendering
+- **Root cause**: Docs site loads `docs/static/js/visualify.js` (legacy bundle), NOT `dist/visualify-docs.js` (docsify plugin bundle)
+- The docsify plugin in `src/docsify/plugin.js` was never registered because `config.markdown` wasn't set
+- **Fix**: Added `visualifyCodeBlockPlugin` function directly in `docs/static/js/configuration.js` with `beforeEach` (replaces ```visualify blocks with chart containers) and `doneEach` (mounts charts via `window.$visualify.Recharts`)
+- Uses `<pre>` block preservation: temporarily replaces `<pre>...</pre>` blocks with placeholders to prevent documentation examples from being converted to live charts
+
+### Key architecture notes
+- `docs/static/js/configuration.js` — main docsify config, loaded by `docs/index.html`
+- `window.$visualify.Recharts` — global API for chart creation in docs mode
+- `<pre lang="markdown">` wrapping in markdown = documentation example (not rendered as chart)
+- Bare ```visualify blocks = live demo (rendered as interactive chart)

package/.claude/mem/notes/2026-02-19-page-mode-docs-update-decisions.md

@@ -0,0 +1,23 @@
+---
+title: Page Mode Docs Update Decisions
+type: note
+tags: [docs, page-mode, components, visualify, potential-duplicate:2026-02-19-visualify-v3-bundle-splitting-docs-restructuring]
+created: 2026-02-19T20:11:12.878Z
+updated: 2026-02-19T20:11:12.878Z
+---
+
+## Page Mode Documentation Update (2026-02-19)
+
+Updated all 9 page mode component docs with visual diagrams, tables, and examples:
+
+- **echart.md**: Added 2 live ```visualify demos (scatter + line chart) - only component that supports live demos since it uses same engine as Charts mode
+- **macaron.md**: ASCII graph hierarchy diagram, interaction flow, selection workflow
+- **scatterL.md**: ASCII viewport-based loading diagram, R-tree API format
+- **visium.md**: ASCII tissue section overlay diagram, 3 data sources explained
+- **dotBio.md**: ASCII dot plot matrix diagram, dual encoding explained
+- **plotly.md**: ASCII data flow diagram, scatter + violin examples
+- **html.md**: 3 use case examples (image, iframe, styled content)
+- **more.md**: Renamed to "Utility Components", covers SearchBar/List/RatioBox
+- **markdown.md**: Created new file (was empty), inline + external file examples
+
+Key decision: Only Echart can have live ```visualify demos. Other components (ScatterL, Visium, DotBio, Plotly, Macaron) require backend APIs - compensated with ASCII diagrams and showcase links.

package/.claude/mem/notes/2026-02-19-react-context-infinite-re-render-loop-fix-pattern.md

@@ -0,0 +1,31 @@
+---
+title: React Context Infinite Re-render Loop Fix Pattern
+type: note
+tags: [react, useEffect, infinite-loop, context, performance, visualify, pattern, potential-duplicate:2026-02-19-visualify-infinite-loop-i18n-fixes]
+created: 2026-02-19T23:18:27.478Z
+updated: 2026-02-19T23:18:27.478Z
+---
+
+## React Context Infinite Re-render Loop Fix Pattern
+
+**Root cause**: `useAppContext()` (React Context with `useState`) creates a new `{ sharedData, setSharedData }` object on every render. Every `setSharedData` call triggers ALL consumer components to re-render, and if those components have `useEffect([props, sharedData])` deps, they fire again — creating infinite loops.
+
+**Fix pattern (applied across 10 files in visualify.js):**
+
+1. **`appContext.js`** — Memoize context value: `useMemo(() => ({ sharedData, setSharedData }), [sharedData])`
+2. **Component useEffects** — Replace `[props, sharedData]` deps with:
+   - Extract stable primitives from props outside useEffect
+   - Use `useRef` for props/sharedData to access latest values without deps
+   - Build `sharedDataSnapshot = JSON.stringify(relevantKeys.reduce(...))` for only the keys the component reads
+   - Deps become `[sharedDataSnapshot, stablePrimitive1, stablePrimitive2]`
+3. **setSharedData guards** — Always check if value actually changed before updating:
+   ```js
+   setSharedData((prev) => {
+     if (JSON.stringify(prev[key]) === serializedNewValue) return prev;
+     return { ...prev, [key]: newValue };
+   });
+   ```
+
+**Files fixed**: appContext.js, timeline.js, echartswitcher.js, visium.js, VisiumPlot.js, ScatterBio.js, dotplot.js, ratio.js, selection.js, macaron.js, searchbar.js, scatterL.js
+
+**Build note**: Legacy IIFE build needs `NODE_OPTIONS="--max-old-space-size=8192"` for rollup.

package/.claude/mem/notes/2026-02-19-version-300-bump-and-build-fixes.md

@@ -0,0 +1,32 @@
+---
+title: Version 3.0.0 Bump and Build Fixes
+type: note
+tags: [visualify, version-bump, 3.0.0, build-fix, typescript, plotly, eslint, potential-duplicate:2026-02-11-3d-visualization-docs-fix-session-summary]
+created: 2026-02-19T19:17:56.850Z
+updated: 2026-02-19T19:17:56.850Z
+---
+
+## Version Bump: 2.5.3-3.dev → 3.0.0-1.dev
+
+**Date**: 2026-02-19
+
+### Build Issues Fixed
+1. **Missing `typescript` dependency** — `react-scripts@5.0.1` requires it. Installed `typescript@^4` with `--legacy-peer-deps` due to peer conflict (react-scripts wants ^3.2.1 || ^4, but latest is v5.9)
+2. **Missing `plotly.js` dependency** — peer dep of `react-plotly.js`. Installed with `--legacy-peer-deps`
+3. **ESLint: React hooks rules violation** in `src/a11y/keyboard-nav.js` — renamed `createKeyboardNavigation` → `useKeyboardNavigation` (function uses hooks but wasn't named as a hook)
+4. **ESLint: Conditional hook call** in `src/core/components/ThreeCustom.js` — `useGLTF` was inside try/catch. Moved to unconditional call with error handling in useEffect
+5. **Missing `useCallback` import** in `src/core/components/ThreeCustom.js`
+6. **TS2323: Duplicate export** in `src/config/validator.ts` — `setValidationLocale` and `getValidationLocale` were both inline-exported and in named export block
+
+### Version locations updated (all hardcoded):
+- `package.json` (version field)
+- `src/cli/index.js` (VERSION const)
+- `src/editor/components/Editor.jsx` (default config)
+- `src/editor/index.js` (DEFAULT_CONFIG)
+- `src/editor/context/EditorContext.js` (initialState)
+- `src/cli/commands/edit.js` (editorConfig)
+- `src/editor/README.md` (docs examples)
+
+### Build Status
+- **Rollup**: All 6 bundles pass (docs, portal, shared, legacy, docs-js)
+- **CRA**: Compiles with warnings (unused vars, exhaustive-deps, source map missing)

package/.claude/mem/notes/2026-02-19-visualify-build-deployment-architecture-bug-fixes.md

@@ -0,0 +1,25 @@
+---
+title: Visualify Build & Deployment Architecture + Bug Fixes
+type: note
+tags: [visualify, deployment, build, bugfix, architecture, potential-duplicate:2026-02-18-codebase-cleanup-docsify-plugin-documentation]
+created: 2026-02-19T21:23:06.697Z
+updated: 2026-02-19T21:23:06.697Z
+---
+
+## Visualify Deployment & Build Architecture
+
+### Build outputs:
+- `build/static/js/visualify.js` — CRA full app bundle (IIFE, ~8MB), used for **direct `<script>` tag deployment** (EsoDev server)
+- `dist/visualify.js` — Rollup library bundle (ESM with bare imports, ~750KB), used for **npm package consumers** only
+- Always use `build/` output for server deployment, NOT `dist/`
+
+### Key bug fixes (2026-02-19):
+1. **VisualifyProvider context bug**: `VisualifyWithStatePreservation` used `useAppContext()` but was rendered outside `VisualifyProvider`. Fix: moved provider to `CreateApp` render root, removed duplicate inner provider from `Visualify` component.
+2. **SearchBar infinite re-render**: `useEffect` depended on entire `sharedData` object, causing re-runs on any state change. Fix: extracted specific `triggerValue = sharedData[triggerKey]` and used `useRef` for sharedData access in fetch, narrowing dependency to only the trigger value.
+3. **CSS layout regression**: Adding background/border/padding to `.selection-box-container` broke existing page layouts. Fix: keep original class minimal, only add styling to new namespaced classes (`.v-timeline-*`, `.v-searchbar-*`).
+
+### Deployment to EsoDev server:
+- Copy `build/static/js/visualify.js` and `build/static/css/visualify.css` to server's `static/` dir
+- Also copy chunk files (`visualify.chunk3.js`, `visualify.chunk4.js`)
+- Server `index.html` should NOT load CDN `visualifyjs@2.x` — causes "Cannot use import statement outside module" error
+- Paths must be relative (e.g., `static/js/visualify.js`) when deployed at subpath like `/EsoDev/`

package/.claude/mem/notes/2026-02-19-visualify-dist-iife-self-contained-build-config.md

@@ -0,0 +1,30 @@
+---
+title: Visualify dist IIFE Self-Contained Build Config
+type: note
+tags: [visualify, rollup, deployment, iife, dist, self-contained, potential-duplicate:2026-02-11-3d-visualization-docs-fix-session-summary]
+created: 2026-02-19T21:45:39.214Z
+updated: 2026-02-19T21:45:39.214Z
+---
+
+## Visualify dist/visualify.js — Fully Self-Contained IIFE
+
+### Rollup config change (2026-02-19):
+- Changed `legacyConfig` and `docsStaticConfig` from ESM with all externals to **IIFE with minimal externals**
+- Only `echarts-gl`, `three`, `@react-three/fiber`, `@react-three/drei`, `plotly.js` remain external
+  - Reason: `echarts-gl` has broken zrender imports that prevent bundling; `plotly.js` is ~3.5MB and causes OOM
+  - Three.js libs are rarely used and very large
+- Everything else (React, echarts, Bootstrap, axios, lodash, react-router-dom, react-select, etc.) is bundled in
+- Build requires `NODE_OPTIONS="--max-old-space-size=8192"` to avoid OOM
+- Output: ~2.9MB minified IIFE, works with plain `<script>` tag
+- CSS is injected via `styleInject` — no separate CSS file needed
+
+### Deployment pattern:
+```
+server/
+├── dist/visualify.js     ← single self-contained script
+└── EsoDev/
+    ├── index.html        ← <script src="../dist/visualify.js"></script>
+    ├── chromium.json
+    └── ...
+```
+No CDN dependencies needed for standard 2D pages.