Deploy Hallway 8 (multi-arc memory game)

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 static/audio/landing.ogg filter=lfs diff=lfs merge=lfs -text
+static/audio/landing.mp4 filter=lfs diff=lfs merge=lfs -text

CLAUDE.md

@@ -28,6 +28,7 @@ static/style.css   skins (body[data-skin=...]) + layout
 static/game.js     client: arc select, rendering, pacing, drift, sid, controls
 scripts/deploy_hf.py       deploy/update the HF Space (run locally)
 scripts/make_private_hf.py toggle Space visibility (--public to release)
+scripts/export_landing_media.py  render landing theme -> ogg + 1080p youtube mp4 (local)
 tests/test_game.py         test suite (no pytest needed)
 docs/ARCS.md               design rules, shared tuning, built + planned arcs
 ```
@@ -102,7 +103,14 @@ first user gesture (autoplay policy). An exported render of the landing theme is
 saved at `static/audio/landing.ogg` (mono OGG Vorbis, ~42s, normalized; rendered
 offline from the same synth via OfflineAudioContext). An always-visible mute toggle (`#sound-toggle`) persists to
 `localStorage` (`h8_muted`). Audio only starts from a user gesture (browser
-autoplay policy). To add a soundscape for a new arc, add a `_<skin>(bus)` builder
+autoplay policy).
+
+**Movement SFX:** committing a choice plays `window.ambience.step(dir, dwellMs)`,
+synthesised (footstep thud + scuff, plus a directional scene-change swish).
+`dwellMs` is how long the player lingered (`performance.now() - decideStart`,
+where `decideStart` is set when the controls appear): a quick, confident press
+gets firm footsteps; a longer deliberation softens to a tiptoe, then to a near
+silent shuffle. Routed through the master gain, so the mute toggle covers it. To add a soundscape for a new arc, add a `_<skin>(bus)` builder
 and branch to it in `play()`.
 
 ## UI conventions
@@ -128,11 +136,16 @@ and branch to it in `play()`.
 
 ## Working conventions (IMPORTANT)
 
-- **Commits/PRs are authored solely by the repo owner** (`alvations
-  <alvations@gmail.com>`). Never add Claude as author or co-author, and never add
-  Claude/Co-Authored-By/session trailers to commits or PR bodies. Use
-  `git -c user.name=... -c user.email=... commit --author="alvations <alvations@gmail.com>"`.
+- **Commits/PRs are authored solely by the repo owner.** Use the owner's git
+  identity already recorded in the repo: read it with
+  `git log -1 --format='%an <%ae>'`. Never add Claude as author or co-author, and
+  never add Claude/Co-Authored-By/session trailers to commits or PR bodies.
+  Commit with
+  `git -c user.name="<owner>" -c user.email="<owner-email>" commit --author="<owner> <owner-email>"`.
 - **Do not put any AI model identifier** in commits, code, comments, or docs.
+- **License/attribution.** Apache-2.0. Copyright holder: `alvations (Melon Lab)`.
+  New source files carry an SPDX header (`SPDX-License-Identifier: Apache-2.0`)
+  plus the copyright line; never remove `LICENSE`, `NOTICE`, or existing headers.
 - **Do not reference the source film or any external IP** anywhere in the repo
   (docs, code, comments, or commit messages). Keep the game's own naming.
 - **Never spoil the game in the instructions/intros.** State the rule generically

NOTICE

@@ -0,0 +1,9 @@
+Hallway 8
+Copyright 2026 alvations (Melon Lab)
+
+This product includes software authored by alvations, Melon Lab.
+
+Licensed under the Apache License, Version 2.0 (the "License"); see the LICENSE
+file. Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

README.md

@@ -46,7 +46,9 @@ feels too long, a calm that shouldn't be there).
 Arcs live as self-contained JSON files in `data/arcs/`. Adding a new one is just
 dropping in another file (see *Adding an arc* below) — no code changes needed.
 The design rules and the queue of future arcs are kept in
-[`docs/ARCS.md`](docs/ARCS.md).
+[`docs/ARCS.md`](docs/ARCS.md). For how this game was built end to end with an AI
+coding agent (the method, the verify-loop, the gotchas, and a replication
+checklist), see [`docs/MAKING_OF.md`](docs/MAKING_OF.md).
 
 ## What makes it unsettling
 
@@ -269,3 +271,20 @@ self-contained:
 To give the arc its own colours, add a `body[data-skin="<name>"]` block in
 `static/style.css`. The new arc appears automatically on the opening screen —
 no code changes required.
+
+---
+
+## License and attribution
+
+Hallway 8 is licensed under the **Apache License, Version 2.0**. See
+[`LICENSE`](LICENSE) for the full text.
+
+Copyright 2026 **alvations** (Melon Lab).
+
+Author: alvations. Affiliation: Melon Lab. Attribution notices are in the
+[`NOTICE`](NOTICE) file; per the license, redistributions and derivative works
+must retain that `NOTICE`. Each source file also carries an SPDX header
+(`SPDX-License-Identifier: Apache-2.0`) and the copyright line.
+
+When contributing, keep your commit author identity as the copyright holder and
+do not remove the license headers or the `NOTICE`.

anomalies.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
 """Anomaly selection and the small "drift" tricks.
 
 Nothing here screams. An anomaly is a single property quietly swapped for a

app.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
 """A tiny Flask server for the memory-loop game.
 
 Run:  python app.py   then open  http://127.0.0.1:5000

docs/MAKING_OF.md

@@ -0,0 +1,244 @@
+# Building Hallway 8 with Claude Code
+
+This is the method behind the game: how it was designed and built end to end
+through a conversation with an AI coding agent (Claude Code), how each feature
+was verified before it shipped, and the gotchas that cost time so you can skip
+them. If you want to reproduce *this* game, read the README. If you want to
+reproduce the *process* on a game of your own, read this.
+
+The whole thing was built by talking to the agent in plain language, one change
+at a time, and having it write the code, run it, screenshot it, test it, and
+commit it. There was no separate design doc up front; the design emerged in the
+first few messages and then got refined by playing.
+
+---
+
+## 0. Setup that made it work
+
+A few things were decided once, early, and paid off every turn:
+
+- **A tiny, no-build stack.** Python + Flask backend, vanilla HTML/CSS/JS
+  frontend, JSON for content. No bundler, no framework, no npm. The agent can
+  edit any file and immediately run the app, which keeps the feedback loop fast.
+- **A `CLAUDE.md` at the repo root.** This is the agent's standing memory: the
+  stack, the core mechanic, the conventions (see below), and "keep it this way"
+  notes next to load-bearing decisions. Every session reads it first, so you
+  don't re-explain the project or re-litigate settled choices.
+- **Explicit conventions, stated once.** Commit authorship, a no-spoilers rule,
+  no em-dashes, colour constraints. Written down, they get honoured for free.
+- **A test runner with zero dependencies** (`python tests/test_game.py`) and a
+  **headless browser** (Chromium via Playwright) for UI verification. The agent
+  can prove a change works instead of guessing.
+
+The single highest-leverage artifact is `CLAUDE.md`. Start it on day one and
+update it whenever a decision becomes load-bearing.
+
+---
+
+## 1. The design conversation
+
+The game started as a discussion, not a spec: *how do you make a "spot the
+change" loop that is about doubting your memory rather than hunting for a weird
+sentence?* That produced a small set of principles that became the mechanic:
+
+- Never describe everything; show only a subset of details each loop.
+- Change *meaning*, not wording. Draw each detail from a pool of interchangeable
+  sentences so players can't diff two loops literally.
+- One quiet mutation per changed loop, never signposted.
+- Frame it as a memory test, not "find the anomaly."
+
+Only after the mechanic felt right did any code get written. Lesson: **spend the
+first messages on the core loop and its framing, not on architecture.**
+
+---
+
+## 2. The working loop
+
+Every feature, from the MVP to the audio, followed the same rhythm:
+
+1. **Ask in plain language** for one change ("add an arc about taking the
+   stairs", "the top bar is hidden on mobile", "make the crackle rarer").
+2. **The agent implements it** across whatever files it touches.
+3. **It verifies before claiming success:**
+   - runs `python tests/test_game.py`,
+   - drives the real app in headless Chromium and screenshots the result,
+   - for logic, plays the game against the server's own answer to prove
+     win/lose paths.
+4. **It commits** (authored as the owner) and **pushes**.
+5. You look at the screenshot / play it, and the next message is the next
+   change. Bugs and polish are just more turns.
+
+This is the important part: **the agent is expected to prove each change, not
+assert it.** Screenshots and a passing test suite in the same turn as the edit
+are what make it safe to move fast.
+
+---
+
+## 3. Architecture decisions (and why)
+
+- **Server owns the truth.** `correct = (choice == "back") == has_anomaly`. The
+  answer lives only in server state and is stripped from every payload (keys
+  starting with `_` are dropped). The browser literally cannot be inspected to
+  cheat. Decide early what must never reach the client.
+- **Content is data, not code.** Each arc is one JSON file of properties,
+  sentence pools, and story. New files appear on the menu automatically. This is
+  what let "add an arc" be a 20-minute change with no engine edits.
+- **Session state keyed by a client-echoed id, not a cookie.** (See lessons.)
+- **Single process, in-memory state.** Fine for this game; it dictates
+  single-worker deployment. Know this constraint before you scale.
+
+---
+
+## 4. Content model: arcs
+
+An arc is a skin + backstory over the shared mechanic. The schema and the design
+rules (every arc needs a strong diegetic hook, an NPC that can become the
+anomaly, a loop-aware NPC twist, and a non-physical `sense` layer) live in
+`docs/ARCS.md`, along with shared tuning and a queue of planned arcs. Keeping a
+living design doc meant new arcs stayed consistent and we never re-derived the
+rules.
+
+The difficulty ramp and the doubt-prompt curve are engine-wide and documented
+so every arc inherits them.
+
+---
+
+## 5. Procedural audio
+
+There are no audio files in the game. Ambience is synthesised live in the
+browser with the Web Audio API (`static/audio.js`): oscillators and filtered
+noise per arc (fluorescent buzz, subway roll, stairwell wind), plus a muted
+arpeggio for the landing. Rare events (a flicker, a passing train, a gust) are
+scheduled sparsely. This kept the repo tiny and every soundscape editable as
+code.
+
+For sharing, the same synth is rendered offline (`OfflineAudioContext`) into an
+OGG and a 1080p MP4 by `scripts/export_landing_media.py`, so the exported media
+is exactly what players hear.
+
+---
+
+## 6. Verification discipline
+
+What the agent actually did to trust its own work:
+
+- **Logic:** ran the app in-process and played optimally by reading the server's
+  hidden answer, asserting the game wins in exactly eight correct calls and that
+  a fresh, cookie-less client keeps its arc (the regression test).
+- **UI:** launched Chromium, drove the flow, and screenshotted the landing, each
+  skin, the win screens, and mobile viewports. A picture caught things a test
+  never would (colours too similar, HUD clipped on mobile).
+- **Audio:** rendered offline and inspected the node graph / sample peaks.
+
+If you take one habit from this project: **make the agent show you a screenshot
+or a green test in the same message it says "done".**
+
+---
+
+## 7. Deployment
+
+The game ships as a Docker Space on Hugging Face (`Dockerfile`, port 7860,
+single worker). `scripts/deploy_hf.py` creates/updates the Space and uploads;
+`scripts/make_private_hf.py` toggles visibility for a private-until-release flow.
+
+Deployment is **local-only** here: the sandboxed web session's network policy
+blocks `huggingface.co` (a 403 at the egress proxy), so deploys must run from a
+machine with normal internet. Know your environment's network policy before you
+plan a deploy.
+
+---
+
+## 8. Hard-won lessons (the gotchas)
+
+These cost real time. Skip them:
+
+- **Cross-site iframe drops cookies.** On Spaces the app runs in an iframe, so
+  the Flask session cookie was silently dropped and every request span a fresh
+  default slot (the arc kept reverting, progress vanished). It reproduced only
+  when hosted, never locally. Fix: hand the client a session id and echo it on
+  every request via a header; keep the cookie only as a same-origin fallback.
+- **`localStorage` throws on opaque origins / private mode.** An unguarded read
+  in a constructor broke audio for some users (and for offline rendering). Wrap
+  storage access in try/catch.
+- **Browser autoplay policy.** Audio can only start after a user gesture. Start
+  ambience on entering a loop / first interaction, and always ship a mute
+  toggle.
+- **Chromium refuses "unsafe" ports** (e.g. 5060, 6000) for page loads. Serve
+  test instances on 8070+.
+- **Centered flexbox clips tall content.** `align-items:center; min-height:100vh`
+  hides the top of anything taller than the viewport, which buried the mobile
+  progress bar. Top-align on mobile and let it scroll.
+- **A live write token is a secret.** When a token has to be used, treat it as
+  exposed the moment it's pasted and rotate it after.
+
+---
+
+## 9. Writing rules (the game's voice)
+
+- **Never spoil the game in the instructions.** State the rule generically
+  (proceed while it matches your memory, turn back if anything changed). Do not
+  name the specific detail or character a player must notice; they discover it.
+- **No em-dashes.** Commas, periods, colons instead. (Arrows in sign content are
+  fine.)
+- **Weave the rule into the story**, per arc, instead of listing it as rules.
+
+These are enforced by writing them into `CLAUDE.md`, so every future edit obeys
+them without a reminder.
+
+---
+
+## 10. Conventions worth copying
+
+From this repo's `CLAUDE.md`, the ones that generalise:
+
+- Commits are authored solely by the repo owner. Decide attribution up front.
+- No AI model identifier in commits, code, comments, or docs.
+- Develop on the branch/flow the owner authorises; commit and push when a change
+  is complete and verified.
+- After UI changes, verify in a real browser and run the tests before committing.
+- Remind the owner when a change needs a manual deploy to reach production.
+
+---
+
+## 11. Replication checklist
+
+To build a similar game with an AI coding agent:
+
+1. **Write the mechanic down** in a few sentences before any code. Nail the
+   framing (what the player is really doing).
+2. **Create `CLAUDE.md`** with: the stack, the one-line mechanic, what must
+   never leak to the client, and your conventions (attribution, tone, colours).
+3. **Ask for a thin, runnable MVP** in a no-build stack. Make "run it" trivial.
+4. **Add a test runner and browser verification early.** Insist the agent proves
+   changes with a screenshot or a passing test in the same turn.
+5. **Model content as data** so new content is a file, not an engine change.
+6. **Iterate one change per message.** Design by playing: react to screenshots,
+   ask for the next tweak.
+7. **Write a living design doc** (`docs/ARCS.md`-style) once you have more than
+   one variant, so consistency survives.
+8. **Keep secrets out of the repo and chat**; when a token is unavoidable,
+   rotate it after use.
+9. **Update `CLAUDE.md` whenever a decision becomes load-bearing** (the iframe
+   fix, the audio design, the tuning curves all live there now).
+10. **Deploy from where the network allows it**, and script the deploy so it is
+    one command.
+
+---
+
+## 12. Prompt playbook
+
+Real prompts from this build that produced good results, lightly generalised:
+
+- "Think of the mechanic first: how do we make it *feel* like X, not Y?"
+- "Build a thin, runnable version I can play."
+- "Add an arc about <situation>; keep the mechanic, give it its own NPC and a
+  psychological twist."
+- "There's a bug: <symptom>. Write a proper test that reproduces it, then fix it,
+  and run random walks to be sure."
+- "Show me a preview of <screen>." (invites a screenshot)
+- "Make the instructions relate to the backstory, and don't reveal any details."
+- "Optimise for mobile; the <element> isn't visible."
+- "Save everything we've learned into `CLAUDE.md`."
+
+The through-line: describe the *goal and the feel*, let the agent choose the
+implementation, and make it show you the result.

hallway.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
 """The corridor: building a loop and describing it.
 
 A "room" is not a paragraph. It is a set of properties, each currently at its

memory.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
 """Tracks how the player behaves across loops.
 
 The point of this module is not scoring. It is to give the game a small

scripts/deploy_hf.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
 """Deploy this repo to a Hugging Face Docker Space.
 
 Run from a machine with normal internet access (not the sandboxed web session,

scripts/export_landing_media.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
+"""Export the landing theme to shareable media, straight from the game's synth.
+
+The landing music is generated live in the browser (`static/audio.js`). This
+script drives that same code headlessly through an OfflineAudioContext, so the
+exported files are exactly what a player hears, then packages them:
+
+  - static/audio/landing.ogg  a small looping-ish OGG (used as an asset)
+  - static/audio/landing.mp4  a 1080p still-card video for YouTube etc.
+
+The card shows the landing screen's text and style ("8 / Somewhere you can't
+quite leave. / Choose a way through.").
+
+Run locally (not in the sandboxed web session):
+
+    pip install playwright imageio-ffmpeg soundfile numpy
+    playwright install chromium
+    python scripts/export_landing_media.py                 # both files
+    python scripts/export_landing_media.py --seconds 300   # longer video
+    python scripts/export_landing_media.py --only mp4      # or: ogg
+
+Nothing here needs the Flask server: audio.js is loaded directly.
+
+NOTE: the arpeggio constants below mirror `_landing` in static/audio.js. If you
+retune the landing theme there, mirror the change here (or vice versa).
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import os
+import sys
+
+import numpy as np
+import soundfile as sf
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+AUDIO_JS = os.path.join(ROOT, "static", "audio.js")
+OUT_DIR = os.path.join(ROOT, "static", "audio")
+SR = 44100
+
+# The landing card: the select screen's text and style, sized for 1080p.
+CARD_HTML = """
+<!doctype html><html><head><meta charset=utf-8><style>
+ html,body{margin:0;height:100%}
+ body{width:1920px;height:1080px;display:flex;align-items:center;justify-content:center;
+   background:radial-gradient(120% 90% at 50% -12%, hsl(212 8% 10%), #0b0c0e 72%);
+   color:#d7d7d2;font-family:"Iowan Old Style","Palatino Linotype",Palatino,Georgia,'DejaVu Serif',serif;}
+ .wrap{text-align:center}
+ .title{font-size:10rem;font-weight:300;letter-spacing:.18em;margin:0 0 2.4rem;color:#e6e6e1}
+ .lead{color:#7d8088;font-size:2rem;line-height:2.4}
+</style></head><body>
+ <div class=wrap>
+   <div class=title>8</div>
+   <div class=lead>Somewhere you can't quite leave.<br>Choose a way through.</div>
+ </div>
+</body></html>
+"""
+
+# Renders the landing theme to a mono WAV blob and downloads it. The synthesis
+# reuses audio.js helpers (window.ambience.constructor); only the scheduling is
+# unrolled here (audio.js schedules with setTimeout, which offline render skips).
+AUDIO_JS_RENDER = """
+async ([SR, dur, fadeIn, fadeOut]) => {
+  const wr = (dv,o,s)=>{ for(let i=0;i<s.length;i++) dv.setUint8(o+i, s.charCodeAt(i)); };
+  const Amb = window.ambience.constructor; const amb = new Amb();
+  const off = new OfflineAudioContext(1, Math.floor(SR*dur), SR);
+  amb.ctx = off;
+  const bus = off.createGain(); bus.gain.value=1; bus.connect(off.destination);
+  const verb = amb._reverb(3.2,2.6); const verbG = amb._gain(0.5); verb.connect(verbG).connect(bus);
+  const voice = amb._gain(0.042); voice.connect(bus);           // mirrors _landing
+  const padG = amb._gain(0.0126); padG.connect(bus);
+  const pad = amb._noise(4); pad.connect(amb._filter('lowpass',240,0.5)).connect(padG); pad.start(0);
+  const chords=[[57,60,64],[53,57,60,64],[48,52,55,60],[55,59,62]];  // vi-IV-I-V
+  const step=0.22, ring=0.95, perChord=12;
+  let idx=0, t=0.05;
+  while (t < dur-0.02){
+    const c=chords[Math.floor(idx/perChord)%chords.length];
+    const tones=c.concat(c.map(m=>m+12));
+    const seq=tones.concat(tones.slice(1,-1).reverse());
+    amb._pluck(voice, verb, amb._mtof(seq[idx%seq.length]), t, ring);
+    t+=step; idx++;
+  }
+  const buf = await off.startRendering();
+  const d = buf.getChannelData(0);
+  let peak=0; for(let i=0;i<d.length;i++){const a=Math.abs(d[i]); if(a>peak)peak=a;}
+  const g = peak? 0.89/peak : 1;   // normalise for standalone playback
+  const N=d.length, fi=Math.floor(SR*fadeIn), fo=Math.floor(SR*fadeOut);
+  const ab=new ArrayBuffer(44+N*2); const dv=new DataView(ab);
+  wr(dv,0,'RIFF'); dv.setUint32(4,36+N*2,true); wr(dv,8,'WAVE'); wr(dv,12,'fmt ');
+  dv.setUint32(16,16,true); dv.setUint16(20,1,true); dv.setUint16(22,1,true);
+  dv.setUint32(24,SR,true); dv.setUint32(28,SR*2,true); dv.setUint16(32,2,true); dv.setUint16(34,16,true);
+  wr(dv,36,'data'); dv.setUint32(40,N*2,true);
+  let o=44;
+  for(let i=0;i<N;i++){ let s=d[i]*g; if(i<fi)s*=i/fi; if(i>=N-fo)s*=(N-i)/fo;
+    s=Math.max(-1,Math.min(1,s)); dv.setInt16(o,s*32767,true); o+=2; }
+  const blob=new Blob([ab],{type:'audio/wav'}); const url=URL.createObjectURL(blob);
+  const a=document.createElement('a'); a.href=url; a.download='landing.wav';
+  document.body.appendChild(a); a.click();
+  return N;
+}
+"""
+
+
+def _launch(p):
+    """Launch Chromium, tolerating this repo's sandbox layout or a normal install."""
+    import glob
+    try:
+        return p.chromium.launch()
+    except Exception:
+        hits = sorted(glob.glob("/opt/pw-browsers/chromium-*/chrome-linux/chrome"))
+        if not hits:
+            raise
+        return p.chromium.launch(executable_path=hits[-1])
+
+
+def render_wav(page, seconds, fade_in, fade_out, dest):
+    page.set_content("<!doctype html><html><body></body></html>")
+    page.add_script_tag(path=AUDIO_JS)
+    with page.expect_download(timeout=120000) as di:
+        page.evaluate(AUDIO_JS_RENDER, [SR, seconds, fade_in, fade_out])
+    di.value.save_as(dest)
+    return dest
+
+
+def render_card(page, dest):
+    page.set_content(CARD_HTML)
+    page.wait_for_timeout(300)
+    page.screenshot(path=dest)
+    return dest
+
+
+def wav_to_ogg(wav_path, ogg_path):
+    data, sr = sf.read(wav_path)
+    sf.write(ogg_path, data, sr, format="OGG", subtype="VORBIS")
+
+
+def mux_video(card_png, wav_path, out_mp4, fps=24):
+    import subprocess
+    import imageio_ffmpeg
+
+    ff = imageio_ffmpeg.get_ffmpeg_exe()
+    subprocess.run(
+        [ff, "-y", "-hide_banner", "-loglevel", "error",
+         "-loop", "1", "-framerate", str(fps), "-i", card_png,
+         "-i", wav_path,
+         "-c:v", "libx264", "-tune", "stillimage", "-preset", "medium",
+         "-pix_fmt", "yuv420p", "-r", str(fps),
+         "-c:a", "aac", "-b:a", "192k", "-ar", str(SR),
+         "-shortest", "-movflags", "+faststart", out_mp4],
+        check=True,
+    )
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--seconds", type=float, default=120, help="video length (s)")
+    ap.add_argument("--ogg-seconds", type=float, default=42.24, help="ogg length (s)")
+    ap.add_argument("--only", choices=["ogg", "mp4"], help="produce just one")
+    ap.add_argument("--out-dir", default=OUT_DIR)
+    args = ap.parse_args()
+
+    os.makedirs(args.out_dir, exist_ok=True)
+    tmp = os.path.join(args.out_dir, "_landing_tmp.wav")
+    card = os.path.join(args.out_dir, "_landing_card.png")
+
+    from playwright.sync_api import sync_playwright
+
+    with sync_playwright() as p:
+        browser = _launch(p)
+        ctx = browser.new_context(
+            viewport={"width": 1920, "height": 1080}, accept_downloads=True
+        )
+        page = ctx.new_page()
+
+        if args.only != "mp4":
+            render_wav(page, args.ogg_seconds, 0.4, 0.6, tmp)
+            wav_to_ogg(tmp, os.path.join(args.out_dir, "landing.ogg"))
+            print("wrote landing.ogg")
+
+        if args.only != "ogg":
+            render_wav(page, args.seconds, 0.6, 1.8, tmp)
+            render_card(page, card)
+            mux_video(card, tmp, os.path.join(args.out_dir, "landing.mp4"))
+            print("wrote landing.mp4")
+
+        browser.close()
+
+    for f in (tmp, card):
+        if os.path.exists(f):
+            os.remove(f)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/make_private_hf.py

@@ -1,4 +1,6 @@
 #!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
 """Toggle the visibility of the Hugging Face Space.
 
 Keep it private until release, then flip it public on the day.

static/audio.js

@@ -1,3 +1,6 @@
+/* SPDX-License-Identifier: Apache-2.0
+ * Copyright 2026 alvations (Melon Lab)
+ */
 /* Procedural ambience, generated live with the Web Audio API.
  *
  * No audio files: each arc's soundscape is synthesised from oscillators and
@@ -18,7 +21,11 @@ class Ambience {
     this.bus = null;
     this.sources = [];
     this.timers = [];
-    this.muted = localStorage.getItem("h8_muted") === "1";
+    let muted = false;
+    try {
+      muted = localStorage.getItem("h8_muted") === "1";
+    } catch (e) {} // localStorage can throw on opaque origins / private mode
+    this.muted = muted;
   }
 
   _ensure() {
@@ -89,6 +96,14 @@ class Ambience {
     return 440 * Math.pow(2, (m - 69) / 12);
   }
 
+  // A short noise source that is NOT tracked (one-shot SFX manage their own
+  // lifetime), so repeated sound effects don't grow the sources list.
+  _noiseOneShot(seconds) {
+    const s = this.ctx.createBufferSource();
+    s.buffer = this._noiseBuffer(seconds || 0.3);
+    return s;
+  }
+
   // one soft, ringing arpeggio note (bell/harp-like) at a scheduled time
   _pluck(out, verb, freq, t, dur) {
     const o = this.ctx.createOscillator();
@@ -286,6 +301,77 @@ class Ambience {
     tick();
   }
 
+  // --- action sound effects -----------------------------------------------
+  // A footstep: a soft low heel-thud plus a short scuff. Routed through the
+  // master gain so the mute toggle covers it.
+  _footstep(t, gain, pitch, bright) {
+    const out = this.master;
+    const o = this.ctx.createOscillator();
+    o.type = "triangle";
+    const base = 110 * pitch;
+    o.frequency.setValueAtTime(base * 1.7, t);
+    o.frequency.exponentialRampToValueAtTime(base * 0.7, t + 0.07);
+    const g = this._gain(0.0001);
+    o.connect(g).connect(out);
+    g.gain.setValueAtTime(0.0001, t);
+    g.gain.linearRampToValueAtTime(gain, t + 0.006);
+    g.gain.exponentialRampToValueAtTime(0.0006, t + 0.13);
+    o.start(t);
+    o.stop(t + 0.17);
+
+    const n = this._noiseOneShot(0.2);
+    const bp = this._filter("bandpass", 1600 * bright, 0.8);
+    const ng = this._gain(0.0001);
+    n.connect(bp).connect(ng).connect(out);
+    ng.gain.setValueAtTime(0.0001, t);
+    ng.gain.linearRampToValueAtTime(gain * 0.5, t + 0.004);
+    ng.gain.exponentialRampToValueAtTime(0.0004, t + 0.05);
+    n.start(t);
+    n.stop(t + 0.12);
+  }
+
+  // A brief directional swish, a nod to an old-school scene-change: sweeps up
+  // when moving on, down when turning back.
+  _swish(t, back) {
+    const n = this._noiseOneShot(0.5);
+    const bp = this._filter("bandpass", back ? 1600 : 700, 0.7);
+    const g = this._gain(0.0001);
+    n.connect(bp).connect(g).connect(this.master);
+    bp.frequency.setValueAtTime(back ? 1600 : 700, t);
+    bp.frequency.exponentialRampToValueAtTime(back ? 600 : 1800, t + 0.28);
+    g.gain.setValueAtTime(0.0001, t);
+    g.gain.linearRampToValueAtTime(0.045, t + 0.06);
+    g.gain.exponentialRampToValueAtTime(0.0004, t + 0.3);
+    n.start(t);
+    n.stop(t + 0.4);
+  }
+
+  // Play the movement sound for a committed choice. `dwellMs` is how long the
+  // player lingered before pressing: a quick, confident press gets real
+  // footsteps; a long deliberation softens to a tiptoe, then to near silence.
+  step(dir, dwellMs) {
+    this._ensure();
+    if (!this.ctx) return;
+    if (this.ctx.state === "suspended") this.ctx.resume();
+    const t = this.ctx.currentTime + 0.01;
+    const back = dir === "back";
+    const pitch = back ? 0.82 : 1.0; // turning back sits a touch lower
+
+    if (dwellMs < 2200) {
+      // confident: two firm steps + a scene-change swish
+      this._footstep(t, 0.22, pitch, 1.0);
+      this._footstep(t + 0.19, 0.19, pitch * 1.03, 1.05);
+      this._swish(t, back);
+    } else if (dwellMs < 5000) {
+      // hesitant: light, slower tiptoe
+      this._footstep(t, 0.08, pitch * 1.15, 1.4);
+      this._footstep(t + 0.27, 0.06, pitch * 1.18, 1.45);
+    } else {
+      // long deliberation: a single, near-silent shuffle
+      this._footstep(t, 0.03, pitch * 1.2, 1.6);
+    }
+  }
+
   // --- controls ------------------------------------------------------------
 
   play(skin) {
@@ -332,7 +418,9 @@ class Ambience {
 
   setMuted(m) {
     this.muted = m;
-    localStorage.setItem("h8_muted", m ? "1" : "0");
+    try {
+      localStorage.setItem("h8_muted", m ? "1" : "0");
+    } catch (e) {}
     if (this.master && this.ctx) {
       const t = this.ctx.currentTime;
       this.master.gain.cancelScheduledValues(t);

static/audio/landing.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:eb0c5cc7f0c2a84c8b83a731bff60bb646def0d55983397863b4c9828d487b81
+size 3080185

static/audio/landing.ogg

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:c3848234bf5e8eb9b66d050cd8c17ebd155bf651066719c30fd6baa279bffbc9
-size 295875
+oid sha256:f14f4becbae11c74fbb35f97f38948bba35995da5588d93b95c5486f4de00db1
+size 295547

static/game.js

@@ -1,3 +1,6 @@
+/* SPDX-License-Identifier: Apache-2.0
+ * Copyright 2026 alvations (Melon Lab)
+ */
 /* Eight -- client.
  *
  * The server owns the truth (whether a place changed) and ships several arcs
@@ -38,6 +41,7 @@ let meta = null;          // current arc's presentation meta
 let selectedArc = null;   // arc id in play
 let pendingChoice = null; // choice awaiting a confidence rating
 let hesitated = false;    // player already admitted doubt this turn (one re-decide)
+let decideStart = 0;      // when the controls appeared, to time the player's dwell
 let drift = 0;            // slowly accumulating presentation drift
 
 // --- helpers ---------------------------------------------------------------
@@ -183,6 +187,7 @@ async function renderRoom(p) {
 
   await sleep(400);
   el.controls.classList.remove("hidden");
+  decideStart = performance.now(); // start timing the player's deliberation
 }
 
 // Lingering on a detail may earn an unsettling aside from the server.
@@ -279,6 +284,11 @@ const HESITATION = [
 
 // Commit the pending choice to the server and move on.
 async function commit(confidence) {
+  // Movement sound, keyed to how long the player lingered: a quick, confident
+  // press gets footsteps; a long deliberation softens toward silence.
+  if (window.ambience) {
+    window.ambience.step(pendingChoice, performance.now() - decideStart);
+  }
   el.confidence.classList.add("hidden");
   const p = await post("/api/act", { choice: pendingChoice, confidence });
   pendingChoice = null;

static/style.css

@@ -1,3 +1,6 @@
+/* SPDX-License-Identifier: Apache-2.0
+ * Copyright 2026 alvations (Melon Lab)
+ */
 :root {
   --bg: #0b0c0e;
   --fg: #d7d7d2;

tests/test_game.py

@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 alvations (Melon Lab)
 """Tests for the memory-loop game.
 
 Runnable two ways: