# Maqueen Lab โ€” Roadmap > **Single source of truth** for what shipped and what's next. **`docs/next.md` was merged into this file** on 2026-05-04 (then removed in the consolidation pass). The "๐ŸŸข Now" section at the top is the active to-do; the rest is the historical phase plan. --- ## ๐ŸŸข Now (active to-do โ€” last touched 2026-05-04) ### ๐Ÿ”ด Bugs to fix from the smoke run (P0) | # | Item | Where | Effort | |---|------|-------|--------| | 1 | Hub-load tests timing out on teardown (5 tests) โ€” `index.html`, `labs/index.html`, `docs/index.html`, `workshops/hub.html`, `docs/lessons/index.html` heavy animations don't finish | `tests/smoke.spec.mjs` โ€” pass `{ waitUntil: 'domcontentloaded' }` to `page.goto`, or stop animations before assertion | 15 min | | 2 | Pre-commit linter hook keeps re-running `inline-md.mjs` on every commit | `tools/git-hooks/pre-commit` โ€” only run if a `.md` file is in the staged diff | 10 min | | 3 | `tests/tests.html` orphan in CI โ€” should be in `ALLOWED_ORPHANS` *or* linked from `docs/index.html` | `tools/_audit-links.py` already allows it; confirm | 5 min | ### ๐ŸŸก Phase 2B remaining | # | Item | Why | Effort | |---|------|------|--------| | 2B-7 | **Split `js/maqueen-tab.js` (4580 LoC)** into per-card modules. Pre-condition: smoke tests green first. | One file = one accident. | 3-4 h | | 2B-10 | **Performance budget** โ€” Lighthouse CI pass + budget file (โ‰ค 1.5 s LCP on cheap Android tablets) | School hardware is slow. | 1 h | ### ๐Ÿš€ Phase 2C ideas | # | Item | Why | Effort | |---|------|------|--------| | 11 | Top 3 wishlist labs (`labs/wishlist.html` votes) | Channel new ideas through the wishlist | varies | | 12 | **Multi-robot Lab** (WebRTC peer-to-peer) | Two Maqueens dancing = viral | 4-6 h | | 13 | **Progress badges / kid passport** (localStorage) | Motivator; no backend | 2 h | | 14 | **Add-on framework** (Gravity sensors + I2C accessories) | Verb namespace stubbed in firmware | 4 h | | 15 | **Phase 2 firmware** (`firmware/v2-raw-pins.ts`) | For advanced learners | 6 h | ### ๐ŸŸข Manual / human-only (not codable) | Item | Owner | |------|-------| | ๐Ÿ“ท Photograph a real micro:bit on a laptop running the app (Etsy hero) | You | | ๐ŸŽฌ Record 60-sec listing video using `seller-only/ETSY_LISTING.md` script | You | | ๐Ÿ›’ Create LAUNCH10 promo code in Etsy Shop Manager | You | ### ๐Ÿ”‡ Won't do - Translate technical docs (`CHANGELOG.md`, `CUSTOMIZE.md`) โ€” contributor-facing, EN is fine - Cross-browser smoke tests (Firefox/WebKit) โ€” Web Bluetooth is Chromium-only anyway - A virtual physics layer for demo-mode โ€” current synthetic responses are enough ### โœ… Recently shipped (v0.1.61, 2026-05-04) - **Living Twin** (`labs/maqueen-twin.html`) โ€” bidirectional BLE-wired cartoon mirror, ๐ŸŽค Voice Tour, ๐ŸŽฏ Mission Mode, ๐ŸŒ EN/FR/AR with RTL. - **Cockpit Lab** (`labs/cockpit-lab/`) โ€” 10 photo-realistic skeuomorphic flight-sim panels. - 4 design iterations preserved in `labs/_archive/cockpit-lab/v1..v4/` + sandbox in `labs/_archive/maqueen/{emu,kid}/`. - Lesson plans for both new labs (`docs/lessons/maqueen-twin.md`, `docs/lessons/cockpit-lab.md`). - Cockpit subfolder reorg: `labs/cockpit-lab/index.html + 1..10.html`. - README EN/FR/AR + CHANGELOG EN/FR/AR + curriculum refreshed. - Production link audit: 128 hrefs, 0 broken. --- ## โœ… Phase 1 โ€” Shipped (v0.1.0 โ†’ v0.1.60) The original "20 things to ship next: 10 app improvements + 10 educational games" โ€” **all checked**. Open the [Changelog](CHANGELOG.html) for the full release-by-release breakdown. Open the [labs wishlist](../labs/wishlist.html) to vote on new ideas; the next batch is curated from there. ### App improvements (10/10) โ€” done - [x] 1. Voice commands ยท [x] 2. Tilt-to-drive ยท [x] 3. AI session summary ยท [x] 4. Time-lapse export ยท [x] 5. Drag-to-trace autopilot ยท [x] 6. AR webcam overlay ยท [x] 7. Robot personalities ยท [x] 8. Battery indicator ยท [x] 9. Telemetry export ยท [x] 10. 2-robot pairing ### Educational games (10/10) โ€” done - [x] 1. SLAM the Room ยท [x] 2. Echo Hunt ยท [x] 3. Maze Runner ยท [x] 4. Buzz the Tune ยท [x] 5. Simon Says NeoPixel ยท [x] 6. Math the Distance ยท [x] 7. Robot Soccer ยท [x] 8. Line Follower Race ยท [x] 9. PWM Lab ยท [x] 10. Morse Decoder ### Bonus shipped during Phase 1 - [x] **8 single-purpose Labs** (`labs/`): Joystick ยท Distance ยท Music ยท Servos ยท IR ยท Lights ยท Vision ยท Co-Pilot - [x] **Right-rail Message Log** in every Lab, faithful to the main app's `> #N VERB` / `< ECHO` format - [x] **Draggable cockpit FABs** (Connect / Labs / Stop) with localStorage position persistence - [x] **Workshops surface**: bilingual manual, booklet, cheat-cards, energizers, hub - [x] **Kid-attracting flyer + poster** (FR, 8 ans+) with comic bursts, real QR codes, mobile scale-to-fit - [x] **Brand sweep** `ROBI-9 LAB โ†’ MAQUEEN LAB` across HTML/CSS/JS - [x] **Auto-rendered HTML for every `.md`** (`docs/_md-render.js`) - [x] **Defensive theme sanitizer** in every lab + hub --- ## ๐ŸŽฏ Phase 2A โ€” Reach (turn product into adoption) The app is great; almost nobody knows it exists yet. | # | Item | Why now | |---|------|---------| | 1 | ~~**i18n parity for the main cockpit** (FR + AR)~~ โ€” **DONE.** `js/lang.js` (1932 LoC) + 304 `data-i18n` attrs + EN/FR/AR dicts (~600 lines each) + 3-flag picker + RTL + localStorage. All HTML surfaces are trilingual. | | 2 | **Etsy package v1 ready-to-list** | `etsy-package/` is half-baked. Finish: hero photos, listing copy locked, quickstart card. This is your distribution. | | 3 | **Teacher kit** โ€” 1-pager lesson plan + rubric per Lab | 8 labs ร— 1 lesson plan = 8 pages. Sells to schools instantly. | | 4 | **Print-quality flyer/poster export** (PDF) | Add a "Save as PDF" CTA + verified A4 print preview. Right now teachers have to know to Ctrl+P. | | 5 | **Curriculum-aligned challenge set** (Cycle 3/4 FR ยท K-8 EN) | Map existing Labs/games to formal learning objectives. Teachers need this verbatim. | ### Checklist - [x] 1. i18n parity โ€” main cockpit (FR + AR) โ€” already shipped via `js/lang.js` - [ ] 2. Etsy package v1 โ€” listing-ready - [x] 3. Teacher kit โ€” 8 lesson plans (one per Lab) at [docs/lessons/](lessons/index.html) โ€” A4 print-ready, mapped to FR Cycle 3/4 + NGSS + CCSS-M + CSTA, with ๐Ÿ’พ PDF button - [x] 4. PDF export from flyer/poster โ€” `๐Ÿ’พ PDF` button on both, with first-click i18n toast hint pointing to "Save as PDF" destination - [x] 5. Curriculum mapping (FR cycles + EN grades) โ€” [docs/curriculum.md](curriculum.html): 8 Labs + 10 games ร— FR Cycle 3/4 ยท NGSS ยท CCSS-M ยท CSTA, with by-grade quick-pick + year-long unit + 4h workshop --- ## ๐Ÿ›  Phase 2B โ€” Hardening (so things don't rot) | # | Item | Why now | |---|------|---------| | 6 | **Smoke tests** (Playwright headless) | 8 labs + main app = a lot of surface. One PR can break a Lab silently. ~200 LoC covers 80% of regressions. | | 7 | **Split `maqueen-tab.js` (4580 LoC)** | One file, one accident. Modularize by card (Drive, Servos, LEDs, etc.). Pre-condition for any further main-app work. | | 8 | **GitHub Actions CI** โ€” lint + tests + Pages deploy | Currently every push is hope. 30-line workflow file. | | 9 | **A11y pass** โ€” keyboard, focus rings, ARIA on FABs/labs | Disabled-kid accessibility is a real selling point and a real bug (FABs aren't keyboard-reachable). | | 10 | **Performance budget** โ€” measure first-paint + JS bundle on Labs | Labs feel snappy on desktop, sluggish on cheap Android tablets (school hardware). Budget: โ‰ค 1.5 s LCP on a ยฃ100 tablet. | ### Checklist - [ ] 6. Smoke tests for all 8 labs + main connect/disconnect path - [ ] 7. `js/maqueen-tab.js` โ†’ `js/maqueen/{drive,servos,leds,...}.js` - [x] 8. CI workflow โ€” `.github/workflows/ci.yml`: link audit (`tools/_audit-links.py --strict`) + inlined-md staleness check + JSON validity + secret-leak grep. Fails the push if any HTML href is broken or if a `.md` was edited without re-running `docs/_inline-md.mjs`. - [x] 9. A11y pass โ€” `js/a11y.js` (auto-injected on 53 pages): skip-link "Skip to main content", visible `:focus-visible` outline overriding legacy `outline:none`, auto-`aria-label` for icon-only buttons, `aria-hidden` on decorative emoji, `prefers-reduced-motion` honored, `lang` ensured. CI workflow extended with a11y sanity (`` + `` checks). - [ ] 10. Perf budget + Lighthouse CI --- ## ๐Ÿš€ Phase 2C โ€” Depth (deepen what already works) | # | Item | Why now | |---|------|---------| | 11 | **3 new labs from `wishlist.html`** (top-voted) | Channel new ideas through the wishlist you just built. Pick 3, ship a "Labs v2" milestone. | | 12 | **Multi-robot Lab** (WebRTC peer-to-peer) | Phase 1 #10 was checked but the demo isn't first-class. Two Maqueens dancing = viral. | | 13 | **Progress badges / kid passport** | Tracks which Labs they've completed. localStorage only โ€” no backend. Big motivator. | | 14 | **Add-on framework** (Gravity sensors + I2C accessories) | Verb namespace stubbed in firmware. Unblock "what else can I plug in?". | | 15 | **Phase 2 firmware** (`firmware/v2-raw-pins.ts`) | Same wire protocol, raw `pins.*` calls instead of `maqueen.*` lib โ€” for advanced learners. | ### Checklist - [ ] 11. Top 3 wishlist labs shipped - [ ] 12. Multi-robot dance demo (1st-class lab) - [ ] 13. Kid passport / badges - [ ] 14. Add-on framework + first I2C accessory - [ ] 15. v2-raw-pins firmware --- ## โšก Multipliers โ€” small effort, large leverage - [x] **One-click "Demo without robot"** โ€” `js/demo-mode.js` injects a fake BLE shim when `?#demo=1` or `localStorage.maqueen.demo='1'`. Replaces `connect/disconnect/sendLine/isConnected`, returns synthetic `ECHO:N ` and DIST/LINE/IR sensor values, shows a ๐ŸŽญ floating badge (click to exit). One-click "๐ŸŽญ Demo (no robot)" CTA on the Labs hub. - [x] **`/share` deep links** โ€” `js/share-link.js` encodes `theme ยท lang ยท demo` into the URL hash. Auto-applies on load (RTL flips for AR). Public API `MqShare.url() / .copy() / .addButton()` for any page that wants a "๐Ÿ”— Share view" button. - [x] **Local-only telemetry** โ€” `js/telemetry.js` auto-tracks visits per surface (`visit.lab.joystick`, `visit.lesson.distance`, `theme.paper`, `lang.fr`, etc.) into localStorage. **Zero network** โ€” no fetch, no beacon, no cookies. Viewer at [`docs/telemetry.html`](telemetry.html) shows heatmap, JSON export, opt-out, and reset. --- ## โš ๏ธ Anti-patterns to avoid - **No new feature before the `maqueen-tab.js` split** (Phase 2B #7). Every new card makes the 4580-line file worse. - **No new Lab without smoke tests** for it. Recurring bugs (joystick logger mount, co-pilot double-mount) prove this. - **Don't translate the main cockpit by hand** โ€” wire it to the same `T={en,fr,ar}` pattern as `workshops/manual` and let it scale. --- ## How to use this file - New ideas โ†’ go to [labs/wishlist.html](../labs/wishlist.html), not here. - Picking up an item โ†’ tick it (`- [x]`), commit with the item number in the message (e.g. `feat(2B-7): split maqueen-tab.js`). - A Phase 2 sub-section is "done" when its checklist is fully ticked โ€” bump the milestone (e.g. v0.2.0 = Phase 2A complete).