Skip to content

Commit cb703af

Browse files
MarkHersheyMarkHershey
committed
Improve agents search
1 parent 4872b45 commit cb703af

2 files changed

Lines changed: 248 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# AGENT.md
2+
3+
## Overview
4+
5+
Epoch is a React timeline editor. Users create tracks (rows) and events (time-bound rectangles). Events can be dragged, resized, and moved between tracks.
6+
7+
## Tech Stack
8+
9+
- React 19 + TypeScript
10+
- Vite (dev server, build)
11+
- Tailwind CSS (utility classes, no CSS files)
12+
- Lucide React (icons)
13+
- No state management library (useState + useRef)
14+
- LocalStorage for persistence
15+
16+
## File Structure
17+
18+
```
19+
App.tsx # Main component, all state, all handlers
20+
types.ts # TypeScript interfaces (ITrack, IEvent, IDragState, etc.)
21+
constants.ts # Default data, zoom levels, color palette
22+
components/
23+
AppHeader.tsx # Top bar with zoom controls
24+
TrackSidebar.tsx # Left sidebar, track list, drag-to-reorder
25+
TimelineCanvas.tsx # Main canvas, renders events, handles interactions
26+
Modal.tsx # Base modal wrapper
27+
TrackModal.tsx # Edit/create track
28+
EventModal.tsx # Edit/create event
29+
DataModal.tsx # Import/export JSON, timeline bounds settings
30+
Button.tsx # Reusable button component
31+
color/ColorPicker.tsx # Color selection grid
32+
utils/
33+
dateUtils.ts # Date parsing, formatting, arithmetic (parseDate, formatDate, addDays, getDaysDiff, etc.)
34+
eventLanes.ts # Calculate lane assignments for overlapping events
35+
```
36+
37+
## Data Model
38+
39+
```typescript
40+
interface ITrack {
41+
id: string;
42+
title: string;
43+
color: string;
44+
order: number; // Controls vertical position
45+
}
46+
47+
interface IEvent {
48+
id: string;
49+
trackId: string;
50+
title: string;
51+
description?: string;
52+
startDate: string; // "YYYY-MM-DD"
53+
endDate: string; // "YYYY-MM-DD"
54+
color?: string;
55+
}
56+
```
57+
58+
## State Location
59+
60+
ALL state lives in `App.tsx`:
61+
62+
- `data: { tracks: ITrack[], events: IEvent[] }` — main data
63+
- `zoomIndex` — current zoom level index
64+
- `dragState` — event drag/resize state
65+
- `isPanning` — canvas pan state
66+
- `viewBounds` — min/max year for timeline range
67+
- `editingTrack`, `editingEvent` — modal editing targets
68+
- `activeModal` — which modal is open (enum ModalType)
69+
70+
## Key Patterns
71+
72+
### Event Positioning
73+
74+
Events are positioned via pixel calculation:
75+
76+
```typescript
77+
left = getDaysDiff(timelineRange.min, eventStart) * pixelsPerDay;
78+
width = durationDays * pixelsPerDay;
79+
```
80+
81+
### Drag/Resize
82+
83+
- `handleDragStart()` — captures initial state
84+
- Global `mousemove`/`mouseup` listeners update position
85+
- On mouseup, calculate delta days and update event dates
86+
87+
### Lane Stacking
88+
89+
`utils/eventLanes.ts` assigns lane indices to overlapping events. Track height expands based on max lane count.
90+
91+
### Zoom
92+
93+
`ZOOM_LEVELS` array in constants.ts. Values are pixels-per-day. Zoom preserves center point using `targetZoomCenterRef`.
94+
95+
### Persistence
96+
97+
Data saved to `localStorage` keys: `chrono_data`, `chrono_bounds`
98+
99+
## Common Tasks
100+
101+
### Add new event field
102+
103+
1. Update `IEvent` in `types.ts`
104+
2. Update `EventModal.tsx` form
105+
3. Handle in `handleSaveEvent()` in `App.tsx`
106+
107+
### Add new track field
108+
109+
1. Update `ITrack` in `types.ts`
110+
2. Update `TrackModal.tsx` form
111+
3. Handle in `handleSaveTrack()` in `App.tsx`
112+
113+
### Modify zoom behavior
114+
115+
Edit `ZOOM_LEVELS` or `DEFAULT_ZOOM_INDEX` in `constants.ts`
116+
117+
### Change default colors
118+
119+
Edit `COLOR_PALETTE` in `constants.ts`
120+
121+
### Add new modal
122+
123+
1. Add enum value to `ModalType` in `types.ts`
124+
2. Create modal component extending `Modal.tsx` pattern
125+
3. Add state and handlers in `App.tsx`
126+
4. Add conditional render in `App.tsx` return
127+
128+
## Commands
129+
130+
```bash
131+
pnpm install # Install deps
132+
pnpm dev # Dev server (localhost:5173)
133+
pnpm build # Production build to dist/
134+
pnpm preview # Preview production build
135+
```
136+
137+
## Conventions
138+
139+
- Functional components only
140+
- Tailwind for all styling (no CSS files)
141+
- Date strings always "YYYY-MM-DD" format
142+
- IDs generated via `crypto.randomUUID()`
143+
- No external state management
144+
- Components receive data + callbacks as props
145+
- All business logic in App.tsx handlers

‎public/llms.txt‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Epoch — The Most Beautiful Timeline Editor You'll Ever Use
2+
3+
> **See your life unfold.** Your past victories, present ambitions, and future dreams—visualized in one stunning, panoramic view.
4+
5+
## What is Epoch?
6+
7+
Epoch is a gorgeous, intuitive visual timeline editor that lets you map out your entire life story. Whether you're planning your career trajectory, tracking personal milestones, documenting project histories, or dreaming about the future—Epoch makes time tangible.
8+
9+
Think of it as the love child of a Gantt chart and a beautiful personal journal, designed for humans who want to *see* where they've been and where they're going.
10+
11+
## Why Epoch?
12+
13+
- **Multi-Track Mastery** — Organize your life into parallel tracks: Work, Personal, Health, Learning, Relationships, Side Projects. Watch how different threads of your life weave together.
14+
15+
- **Buttery Smooth Interactions** — Drag events to reschedule them. Resize by dragging edges. Everything feels natural and responsive.
16+
17+
- **Smart Lane Stacking** — Overlapping events? No problem. Epoch automatically stacks them in intelligent lanes so nothing gets hidden.
18+
19+
- **Infinite Zoom** — View decades at a glance or zoom into hour-by-hour detail. From 10,000 feet to ground level in a scroll.
20+
21+
- **Full Color Control** — Color-code tracks and individual events. Make your timeline as vibrant as your life.
22+
23+
- **Your Data, Your Control** — Export to JSON anytime. Import from JSON. No accounts, no cloud lock-in. Everything persists locally in your browser.
24+
25+
## Key Features
26+
27+
| Feature | Description |
28+
|---------|-------------|
29+
| Multi-Track Timeline | Organize events into separate tracks (Work, Personal, etc.) |
30+
| Drag & Drop | Move events by dragging, resize by dragging edges |
31+
| Smart Lane Stacking | Overlapping events automatically stack in lanes |
32+
| Dynamic Track Heights | Tracks expand to fit overlapping events |
33+
| Zoom Controls | From year overview to day-level detail |
34+
| Color Coding | Customizable colors for tracks and individual events |
35+
| Import/Export | Save and load timelines as JSON files |
36+
| Responsive Design | Works on desktop and tablet |
37+
38+
## How to Use
39+
40+
| Action | Gesture |
41+
|--------|---------|
42+
| Add Event | Double-click on empty canvas |
43+
| Edit Event | Double-click on an event |
44+
| Move Event | Drag the event |
45+
| Resize Event | Drag the left or right edge |
46+
| Add Track | Click the + button in the sidebar |
47+
| Edit Track | Hover over track name, click "Edit" |
48+
| Zoom | Use zoom controls in header or Ctrl+scroll |
49+
| Pan | Click and drag on empty canvas |
50+
51+
## Data Format
52+
53+
Epoch uses a simple JSON format:
54+
55+
```json
56+
{
57+
"tracks": [
58+
{ "id": "1", "title": "Career", "color": "#3b82f6", "order": 0 },
59+
{ "id": "2", "title": "Personal", "color": "#10b981", "order": 1 }
60+
],
61+
"events": [
62+
{
63+
"id": "e1",
64+
"trackId": "1",
65+
"title": "Started New Job",
66+
"startDate": "2024-01-15",
67+
"endDate": "2024-02-28",
68+
"color": "#3b82f6"
69+
}
70+
]
71+
}
72+
```
73+
74+
## Tech Stack
75+
76+
- **React 19** — Cutting-edge UI framework
77+
- **TypeScript** — Full type safety
78+
- **Vite** — Lightning-fast build tool
79+
- **Tailwind CSS** — Utility-first styling
80+
- **Lucide React** — Beautiful icons
81+
82+
## Perfect For
83+
84+
- **Project Managers** — Visualize project timelines and milestones
85+
- **Students** — Plan your academic journey and career path
86+
- **Job Seekers** — Map out your career history for interviews
87+
- **Writers** — Plot timelines for novels and stories
88+
- **Goal Setters** — Track progress on life goals
89+
- **Event Planners** — Coordinate complex event schedules
90+
- **Life Coaches** — Help clients visualize their journey
91+
- **Researchers** — Create historical or project timelines
92+
93+
## Why We Built This
94+
95+
Because spreadsheets are boring. Because Gantt charts feel corporate. Because your life deserves better than a bullet-point list.
96+
97+
Epoch is time made visual. It's your story, rendered beautifully.
98+
99+
---
100+
101+
**Built with love for people who think in timelines.**
102+
103+
*Epoch: Where moments become movements.*

0 commit comments

Comments
 (0)