📊 Project Report · Maqueen Lab

📊 What this page is

End-to-end status of the Maqueen Lab project — what's shipped, what's in flight, and what's still left. Auto-rendered from observed repo state, not from a wishlist.

v0.1.60 firmware/build version 53 HTML files 0 broken links 32/32 smoke tests passing 3 languages (EN · FR · AR) 5 themes 🌐 Live

📐 By the numbers ✅ Shipped 🟡 Partial 🔵 What's left 🔴 Manual / human-only 🏗️ Architecture map 🛠 CI & quality 🔇 Won't do

📐 By the numbers

Total HTML

across 5 surfaces

Labs

single-purpose, kid-friendly

Lessons

A4 print-ready, mapped

Workshops

manual · booklet · cards · …

Smoke tests

all passing in 1.3 min

i18n strings

~3 k

EN · FR · AR everywhere

Markdown docs

+ 6 translations

JS modules

4 new

telemetry · share · demo · a11y

✅ Shipped

Phase 1 — Original 20-item roadmap (v0.1.0 → v0.1.60)

Category	Done
10 app improvements	Voice commands · Tilt-to-drive · AI session summary · Time-lapse export · Drag-to-trace autopilot · AR webcam overlay · Robot personalities · Battery indicator · Telemetry export · 2-robot pairing
10 educational games	SLAM the Room · Echo Hunt · Maze Runner · Buzz the Tune · Simon Says NeoPixel · Math the Distance · Robot Soccer · Line Follower Race · PWM Lab · Morse Decoder

✓ 20 / 20

Phase 2A — Reach (turn product into adoption)

#	Item	What landed	Status
1	Main cockpit i18n (FR + AR)	`js/lang.js` 1932 LoC + 304 `data-i18n` + flag picker + RTL	DONE
2	Etsy package — slim & ready	Slimmed 86→10 files (260 KB). Build script tested, 1.02 MB ZIP	DONE
3	Teacher kit (8 lesson plans)	A4 print-ready, mapped to FR Cycle 3/4 + NGSS + CCSS-M + CSTA, 💾 PDF button	DONE
4	PDF export from flyer/poster	💾 PDF button on both, first-click i18n toast hint	DONE
5	Curriculum mapping	8 Labs + 10 games × FR Cycle 3/4 · NGSS · CCSS-M · CSTA	DONE

✓ 5 / 5

⚡ Multipliers — small effort, large leverage

Item	What it does	Status
🎭 Demo without robot	`js/demo-mode.js` — fake BLE shim activated by `?#demo=1` or localStorage flag. Replaces `connect/sendLine/isConnected`; emits synthetic `ECHO:N` + DIST/LINE/IR sensor values. Floating orange badge. Conversion lever: teachers/kids try every Lab without buying hardware.	DONE
🔗 /share deep links	`js/share-link.js` — encodes `theme · lang · demo` into URL hash. Auto-applies on load (RTL flips for AR). Public API `MqShare.url() / .copy() / .addButton()`.	DONE
📊 Local-only telemetry	`js/telemetry.js` + viewer — auto-tracks visits, themes, langs into localStorage. Zero network — no fetch, no beacon, no cookies. Heatmap with bar charts, JSON export, opt-out.	DONE

✓ 3 / 3

🛠 Phase 2B — Hardening (4 of 5)

#	Item	Status
2B-6	Smoke tests (Playwright) — 32 tests covering hubs · labs · lessons · demo-mode · telemetry · share-link · a11y · lang switcher · auto-render	DONE — 32/32
2B-7	Split `maqueen-tab.js` (4580 LoC)	PENDING
2B-8	GitHub Actions CI — link audit + inlined-md staleness + JSON validity + secret-leak guard + a11y sanity + smoke tests	DONE
2B-9	A11y pass — `js/a11y.js` on 53 pages: skip-link, focus-visible ring, auto-aria-label, aria-hidden on decorative emoji, prefers-reduced-motion, lang ensured	DONE
2B-10	Performance budget (Lighthouse CI)	PENDING

🌍 i18n parity (full coverage)

Surface	EN	FR	AR	Mechanism
Main app `index.html`	✓	✓	✓	`js/lang.js` + 304 `data-i18n`
Labs (10 files)	✓	✓	✓	Inline T table
Workshops (9 files)	✓	✓	✓	3-file pattern + inline T
Docs guides (5 × 3 files)	✓	✓	✓	3-file pattern
Auto-rendered (CHANGELOG · CUSTOMIZE · todo · README)	✓	✓	✓	`_md-render.js` lang-aware loader
Flyer + Poster	✓	✓	✓	Inline T table

Translation files for FR + AR: README.{fr,ar}.md, docs/{CHANGELOG,CUSTOMIZE,todo}.{fr,ar}.md — +1132 lines of new content. Every HTML auto-renders the right language.

🏗️ Bonus shipped during this session

8 single-purpose Labs (labs/) with right-rail Message Log faithful to main app's > #N VERB / < ECHO format
Cross-link labs ↔ lessons (📚 Lesson button on every lab)
Brand sweep: ROBI-9 LAB → MAQUEEN LAB across HTML/CSS/JS (90 occurrences); mascot Robi-9 → Maqueen (14 files)
Auto-rendered HTML for every .md via docs/_md-render.js + docs/_inline-md.mjs (works over file:// too — no CORS)
Pre-commit hook auto-runs inline-md when markdown changes; quiet on no-op
Defensive theme sanitizer in every lab
Mobile scale-to-fit for flyer + poster (A4 layout preserved on phones)
Slim Etsy package — 86 → 10 essential files (260 KB)
Real QR code on flyer + poster pointing to live app
Asset-ref checker (tools/_check-asset-refs.py) — caught 3 broken refs in distance-lab
Link audit (tools/_audit-links.py) — 53 HTML, 0 broken hrefs, 1 acceptable orphan

🟡 Partial / work-in-progress

Nothing currently mid-flight in the codebase. Last partial item (Etsy package) was either shipped (slim version) or punted to manual (the 3 launch-critical photo/video items).

🔵 What's left

Phase 2B — Hardening (2 of 5 remaining)

#	Item	Why now	Effort
2B-7	Split `js/maqueen-tab.js` (4580 LoC) into per-card modules	Pre-condition for any further main-app work. One file = one accident. Now safe with smoke tests green.	3-4 h
2B-10	Performance budget — Lighthouse CI + budget file	School hardware is slow. Catch perf regressions in CI. Budget: ≤ 1.5 s LCP on cheap Android tablet.	1 h

Phase 2C — Depth (5 of 5 remaining)

#	Item	Effort
11	Top 3 wishlist labs (curated from labs/wishlist.html votes)	varies
12	Multi-robot Lab (WebRTC peer-to-peer) — Phase 1 #10 was checked but no first-class lab	4-6 h
13	Progress badges / kid passport (localStorage-only, 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`) — same protocol, raw `pins.*` calls	6 h

🔴 Manual — only you can do

These are not codable. Either hardware/photo or external account access. Block the Etsy publish until done.

Item	Why
📷 Photograph a real micro:bit on a laptop running the app (Etsy hero image)	Single biggest Etsy thumbnail conversion factor for teacher-product listings.
🎬 Record a 60-second listing video using `seller-only/ETSY_LISTING.md` as the script	Etsy algorithmically prefers listings with video by ~30%.
🛒 Create LAUNCH10 promo code in Etsy Shop Manager	Drives first 10 reviews fast.

🏗️ Architecture map

5 surfaces, all reachable from the main index.html hub. Full link audit: 0 broken hrefs, 1 acceptable orphan (tools/tests.html).

maqueen-app/
├── index.html                 ← Main app (BLE cockpit + Playground tabs)
├── README.html                ← auto-rendered from README.md (+ FR/AR variants)
│
├── labs/                      ← Phase 1 bonus · 10 HTML files
│   ├── index.html               ← Labs hub (8 cards + wishlist)
│   ├── joystick · distance · music · servo · ir · lights · vision · copilot
│   └── wishlist.html            ← community vote
│
├── docs/                      ← Documentation surface
│   ├── index.html               ← Docs hub (10+ cards)
│   ├── guide · pinout · plan · schematics · schematics-kids  ← 5 guides × 3 langs
│   ├── lessons/                 ← Phase 2A-3 · 8 A4 lesson plans + index
│   ├── curriculum.html          ← Phase 2A-5 · standards mapping
│   ├── telemetry.html           ← Multiplier 1 · usage heatmap
│   ├── report.html              ← this page
│   ├── CHANGELOG · CUSTOMIZE · todo · next  ← auto-rendered .md
│   └── _md-render.js · _inline-md.mjs       ← shared renderer
│
├── workshops/                 ← Printables (FR/EN/AR)
│   ├── hub.html                 ← workshops hub (8 cards)
│   ├── manual.{html,fr,ar}      ← 12-mission classroom manual
│   ├── booklet · cheatcards · energizers
│   └── flyer.html · poster.html ← A4 print + 💾 PDF + QR + i18n
│
├── js/                        ← Behavior layer
│   ├── ble.js · ble-shim.js · ble-scheduler.js · core.js · maqueen-tab.js (4580 LoC) · …
│   ├── lang.js                  ← i18n machinery (1932 LoC, EN/FR/AR)
│   ├── a11y.js            ← skip-link · focus-ring · aria-label · prefers-reduced-motion
│   ├── telemetry.js       ← localStorage-only visit counters
│   ├── share-link.js      ← URL-hash state encoder
│   └── demo-mode.js       ← fake BLE shim (try without robot)
│
├── firmware/                  ← v1-maqueen-lib.ts (MakeCode, BLE UART)
├── etsy-package/              ← slim, 10 files, 260 KB
│
├── tests/smoke.spec.mjs       ← Phase 2B-6 · 32 Playwright tests
├── .github/workflows/ci.yml   ← Phase 2B-8 · link audit + tests + a11y + secrets
└── tools/
    ├── _audit-links.py          ← static link/orphan audit (used by CI)
    ├── _check-asset-refs.py     ← finds missing assets
    ├── inject-script.py         ← bulk-inject <script> into all HTML
    └── git-hooks/pre-commit     ← auto-runs inline-md when .md changes

🛠 CI & quality

Every push and PR to main runs two CI jobs. They block merge if anything regresses.

Job	Checks	Failure mode
audit	✅ Link audit (53 HTML · 0 broken hrefs · 1 allowed orphan) ✅ Inlined-md staleness — refuses commits that edited `.md` without re-running the inliner ✅ JSON validity — `product.json` + `build-info.json` ✅ Secret-leak grep — `API_KEY=` · `PRIVATE_KEY` · `TODO:.*SECRET` ✅ A11y sanity — every `<html>` has `lang`, every `<img>` has `alt`	Hard-fails on broken hrefs or stale inlined md
smoke	✅ Playwright headless (chromium) ✅ 32 tests covering hubs · labs · lessons · auto-render · demo-mode · telemetry · share-link · a11y · lang switcher · workshops hub flyer/poster ✅ Total runtime ~1.3 min in CI	Fails on any test failure; uploads Playwright report on failure

Local quality tools

npm test — run smoke tests
node docs/_inline-md.mjs — refresh inlined markdown blocks
python tools/_audit-links.py --strict — link audit (CI mode)
python tools/_check-asset-refs.py path/to/x.html — verify asset refs exist
node etsy-package/build-package.js — build the buyer ZIP

🔇 Explicitly 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
Virtual physics layer for demo-mode — current synthetic responses are enough; full physics would 5-10× the code
Modify js/ble.js — stable forked dependency from bit-playground; rule is to wrap, never patch

📈 Where we are now

Phase 1 (20 items) DONE · Phase 2A (5 items) DONE · Multipliers (3 items) DONE · Phase 2B (3 of 5) 3/5 · Phase 2C (0 of 5) 0/5 · Manual 3 items pending

Recommended next pick: 2B-7 (split maqueen-tab.js) — now safe to attempt with smoke tests green. Then 2B-10 (Lighthouse CI) — small, high-leverage.