5.6 KiB
Speaking Lab Home Page v1 Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Make / a dedicated material-browsing home page with search, categories, generated preview covers, and card navigation into the study page.
Architecture: Move the existing study page markup from index.html to study.html, then replace index.html with a home page powered by new home.js. Reuse /api/videos and the existing speaking-lab-state-v1 localStorage structure for login/admin state and progress summaries. Keep backend API unchanged except making / return the new home page.
Tech Stack: FastAPI static files, vanilla HTML/CSS/JS, localStorage, existing Node helper tests.
File Structure
- Create
F:\ooo\speaking-practice-local\study.html: current study page markup, loadingapp.js. - Replace
F:\ooo\speaking-practice-local\index.html: new home page markup, loadinghome.js. - Create
F:\ooo\speaking-practice-local\home.js: home page state, API load, search/category filtering, generated covers, login/admin UI, and card navigation. - Modify
F:\ooo\speaking-practice-local\app.js: read?video=<id>on study page load. - Modify
F:\ooo\speaking-practice-local\styles.css: add home page/card/cover styles. - Modify
F:\ooo\speaking-practice-local\backend\main.py: keep/returningindex.html.
Task 1: Split Home And Study Pages
Files:
-
Create:
F:\ooo\speaking-practice-local\study.html -
Modify:
F:\ooo\speaking-practice-local\index.html -
Step 1: Copy current study markup to
study.html
Copy the current contents of index.html exactly into study.html.
- Step 2: Replace
index.htmlwith home shell
Use a home page structure with:
<body class="home-page">
<header class="topbar home-topbar">...</header>
<main class="home-shell">
<section class="home-library">
<div id="homeCategoryFilters" class="home-categories"></div>
<div id="homeStatus" class="home-status"></div>
<div id="homeGrid" class="home-grid"></div>
</section>
</main>
<script src="./home.js"></script>
</body>
Include login/register fields equivalent to the study page and an admin link/button hidden by default.
- Step 3: Run syntax-neutral check
Run:
Select-String -Path index.html,study.html -Pattern "home.js|app.js|study-shell|home-grid"
Expected:
index.htmlreferenceshome.jsandhome-grid.study.htmlreferencesapp.jsandstudy-shell.
Task 2: Add Home Page Logic
Files:
-
Create:
F:\ooo\speaking-practice-local\home.js -
Step 1: Create home.js
Implement:
-
load local state from
speaking-lab-state-v1 -
login/register/logout matching existing local behavior
-
load
/api/videos -
search by title, speaker, description, tags
-
category filtering by tags
-
render generated cover cards
-
show subtitle languages
-
show progress summaries using local helper equivalents
-
click card ->
study.html?video=<id> -
Step 2: Run check
Run:
node --check home.js
Expected: exit code 0.
Task 3: Teach Study Page URL Selection
Files:
-
Modify:
F:\ooo\speaking-practice-local\app.js -
Step 1: Add requested video helper
Add:
function getRequestedVideoId() {
if (!IS_BROWSER) return null;
return new URLSearchParams(window.location.search).get("video");
}
- Step 2: Prefer requested video after API load
In initializeApp(), after loading videos and before fallback selection, use:
const requestedVideoId = getRequestedVideoId();
if (requestedVideoId && getVideo(requestedVideoId)) {
activeVideoId = requestedVideoId;
}
- Step 3: Run checks
Run:
node --check app.js
node tests\progress-helpers.test.mjs
Expected: both pass.
Task 4: Add Home Styles
Files:
-
Modify:
F:\ooo\speaking-practice-local\styles.css -
Step 1: Add home page CSS
Add styles for:
-
.home-page -
.home-topbar -
.home-shell -
.home-categories -
.home-grid -
.home-card -
.home-cover -
.home-card-meta -
.home-progress -
responsive mobile grid
-
Step 2: Run smoke checks
Run:
node --check home.js
node --check app.js
Expected: both pass.
Task 5: Verify Locally
Files:
-
No code unless verification reveals a defect.
-
Step 1: Static verification
Run:
python -m py_compile backend\main.py backend\db.py
node --check home.js
node --check app.js
node --check admin.js
node tests\progress-helpers.test.mjs
node tests\admin-file-input.test.mjs
Expected: all pass.
- Step 2: Browser verification
Open:
http://127.0.0.1:8000/
Expected:
- Home page appears.
- Search input is visible.
- Category chips render.
- Cards render with generated covers.
- Clicking a card opens
study.html?video=<id>.
Open:
http://127.0.0.1:8000/study.html
http://127.0.0.1:8000/admin.html
Expected both still work.
Self-Review
Spec coverage:
/opens home page: Tasks 1 and 5.- Current study page moves to
study.html: Task 1. - Search/categories/cards/generated covers: Tasks 2 and 4.
- Card navigation to
study.html?video=<id>: Tasks 2 and 3. - Admin entry for admin users: Task 2.
- No backend schema/API changes: plan keeps backend unchanged.
Placeholder scan:
- No unresolved placeholders.
Type consistency:
- Video IDs are strings in frontend navigation.
- Home state uses the same
speaking-lab-state-v1key as existing pages.