# Changelog

## v0.1.62 — 2026-05-05

**Wishlist completion sprint** — every one of the 27 lab ideas on `labs/wishlist.html` (across 5 sections: 🎮 PLAY · 🐙 SMART & SOCIAL · 🥷 HACK · 🔧 BUILD · 👁 SENSE) ships as a working MVP. 26 new labs landed in three commits, each built by parallel agents in their own worktree-style file. Co-Pilot was already shipped from v0.1.61.

### Added — 🔧 BUILD (4 labs, commit `dea7131`)

- `labs/mod-lab.html` (949 lines) — interactive wiring guide for add-ons. 4 tabs: 2nd Servo (P15) · OLED SSD1306 (I²C 0x3C) · Gas Sensor (analog) · Color Sensor TCS34725 (I²C 0x29). Inline-SVG schematics with highlighted pin pads, MakeCode TS snippets with copy buttons, "Test it" buttons that auto-promote from stub→live BLE the moment the verb ships.
- `labs/addon-lab.html` (880 lines) — plug-and-play I²C wizard. 4-step stepper: plug · scan (128-cell hex grid) · identify (TCS34725 / VL53L0X / MPU6050 / BME680 / SSD1306) · test & expose. Persists chosen sensors to `localStorage["maqueen.addons"]` for downstream labs.
- `labs/power-lab.html` (698 lines) — current draw + runtime simulator. Live meter (mA / V / runtime / 60s spark-line) ‖ "What if?" simulator (motors slider · NeoPixels 0-24 · OLED/gas/buzzer toggles · 3 presets). Synthetic demo data when no real telemetry within 1.5s; chip auto-clears on first `POWER:` frame.
- `labs/cad-lab.html` (974 lines) — 3D-print accessory gallery. 8 items (Servo Claw · Sensor Mount · FPV Phone Holder · Parade Hat · Bumper Ring · Battery Doubler · Pen Adapter · Cable Comb). Filter pills, click-to-zoom modal, pin-to-list (`localStorage["cad-pinned"]`). STL downloads stubbed pending real files.

### Added — 🎮 PLAY (6 labs, commit `53e9965`)

- `labs/race-lab.html` (1027 lines) — line-following race with lap timer, leaderboard, **ghost replay**. Two track shapes (oval / figure-8). Best-lap ghost stored per shape.
- `labs/swarm-lab.html` (781 lines) — control 2-4 bots from one phone. 4 BLE slots (each holds its own `navigator.bluetooth.requestDevice()`). Formations + simultaneous start + follow-the-leader + mirror + spin chorus.
- `labs/sumo-lab.html` (1076 lines) — two bots, one ring. 60s clock, HP, ring-out detection, 4 tactics (Charge/Spin/Wedge/Defend), single-elimination bracket up to 8 fighters.
- `labs/drawing-lab.html` (773 lines) — clip a pen, drive shapes. 3 modes: Polygon · Spirograph (hypotrochoid) · Free (Catmull-Rom). Save planned path as SVG.
- `labs/story-lab.html` (796 lines) — bot drives between scene-cards, each card fires sound/light/motion. 3 preset stories. Print scene cards as 10cm tiles.
- `labs/slow-lab.html` (717 lines) — move as slowly as possible. Smoothness scoring via jerk integration. 4 zen achievements (Snail · Glacier · Statue · Zen ⭐⭐⭐).

### Added — 🐙 SMART & SOCIAL (5 labs, commit `53e9965`)

- `labs/behavior-lab.html` (817 lines) — drag-block visual programming. Rule canvas (WHEN → DO → THEN), live MakeCode TypeScript codegen, 10 Hz rule engine.
- `labs/trick-lab.html` (982 lines) — train your bot with clap patterns. Mic peak detection (RMS + EMA-baseline + 200ms refractory) with ±150ms match tolerance. Spacebar fallback when mic denied.
- `labs/hunt-lab.html` (829 lines) — virtual map, blind bot. Pirate-themed 10×10 grid · 3 treasures · randomized walls · best-time/fewest-moves leaderboard.
- `labs/mirror-lab.html` (747 lines) — one bot mimics another. Independent BLE per bot. 4 modes: direct · inverted · delayed · blind echo.
- `labs/personality-lab.html` (744 lines) — 4-slider personality mixer (boldness · chattiness · sleepiness · explorer-ness). Single scheduler drives both canvas wanderer and BLE dispatch.

### Added — 🥷 HACK (8 labs, commit `e8aedf1`)

- `labs/ble-sniffer-lab.html` (860 lines) — live hex dump + annotated decoder + replay queue. Recognizes M/STOP/BUZZ/TONE/LED/RGB/SRV/IR/DIST/LINE/BAT/HEAD/POLL/EDGE/HELLO/ECHO/INFO/ERR. Save/load captures as JSON.
- `labs/protocol-lab.html` (985 lines) — author your own command verbs. 6 default verbs (WIGGLE · DANCE · PIROUETTE · SOS · HEARTBEAT · ZIGZAG). Compile to UART stream with token highlighting.
- `labs/fuzz-lab.html` (806 lines) — 6 strategies (random · mutate · boundary · long-string · format-string · buffer-overflow). Confirm dialog if iters > 1000. Auto-stop on consecutive errors / motor stall. EMERGENCY STOP. Smallest-crash leaderboard.
- `labs/identity-lab.html` (638 lines) — change BLE name. 8 absurd defaults (NotARobot · BroomCloset · DEFINITELY-A-FAX-MACHINE…). IDENT verb stub with auto-promote when firmware ships.
- `labs/ircap-lab.html` (975 lines) — universal remote. 4-step wizard with pulse-train visualizer. Mischief mode toggle.
- `labs/cipher-lab.html` (1056 lines) — encrypted bot↔bot radio. 5 ciphers (Caesar · ROT13 · XOR · Vigenère · Atbash). 5 break-the-cipher challenges with frequency-analysis chart.
- `labs/walkie-lab.html` (758 lines) — off-grid bot↔bot radio chat. Channel scanner (0-83), 4-bot roster. Verbs WALKIE_JOIN/LEAVE/BEACON/MSG stubbed pending firmware RADIO support.
- `labs/worm-lab.html` (810 lines) — multi-bot propagation visualizer + containment game. 3-12 nodes, configurable range + spread rate. 4 achievements.

### Added — 👁 SENSE (3 labs, commit `e8aedf1`)

- `labs/compass-lab.html` (770 lines) — drive due north. P-controller heading lock with tolerance pills. Magnetic treasure hunt with µT bar.
- `labs/logger-lab.html` (894 lines) — STEM-grade data logger. 7 channels (Distance · IR-L · IR-R · Heading · Battery · Current · Temp). 1-20 Hz sample rate. CSV export with metadata comment header. Multi-line graph with hover crosshair + event markers.
- `labs/diagnostic-lab.html` (1066 lines) — Robot Checkup. 11 subsystem tests (4 auto + 6 kid-confirm thumbs-up + 1 graceful-fallback compass). Save last 10 reports. Print-friendly report layout.

### Updated — wishlist + index links

- `labs/wishlist.html` — every idea card now carries a `✅ SHIPPED` badge and an "Open lab →" button linking to its actual file. Section headings show counts (PLAY 6 / SMART 5 / HACK 8 / BUILD 5 / SENSE 3 = 27). Hero reframed from "vote on what we build next" to "every wish shipped — this page is now your feature index". EN / FR / AR locales updated.
- `labs/index.html` — Available Labs heading now shows `27 / 27 SHIPPED` chip. Bottom CTA recolored from amber-vote to neon-shipped, copy updated across EN / FR / AR.

### Conventions uniformly applied to all 26 new labs

- `<html lang="en" data-theme="carbon">`
- Standard `<head>` link/script set: theme.css · doc-shell.css · lab-logger.css?v=6 · newtab.js · ble-shim.js · ble.js · lab-logger.js?v=6
- Palette restricted to `--cyan #22d3ee · --amber #fbbf24 · --neon #a3e635 · --red #ef4444`
- `js/ble.js` LOCKED — multi-bot labs (Mirror · Swarm · Sumo · Cipher · Walkie · Worm) use independent `navigator.bluetooth.requestDevice()` instances per slot
- All "future firmware verb" labs send live first, fall through to clearly-chipped stub log otherwise — auto-promote with zero code change when firmware lands
- No README/docs files created per lab (single-source CHANGELOG entry covers them)

## v0.1.61 — 2026-05-04

Two new labs: a photo-realistic Cockpit Lab (10 simulator panels) and a fully BLE-wired Living Twin (cartoon Maqueen mirroring the real robot in real time, with voice tour, mission mode, and EN/FR/AR i18n).

### Added — Living Twin (`labs/maqueen-twin.html`)

- **Bidirectional BLE wiring** via `js/ble-shim.js` + `js/ble.js` (the legacy main BLE module, **untouched**). Twin → Robot: click cartoon buzzer → `BUZZ:440,200`; click matrix → `CMD:HEART/SMILE/SAD/CLEAR`; click A/B → `CMD:`; type message → `TEXT:`. Robot → Twin: `ACC:` tilts the cartoon body, `BTN:A:PRESS` flashes the cartoon button + speech bubble + sticky-note narration, `TEMP/LIGHT/SOUND/COMPASS` update live readouts, `LEDS:` mirrors the real matrix.
- **🎤 Voice Tour** — 8-step guided narration via Web Speech API. Each step glows a robot part with a yellow ring, speaks one kid-friendly sentence, auto-advances on speech end. Prev/Pause/Next/Stop.
- **🎯 Mission Mode** — 6 challenges with star counter (⭐ N/6): say HEART, beep buzzer, press REAL Button A, tilt sideways, send a message, show all 4 faces. Confetti burst + voice "mission accomplished" on full clear.
- **🌐 i18n picker** (🇬🇧 EN · 🇫🇷 FR · 🇸🇦 AR Modern Standard Arabic). Auto-detects browser language, persists via `localStorage`. Speech voice picks language-matched system voice. Arabic switches body to `dir="rtl"` for proper RTL layout.
- **"What did I just do?" sticky note** narrates every action in kid language so cause→effect→name is explicit.
- **🎨 demo / ✨ LIVE tags** — clearly labels which animations are real vs decorative (no lying to kids about wheels/ultrasonic/RGB-LEDs that aren't in the firmware protocol yet).

### Added — Cockpit Lab (`labs/cockpit-lab/`)

- **10 photo-realistic skeuomorphic flight-simulator-style panels** (Flight Sim, Race Car, Submarine, Spaceship, Steam Loco, Helicopter, Sailboat, Excavator, Mech, Rally). Brushed-metal panels, chrome bezel gauges, throttle levers, knurled knobs, switches with shadow depth, wooden vehicle silhouette perched on top — matching the workshop poster aesthetic.
- 10 themes (steel, carbon, sub, space, wood, olive, mahogany, hazard, mech, rally) — same hardware mapping (motors, servo, RGB LEDs, matrix, IR, line sensors), 10 different metaphors.
- Generator at `tools/_build-cockpit-mockups.py` — single Python source emits all 10 panels + gallery into `labs/cockpit-lab/`.

### Added — Documentation

- `docs/lessons/maqueen-twin.md` — 60-min lesson plan, ages 8-12.
- `docs/lessons/cockpit-lab.md` — 45-min design-literacy lesson, ages 9-14.
- `docs/curriculum.md` — updated to 10 Labs total with formal standards (FR Cycle 3-4, NGSS, CCSS, CSTA).
- README (EN/FR/AR) — Living Twin + Cockpit Lab sections; status bumped to v0.1.61.

### Reorganized

- `labs/cockpit-lab*.html` (11 files) → `labs/cockpit-lab/index.html` + `1.html..10.html` subfolder.
- 4 design iterations preserved in `labs/_archive/cockpit-lab/v1..v4/` + sandbox iteration in `labs/_archive/maqueen/{emu,kid}/` (3 emu views + 7 kid personalities).
- Archived generator files in `tools/_archive/`.
- `labs/index.html` collapsed: 5 cockpit-version pills → 1 + new Living Twin pill.

### Notes

- **`js/ble.js` is unchanged** (verified: last touched in commit `d5b87e6` for v0.1.60). Living Twin uses the same `ble-shim.js` + `ble.js` pattern as `distance-lab.html`, `copilot-lab.html`, `ir-lab.html`.
- **No firmware changes.** The Twin uses only the existing protocol (`BUZZ:`, `CMD:`, `TEXT:`, `BENCH:` outgoing; `ACC:`, `BTN:`, `LEDS:`, `TEMP:`, `LIGHT:`, `SOUND:`, `COMPASS:` incoming).
- Production link audit: 128 production hrefs checked, **0 broken** after the cockpit subfolder reorg.

---

## v0.1.60 — 2026-05-02

Big surface expansion: a `labs/` folder with 8 single-purpose kid labs, draggable cockpit FABs in the main app, brand sweep, and printable workshop artifacts (flyer + poster) with real QR codes.

### Added — Labs surface (`labs/`)

- **8 single-purpose Labs**: Joystick, Distance, Music, Servos, IR, Lights, Vision, Co-Pilot. Each lab connects via the same `js/ble.js`, mounts the live robot, and pins a right-rail **Message Log** faithful to the main app's MESSAGE LOG (TX `> #N VERB` / RX `< ECHO` format).
- `labs/index.html` hub + `labs/wishlist.html` (next-lab vote board).
- `labs/lab-logger.js` + `.css` — pinned right-rail logger with drag-resize, `lockShimHook` via `Object.defineProperty` (un-overridable handler chain), classifyLine() auto-detect of TX/RX/ERR.
- Defensive theme sanitizer in every lab + hub: `if (_validThemes.indexOf(t) === -1) t = 'carbon'` — protects the lab palette (`carbon / forest / steel / paper / pearl`) from cross-surface localStorage propagation accidents.

### Added — Cockpit (main app)

- **Draggable FABs**: CONNECT, LABS, STOP. Pointer-events drag with 8px click-vs-drag threshold; positions persist in localStorage. LABS anchor sets `draggable=false` + `dragstart preventDefault` to defeat HTML5 drag-to-bookmark interception.

### Added — Workshops

- `workshops/flyer.html` + `workshops/poster.html` — kid-attracting v2 (FR, 8 ans+).
  - Comic-book bursts (POW / BAM / ZAP / BOOM via 12-pt clip-path stars).
  - Wave emanations behind mascot, "VROUM VROUM!" speech bubble.
  - Animated SVG illustrations: radar sweep, servo wave, music notes, LED pulse.
  - Real QR code via `js/qrcode.min.js` (qrcode-generator API: `createSvgTag()`).
  - Official `assets/logo.svg` + "MAQUEEN LAB" wordmark in the hero.
  - **Mobile-friendly scale-to-fit**: A4 internal layout preserved; JS sets `transform: scale()` on viewports ≤ 820px and collapses the layout-box height so there's no white tail. Print path untouched (still true A4).

### Fixed — Reliability

- **`sw.js`** — atomic `cache.addAll` was failing on missing assets. Now per-asset `cache.add().catch()`. Removed 5 dead asset entries. Cache renamed `maqueen-lab-v11`.
- **`js/ble-scheduler.js`** — wrapper was swallowing the awaited promise (`return throttledSend(line)`).
- **Joystick lab logger** — DOMContentLoaded handler was inside an IIFE that ran *after* DCL. Fixed with readyState-aware mount.
- **Co-Pilot lab** — both DCL + readyState fallback fired, double-mounting the logger. Added `_copilotMounted` guard.

### Fixed — Theming

- Reverted the `mb_theme → robi.theme` cross-surface unification — main app and labs have **different palettes** (only `forest` overlaps). Each surface owns its own localStorage key.
- Added theme sanitizer to all labs + `labs/index.html` + `labs/wishlist.html`.
- Servo-lab regression: sanitizer ran *before* the localStorage fallback → reset to `carbon` on every visit. Reordered.

### Changed — Brand

- Sweep `ROBI-9 LAB` → `MAQUEEN LAB` across HTML strings *and* CSS / JS comments (`docs/doc-shell.css`, `workshops/theme.css`, `js/voice-picker.js`).

### Docs

- `docs/index.html` + every guide / pinout / plan / schematics page: theme + lang selectors, Robi-9 mascot pill, faithful to `workshops/hub.html`.

## v0.1.55 — 2026-04-27

The Maqueen tab is now the front door. Heavy clean-up of duplicated
controls in the Playground sub-tabs, big BLE-reliability rewrite, and a
bunch of firmware polish.

### Added — UI

- **Two top tabs**: 🤖 **Maqueen** (real-robot UI) and 🧪 **Playground**
  (collapsible group of legacy bit-playground sub-tabs).
- **Maqueen tab cards**: Drive · Servos (with Mechanic-Kit picker:
  Forklift / Loader / Beetle / Push) · Simple LEDs · NeoPixels · Buzzer
  · Ultrasonic · IR remote · Line sensors (Follow-line auto mode now
  lives inside this card).
- **Live sensor strip** across the top: LINE, DIST, IR, ACC, BLE bench
  (sent · echoed · lost · avg ms), three poll buttons, `streams: ON/OFF`
  chip.
- **Streams auto-toggle** on/off when entering/leaving the Sensors /
  Graph / 3D sub-tabs.
- **Hold to drive (release = stop)** option in the Drive panel.
- **DIST/LINE auto-poll rate sliders** (200–2000 ms) and Follow-line
  tick slider (100–1000 ms) — all persisted in localStorage.
- Auto-pollers **pause when leaving the Maqueen tab** to spare BLE
  bandwidth.

### Added — Firmware (now v0.1.55)

- **ACC / LIGHT / SOUND streams** emit a heartbeat ≥ once per
  ~500–1000 ms even when the value hasn't changed, so the Graph never
  looks frozen.
- **`STREAM:on|off`** verb to opt into/out of ACC/LIGHT/SOUND streams
  (off by default to keep the BLE channel free).
- **`LM:HEX`** — 5×5 LED matrix bitmap; the Controls sub-tab can draw
  on the board.
- **`OTHER:*`** verbs from the More tab now show visible micro:bit-screen
  feedback (digits, heart, arrows, switch icons, bar graphs, scrolling
  text) instead of silently acking.
- **`DIST?`** returns `DIST:-` instead of `DIST:500` when no obstacle is
  detected.
- **`HELLO` / `HELLO:<ver>`** confirms connection and reports firmware
  version on the Connect card.

### Fixed — BLE / connectivity

- **Single global write serializer** awaits each `writeValue()` Promise.
  No more `NetworkError: GATT operation already in progress`.
- **One source of truth for connection state** — DOM signal +
  MutationObserver, broadcasts `connected` / `disconnected` events.
- **Pending sends rejected on disconnect** (no more silent hangs).
- **Removed `input.compassHeading()` from auto-stream** — it was
  triggering tilt-game calibration that blocked the BLE handler. Root
  cause of the long-standing "no echo" symptom.

### Removed (duplicates of Maqueen-tab panels)

- Touch P0 / P1 / P2 cards (Maqueen wires P13/P14 to line sensors;
  P0/P1/P2 not exposed for touch).
- Buzzer card from Controls (duplicate of Maqueen Buzzer).
- Servo / LED / Buzzer cards from More (duplicates of Maqueen panels).
- GamePad sub-tab (duplicate of Maqueen Drive).
- Motors sub-tab (duplicate of Maqueen Servos with kit picker).

Net Playground sub-tab count: **8 → 6**.

### Changed — build/version policy

- Pre-commit hook auto-bumps `BUILD_VERSION` **only** when
  `firmware/v1-maqueen-lib.ts` is in the staged change. Docs commits no
  longer bump the version label — the stamp now tracks real firmware
  churn.
- The `.hex` is **not** auto-compiled. Re-build it in MakeCode and
  re-flash when the version changes (see User Guide → "Building the
  firmware .hex").

## v0.1.x — auto-bump enabled

Pre-commit hook (`tools/git-hooks/pre-commit`) now bumps the firmware
patch version + UTC build date on every commit. Set
`SKIP_FW_BUMP=1 git commit ...` to opt out for a specific commit.

## v0.1.0 — 2026-04-26 (in progress)

Initial scaffold. Forked from [bit-playground](https://github.com/abourdim/bit-playground) v1.2.0.

### Added

- Project structure forked from bit-playground.
- Maqueen-specific config (`package.json`, `product.json`, `manifest.json`).
- Maqueen Lite v4 firmware scaffold (`firmware/v1-maqueen-lib.ts`) — BLE UART verbs with sequence + echo confirmation, USB serial mirror, boot banner.
- BLE scheduler wrapper (`js/ble-scheduler.js`) — wraps existing `js/ble.js` with sequence numbers, echo validation, coalescing, rate limiting, animation registry. **Does not modify `js/ble.js`.**
- Servo Explorer (pilot) — visual + calibration + sweep + code panel + auto-demo.

### Removed

- bit-playground's non-Maqueen 3D models (`arm.js`, `balance.js`, `buggy.js`, `weather.js`).
- bit-playground's docs (`docs/`) and Etsy package (will be regenerated for maqueen-app).
- bit-playground's makecode-extension scaffold (replaced with Maqueen-specific firmware).
- bit-playground branding from configs.

### Notes

- `js/ble.js` from bit-playground is reused **unchanged**. New code wraps it; never edits it.
- Firmware uses the `pxt-maqueen` MakeCode extension for hardware access.
- Same BLE UART wire protocol works with future raw-pin firmware (`firmware/v2-raw-pins.ts`).