Files
speaking-practice/docs/superpowers/plans/2026-06-02-speaking-lab-home-page.md
T
2026-06-03 00:34:42 +08:00

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, loading app.js.
  • Replace F:\ooo\speaking-practice-local\index.html: new home page markup, loading home.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 / returning index.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.html with 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.html references home.js and home-grid.
  • study.html references app.js and study-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-v1 key as existing pages.