astrolabe-nvc/CLAUDE.md

# CLAUDE.md

Instructions for Claude Code when working on this project.

## Project Overview

**Astrolabe** is a lightweight, browser-based snippet manager for Vega-Lite visualizations. Pure vanilla JavaScript, no build tools, retro Windows 2000 aesthetic.

## Architecture

- **Frontend-only**: HTML/CSS/JavaScript with CDN dependencies (Monaco Editor, Vega-Embed)
- **Storage**:
  - **Snippets**: localStorage (id, name, created, modified, spec, draftSpec, comment, tags, datasetRefs, meta)
  - **Datasets**: IndexedDB (unlimited size, multi-format: JSON/CSV/TSV/TopoJSON, inline & URL sources)
- **Structure**: Three resizable panels (snippet library, Monaco editor, live preview) + Dataset Manager modal
- **Deployment**: Root folder contains `index.html` and all app files; `/project-docs` folder contains development documentation
- **No build tools**: Open `index.html` directly in browser (needs local server for service worker and IndexedDB)

## Current Status

**Version**: 0.3.0 (Alpha - pre-1.0 development)
**Deployment**: Live at astrolabe-viz.com
**Mode**: Alpha testing and iterative improvements

### Core Capabilities
- Snippet management with draft/published workflow
- Dataset library (IndexedDB) with multi-format support (JSON, CSV, TSV, TopoJSON)
- Dataset reference resolution in Vega-Lite specs
- Progressive Web App with offline functionality and installability
- User settings and theme system (Light, Dark Experimental)
- Import/export functionality for snippets and datasets
- Real-time search and multi-field sorting
- Cross-platform keyboard shortcuts
- Toast notification system
- Storage monitoring with visual warnings
- URL state management (shareable links, browser navigation)
- Bidirectional snippet ↔ dataset linking
- Table preview with type detection
- Extract inline data to datasets

See `project-docs/architecture.md` for complete technical details.

## Development Mode

Development is **iterative** based on:
- Bug reports and fixes
- User feedback and feature requests
- Performance optimization
- Cross-browser compatibility improvements
- Code quality enhancements

When implementing changes:
- Treat each issue/enhancement as an independent task
- Group related bugfixes in a single commit
- Update CHANGELOG.md for user-facing changes
- Test thoroughly across different browsers when possible
- Maintain backward compatibility with existing data

### Release Process
Astrolabe uses semantic versioning with alpha releases (`0.x.y`) until public launch. Each release requires version updates in four files: `config.js` (APP_VERSION), `sw.js` (CACHE_NAME), `CLAUDE.md`, and `CHANGELOG.md`. See `project-docs/release-checklist.md` for the complete workflow.

## Development Principles

- **Lean**: No frameworks, no build step, minimal dependencies
- **Maintainable**: Clean code organization with logical separation of concerns
- **Simple**: Favor code removal over addition; avoid over-engineering
- **Local-first**: All data stored in browser, no server dependencies

## General coding instructions (important)
- Astrolabe is a project with minimalistic philosophy; it tries to avoid external dependencies and complexity, if possible. This means that whatever new feature, refactor, or bug fix is being considered, the solution should not be over-engineered unless absolutely necessary. The importance and complexity of a feature defines allowed number of lines of code dedicated to it.
- Pay attention to the existing code base style and approaches and try to adhere to the existing style instead of bringing your own vision.
- When updating documentation, do not record intermediate changes - write them always as a matter-of-fact information.
- When working on the code, if you notice any opportunities to better bring the project to the state above - bring this to user's attention and ask for approval to implement the suggested changes.
- When attempting to implement a new feature, research whether a similar method or fuction already exists elsewhere. Propose to either enhance existing one, or create a new method in such cases.
- Testing: The user always tests changes manually. Do not start local servers or attempt to run the application.

## Documentation guidelines
- **Conciseness**: Keep documentation compact and practical. Avoid verbose explanations or unnecessary code examples in technical docs.
- **Code examples**: Only include code examples in documentation when they genuinely clarify complex concepts. Omit examples for straightforward implementations.
- **User-facing content**: When updating help/about sections in the UI (like index.html modals), keep additions brief and integrated with existing content style.
- **Technical docs**: Focus on "what" and "why" rather than "how" - developers can read the actual code for implementation details.