.ai-context

# Deep Time Navigator Visualization Project - AI Context

## Project Overview
The Deep-Time Navigator Timeline is an interactive web application that visualizes world events through deep time using logarithmic scaling. It allows users to zoom from the Big Bang to the present day, with recent events taking up more space and ancient events compressed. The project is inspired by a physical log-scale geological timeline created on adding-machine tape in the 1970s.

**Live Site**: https://deep-timeline.oberbrunner.com
**License**: MIT

## Tech Stack
- **Framework**: Astro 5.8.0 (static site generator + component islands)
- **Runtime**: Bun (package manager and runtime)
- **Reactivity**: Solid.js 1.9.7 (primary reactive framework)
- **Visualization**: Pure SVG + Solid.js (no D3 - completely removed)
- **Styling**: TailwindCSS 4.1.7 (utility-first CSS)
- **Date/Time**: Temporal Polyfill for precise date arithmetic
- **Testing**: Vitest for unit tests
- **Deployment**: Cloudflare (static site + worker)

## Architecture & Core Classes

### Key Files Structure
```
src/
├── deep-time.ts              # Core time representation class
├── log-timeline.ts           # Timeline visualization logic
├── stores/                   # Solid.js reactive stores
│   ├── global-timeline.ts    # Global timeline state
│   ├── events-store.ts       # Events and category state
│   └── interaction-store.ts  # UI interaction state
├── components/               # Solid.js reactive components
│   ├── Timeline.tsx          # Main orchestration component
│   ├── TimelineSVG.tsx       # SVG container with interactions
│   ├── TimelineAxis.tsx      # Axis rendering
│   ├── TimelineTicks.tsx     # Tick marks and labels
│   ├── TimelineEvents.tsx    # Event visualization
│   ├── TimelineHover.tsx     # Hover indicators
│   ├── TimelineControls.tsx  # Invisible control handlers
│   ├── CategoryControls.tsx  # Invisible category handlers
│   ├── TimeDisplay.tsx       # Time display components
│   └── AboutPopup.astro      # Info modal (legacy Astro)
├── scripts/
│   └── events.ts            # Event loading and management
└── pages/
    └── index.astro          # Entry point with static HTML structure
```

### Core Classes

#### `DeepTime` (`src/deep-time.ts`)
- **Purpose**: Universal time representation using 64-bit float minutes since 1970 UTC
- **Range**: From Big Bang (~13.8B years ago) to far future with minute precision
- **Key Features**:
  - Handles times outside JavaScript Date/Temporal ranges
  - Supports parsing from multiple formats (ISO, "1000BC", years ago, etc.)
  - Logarithmic scaling methods for timeline positioning
  - Precise arithmetic using Temporal when possible, fallback to astronomical calculations
- **Usage**: `new DeepTime("13.8e9 years ago")` or `new DeepTime({year: -66000000})`

#### `LogTimeline` (`src/log-timeline.ts`)
- **Purpose**: Manages logarithmic timeline positioning and interactions
- **Key Features**:
  - Pixel ↔ time conversion with log scaling
  - Zoom/pan operations around focal points
  - Automatic tick generation for time labels
  - Reference time (usually "now") for relative positioning
  - **New**: Reactive updates via callback system
- **Usage**: `new LogTimeline(width, leftTime, rightTime)`

### Reactive State Architecture (Solid.js)

#### Stores (`src/stores/`)
- **`global-timeline.ts`**: Central timeline instance and ready state
- **`events-store.ts`**: Event data, filtering, and category management
- **`interaction-store.ts`**: UI state (hover, panning, dimensions)

#### Component Hierarchy
```
Timeline.tsx (orchestrator)
├── TimelineControls.tsx (invisible - handles zoom/pan buttons)
├── CategoryControls.tsx (invisible - handles category checkboxes)
└── TimelineSVG.tsx (main SVG container)
    ├── TimelineAxis.tsx (blue timeline axis)
    ├── TimelineTicks.tsx (time labels)
    ├── TimelineEvents.tsx (event markers with clustering)
    └── TimelineHover.tsx (hover line indicator)
```

### Data & Events
- Historical events loaded from JSON files via `scripts/events.ts`
- Real-time news feed via Cloudflare Worker (`timeline-events-worker/`)
- Uses Reddit's r/worldnews as current events source
- Event clustering algorithm prevents visual overlap

### Gesture Server
For museum or touchless use, there's an SSE (Server-Sent Events)-based
gesture interface controller at `src/gesture-interface.ts` with a
store at `src/stores/gesture-store.ts`. There is a demo gesture server
which serves random pan/zoom gestures for testing. To enable it, pass
`gestureEnabled={true}` to the Timeline component in
LogTimelineVisualization.astro. It is normally set to false for
production use.

## Development Patterns

### Code Style
- **Prettier**: Single quotes, no semicolons, no trailing commas
- **TypeScript**: Strict mode enabled
- **Import Style**: ES modules with explicit `.ts` extensions
- **Error Handling**: Comprehensive validation with descriptive error messages

### Reactive Patterns
- **Signals**: Used for simple reactive values (`timelineReady`, `globalTimeline`)
- **Stores**: Used for complex state objects (`eventsState`, `interactionState`)
- **Memos**: Used for derived computations (`visibleEvents`, `ticks`)
- **Effects**: Used for syncing reactive state to DOM elements

### Time Handling Conventions
- All internal time stored as minutes since 1970 UTC (float64)
- Use `DeepTime` for all time operations, never raw Date objects
- Astronomical year numbering (year 0 = 1 BCE)
- Prefer Temporal API when within range (~±270K years from 1970)

### SVG Rendering (Pure Solid.js)
- **No D3**: All SVG generation done with Solid.js JSX
- **Reactive**: SVG elements update automatically via Solid.js reactivity
- **Performance**: Memoized computations prevent unnecessary re-renders
- **Interactions**: Native event handlers on SVG elements

### Testing
- Comprehensive unit tests in `test/` directory
- Test files mirror source structure (`deep-time.test.ts`, etc.)
- Focus on edge cases (Big Bang, far future, leap years, etc.)
- Run with: `bun test`

## Key Algorithms

### Logarithmic Scaling
The core insight is mapping time to log space relative to "now":
```typescript
// Convert time to log position
logTime = log(refTime - time.minutesSinceEpoch)
// With clamping to prevent log(0) or log(negative)
```

### Zoom Implementation
Zooming preserves a focal point by scaling log-space distances:
```typescript
// Get log distances from focal point to endpoints
logDistLeft = leftTime.toLog(refTime) - focalTime.toLog(refTime)
logDistRight = focalTime.toLog(refTime) - rightTime.toLog(refTime)
// Scale distances by zoom factor
newLogDistLeft = logDistLeft / zoomFactor
```

### Event Clustering
Prevents visual overlap of events:
- Groups nearby events within configurable pixel distance
- Pushes clustered events vertically with connecting lines
- Uses significance-based opacity for visual hierarchy

## Component Design Patterns

### Invisible Control Components
- **Purpose**: Bridge between static HTML (from Astro) and reactive Solid.js state
- **Pattern**: Components that return `null` but manage DOM event handlers
- **Examples**: `TimelineControls.tsx`, `CategoryControls.tsx`
- **Benefits**: Separation of concerns, modularity, clean state management

### Reactive SVG Architecture
- **TimelineSVG**: Container with interaction handlers (mouse, touch, wheel)
- **Sub-components**: Specialized rendering for axis, ticks, events, hover
- **Props flow**: Timeline instance passed down, stores accessed directly
- **Performance**: Memoized calculations, efficient re-rendering

### State Management
- **Global timeline**: Single source of truth via `globalTimeline` signal
- **Event data**: Managed in `eventsStore` with filtering and categorization
- **UI interactions**: Tracked in `interactionStore` (hover, panning, dimensions)

## Development Workflow

### Commands
- `bun install` - Install dependencies
- `bun run dev` - Start dev server (localhost:4321)
- `bun run build` - Build for production
- `bun run test` - Run test suite
- `bun run format` - Format code with Prettier

### File Organization
- No barrel exports - import directly from specific files
- CSS in `src/styles/` - component-specific styles in components
- Tests mirror source structure in `test/` directory
- Documentation in markdown files at root level

## Common Tasks & Patterns

### Adding New Timeline Features
1. Update `LogTimeline` class if core functionality needed
2. Add reactive state to appropriate store
3. Create or update Solid.js components
4. Add tests for new functionality

### Adding Event Visualizations
- Extend `TimelineEvents.tsx` component
- Use `createMemo` for expensive calculations
- Follow clustering and significance patterns

### Time Parsing
The `DeepTime` constructor accepts many formats:
- ISO strings: `"2025-01-01T00:00:00Z"`
- Historical: `"1000BC"`, `"65000000 years ago"`
- Objects: `{year: -66000000}`, `{yearsAgo: 1000}`

### Performance Considerations
- Solid.js reactivity handles efficient updates automatically
- Event clustering prevents performance issues with many events
- Log calculations are cached where possible
- Timeline updates use batched callbacks to prevent cascade updates

## Current Focus Areas
- Real-time event integration via Cloudflare Worker
- Interactive zoom/pan performance optimization
- Historical event data curation and accuracy
- Mobile responsiveness and touch interactions

## Known Issues & Limitations
- JavaScript float precision limits at extreme time scales
- Temporal API has ~±270K year range limitation
- Mobile touch interactions need refinement
- News feed depends on Reddit API availability

## Architecture Benefits of Current Design

### Solid.js + Pure SVG Advantages
- **Performance**: Solid.js fine-grained reactivity is faster than D3's DOM manipulation
- **Simplicity**: Pure SVG components are easier to understand and debug
- **Maintainability**: Standard React-like component patterns
- **Bundle size**: Smaller without D3 dependency
- **Type safety**: Better TypeScript integration than D3

### Store-based State Management
- **Predictable**: Clear data flow through reactive stores
- **Debuggable**: Easy to track state changes
- **Modular**: Each store handles specific concerns
- **Testable**: Stores can be tested independently

## Future Enhancement Ideas
- Custom event collections/themes
- Collaborative event editing
- Multiple timeline tracks (science, politics, art)
- 3D visualization experiments
- Educational curriculum integration
- Animation system for smooth transitions