brainsmatics 1.1.65 → 1.1.67

package/AGENTS.md

@@ -7,27 +7,31 @@ It is consumed by tools such as OpenCode, Cursor, Claude Code, etc.
 Project Overview
 ======================================================================
 
-Project name: brain-ui
+Project name: brain-ui (brainsmatics)
 
-This is a frontend UI project built with:
+This is a **React component library** for neuroscience data visualization, built with:
 
 - React 18
-- TypeScript
-- Vite
-- Ant Design (antd)
-- Three.js
-- Storybook
-
-The project contains reusable UI components and 3D / visualization related components.
-Agents must follow the conventions and constraints defined below.
+- TypeScript 4.9.5
+- Vite 4.2.0
+- Ant Design (antd) 5.24.6 + Ant Design X (@ant-design/x) 1.1.0
+- Three.js 0.157.0
+- Storybook 7.0.6
+
+The project provides reusable UI components for:
+- **3D brain visualization** (neurons, brain atlases, regions, SWC files)
+- **2D data viewers** (grids, thumbnails, navigation trees)
+- **AI chat integration** (LLM-powered neuroscience assistant)
+- **Medical imaging** (NIfTI, TIFF, GeoTIFF support)
 
 ======================================================================
 Package Management
 ======================================================================
 
 Preferred package manager:
-- pnpm (preferred if lockfile exists)
-- npm or yarn if pnpm is unavailable
+- **pnpm** (preferred if lockfile exists - `pnpm-lock.yaml`)
+- **npm** (if `package-lock.json` exists)
+- **yarn** (if `yarn.lock` exists)
 
 Do NOT introduce new dependencies unless explicitly requested.
 
@@ -36,36 +40,101 @@ Development / Build Commands
 ======================================================================
 
 Install dependencies:
-- pnpm install
-- npm install
-- yarn install
+```bash
+pnpm install
+# or
+npm install
+# or
+yarn install
+```
 
 Start development server:
-- pnpm dev
-- npm run dev
-
-Production build:
-- pnpm build
-- npm run build
+```bash
+pnpm dev
+# or
+npm run dev
+```
+
+Production build (library):
+```bash
+pnpm build
+# or
+npm run build
+```
 
 Preview production build:
-- pnpm preview
-- npm run preview
+```bash
+pnpm preview
+# or
+npm run preview
+```
 
 ======================================================================
 Storybook
 ======================================================================
 
 Run Storybook locally:
-- pnpm storybook
-- npm run storybook
+```bash
+pnpm storybook
+# or
+npm run storybook
+```
 
 Build Storybook:
-- pnpm build-storybook
-- npm run build-storybook
+```bash
+pnpm build-storybook
+# or
+npm run build-storybook
+```
 
 Story files should be colocated with components and named:
-- *.stories.tsx
+- `*.stories.tsx`
+- `*.stories.ts`
+
+Storybook configuration:
+- Main config: `.storybook/main.js`
+- Preview config: `.storybook/preview.js`
+- Custom middleware: `.storybook/middleware.js` (for API proxying)
+
+======================================================================
+Project Structure
+======================================================================
+
+```
+src/
+├── component/
+│   ├── 2d/           # 2D visualization components
+│   │   ├── gridviewer/      # Grid-based data viewer
+│   │   ├── navtree/         # Navigation tree component
+│   │   ├── navigation/      # Navigation controls
+│   │   ├── thumbnail/       # Thumbnail viewer
+│   │   ├── distribution/    # Data distribution charts
+│   │   ├── mulifiveiewer/   # Multi-view layout
+│   │   ├── twoviewer/       # Dual view comparison
+│   │   └── ...
+│   ├── 3d/           # 3D visualization components
+│   │   ├── functionLoop/    # AI-powered functional circuit analysis
+│   │   ├── aichat/          # AI chat interface (@ant-design/x)
+│   │   ├── swctree/         # SWC neuron file viewer
+│   │   ├── modalLoader/     # 3D model loader (FBX/OBJ)
+│   │   ├── stlLoader/       # STL file loader
+│   │   ├── atlas/           # Brain atlas viewer
+│   │   ├── sideBar/         # 3D viewer sidebar
+│   │   ├── volumeAnalysis/  # Volume data analysis
+│   │   ├── registration/    # Image registration
+│   │   └── ...
+│   ├── common/       # Shared UI components
+│   │   ├── Button/
+│   │   └── Header/
+│   ├── types/        # TypeScript type definitions
+│   └── util/         # Utility functions
+│       ├── i18n.ts          # Internationalization (i18next)
+│       ├── global.ts        # Global state/variables
+│       ├── swc.ts           # SWC file utilities
+│       └── ...
+├── stories/          # Storybook stories
+└── assets/           # Static assets (fonts, icons)
+```
 
 ======================================================================
 TypeScript Rules
@@ -81,16 +150,23 @@ TypeScript Rules
 
 Example:
 
+```typescript
 interface ComponentProps {
   value: number;
   onChange?: (value: number) => void;
 }
+```
+
+Compiler options (from tsconfig.json):
+- Strict mode enabled (`strict: true`)
+- Declaration files generated (`declaration: true`)
+- Path mapping: `"brainsmatics/STAM"` → `dist/component/STAM.d.ts`
 
 ======================================================================
 React Rules
 ======================================================================
 
-- Use function components only
+- Use **function components only**
 - Do NOT use class components
 - Follow the Rules of Hooks
 - Prefer composition over inheritance
@@ -98,35 +174,47 @@ React Rules
 - Avoid deeply nested JSX structures
 
 State management:
-- Prefer local state (useState / useReducer)
-- Avoid unnecessary global state
+- Prefer local state (`useState` / `useReducer`)
+- Use global state sparingly (see `src/component/util/global.ts`)
 - Use refs for mutable values that should not trigger re-render
 
+Performance:
+- Use `useMemo` / `useCallback` for expensive computations
+- Avoid creating new objects/functions inside render unless required
+
 ======================================================================
 Component Structure
 ======================================================================
 
 Recommended component structure:
 
+```
 ComponentName/
-  ├─ index.tsx
-  ├─ index.less | index.css | index.scss
-  ├─ ComponentName.stories.tsx
-  └─ types.ts (optional)
+  ├─ index.tsx              # Main component export
+  ├─ index.css              # Component styles
+  ├─ ComponentName.stories.tsx   # Storybook stories
+  ├─ types.ts               # Component-specific types (optional)
+  └─ SubComponent.tsx       # Child components (optional)
+```
 
 Rules:
-- index.tsx exports the component
-- styles are colocated with the component
-- stories demonstrate common usage and edge cases
+- `index.tsx` exports the component
+- Styles are colocated with the component
+- Stories demonstrate common usage and edge cases
+- Use CSS Modules for complex styling (e.g., `index.module.css`)
 
 ======================================================================
 Ant Design (antd) Usage
 ======================================================================
 
 - Use antd components as the primary UI building blocks
+- Also available: **Ant Design X** (`@ant-design/x`) for AI chat interfaces
+  - `Bubble` - Chat message bubbles
+  - `Sender` - Message input
+  - `Prompts` - Prompt suggestions
 - Avoid copying or modifying antd internal styles
 - Prefer composition instead of overriding antd components
-- Use className or style props for customization
+- Use `className` or `style` props for customization
 - Avoid deep CSS selectors targeting antd internals
 
 ======================================================================
@@ -134,28 +222,105 @@ Three.js Usage
 ======================================================================
 
 - Keep Three.js logic isolated from UI logic when possible
+- Use shared global scene/camera from `src/component/util/global.ts`
 - Avoid heavy allocations inside render loops
 - Be mindful of GPU memory usage
 - Always clean up resources when no longer needed:
-  - geometry.dispose()
-  - material.dispose()
-  - texture.dispose()
-
+  ```typescript
+  geometry.dispose()
+  material.dispose()
+  texture.dispose()
+  ```
 - Avoid unnecessary re-creation of:
   - geometries
   - materials
   - textures
 - Prefer memoization for expensive objects
 
+Common Three.js imports:
+```typescript
+import * as THREE from "three";
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';
+import { FontLoader } from 'three/examples/jsm/loaders/FontLoader';
+import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry';
+import { Line2 } from "three/examples/jsm/lines/Line2";
+import { LineMaterial } from "three/examples/jsm/lines/LineMaterial";
+import { LineGeometry } from "three/examples/jsm/lines/LineGeometry";
+```
+
+======================================================================
+Internationalization (i18n)
+======================================================================
+
+The project uses **i18next** with react-i18next for internationalization.
+
+Supported languages:
+- English (`en_us`)
+- Chinese (`zh_cn`)
+
+Translation files:
+- `src/component/util/en_us.json`
+- `src/component/util/zh_cn.json`
+
+Usage in components:
+```typescript
+import { change_language } from '../util/i18n';
+
+// Component receives `t` function via props
+interface Props {
+  t: (key: string) => string;
+}
+```
+
+======================================================================
+Key Dependencies
+======================================================================
+
+Core:
+- `react` / `react-dom` (peer dependencies, >=18.0.0)
+- `typescript` 4.9.5
+
+UI Framework:
+- `antd` 5.24.6
+- `@ant-design/x` 1.1.0 (AI chat components)
+- `@ant-design/x-markdown` 2.0.0-alpha.5
+
+3D Visualization:
+- `three` 0.157.0
+- `@types/three` 0.157.2
+
+Medical Imaging:
+- `@itk-wasm/image-io` 1.6.0
+- `nifti-reader-js` 0.8.0
+- `geotiff` 2.1.3
+- `tiff` 6.0.0
+
+Charts & Data:
+- `echarts` 5.5.1
+- `react-window` 1.8.9 (virtualization)
+
+Maps:
+- `leaflet` 1.9.4
+- `react-leaflet` 4.2.1
+
+Utilities:
+- `i18next` / `react-i18next` (internationalization)
+- `socket.io-client` 4.8.1
+- `markdown-it` 14.1.0
+- `react-markdown` 10.1.0
+- `dompurify` 3.2.5
+
 ======================================================================
 Performance Guidelines
 ======================================================================
 
 - Avoid unnecessary re-renders
-- Use useMemo / useCallback for expensive computations
+- Use `useMemo` / `useCallback` for expensive computations
 - Do not create new objects/functions inside render unless required
-- Be careful with requestAnimationFrame loops
+- Be careful with `requestAnimationFrame` loops
 - Pay attention to performance in Three.js related code
+- Use `react-window` for long lists
+- Dispose Three.js resources properly
 
 ======================================================================
 Error Handling
@@ -165,6 +330,7 @@ Error Handling
 - Log meaningful error messages
 - Validate external or dynamic data before usage
 - Prefer early returns over deeply nested conditionals
+- Use antd's `message` API for user-facing errors
 
 ======================================================================
 Imports & Naming
@@ -172,15 +338,33 @@ Imports & Naming
 
 Imports order:
 1. React and external libraries
-2. UI components
-3. hooks / utils
-4. styles
+2. UI components (antd, @ant-design/x)
+3. Three.js and visualization libraries
+4. Internal hooks / utils
+5. Styles
 
 Naming conventions:
-- Components: PascalCase
-- Hooks: useSomething
+- Components: PascalCase (e.g., `FunctionLoop`, `SwcTree`)
+- Hooks: camelCase with `use` prefix (e.g., `useSomething`)
 - Files: follow existing project convention
 - Variables: camelCase
+- Constants: UPPER_SNAKE_CASE
+
+======================================================================
+Build Configuration
+======================================================================
+
+Vite configuration (`vite.config.js`):
+- Library mode build (outputs ES and CJS formats)
+- Entry point: `src/index.ts`
+- External dependencies: `react`, `react-dom`
+- TypeScript declaration files generated
+- Proxy configured for `/api` → `http://192.168.50.54:8080`
+
+Output:
+- Main: `dist/index.mjs`
+- Types: `dist/index.d.ts`
+- CSS: `dist/style.css`
 
 ======================================================================
 Testing (If Present)
@@ -189,6 +373,7 @@ Testing (If Present)
 - Prefer testing public behavior over implementation details
 - Avoid excessive snapshot testing
 - Keep tests focused and readable
+- Use Storybook for component testing and documentation
 
 ======================================================================
 Agent Behavior Rules (IMPORTANT)
@@ -203,6 +388,7 @@ When modifying code, agents MUST:
 5. Do NOT introduce new dependencies unless requested
 6. Ensure TypeScript types remain correct
 7. Ensure Storybook stories still work if affected
+8. Respect the existing component architecture (2d vs 3d separation)
 
 If a change is non-trivial, explain WHY the change is needed.
 
@@ -213,7 +399,8 @@ Out of Scope
 - Backend logic
 - API implementations
 - CI/CD configuration unless explicitly requested
+- Database schema changes
 
 ======================================================================
 End of AGENTS.md
-======================================================================
+======================================================================

package/dist/component/2d/charts/BarChart.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+export interface BarData {
+    name: string;
+    value: number;
+    itemStyle?: {
+        color?: string | {
+            type: string;
+            x: number;
+            y: number;
+            x2: number;
+            y2: number;
+            colorStops: {
+                offset: number;
+                color: string;
+            }[];
+        };
+    };
+}
+export interface BarChartProps {
+    data: BarData[];
+    title?: string;
+    xAxisLabel?: string;
+    yAxisLabel?: string;
+    width?: string | number;
+    height?: string | number;
+    horizontal?: boolean;
+    showDataLabels?: boolean;
+    description?: string;
+    onBarClick?: (data: BarData) => void;
+}
+declare const BarChart: React.FC<BarChartProps>;
+export default BarChart;

package/dist/component/2d/charts/ChordChart.d.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+export interface ChordNode {
+    name: string;
+    itemStyle?: {
+        color?: string;
+    };
+}
+export interface ChordLink {
+    source: string;
+    target: string;
+    value: number;
+    lineStyle?: {
+        color?: string;
+        opacity?: number;
+    };
+}
+export interface ChordChartProps {
+    nodes: ChordNode[];
+    links: ChordLink[];
+    title?: string;
+    width?: string | number;
+    height?: string | number;
+    showLabels?: boolean;
+    labelRotate?: boolean;
+    description?: string;
+    onNodeClick?: (nodeName: string) => void;
+    onLinkClick?: (link: ChordLink) => void;
+}
+declare const ChordChart: React.FC<ChordChartProps>;
+export default ChordChart;

package/dist/component/2d/charts/HeatmapChart.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+export interface HeatmapData {
+    x: string;
+    y: string;
+    value: number;
+    displayValue?: number | string;
+}
+export interface HeatmapChartProps {
+    xCategories: string[];
+    yCategories: string[];
+    data: HeatmapData[];
+    title?: string;
+    width?: string | number;
+    height?: string | number;
+    minValue?: number;
+    maxValue?: number;
+    colorRange?: string[];
+    showLabels?: boolean;
+    description?: string;
+    onCellClick?: (data: HeatmapData) => void;
+}
+declare const HeatmapChart: React.FC<HeatmapChartProps>;
+export default HeatmapChart;

package/dist/component/2d/charts/RadarChart.d.ts

@@ -0,0 +1,34 @@
+import React from 'react';
+export interface RadarIndicator {
+    name: string;
+    max: number;
+    min?: number;
+}
+export interface RadarSeries {
+    name: string;
+    value: number[];
+    itemStyle?: {
+        color?: string;
+    };
+    areaStyle?: {
+        color?: string;
+        opacity?: number;
+    };
+    lineStyle?: {
+        color?: string;
+        width?: number;
+    };
+}
+export interface RadarChartProps {
+    indicators: RadarIndicator[];
+    data: RadarSeries[];
+    title?: string;
+    width?: string | number;
+    height?: string | number;
+    shape?: 'polygon' | 'circle';
+    showLegend?: boolean;
+    description?: string;
+    onSeriesClick?: (seriesName: string) => void;
+}
+declare const RadarChart: React.FC<RadarChartProps>;
+export default RadarChart;

package/dist/component/2d/charts/SankeyChart.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+export interface SankeyNode {
+    name: string;
+    itemStyle?: {
+        color?: string;
+        borderColor?: string;
+        borderWidth?: number;
+    };
+}
+export interface SankeyLink {
+    source: string;
+    target: string;
+    value: number;
+    lineStyle?: {
+        color?: string;
+        opacity?: number;
+    };
+}
+export interface SankeyChartProps {
+    data: {
+        nodes: SankeyNode[];
+        links: SankeyLink[];
+    };
+    title?: string;
+    width?: string | number;
+    height?: string | number;
+    description?: string;
+    onNodeClick?: (nodeName: string) => void;
+    onLinkClick?: (link: SankeyLink) => void;
+}
+declare const SankeyChart: React.FC<SankeyChartProps>;
+export default SankeyChart;

package/dist/component/2d/charts/index.d.ts

@@ -0,0 +1,10 @@
+export { default as SankeyChart } from './SankeyChart';
+export type { SankeyChartProps, SankeyNode, SankeyLink } from './SankeyChart';
+export { default as BarChart } from './BarChart';
+export type { BarChartProps, BarData } from './BarChart';
+export { default as ChordChart } from './ChordChart';
+export type { ChordChartProps, ChordNode, ChordLink } from './ChordChart';
+export { default as RadarChart } from './RadarChart';
+export type { RadarChartProps, RadarIndicator, RadarSeries } from './RadarChart';
+export { default as HeatmapChart } from './HeatmapChart';
+export type { HeatmapChartProps, HeatmapData } from './HeatmapChart';

package/dist/component/2d/index.d.ts

@@ -7,3 +7,4 @@ export { default as Thumbnail } from "./thumbnail";
 export { default as MulfiViewer } from "./mulifiveiewer";
 export { default as Distribution } from "./distribution";
 export { default as Z } from "./js/index.js";
+export * from "./charts";

package/dist/{deflate-3e488582.mjs → deflate-2e40cd1a.mjs}

@@ -1,4 +1,4 @@
-import { i as r } from "./index-74ec7690.mjs";
+import { i as r } from "./index-4863f635.mjs";
 import { B as o } from "./basedecoder-11034ec6.mjs";
 import "react";
 import "react-dom";

package/dist/{deflate-ae534b41.js → deflate-327fcbc7.js}

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./index-b0a350ce.js"),t=require("./basedecoder-0503cc54.js");require("react");require("react-dom");class d extends t.BaseDecoder{decodeBlock(e){return r.inflate_1(new Uint8Array(e)).buffer}}exports.default=d;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("./index-521f4ce7.js"),t=require("./basedecoder-0503cc54.js");require("react");require("react-dom");class d extends t.BaseDecoder{decodeBlock(e){return r.inflate_1(new Uint8Array(e)).buffer}}exports.default=d;