# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A single-user local web app: paste a Google Calendar ICS URL, see a two-year
(current + next) calendar overview. Each day is split into three segments —
morning (00:00–12:00), afternoon (12:00–18:00), evening (18:00–24:00) — that
light up based on events, colored by emoji found at the start of the event
title (configured in `tags.json`). No build step, no frontend framework,
one runtime dependency (`node-ical`).

## Commands

- `npm start` (or `./start.sh`, which runs on port 4000 instead of the
  default 3000) — starts the server. Loads `.env` if present via Node's
  native `--env-file-if-exists` flag (no dotenv dependency).
- `npm test` (or `node test_days.js`) — runs the one test file, a plain
  `assert`-based script (no test framework) covering the recurrence/segment
  logic in `days.js`.
- `PORT=<n> npm start` — override the port (default 3000).

## Architecture

- **`days.js`** — the only file with real logic, and the only one covered
  by tests. `buildOverview(icsText, tagsConfig, rangeStartStr, rangeEndStr)`
  is a pure function: parses ICS text via `node-ical`, expands every VEVENT
  (recurring or not) with `ical.expandRecurringEvent(..., { expandOngoing: true })`
  — this one call correctly handles EXDATE and RECURRENCE-ID overrides, so
  there's no manual recurrence-expansion or override-merging code here.
  Returns `{ "YYYY-MM-DD": { segments: [...], tooltip: "..." } }`.
  - Each `segments[i]` is `null` (nothing), `'muted'` (untagged event
    present but not called out), a color name string (one leading emoji
    matched, from `tagsConfig`), or a 2-element array of color names (two
    leading emoji — see below).
  - **Emoji detection**: `leadingEmojis()` reads up to 2 emoji from the
    start of the event title, tolerating a single space between them (so
    both `"✈️💜 Title"` and `"✈️ 💜 Title"` count as a pair). A title with
    one leading emoji not present in `tagsConfig` still gets a color (the
    `UNKNOWN_EMOJI_COLOR` fallback), so it stands out from plain
    untagged/muted events.
  - **All-day events**: DTEND is exclusive per RFC 5545, handled by
    subtracting 1ms before computing the local day.
  - **No-TZID timestamps**: treated as floating local time per RFC 5545
    (formatted in the system's own timezone, not UTC) — this matches how
    `node-ical` itself encodes date-only DTSTART values, so the two stay
    consistent. Don't default these to UTC; that was a real bug once.
- **`server.js`** — a bare `node:http` server, no framework (routes are
  simple enough not to need one). `GET /api/overview?url=<ics>` fetches the
  URL server-side and calls `buildOverview` — this exists only because
  Google's ICS endpoint can't be fetched from the browser (CORS). Validates
  the URL is `http`/`https` before fetching (the one trust-boundary check,
  since the server will fetch whatever URL it's given). `tags.json` is read
  fresh on every request (no caching), so editing it takes effect on the
  next reload with no restart needed — only changes to `.js` files need a
  server restart.
- **`public/index.html`** — the entire frontend: HTML, CSS, and JS inline in
  one file, no build step. Fetches `/api/overview` and `/tags.json`, renders
  a 12-month grid per year. Colors are CSS custom properties
  (`TAG_COLOR_VAR` maps a color name from `tags.json` to a `--var`); a
  segment holding a 2-color array renders as a `linear-gradient` split
  top/bottom instead of a flat fill. Tooltips use the native `title`
  attribute (no custom tooltip JS) — hover text is built server-side in
  `days.js`.
- **`tags.json`** — user-editable, not code. Maps an emoji to
  `{ label, color }`. `color` must be one of the names in `TAG_COLOR_VAR` in
  `index.html` (`blue`, `aqua`, `yellow`, `green`, `violet`, `red`,
  `magenta`, `orange`, `gray`, `purple`, `lightblue`, `white`) — an unrecognized
  color name silently falls back to blue rather than erroring, so a typo
  here won't crash anything but will look wrong.
- **`.env`** (gitignored) — optional `CALURL=<ics url>`, used only to
  prefill/auto-load the URL input on page load via `GET /api/default-url`.
  Never log or print its value; it's a private calendar URL.