# Mailbox

An open mailbox where anyone can leave Austin a text message, an MP3 voice message, or both, plus an inbox where Austin reads, listens, sorts and answers them, mostly from his phone while out on walks. It lives in the toolbox at `tools/public/mailbox/` → `/mailbox` as a public work in progress, and is meant to leave the toolbox one day and become a real service (own repository, own backend). "Mailbox" is the working name.

**This is a mock-up.** Nothing is connected: no email, no server, no file storage, no login. The form saves a message only in the visitor's own browser, and the Developer tab is a public demo of the inbox that reads that same local data. The interface says so on every screen, and that honesty is a rule (see `CLAUDE.md`).

Start here, then read the others as needed:

| File | What it is |
|---|---|
| `CLAUDE.md` | Rules for anyone (human or agent) changing code here: honesty about what is connected, data and security rules, what to run before pushing |
| `README.md` | This file: what exists, how it is built, how to run and test it |
| `TASKS.md` | The live checklist and the "next up" list. Start here to find work. Update it when you finish or add work |
| `DECISIONS.md` | Judgment calls made so far and the open questions for Austin |
| `PLAN.md` | The workflow, the recommended tech stack with alternatives, and the road from this mock-up to a real service |
| `ANTI-SPAM.md` | The layers of bot and abuse protection, what the mock shows, and what a real build must do on the server |
| `DATA-MODEL.md` | Exact shapes of messages and audio references, storage keys, the backup format, and a proposed server schema |
| `info.md` | The short public write-up shown at `/mailbox/info` |
| `meta.json` | Toolbox metadata (title, status, storage disclosure) |

## What works today (v0.1)

**Submit a message tab (the public form)**

- Name, email for a private reply, subject, message text (5,000 characters, with a counter), and one MP3 (10 MB, 5 minutes). All optional except that there must be text or audio.
- The MP3 is checked by name, by reported type, by size, by its first bytes (a renamed PNG is rejected), and by its length as the browser reads it.
- Permissions: keep it private, may use anonymously, or may use with first name; and a preference for a voice or written reply.
- A "Before you send" list of disclaimers and a required checkbox. A clear "Mock-up, nothing is connected and nothing is sent" banner on every screen and in the button label.
- Bot defenses shown as illustrations: a hidden honeypot field, a time-to-fill check, a link-count check, and a clearly marked placeholder where a real bot check (such as Cloudflare Turnstile) would go.
- After sending, a result screen says nothing was sent, shows what the spam checks decided, and offers to open the message in the Developer inbox.

**Developer · Inbox tab (the recipient inbox)**

- A card per message with a state (New, Open, Responded, Done, Held), a title, sender, how long ago, audio length, a date chip (red when overdue), and a notes marker.
- Filters (Active, New, To respond, Responded, Done, Held, All) with counts, search across everything, and a sort menu (My order, Newest, Oldest, Date).
- Manual order: drag the grip (mouse or touch), or focus it and use the arrow keys, or use Up, Down and To top inside a card. "Bump to top" is also a button on every card.
- Opening a card marks it read. Inside: the full text, an audio player with −15s, +30s and a speed button (shared by every player), a transcript box, your title, a date, notes, a reply workspace (written reply or transcription, an attached reply MP3, where it went), Mark responded, Mark done, Hold as spam, and Delete.
- Audio keeps playing while you edit notes or the list re-renders.
- Developer tools: simulate a normal message, a bot message or link spam, reset to sample messages, download or import a backup (text and notes only), erase everything, and a table of what is and is not connected.

**Storage.** Messages, notes and drafts live in `localStorage` under `mailbox.v1`; audio blobs live in the IndexedDB database `mailbox-audio`; view preferences in `mailbox.ui` and playback speed in `mailbox.rate`. Sample audio is a short generated tone, labelled as a demo, so the sample inbox has sound without shipping any audio files.

## What does not work yet, on purpose

- Nothing is sent, received, emailed, stored on a server or protected by a login. The Developer tab is public.
- No real bot check, no server-side validation, no rate limiting.
- No transcription (the button is disabled), no recording in the browser, no notifications, no way to send a reply or publish one.
- Backups do not include audio files.

## How it is built

Plain JavaScript modules with no build step, so the folder can be copied out of the toolbox as it is. Code that does not need a browser is kept separate so it can be unit tested and reused by the real service.

```
index.html            page shell: header, tabs, disclaimer banner, toast
assets/app.css        styles (tokens on :root, dark by default, light when the device prefers it)
assets/js/
  app.js              boot, first-run sample data, hash routing (#/send, #/inbox)
  model.js            constants, limits, normalizers, state labels, formatting      (pure)
  validate.js         form validation, MP3 sniffing, spam signals                    (pure)
  order.js            manual reordering: moveBefore, moveAfter, moveBy, bump         (pure)
  view.js             filters, search, sorting, counts, overdue, relative time       (pure)
  wav.js              generates the demo tone audio                                  (pure)
  store.js            localStorage state holder, IndexedDB audio blobs
  sample.js           sample and simulated messages
  ui.js               h() DOM helper (drops falsy children), icons, toast, download
  views/form.js       the intake form
  views/inbox.js      the inbox list, filters, drag and drop
  views/card.js       one message card, built once and updated in place
  views/player.js     audio player with skip and speed
  views/devtools.js   developer tools panel
tests/unit/           node:test tests for the pure modules
tests/e2e/smoke.mjs   Playwright test of the whole thing on desktop and phone
```

Two design points worth knowing. First, the order of `state.messages` IS the manual order, so there is one source of truth and "bump" is just a move to index 0. Second, cards are built once per message and updated in place; the list only moves DOM nodes that are out of place, which is what lets audio keep playing and a text box keep its caret while the state re-renders.

## Run and test

```
npm run dev                                      # from the repo root: builds and serves http://localhost:4173
# then open http://localhost:4173/mailbox/

node --test tools/public/mailbox/tests/unit/*.test.mjs
node tools/public/mailbox/tests/e2e/smoke.mjs --shots <dir>     # needs npm run dev running, and Playwright
```

The end-to-end test uploads a real (tiny, silent) MP3, checks validation, honeypot, persistence, bump, mouse and touch drag, keyboard reorder, audio that keeps playing, backup and restore, and phone layout. Look at the screenshots it writes, not just the pass count.

## Moving it out of the toolbox

Copy `tools/public/mailbox/` to a new repository. It has no dependencies and no imports from outside its folder. The toolbox-specific bits are `meta.json`, `info.md`, and the card thumbnail and sprite icon in `shell/` (`shell/images/thumbs/mailbox.svg`, `ti-mail` in `shell/icons/sprite.svg`). The plan for what to build next is in `PLAN.md`.
