npm install
npm run dev          # http://localhost:5173/src/  (unbundled ES modules)
npm run build        # -> dist/index.html  (one self-contained file)
npm start            # MCP server, Streamable HTTP: http://127.0.0.1:3000/mcp
npm run start:stdio  # MCP server over stdio (Claude Desktop / Claude Code)
npm test             # unit + server tests (node:test, no browser; server test needs a build)
npm run test:e2e     # build + browser tests in headless Chrome

ngrok http 3000                                        # terminal 1 -> https://abc123.ngrok.app
HOST=:: ALLOWED_HOSTS=abc123.ngrok.app npm start       # terminal 2, with the ngrok host allowed

{
  "mcpServers": {
    "habit-tracker": { "command": "node", "args": ["/absolute/path/to/habit-tracker/server/stdio.js"] }
  }
}

habit-tracker/
├── manifest.json            app metadata: entry, icon, storage key
├── src/
│   ├── index.html           markup: header, tabs, backup banner, view root, dialogs, live region
│   ├── style.css            tokens (light + dark), habit rows, week grid, ring, heatmap, dialogs
│   ├── app.js               boot: load → store → clock → wire UI → subscribe(render, save) → render
│   ├── habits/              core — pure, no DOM, tested in Node
│   │   ├── constants.js     schema version, storage keys, colours, starter habits, empty state
│   │   ├── dates.js         "YYYY-MM-DD" keys: toKey, addDays, weekday, weekStartOf, range (DST-safe)
│   │   ├── schedule.js      isDue, schedule shapes, week days
│   │   ├── stats.js         streaks, best streak, 30-day rate, heatmap, today progress (memoized)
│   │   ├── actions.js       action creators (make ids, today, timestamps)
│   │   ├── reducer.js       (state, action) → newState, all business rules
│   │   ├── schema.js        migrate + invariant checks for stored / imported data
│   │   ├── store.js         state, dispatch, subscribe, undo/redo history
│   │   └── persistence.js   debounced localStorage save, load, JSON/CSV export, lastExportAt
│   └── ui/                  browser only
│       ├── dom.js           h() / s() element builders, focus helpers
│       ├── tabs.js          renderer: the only code that writes the view DOM; tab switching
│       ├── today-view.js    due list, check buttons, progress ring, empty state + starters
│       ├── week-view.js     habits × days table, visible week
│       ├── detail-view.js   heatmap SVG, stat cards, archive / restore / delete
│       ├── day-cell.js      how one habit-day looks and is announced (shared)
│       ├── format.js        date, streak and rate text
│       ├── controls.js      taps, long-press, toolbar
│       ├── dialogs.js       habit editor, day stepper / skip, backup & settings, confirm
│       ├── keyboard.js      grid navigation, shortcuts
│       ├── celebrate.js     streak milestones (7 / 30 / 100 / 365)
│       ├── clock.js         today, midnight rollover, visibilitychange
│       ├── status.js        aria-live, toasts, "Not saved" badge, backup banner
│       ├── icons.js         inline SVG icons + empty-state illustration
│       ├── theme.js         light / dark switch (remembered; follows OS / host until used)
│       └── host.js          MCP Apps host bridge: handshake, auto-resize, host theme, downloads
├── server/                  MCP server (Node)
│   ├── habits.js            tool show_habit_tracker + resource ui://habit-tracker/app.html
│   ├── html.js              loads dist/index.html and the icon
│   ├── http.js              Streamable HTTP entry (ChatGPT, claude.ai)
│   └── stdio.js             stdio entry (Claude Desktop, Claude Code)
├── assets/icons/habit-tracker.svg
├── scripts/
│   ├── build.js             esbuild bundle + inline CSS/JS/icon → dist/index.html
│   └── serve.js             zero-dependency dev server
├── tests/
│   ├── dates.test.js        DST, leap day, year boundary
│   ├── schedule.test.js
│   ├── stats.test.js        the spec's streak table, weekly streaks, rate, heatmap
│   ├── reducer.test.js
│   ├── schema.test.js
│   ├── store.test.js
│   ├── persistence.test.js  + CSV, lastExportAt
│   ├── server.test.js       real HTTP server: tool, resource, 403 on bad Host / Origin
│   └── e2e/
│       ├── app.e2e.js       headless Chrome against dist/index.html (fake clock)
│       └── host.e2e.js      app inside a minimal MCP Apps host (handshake, resize, theme, download)
├── dist/index.html          build output
├── package.json
└── README.md

event → controller → dispatch(action) → reducer (pure) → store (history) → render + debounced save
                                                                              ↑
                                         clock (midnight / tab visible) → render with new `today`