negotium/docs/superpowers/specs/2026-08-15-fix-and-harden-design.md

# Negotium: Fix and Harden — Design

**Date:** 2026-08-15
**Status:** Approved, not yet implemented

## Context

Negotium is a minimalist Svelte to-do app scoped to exactly two days, Today and Tomorrow. Tasks are stored client-side in `localStorage`, one key per date. It ships as a static nginx image published to GHCR.

The app has not been updated in roughly ten months. An audit found that its headline feature — automatic carry-over of tasks across the day boundary — has never worked, alongside several correctness, accessibility, and payload problems.

This design covers correctness and foundations only. No new user-facing features, no changes to the two-day model, and no visual redesign.

## Findings this design addresses

### Correctness

1. **Carry-over is dead code.** `checkAndMigrateTasks()` (`src/App.svelte:118`) guards on `currentDate !== today`. `currentDate` is initialized from `new Date().toDateString()` at `src/App.svelte:14` and compared against a fresh `new Date().toDateString()` milliseconds later in `onMount`. The condition is never true.

   "Tomorrow becomes Today" does work, but incidentally — tomorrow's tasks are written under tomorrow's date key, which is simply what gets read as today after midnight. What is genuinely broken is carry-over of *unfinished* work: those tasks remain under the previous day's key, are never displayed again, and are never cleaned up.

2. **No midnight rollover while open.** There is no timer or `visibilitychange` listener. A tab left open overnight keeps `selectedDate` pinned to the previous day, still labels it "Today" (`buttonText` at `src/App.svelte:153` only recomputes when `selectedDate` changes; the `new Date()` inside it is not a reactive dependency), and writes all subsequent edits into the previous day's key.

3. **Only one day back.** Even had the guard been correct, the logic inspects yesterday alone. A three-day absence would still drop work.

4. **Unbounded storage growth.** Every date key ever written persists indefinitely.

5. **Unguarded `JSON.parse`.** `src/App.svelte:108` will throw on any corrupt value and white-screen the app. `localStorage` access is also unguarded against Safari private mode and quota exhaustion.

### Accessibility

6. **Delete button invisible to keyboard users.** `.delete-btn` is `opacity: 0`, revealed only by `.task-item:hover` (`src/style.css:360`). The `:focus-visible` outline (`src/style.css:509`) renders on a zero-opacity element and is therefore also invisible.

7. **Invalid nested interactives.** The task row is `role="button"` with `tabindex="0"` (`src/App.svelte:336`) and contains two real `<button>` elements.

8. **Backspace destroys a task with no recovery.** `src/App.svelte:55`, on a focusable row.

9. **Reordering is desktop-mouse-only.** HTML5 drag events do not fire on touch, and there is no keyboard alternative.

### Payload and startup

10. **`lottie-web` is 305 KB of a 337 KB bundle** (~91%), statically imported at `src/App.svelte:5` to play one decorative empty-state animation. It ships to every visitor regardless of whether the empty state renders.

11. **The 200 KB README screenshot is served to users.** `publicDir: 'assets'` (`vite.config.mjs:6`) copies `assets/screenshot.png` into `dist/`.

12. **A 500 ms artificial loading screen** on every launch (`src/App.svelte:212`) for an app with no async work.

13. **Dark-mode flash.** `index.html:16` hardcodes the light background; `darkMode` is only read from `localStorage` after mount.

### Build and infrastructure

14. **Non-reproducible Docker builds.** `package-lock.json` is gitignored and untracked, so the `npm install` in `Dockerfile:14` resolves fresh versions on every build. Combined with the daily cron in `.github/workflows/docker-publish.yml:9`, the published `:main` image drifts silently.
15. `dist/` is not gitignored.
16. Svelte 4.2 → current 5.56; Vite 5.0 → current 8.2.
17. No tests, no linting.

## Goals

- Carry-over works, across arbitrary multi-day gaps, and is covered by tests.
- Rollover is detected while the app is open.
- Storage is bounded, resilient to corruption, and survives an unavailable `localStorage`.
- Reordering works on touch and by keyboard.
- Initial payload drops by roughly 90%.
- Dependencies are current and builds are reproducible.

## Non-goals

- The two-day model. No projects, tags, due dates, or recurrence.
- Visual redesign. Layout, palette, and type stay as they are.
- Sync, accounts, or any server component.
- PWA/offline and data export/import — deliberately deferred to a later pass.
- TypeScript.

## Approach

Extract non-visual logic from `App.svelte` into small, individually testable plain-JS modules, then fix the defects inside those modules where they can be verified. `App.svelte` is reduced to a view layer and keeps its existing markup and CSS.

The extraction is a precondition, not incidental cleanup: the defects that matter most are time-dependent, and `new Date()` is currently called inline in five places inside a component that needs a DOM to instantiate. Injecting the clock is what makes "what happens at midnight" an ordinary unit test.

Alternatives considered and rejected:

- **Surgical in-place patches.** Lowest risk, but the rollover fix would ship verified only by hand — which is how it shipped broken originally — and the dependency drift would remain.
- **Full rewrite in Svelte 5 + TypeScript with stores.** Cleanest end state, but a ground-up rebuild of a working UI carries a materially higher chance of silently altering UX, and TypeScript is heavy ceremony for an app with three data shapes.

## Module design

```
src/
  lib/
    dates.js      date-key formatting and display labels
    storage.js    localStorage persistence, enumeration, pruning
    rollover.js   day-boundary rules
    tasks.js      pure task operations
  App.svelte      view only
  main.js
  style.css
```

Every function needing the current time receives it as an argument. No module below calls `new Date()` internally.

### `dates.js`

| Function | Purpose |
|---|---|
| `toKey(date)` | `Date` → `YYYY-MM-DD` in local time |
| `fromKey(key)` | `YYYY-MM-DD` → `Date` at local midnight |
| `addDays(date, n)` | Date arithmetic |
| `labelFor(dateKey, todayKey)` | `"Today"` / `"Tomorrow"` / formatted long date |

### `storage.js`

| Function | Purpose |
|---|---|
| `loadTasks(dateKey)` | Returns `[]` on missing, unparseable, or non-array values |
| `saveTasks(dateKey, tasks)` | Persists; never throws to the caller |
| `listTaskKeys()` | All `negotium-tasks-*` keys currently present |
| `removeTasks(dateKey)` | Deletes one date's entry |
| `loadTheme()` / `saveTheme(mode)` | Theme preference |
| `migrateLegacyKeys()` | One-time old-format → ISO conversion |

All access is wrapped. If `localStorage` throws on access, the module falls back to an in-memory `Map` for the session so the app still runs.

### `rollover.js`

| Function | Purpose |
|---|---|
| `rollover(now)` | Applies carry-over for all past dates; returns the resulting Today list |
| `nextMidnight(now)` | Milliseconds until the next local midnight, for scheduling |

### `tasks.js`

Pure functions over task arrays, returning new arrays: `addTask`, `toggleTask`, `deleteTask`, `reorderTask`, `clearCompleted`. Plus a bounded undo stack (last 10 operations) recording enough state to restore a deleted task at its original index.

Task shape is unchanged except that `id` becomes `crypto.randomUUID()` rather than `Date.now()`.

## Storage format and migration

Keys move from `negotium-tasks-Mon Aug 15 2026` to `negotium-tasks-2026-08-15`.

The multi-day carry-over rule requires enumerating stored dates and comparing them against today. ISO keys make that a string comparison; `toDateString()` keys would require re-parsing every key. Sortable keys keep the rollover logic simple enough to be visibly correct.

Migration runs once, before any other storage read:

1. Enumerate `negotium-tasks-*` keys.
2. For each key not already matching `YYYY-MM-DD`, parse the legacy suffix via `new Date(suffix)`.
3. On a valid parse, rewrite the value under the ISO key. If the ISO key already holds tasks, concatenate legacy first, then existing.
4. Delete the legacy key.
5. On an unparseable suffix, leave the key untouched and skip it — never destroy data that cannot be interpreted.

The live deployment at `negotium.aculix.org` holds real data in the legacy format. This path is written and tested before anything else.

## Rollover behaviour

On rollover, for every stored date key strictly earlier than today:

1. Unfinished tasks are collected, oldest date first, preserving within-day order.
2. They are placed **above** any tasks already present in Today.
3. Completed tasks from those dates are discarded.
4. The old date key is deleted.

Pruning is therefore a side effect of carry-over; there is no separate retention policy.

Future-dated keys (Tomorrow) are never touched.

Rollover is triggered from four places:

- On mount.
- On `visibilitychange` when the document becomes visible.
- On window `focus`.
- From a `setTimeout` scheduled to the next local midnight, which reschedules itself on fire.

The timer covers a pinned tab crossing midnight unattended. `visibilitychange` and `focus` cover machine sleep, where timers do not fire reliably.

## Error handling

| Condition | Behaviour |
|---|---|
| Corrupt JSON in a task entry | Treated as empty; app continues |
| Value present but not an array | Treated as empty |
| `localStorage` throws on access | In-memory fallback for the session |
| Quota exceeded on write | Write dropped; in-memory state stays authoritative |
| Legacy key with unparseable date | Left in place, skipped |

Nothing in this table is permitted to prevent the app from starting.

## Testing

Vitest against `src/lib/`. No component tests in this pass — that requires jsdom and testing-library, and by then all consequential logic lives in `lib/`.

**Migration:** legacy → ISO conversion; collision with an existing ISO key merges in the correct order; unparseable suffix is left alone; migration is idempotent across repeated runs.

**Rollover:** same day is a no-op; one-day gap; multi-day gap ordering; completed tasks dropped; within-day order preserved; carried tasks precede existing Today tasks; future keys untouched; empty prior days; DST spring-forward and fall-back boundaries; `nextMidnight` correctness across a DST change.

**Storage:** corrupt JSON returns `[]`; non-array returns `[]`; throwing `localStorage` falls back to memory.

**Tasks:** whitespace-only input rejected; text trimmed; toggle; delete; reorder to first, last, and middle positions; `clearCompleted`; undo restores a deleted task at its original index; undo stack is bounded at 10.

## UX changes

Three deliberate deviations, each approved:

1. **Backspace no longer deletes a focused task.** `Delete` still does, as documented. Backspace is the accidental trigger — pressed meaning "go back", or while typing — and it currently destroys a task irrecoverably.
2. **Undo is `Cmd/Ctrl+Z`, with no new on-screen UI.** A toast would be more discoverable but introduces a UI element to an app that has none. Documented in the README instead.
3. **The 500 ms splash screen is removed.** It fronts no async work.

Everything else — the two-day toggle, the input, the checkbox and delete affordances, the stats line, the empty state, the palette, spacing, and type — is unchanged.

## Accessibility changes

- Task row loses `role="button"` and `tabindex="0"`; it becomes a plain container. The checkbox button carries the accessible name.
- Delete button revealed on `:focus-within` as well as `:hover`.
- `Alt+↑` / `Alt+↓` reorders a task when its row has focus.

## Reordering rewrite

HTML5 drag-and-drop is replaced with Pointer Events, which unifies mouse, touch, and pen through one code path. Roughly 80 lines, no new dependency. `event.dataTransfer.setData('text/html', event.target)` at `src/App.svelte:63` — which passes a DOM node where a string is required — disappears with it.

Keyboard reordering via `Alt+Arrow` is included, so reordering is no longer pointer-exclusive.

## Payload and build

- **Lottie removed**, empty-state animation redrawn as an inline animated SVG in the existing accent colour. Expected bundle: 337 KB → ~30 KB.
- **Theme applied pre-paint** by an inline script in `<head>` that reads the stored preference and sets a class on `<html>` before first paint.
- **`publicDir`** switched to a dedicated `public/` holding only runtime assets. `screenshot.png` moves to `docs/` and is referenced from the README by its new path.
- **`.gitignore`**: add `dist/`, remove `/package-lock.json`, change `/.DS_Store` to `.DS_Store` so nested copies are covered.
- **`package-lock.json` committed**; `Dockerfile` switched from `npm install` to `npm ci`.
- **Vite 5 → 8**, **Svelte 4 → 5**. The Svelte upgrade rewrites reactive declarations (`$:` → `$derived` / `$effect`) and the mount API at `src/main.js:3`. Mechanical at this size, but it touches nearly every reactive line.

## Sequencing

1. Tooling: Vitest, `.gitignore`, commit the lockfile, `npm ci` in the Dockerfile.
2. `dates.js` and `storage.js` with the legacy migration, fully tested, before any behaviour changes.
3. `rollover.js` with the full carry-over test matrix.
4. `tasks.js` including undo.
5. Rewire `App.svelte` to the modules, still on Svelte 4, verifying no visible change.
6. Svelte 4 → 5 and Vite 5 → 8.
7. Drop Lottie; inline SVG empty state; remove the splash; pre-paint theme.
8. Accessibility fixes.
9. Pointer Events reordering plus `Alt+Arrow`.
10. README corrections: the carry-over rule as actually implemented, revised keyboard shortcuts, the new storage key format.

Steps 2–4 are independently verifiable before anything user-visible moves. Step 5 is the riskiest single step and should be reviewed against the running app.

## Risks

| Risk | Mitigation |
|---|---|
| Migration loses real user data | Written and tested first; unparseable keys are never deleted; merge order defined |
| Svelte 5 upgrade alters behaviour subtly | Sequenced after the rewire, so `lib/` tests are already green and isolate the cause |
| Redrawn empty-state animation is not liked | Self-contained and easily iterated; the lazy dynamic-import route remains available as a fallback |
| Pointer Events regress desktop dragging | Largest and most isolated step, sequenced last so it can be dropped without affecting the rest |

## Deferred

- PWA manifest, service worker, offline support, installability.
- Data export/import for backup and portability.
- Component-level tests.
- Linting and formatting configuration.

These were considered and consciously postponed. PWA and export/import are the natural next pass — for a local-first, privacy-oriented app they are the largest genuine capability gaps.