# Lantern Run — design

Status: design only. No code written, nothing run, no playtest. Every number is a **design setting** until measured.
Existing project: empty (only `.claude/`), so no existing source or licensing constraints. Plan to draw everything with canvas shapes and synthesise sounds, so no third-party assets are needed.

## Premise
Dusk on one long street. The festival starts in 75 seconds. Six lanterns wait in the shed at the west end. Carry them to six hanging posts along the street and light the street before the first drum.

## First second
A side-on view of the street. The shed is at left with six lanterns on a shelf. Six dark posts are spaced to the right, each labelled 1–6. A sun-to-moon bar across the top is the countdown. A small figure stands at the shed. A hint reads "Load lanterns (Space / LOAD), then walk right". The shed shows a "carry 0/3" marker and a speed gauge.

## The decision (verb: carry)
At the shed the player chooses how many lanterns (1–3) to take on this trip. This is the only real choice, and it recurs every trip.

| | Small trip (1) | Heavy trip (3) |
|---|---|---|
| Walk speed | fast (5 m/s) | slow (2 m/s) |
| Trips needed | many; each means walking back | few |
| Crowd hazards | can dash over them | cannot dash; a hit stalls you and can smash a lantern |

Loads of 0/1/2/3 give 6 / 5 / 3.5 / 2 m/s. The speed shown beside the figure changes as lanterns are added, so the cost is visible before leaving.

- Always carrying 1 is too slow because of the walking back. Estimate: about 92 s against a 75 s limit, so it loses.
- Always carrying 3 is fast only if the crowd is avoided. Estimate: about 69 s with no hits, but a smash costs a lantern and a re-fetch trip. This probably loses after one or two hits.
- Mixed play (such as 2+2+2, or 3 then 2 then 1) wins with a small margin. Estimate: about 66 s for 2+2+2.
- The endgame is a real choice. With two lanterns left, the player picks one trip of two or two trips of one, depending on how crowded the street looks.

## Round loop
1. **Load.** At the shed, Act adds a lantern (0.5 s each, max 3). Undo removes one. The player can leave with any load of 1–3.
2. **Walk out.** The player walks right. Posts are lit in order from the shed outward (post 1, then 2, and so on). Each carried lantern is hung at the next unlit post, and the player presses Act at that post to hang it (1.5 s).
3. **Dodge the crowd.** Festival-goers cross the street. Each crossing is shown by a ground marker and a footstep sound 1.2 s before the person arrives, and a new one starts about every 5 s. Dash (load ≤1 only) is a 0.4 s hop that clears a crowd. With a load of 2–3 the player cannot dash, so the only response is to stop or turn back before the marker fires.
4. **Walk back.** After hanging all lanterns the player returns at 6 m/s to the shed (load 0). Walking with an unhung lantern is allowed, so the player may turn back early. Unhung lanterns stay with the player and are not lost.
5. Repeat until all six posts are lit.

Crowd hit: the player stalls 0.8 s per lantern carried. At load 3 one lantern also smashes, and that lantern returns to the shed shelf as stock to be fetched again.

**Difficulty:** crowd frequency goes from every 6 s to every 4 s over the round. Crossings begin farther down the street, so the far posts are the risky ones. The warning time stays at 1.2 s so the response remains possible.

## Win, loss, restart
- **Win:** the sixth post is lit before the timer ends. The street glows. A result screen shows the time, the number of trips and a "style" label (for example "Steady hands" or "Heavy hauler"). The best time is saved in `localStorage` and persists across restarts. Nothing else persists.
- **Loss:** the timer ends with at least one post dark. The drums start, the lit posts stay lit and the remaining posts stay dark. The result screen shows "N of 6 lit".
- Both end states stay on screen until the player presses Restart (R / Enter / tap RESTART). They do not auto-advance. Restart resets the timer, stock, posts and crowd schedule to the same initial state.

## Controls (every promised input exists on both devices)
| Action | Keyboard | Touch |
|---|---|---|
| Move left / right | ←/→ or A/D | hold on-screen ◀ ▶ buttons (large, bottom corners) |
| Act (load / hang) | Space or Enter | large ACT button (bottom right) |
| Undo load | Backspace or S | small UNDO button |
| Dash | ↑ or W | DASH button, shown only when load ≤1 |
| Pause | P | pause icon (top right) |
| Restart | R (and Enter on the result screen) | RESTART button on the result screen |

On touch, buttons are at least 64 px, the page disables scroll and zoom gestures, and both buttons can be held at the same time as ACT. The ACT button's label changes to "LOAD", "HANG" or "—" depending on the context.

## Requirements → rules → feedback
| Brief phrase | Rule | Feedback that teaches it |
|---|---|---|
| deliver six lanterns | six posts, six units of stock | the shelf lamp count and a "lit n/6" counter |
| down one street | one horizontal street, one lane | a single scrolling or fixed strip with posts numbered |
| before a festival starts | 75 s timer, hard loss at 0 | the moon bar fills and the drums start at 10 s remaining |
| quick small trips | load 1 is fast, with a dash | the speed gauge reads high and the figure looks light |
| heavier trips | load 3 is slow, with no dash and a smash risk | the speed gauge drops, the figure bends and the lanterns clink |
| keyboard and touch | the table above | on-screen buttons shown when a touch event is detected |

## Scope (smallest complete version)
- One screen, one canvas, no scrolling beyond the street (street length 60 m, fitted to the width).
- Actors: the player, six posts, a shed, and crowd walkers (two or three simple shapes).
- No levels, no menus beyond Start, Pause and Result.
- Sound (synthesised with WebAudio, off until the first input): footstep warning, clink on load, hang chime, smash, drum at the end, a short win jingle.
- No tutorial beyond the first-screen hint; the speed gauge teaches the trade.

## Look and sound
A dusk palette with warm lantern yellow against a deep blue street. Lanterns glow when lit. High contrast for the warning marker (a pulsing red-orange ring on the ground). Colour is never the only cue: the warning also has a sound, and the load level is shown as a number.

## Feasibility walk-through (arithmetic only, not measured)
- **Normal route (2+2+2):** posts at 10, 20, … 60 m. Trip 1 reaches 20 m, trip 2 reaches 40 m, trip 3 reaches 60 m. Walking out takes (20+40+60)/3.5 ≈ 34 s, walking back 120/6 = 20 s, hanging 9 s and loading 3 s, for about 66 s. That leaves about 9 s of slack for crowd stalls.
- **Edge case (all 1s):** out 210/5 = 42 s, back 210/6 = 35 s, hanging 9 s and loading 3 s, for about 89–92 s. It loses by design.
- **Edge case (3+3 with one smash at the far end):** the smashed lantern forces a third trip of 60 m out and back at load 1, about 22 s extra, so about 91 s total. It loses, so the heavy gamble is visibly punished.

If measuring shows that any single strategy wins more than about 70% of the time, tune the speeds, timer or crowd interval (the first suspects are the load-2 speed and the 75 s timer).

## Done means (observable checks, not yet run)
1. **Full round:** start, load 2 three times, hang all six and see "You win" with the time and the best time saved. Reload the page and the best time is still shown. Separately, load 1 six times and confirm the timer ends with "N of 6 lit" and the loss screen stays until Restart.
2. **Input and feedback edge case:** with load 3, press Dash (key and touch button) and nothing happens, the button is hidden, and a brief "too heavy" cue plays. Walk into a crowd marker at load 3 and confirm the stall, the smash, and the shelf count rising by one. Do the same with a keyboard-only run and a touch-only run, including holding ◀ and ACT together on touch.
3. **Restart:** after both a win and a loss, press R (or tap RESTART) and confirm the timer is 75 s, the shelf shows 6, all posts are dark, the crowd schedule starts over and the best time is kept.
