') + ')', 'gi'); if (regex.test(text)) { found = true; var frag = document.createDocumentFragment(); var parts = text.split(regex); parts.forEach(function(part, i) { if (i % 2 === 0) { frag.appendChild(document.createTextNode(part)); } else { var span = document.createElement('span'); span.className = 'userscript-highlight'; span.textContent = part; frag.appendChild(span); } }); node.parentNode.replaceChild(frag, node); } }); } else if (node.nodeType === 1 && node.childNodes) { // element var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT']; if (!skipTags.includes(node.tagName)) { Array.from(node.childNodes).forEach(highlight); } } } highlight(document.body); // Re-highlight on dynamic content var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1 || node.nodeType === 3) highlight(node); }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Strip utm_, fbclid, gclid, etc. from all links on page (function() { var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid', 'ref', 'ref_src', 'source', 'medium', 'campaign']; function cleanUrl(url) { try { var u = new URL(url, window.location.origin); var changed = false; trackingParams.forEach(function(p) { if (u.searchParams.has(p)) { u.searchParams.delete(p); changed = true; } }); return changed ? u.toString() : url; } catch (e) { return url; } } function cleanLinks() { document.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } cleanLinks(); var observer = new MutationObserver(function(mutations) { mutations.forEach(function(m) { m.addedNodes.forEach(function(node) { if (node.nodeType === 1) { if (node.tagName === 'A') cleanLinks(); node.querySelectorAll('a[href]').forEach(function(a) { var clean = cleanUrl(a.href); if (clean !== a.href) a.href = clean; }); } }); }); }); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); } })(); (function(){ try { var __m = "youtube.com"; var __re = new RegExp('^' + "youtube\\.com" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Auto-enable theater mode on YouTube (function() { function tryTheater() { var btn = document.querySelector('button[aria-label="Theater mode"], ytd-player #player button[title="Theater mode"]'); if (btn && !btn.classList.contains('activated')) { btn.click(); } } // Try immediately tryTheater(); // Try after navigation (SPA) var lastUrl = location.href; setInterval(function() { if (location.href !== lastUrl) { lastUrl = location.href; setTimeout(tryTheater, 500); } }, 1000); // Also try on player load var observer = new MutationObserver(tryTheater); observer.observe(document.body, { childList: true, subtree: true }); })(); } } catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); } })(); (function(){ try { var __m = "*"; var __re = new RegExp('^' + ".*" + ', 'i'); if (__m === '*' || __re.test(location.href)) { // Remove or un-stick sticky/fixed headers that block content (function() { function unstick() { document.querySelectorAll('header, nav, [role="banner"], .header, .navbar, .sticky, .fixed-top, [style*="position: fixed"], [style*="position:sticky"]').forEach(function(el) { if (el.style.position === 'fixed' || el.style.position === 'sticky' || getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') { el.style.position = 'static'; el.style.top = 'auto'; el.style.zIndex = 'auto'; } }); } unstick(); var observer = new MutationObserver(unstick); observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] }); })(); } } catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); } })(); })(); Add multi-stage module support with progressive completion tracking by Prorickey · Pull Request #2 · Prorickey/CodeFTC · GitHub
Skip to content

Add multi-stage module support with progressive completion tracking - #2

Merged
Prorickey merged 6 commits into
mainfrom
claude/multi-stage-modules-gdC9r
Apr 20, 2026
Merged

Add multi-stage module support with progressive completion tracking#2
Prorickey merged 6 commits into
mainfrom
claude/multi-stage-modules-gdC9r

Conversation

@Prorickey

@ProrickeyProrickey commented Apr 19, 2026

Copy link
Copy Markdown
Owner

Summary

This PR introduces a new "multi-stage" module type that allows lessons to be structured as sequential stages with individual test validation and completion tracking, rather than separate lessons. Users progress through stages linearly, with code persistence per stage and the ability to view solutions.

Key Changes

  • New Multi-Stage Module Type: Added ModuleType enum ("lessons" | "multistage") to support two module structures

    • Modules can now be configured as "type": "multistage" in _module.json
    • Multi-stage modules contain stage folders with stage.json metadata instead of lesson folders
    • Validation ensures modules don't mix lesson and stage structures

  • MultiStageModulePage Component: New full-featured editor page for multi-stage modules

    • Resizable three-panel layout: lesson content, code editor, and test output
    • Per-stage code persistence (localStorage + debounced DB sync)
    • Stage navigation via stepper component with completion indicators
    • Solution viewing and code reset functionality
    • Deep-linking support via ?stage=N URL parameter

  • Stage Progression System:

    • Stages unlock sequentially after passing tests
    • Completion state tracked per stage with localStorage and database persistence
    • Test results cached per stage to show completion status in sidebar
    • Advance button disabled until all tests pass for current stage

  • Sidebar Enhancements:

    • Multi-stage modules display with Layers icon and expandable stage list
    • Per-stage progress indicators (completed/current/locked states)
    • Completion checkmark shown for fully-completed modules (logged-in users)
    • Test pass indicators loaded from localStorage on mount

  • ModuleStageStepper Component: Visual progress indicator showing all stages

    • Completed stages show checkmark, current stage highlighted, locked stages disabled
    • Clickable to jump to unlocked stages
    • Responsive layout with truncated stage titles

  • Analytics & Persistence:

    • New stage_complete event type for tracking stage progression
    • MultiStageProgressState schema (v2) stores: currentStage, perStageCode, completedStages
    • Validation function isMultiStageProgressState() ensures data integrity
    • Debounced DB sync (1.5s) for code changes to reduce API calls

  • Content Structure:

    • "Getting Started" module converted to multi-stage format
    • Each stage has: stage.json (metadata), content.mdx, Test.java, optional Starter.java/Solution.java
    • Module-level Starter.java and Solution.java serve as defaults

  • Route Handling:

    • /lessons/[moduleSlug] now routes to MultiStageModulePage for multi-stage modules
    • Lesson-type modules redirect to first lesson for backward compatibility
    • Proper 404 handling for missing modules

Notable Implementation Details

  • Code Initialization Priority: Per-stage starter code → module starter code → carried-forward code from previous stage
  • Hydration Strategy: localStorage loads first for instant UI, then DB state fetches and overrides if user is logged in
  • URL Sync: Stage parameter kept in sync with current stage (1-indexed for human readability)
  • Test Caching: Test results stored separately per stage to enable sidebar progress display without re-running
  • Solution Toggle: Overlays solution code over editor with visibility toggle, preserving editor state

https://claude.ai/code/session_01W5AZ6xRSdbJ7GzoHnUUAdZ

@claude
feat: add multi-stage module type with gated stepper progression
5891f58
Introduces "multistage" as a new ModuleType alongside "lessons". Multi-stage
modules present the module itself as a single ordered journey: stages are
gated by their tests, code carries forward between stages (with optional
per-stage Starter.java for resets), and progress persists as JSON in the
existing UserProgress.code column.
- lib/types.ts: ModuleType, Stage, MultiStageModuleData, MultiStageProgressState
- lib/lessons.ts: type-aware loader, getMultiStageModuleData, authoring validation
- app/lessons/[moduleSlug]/page.tsx + MultiStageModulePage client component
- app/lessons/[moduleSlug]/[lessonSlug] redirects multi-stage modules to /lessons/<slug>
- components/lesson/ModuleStageStepper
- Sidebar branches on module.type, rendering stage checklist for multi-stage
- /api/progress validates v2 JSON payloads, keeps legacy strings working
- /api/analytics/event accepts stage_complete (new enum value + migration)
- Converts 01-getting-started to multi-stage: module-level Starter/Solution,
per-stage Starter.java for independent OpModes, stage.json per stage
@vercel

vercelBot commented Apr 19, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

ProjectDeploymentActionsUpdated (UTC)
code-ftcErrorErrorApr 19, 2026 9:12pm

@Prorickey
fix(multistage): unlock first stage in sidebar and auto-scroll stepper
4d798c5
- Sidebar: unlock any stage at or before saved currentStage so stage 0
is reachable from an unvisited multi-stage module (previously all
stage links were disabled until the user was already inside).
- Stepper: replace wrapping pill row with a single horizontal track
that auto-centers the current stage with a slide animation on
advance; no manual scroll or jump interaction.
@Prorickey
fix(multistage): stable sidebar progression and URL-driven stage view
be7f8b2
- Unlock stages based on completions (maxCompleted+1) rather than the
transient currentStage, so navigating backward never re-locks a
stage you already advanced past.
- React to ?stage= changes after mount so sidebar links actually swap
the displayed stage instead of just updating the URL.
- Dispatch ftc-tests-updated when module state is persisted so the
sidebar reflects advancement immediately.
- Derive sidebar isCurrent from the URL on the active module to
avoid a styling flicker between navigation and localStorage write.
@Prorickey
chore: gitignore playwright test-results
8994948
@Prorickey
fix(getting-started): carry-forward code and register prior-stage dev…
b015f3e
…ices
- Prioritize carry-forward over per-stage Starter.java so each stage
builds on the learner's prior code by default.
- Register testMotor on the servo-control stage test and testServo on
the telemetry stage test so carried-forward code referencing earlier
devices executes instead of throwing before assertions.
@Prorickey
feat(sidebar): group modules into named sections
3085202
- Add content/lessons/_sections.json declaring 4 sections: The Basics,
Sensors & Feedback, Autonomy & Control, Advanced Systems.
- getModuleSections() loader resolves slugs in declared order, with an
auto 'Other' bucket for unlisted modules.
- Sidebar and ProgressPage iterate sections and render a small header
above each group; flatten modules internally so progress lookup
behavior is unchanged.
feat(state-machines): convert module to multi-stage
Two stages with carry-forward priority, module-level Starter/Solution.
chore: remove multithreading module and curriculum intro section
Also bypass generateMetadata for multistage modules to avoid ENOENT on
old lesson URLs, drop unused brace-expansion override, and clear a
stale eslint-disable.
@Prorickey
Prorickey merged commit 5ed0277 into mainApr 20, 2026
2 checks passed
@Prorickey
Prorickey deleted the claude/multi-stage-modules-gdC9r branch April 20, 2026 03:12
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Prorickey@claude