astrolabe-nvc/docs/dev-plan.md

Astrolabe Development Plan

A lightweight, browser-based snippet manager for Vega-Lite visualizations

For AI Context: See CLAUDE.md for current status and key patterns. This Document: Complete development roadmap and technical decisions.

Project Vision

Astrolabe is a focused tool for managing, editing, and previewing Vega-Lite visualization specifications. It emphasizes efficient snippet management with a clean, resizable three-panel interface: snippet library, Monaco editor with schema-aware autocomplete, and live preview.

Design Principles

• Local-first: All data stored in browser (localStorage, future IndexedDB migration)
• Minimal dependencies: Vanilla JavaScript, no build tools, direct CDN imports
• Developer-friendly: Full JSON schema support, syntax validation, and intellisense
• Version-aware: Draft/published workflow for safe experimentation
• Dataset management: Separate storage for datasets with reference system
• Extensible: Clean architecture for future cloud sync and authentication

Planned Feature Set

• Resizable three-panel layout with show/hide toggles
• Auto-saving draft system with explicit publishing
• Snippet organization with sorting and search
• Storage monitoring and size tracking
• Export/import functionality
• Dataset library and management
• (Future) Authentication and cloud synchronization

---

Development Roadmap

Phase 0: Storage Architecture Design ✅ COMPLETE

Goal: Define data structures that accommodate full feature set

• Design snippet schema: {id, name, created, modified, spec, draftSpec, comment, tags[], datasetRefs[], meta}
• Design dataset schema: {id, name, created, modified, data, format, rowCount, columnCount, size, columns, comment, tags, meta}
• Design settings schema: {panelWidths[], panelVisibility[], autoSaveDelay, meta}
• Plan localStorage key structure and namespacing
• Define upgrade/migration path for schema changes
• Document storage architecture decisions (see storage-examples.md)

Deliverable: Documented data model that supports all planned features

Key Decisions Made:

• ID generation: Date.now() + random numbers for uniqueness
• Auto-naming: ISO datetime format for default snippet names
• Draft/published workflow: separate spec and draftSpec fields
• Computed metadata: automatic calculation of size, rowCount, columns for datasets
• Extensibility: meta field in all schemas for future enhancements
• Settings persistence: panel state and UI preferences stored locally

---

Phase 1: Static HTML Structure ✅ COMPLETE

Goal: Basic three-panel layout with placeholder content

Deliverables:

• Three-panel flexbox layout (snippet library, editor, preview)
• Header with site branding (🔭 Astrolabe) and action links
• Toggle button strip with emoji icons (📄 ✏️ 👁️)
• Retro Windows 2000 aesthetic with classic colors and square edges
• Sort and search controls in snippet panel header
• Metadata panel for snippet details

---

Phase 2: Resizable Panels ✅ COMPLETE

Goal: Make panels draggable to resize

Deliverables:

• Drag handles between panels with hover/active states
• Mouse-based horizontal resizing with 200px minimum widths
• Panel memory system preserving preferred sizes when toggled
• Proportional redistribution when panels are hidden/shown
• localStorage persistence for panel widths, visibility, and memory
• Toggle buttons with active state indicators

---

Phase 3: Monaco Editor Integration ✅ COMPLETE

Goal: Working code editor with Vega-Lite schema

Deliverables:

• Monaco Editor v0.47.0 loaded from CDN
• JSON language mode with Vega-Lite v5 schema validation
• Autocomplete and intellisense for Vega-Lite specifications
• Format on paste/type enabled
• Error handling for schema loading failures

---

Phase 4: Vega-Lite Rendering ✅ COMPLETE

Goal: Live preview of visualizations

Deliverables:

• Vega, Vega-Lite, and Vega-Embed libraries loaded via CDN
• AMD loader conflict resolution between Monaco and Vega
• 1.5s debounced rendering on editor changes
• Immediate rendering on snippet selection
• Error display in preview panel for invalid specs
• SVG rendering for high-quality output

---

Phase 5: Data Model + LocalStorage ✅ COMPLETE

Goal: Persist snippets and load them on page refresh

Deliverables:

• SnippetStorage wrapper with error handling
• Full Phase 0 schema implementation (id, name, created, modified, spec, draftSpec, comment, tags, datasetRefs, meta)
• ID generation using timestamp + random numbers
• Auto-naming with ISO datetime format (YYYY-MM-DD_HH-MM-SS)
• Dynamic snippet list rendering with relative date formatting
• Default snippet initialization on first load
• Snippet selection loading specs into editor

---

Phase 6: Snippet Selection & Basic CRUD ✅ COMPLETE

Goal: Core snippet management with advanced organization

Deliverables:

• Snippet selection loading into editor with live preview
• Ghost card "Create New Snippet" interface at top of list
• Duplicate button creating copies with "_copy" suffix
• Delete button with confirmation dialog
• Inline name editing in metadata panel with auto-save
• Comment field with auto-save
• 1-second debounced auto-save for spec and metadata changes
• Multi-field sorting (Modified/Created/Name) with ascending/descending toggle
• Visual sort indicators with arrow icons (⬇⬆)
• Real-time search across name, comment, and spec content (300ms debounce)
• Search clear button
• Settings persistence for sort preferences
• Smart state management maintaining selection during operations
• Synchronous flag-based prevention of auto-save during programmatic updates

---

Phase 7: Draft/Published Workflow ✅ COMPLETE

Goal: Safe experimentation without losing working versions

Deliverables:

• Draft/Published toggle buttons in editor header (merged visual design)
• Status indicator lights on snippets (🟢 green = no changes, 🟡 yellow = has draft)
• Publish button (green, copies draftSpec → spec)
• Revert button (orange, copies spec → draftSpec with confirmation)
• Context-aware button visibility (only shown in draft mode)
• Read-only published view when draft exists
• Auto-draft creation when editing published view without draft
• Auto-select first snippet on page load
• Instant status light updates after auto-save

---

Phase 8: Storage Monitoring ✅ COMPLETE

Goal: Show storage usage and limits

Deliverables:

• Storage usage calculation using Blob API for accurate byte counting
• Progress bar display showing usage vs 5MB limit (e.g., "2.3 MB / 5 MB")
• Visual warning states: green (normal), orange (90%+ warning), red (95%+ critical)
• Storage monitor positioned at bottom of snippet panel below metadata
• Automatic updates after every save operation
• Alert dialog when localStorage quota is exceeded
• Flexbox layout ensuring monitor stays at panel bottom with scrollable snippet list

---

Phase 9: Export/Import ✅ COMPLETE

Goal: Portability and backup

Deliverables:

• Export all snippets to JSON file with auto-generated filename (astrolabe-snippets-YYYY-MM-DD.json)
• Import snippets from JSON with automatic format detection
• Support for both Astrolabe native format and external formats
• Automatic field mapping and normalization (createdAt → created, content → spec, draft → draftSpec)
• "imported" tag automatically added to externally imported snippets
• ID conflict resolution with automatic regeneration
• Additive import (merges with existing snippets, no overwrites)
• Success/error feedback with import count
• File picker integration with header Import/Export links
• Snippet size display in list (shows KB for snippets ≥ 1 KB, right-aligned)

Note: Drag-and-drop import and selective export options deferred to future phases

---

Phase 10: Dataset Management - Part 1

Goal: Separate dataset storage infrastructure

• Implement dataset storage schema from Phase 0
• Create dataset CRUD operations
• Add dataset library panel/modal
• List all stored datasets with metadata
• Add/delete/rename datasets
• Display dataset size and row counts

Deliverable: Basic dataset storage separate from snippets

---

Phase 11: Dataset Management - Part 2

Goal: Reference datasets from specs

• Detect inline data in Vega-Lite specs
• "Extract to dataset" feature for inline data
• Replace inline data with dataset references
• Auto-resolve dataset references when rendering
• Update snippet UI to show linked datasets
• Handle missing dataset references gracefully

Deliverable: Specs can reference shared datasets

---

Phase 12: Polish & UX Refinements

Goal: Professional feel and usability

• Improved visual design (minimal but polished CSS)
• Keyboard shortcuts (Ctrl+S to publish, Ctrl+N for new, etc.)
• Better error messages and validation feedback
• Loading states for rendering
• Empty states (no snippets, no datasets)
• Tooltips for buttons and features
• Cross-browser testing (Chrome, Firefox, Safari)

Deliverable: Polished, production-ready MVP

---

Phase 13: Advanced Snippet Features

Goal: Power user functionality

• Basic tagging system with tag filtering
• Snippet templates/starter library
• Bulk operations (delete multiple, export selected)
• Size calculation and display for snippets

Deliverable: Enhanced snippet discovery and organization

Note: Search/filter and sorting already implemented in Phase 6

---

Phase 14: Authentication & Backend (Future)

Goal: Multi-device sync and sharing

• Design minimal backend API
• User authentication (email/password or OAuth)
• Sync localStorage ↔ cloud storage
• Conflict resolution strategy
• Share snippets via URL
• Public snippet gallery (optional)

Deliverable: Cloud-backed, multi-device Astrolabe

---

Technical Stack

• Frontend: Vanilla JavaScript (ES6+), HTML5, CSS3
• Editor: Monaco Editor v0.47.0 (via CDN)
• Visualization: Vega-Embed v6 (includes Vega v5 & Vega-Lite v5)
• Storage: LocalStorage → IndexedDB (when needed)
• Architecture: Modular script organization with simple file separation
• Backend (future): TBD (minimal REST API)

Project Structure

/
├── index.html                 # Main HTML structure and markup
├── CLAUDE.md                  # Project instructions for Claude Code
├── src/
│   ├── styles.css            # Retro Windows 2000 aesthetic styling
│   └── js/                   # Modular JavaScript organization
│       ├── config.js         # Global variables, settings, & sample data
│       ├── snippet-manager.js # Snippet storage, CRUD operations & localStorage wrapper
│       ├── panel-manager.js  # Panel resize, toggle & memory system
│       ├── editor.js         # Monaco Editor initialization & Vega-Lite rendering
│       └── app.js            # Application initialization & event handlers
└── docs/
    ├── dev-plan.md           # This development roadmap
    └── storage-examples.md   # Data model specifications

Development Principles

• Iterative: Each phase produces working, testable functionality
• Lean: No frameworks, no build step, minimal dependencies
• Data-first: Storage schema designed upfront for extensibility
• User-focused: Auto-save, clear state, forgiving UX
• Maintainable: Clean code organization with logical separation of concerns
• Simple: Favor code removal over addition; avoid over-engineering

Code Organization

• index.html: Main HTML structure with semantic markup
• app.js: Application initialization and event handler registration
• config.js: Global variables, settings management, and sample data
• snippet-manager.js: Storage wrapper and all snippet CRUD operations
• panel-manager.js: Layout resizing, toggling, and persistence
• editor.js: Monaco and Vega library loading and rendering logic
• styles.css: Retro Windows 2000 aesthetic with component-based organization

---

Current Status

Completed: Phases 0-9 (Storage, UI, editor, rendering, persistence, CRUD, organization, draft/published workflow, storage monitoring, import/export) Next: Phase 10 - Dataset Management See: CLAUDE.md for concise current state summary

---

Implemented Features

Core Capabilities (Phases 0-9)

• Three-panel resizable layout with memory and persistence
• Monaco Editor v0.47.0 with Vega-Lite v5 schema validation
• Live Vega-Lite rendering with debounced updates and error display
• localStorage-based snippet management with full CRUD
• Multi-field sorting (Modified/Created/Name) with direction toggle
• Real-time search across snippet name, comment, and spec content
• Auto-save system (1s debounce) for specs and metadata
• Ghost card interface for snippet creation
• Draft/Published workflow with version control
• Status indicator lights (green/yellow) showing draft state
• Context-aware Publish/Revert buttons with color coding
• Storage monitoring with visual progress bar and warning states
• Export/Import functionality with format auto-detection
• Snippet size display (right-aligned, shown for ≥ 1 KB)
• Retro Windows 2000 aesthetic throughout

Technical Implementation

• State Management: Synchronous isUpdatingEditor flag prevents unwanted auto-saves
• View Modes: currentViewMode tracks draft vs published state
• Read-only Logic: Monaco editor locked in published view when draft exists
• Auto-draft Creation: Editing published without draft auto-switches to draft mode
• Debouncing: 1.5s render, 1s auto-save, 300ms search
• AMD Resolution: Temporary window.define disabling for Vega library loading
• Panel Memory: localStorage persistence for sizes and visibility across sessions
• Data Model: Phase 0 schema with spec (published) and draftSpec (working) fields
• Storage Calculation: Blob API for accurate byte counting of snippet data
• Flexbox Layout: Scrollable snippet list with fixed metadata and storage monitor at bottom
• Import/Export: Format detection, field normalization, ID conflict resolution, additive merging
• Size Display: Per-snippet size calculation with conditional rendering (≥ 1 KB threshold)