Bootstrap AGENTS.md and agent documentation

.github/copilot-instructions.md

@@ -1,193 +1,13 @@
-# Miew 3D Molecular Viewer - Repository Instructions
+See [AGENTS.md](../AGENTS.md) — single source of truth for full agent instructions, architecture, and design docs.
 
-## Project Overview
+<!-- CODE COMPLETION CACHE: The rules below are mirrored from AGENTS.md for inline code completion engines that do not load external files. -->
 
-Miew is a high-performance web tool for advanced visualization and manipulation of molecular structures. It provides a full-featured set of tools for 3D visualization and editing of small molecules as well as large molecular complexes, including means to view, analyze, and modify the 3D structure of a molecule.
+## Core Invariants
+- `packages/miew` is framework-agnostic pure ES6+ (Three.js 0.153). Never import React into core.
+- `packages/miew-app` and `packages/miew-react` use React 19, Redux Toolkit, and SCSS modules.
+- Explicitly dispose Three.js geometries, buffer attributes, and materials on teardown or mode rebuilds to avoid GPU memory leaks.
 
-The project works as a standalone web application or integrates as a component into web pages. It targets the latest versions of WebGL-enabled desktop (Chrome, Firefox, Safari, Edge) and mobile (iOS, Android) browsers.
-
-## Monorepo Structure
-
-This is a Yarn monorepo organized as follows:
-
-- **Root level**: Contains monorepo configuration, shared tooling, and documentation
-- **packages/miew**: Core JavaScript library with the 3D molecular viewer, including docs, examples, and old demo application
-- **packages/miew-react**: React.js wrapper component for easy integration
-- **packages/miew-app**: New demo application built with React with the goal to replace the old demo application (work in progress)
-
-Note that the core library (`miew`) is framework-agnostic and does not depend on React or any other UI framework. It started in 2015 and can be considered as a legacy-style JavaScript library. It implements its own mutable state management. Other packages (`miew-react`, `miew-app`) are built with modern React best practices.
-
-### Key Directories
-
-- `/packages/miew/src/`: Core library source code
-  - `/chem/`: Chemistry-related classes (Complex, Atom, Bond, etc.)
-  - `/gfx/`: Graphics rendering (modes, colorers, materials, shaders)
-  - `/io/`: File input/output (loaders, parsers for PDB, SDF, etc.)
-  - `/ui/`: User interface components and controls
-  - `/utils/`: Utility functions and helpers
-- `/packages/miew/demo/`: Old demo application assets and scripts
-- `/packages/miew/examples/`: Usage examples and integration samples
-- `/packages/miew/test/`: Unit and E2E tests
-- `/packages/miew/docs/`: Documentation and tutorials
-- `/packages/miew-react/src/`: React component wrapper
-- `/packages/miew-react/types/`: Type definitions for use by TypeScript projects
-- `/packages/miew-app/src/`: New React-based demo application
-
-## Technologies and Frameworks
-
-### Core Technologies
-- **JavaScript ES6+**: Primary language for the core library
-- **Three.js 0.153.0**: 3D graphics rendering engine
-- **WebGL**: Hardware-accelerated 3D graphics
-- **Lodash**: Utility library
-
-### Build Tools and Development
-- **Webpack 5**: Module bundler for all packages
-- **Babel**: JavaScript transpilation with preset-env and preset-react
-- **Yarn 3**: Package manager with workspaces
-- **Node.js 22-26**: Development environment
-
-### React Ecosystem (miew-app, miew-react)
-- **React 16/19**: UI framework
-- **React Redux 7**: State management
-- **React Bootstrap**: UI components
-- **React Icons**: Icon library
-
-### Testing and Quality (miew)
-- **Mocha**: Test runner
-- **Chai**: Assertion library
-- **ESLint**: Linting with Airbnb base config
-- **Stylelint**: CSS/SCSS linting
-- **NYC**: Code coverage
-- **Selenium WebDriver**: E2E testing
-
-### Testing and Quality (miew-app, miew-react)
-- **Jest**: Test runner and assertion library
-- **React Testing Library**: React component testing
-
-## Coding Standards and Conventions
-
-### Code Quality and Change Management
-- **Keep changes focused**: Each commit should address a single, well-defined issue or feature
-- **Honor Single Responsibility Principle**: Classes and functions should have one clear purpose
-- **Avoid irrelevant changes**: Don't mix formatting, refactoring, or unrelated fixes in feature commits
-- **Split large changes**: Break substantial modifications into multiple commits and pull requests for easier review
-- **One concept per PR**: Each pull request should implement one feature, fix one bug, or address one improvement
-
-### JavaScript/ES6+
-- Follow **Airbnb JavaScript Style Guide** via ESLint configuration
-- Use ES6+ features: arrow functions, destructuring, template literals, modules
-- Use `import`/`export` for modules (no CommonJS in source)
-- Prefer `const` and `let` over `var`
-- Use meaningful variable and function names
-- Comment complex algorithms and mathematical computations
-
-### React/JSX (for React packages)
-- Use functional components with hooks when possible
-- Follow React best practices for state management
-- Use JSX for component rendering
-- Implement proper prop validation
-- Use SCSS modules for styling
-
-### File Naming
-- Use PascalCase for class files, React components, and SCSS modules: `ComplexVisual.js`, `AboutPanel.module.scss`
-- Use camelCase for utility files and modules: `settings.js`, `getTopWindow.js`, `main.scss`
-
-### Code Organization
-- One class per file for major components
-- Group related functionality in modules/directories
-- Use barrel exports (`index.js`) for clean imports
-- Keep test files adjacent to source files with `.test.js` suffix
-
-## Development Workflow
-
-### Git Commit Messages
-Follow these guidelines for writing clear and consistent commit messages:
-
-- **Capitalize and use imperative mood**: Start with a verb like "Add", "Fix", "Update", "Remove"
-- **Keep subject line concise**: Aim for 50 characters or less
-- **Separate subject from body**: Use a blank line between the subject and detailed description
-- **Focus on what and why**: Explain what changed and why, not how it was implemented
-
-Examples:
-```
-Add support for CIF file format
-
-Implement parser and loader for Crystallographic Information File
-format to support crystal structure visualization. This addresses
-user requests for broader file format compatibility.
-```
-
-```
-Fix memory leak in molecular rendering
-
-Properly dispose of Three.js geometries and materials when
-switching between visualization modes to prevent browser
-memory exhaustion with large molecules.
-```
-
-### Package Scripts
-- `yarn ci`: Full CI pipeline (clean, lint, test, build)
-- `yarn test:e2e`: Run time-consuming end-to-end visual regression tests for `miew` package
-
-### Testing Guidelines
-- Write unit tests for new functionality
-- Place the unit tests in the same directory as the source files
-- Use descriptive test names and organize with `describe` blocks
-- Mock external dependencies appropriately
-- Maintain high test coverage for critical paths
-
-### Browser Support
-- Target modern browsers with WebGL support
-- Test on Chrome, Firefox, Safari, and Edge
-- Consider mobile browser limitations
-- Graceful degradation for unsupported features
-
-## Architecture Patterns
-
-### Core Library (miew)
-- **Event-driven architecture**: Use EventDispatcher for component communication
-- **Plugin system**: Modes, colorers, and materials are pluggable
-- **Separation of concerns**: Clear separation between chemistry (chem/), graphics (gfx/), and UI (ui/)
-- **Factory patterns**: For creating parsers, loaders, and visual representations
-
-### Graphics Pipeline
-- Uses Three.js scene graph
-- Custom shaders for advanced rendering effects
-- Support for multiple rendering modes (wireframe, space-filling, cartoon, etc.)
-- Efficient instancing for molecular structures
-
-### State Management
-- Settings system for persistent configuration
-- Immutable state updates where possible
-- React Redux for React-based applications
-
-## Performance Considerations
-
-- Optimize for large molecular structures (10K+ atoms)
-- Use GPU-accelerated rendering through WebGL
-- Implement efficient picking and selection algorithms
-- Memory management for large datasets
-- Progressive loading for better user experience
-
-## Documentation Guidelines
-
-- Use JSDoc for API documentation
-- Include examples in documentation
-- Update CHANGELOG.md for user-facing changes
-- Maintain README files for each package
-- Consider writing tutorials for complex features
-
-## Security and Dependencies
-
-- Keep dependencies updated, especially Three.js and security-sensitive packages
-- Use exact versions for critical dependencies
-- Review dependency vulnerabilities regularly
-- Sanitize user inputs, especially in parsers
-
-## Browser Compatibility Notes
-
-- WebGL 1.0 minimum requirement
-- Modern JavaScript features (ES6+) - no IE support
-- Use feature detection for advanced WebGL capabilities
-- Test on mobile devices for touch interactions
+## Conventions
+- PascalCase: Classes, React components, SCSS modules (`ComplexVisual.js`, `AboutPanel.module.scss`).
+- camelCase: Utilities, helpers, hooks (`settings.js`, `useViewer.js`).
+- Test files: Colocate adjacent to source (`*.test.js`).

AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in the Miew monorepo.
+
+**Living documentation**: When you make a mistake or discover non-obvious behavior, record it in [Lessons Learned](docs/agents/lessons-learned.md). When defining or clarifying domain terms, update [CONTEXT.md](CONTEXT.md).
+
+## Subsystems & Invariants
+
+- **Core Library (`packages/miew`)**: Pure ES6+ / Three.js 0.153 3D visualization engine. Framework-agnostic (never import React). Mutable scene graph and object pooling for 60 FPS performance on large complexes.
+- **React Components (`packages/miew-react`)**: Declarative React 19 wrapper component (`<Miew />`).
+- **Modern Web App (`packages/miew-app`)**: React 19 + Redux Toolkit + React-Bootstrap web application replacing the legacy demo. Requires responsive mobile and touch support.
+
+## Critical Guardrails & Patterns
+
+- **Framework Isolation**: Never import React or UI framework packages into `packages/miew`.
+- **Three.js Resource Disposal**: Explicitly dispose of Three.js geometries, buffer attributes, and materials when destroying or rebuilding visual representation modes to prevent GPU memory leaks.
+- **File Naming & Colocation**: PascalCase for class files, React components, and SCSS modules (`AboutPanel.module.scss`). camelCase for utilities (`settings.js`). Colocate test files adjacent to source with `.test.js` suffix.
+- **Single Responsibility**: Dedicated, colocated modules for new concerns (components, hooks, utilities, parsers) rather than appending to existing files.
+
+## Context Pointers
+
+- `Architecture`: Data pipeline, package responsibilities, and Three.js scene graph lifecycle → [docs/agents/architecture.md](docs/agents/architecture.md)
+- `Code Style`: ESLint 9, SCSS modules, Stylelint 17, testing frameworks, and resource disposal → [docs/agents/code-style.md](docs/agents/code-style.md)
+- `Domain Language`: Canonical terminology and forbidden synonyms → [CONTEXT.md](CONTEXT.md)
+- `Design System`: Visual tokens, UI architecture, responsive and touch guidelines → [DESIGN.md](DESIGN.md)
+- `Issue Tracker`: GitHub CLI operations and wayfinding workflow → [docs/agents/issue-tracker.md](docs/agents/issue-tracker.md)
+- `Triage Labels`: Canonical triage roles to tracker labels mapping → [docs/agents/triage-labels.md](docs/agents/triage-labels.md)
+
+## Commands
+
+- Monorepo full CI: `yarn ci`
+- Fast core validation: `cd packages/miew && yarn ci-fast`
+- Package scripts: `yarn workspace <miew|miew-app|miew-react> <lint|test|build|...>`
+- Run project checks through package scripts, not raw tool binaries.
+
+## Git & Commits
+
+- Imperative commit subject line (50 chars or less, no trailing period), e.g. `Add mmCIF secondary structure parser`.
+- Keep commits atomic and informative. Preserve clean rebase history; squash only temporary work.

CONTEXT.md

@@ -0,0 +1,59 @@
+# Miew
+
+High-performance 3D molecular visualization system for rendering chemical structures and macromolecular complexes in WebGL.
+
+## Language
+
+### Chemical Structure
+
+**Complex**:
+A complete molecular hierarchy comprising atoms, bonds, residues, chains, and secondary structures.
+_Avoid_: Molecule, structure, model
+
+**Residue**:
+A monomeric building block within a macromolecular chain, such as an amino acid, nucleotide, or solvent molecule.
+_Avoid_: Monomer, unit, component
+
+**Chain**:
+A continuous polymer sequence of bonded residues within a Complex.
+_Avoid_: Polymer, strand, subunit
+
+**Secondary Structure**:
+The local spatial conformation of a macromolecular chain backbone, primarily alpha-helices and beta-sheets.
+_Avoid_: Fold, motif
+
+### Visualization
+
+**Viewer**:
+The primary 3D WebGL engine and canvas orchestrator controlling scene rendering, cameras, animations, and input events.
+_Avoid_: Canvas, player, window
+
+**Representation**:
+A visual entity defining how a selected subset of a Complex is rendered, combining a Mode, Colorer, Material, and Selector.
+_Avoid_: Visual, style preset, display
+
+**Mode**:
+A geometric representation algorithm that generates 3D geometry from chemical topology, such as Cartoon, Lines, Balls & Sticks, or QuickSurface.
+_Avoid_: Geometry, shape, style
+
+**Colorer**:
+A strategy for assigning color attributes to atoms, residues, or surfaces based on chemical or physical properties.
+_Avoid_: Palette, theme, color scheme
+
+**Material**:
+A shader and optical surface definition specifying properties such as shininess, roughness, opacity, and wireframe display.
+_Avoid_: Shader, texture, finish
+
+**Selector**:
+A domain query expression that evaluates and filters atoms and residues within a Complex.
+_Avoid_: Filter, query, mask
+
+### Data Pipeline
+
+**Parser**:
+A format-specific deserializer that transforms chemical file data into a Complex.
+_Avoid_: Reader, importer, decoder
+
+**Loader**:
+An I/O provider responsible for retrieving raw molecular data from remote repositories or local sources.
+_Avoid_: Fetcher, downloader