Study/PROGRESS.md

90 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Study Desk V2 — progress and resume notes
Updated 2026-11-11. Branch: **v2**. Original V1: **main**, preserved at `7bd0a9a`.
Work remains local; no push, repository creation or production deployment has been performed.
## Product and architecture
This is a rebuilt app using React + Vite + TypeScript, Hono/Node HTTP server, built-in
`node:sqlite`, SQLite FTS5, local document storage and a persistent document queue. One process,
one data volume, one administrator. Anonymous visitors get public read-only shares and
browser-local study progress. Administrator progress stays server-side.
The previous agent implemented the core product and committed it through `c549c34`:
classes/folders, CRUD/duplicate/move/search, quiz sessions/results/history, FSRS flashcards,
imports/exports/templates, documents/extraction/retrieval/OCR, provider adapters, editable
AI drafts, tool-based assistant actions, sharing, analytics and the responsive themed UI.
User feedback fixes are already included: larger clickable flashcards, arrow keys, streak
effects, persistent review sidebar, live quiz score, shared quiz timers, SATA credit details,
type-grouped materials, copyable import instructions and assistant library links.
## Current continuation
- Confirmed original 162 tests pass; sandbox networking initially blocked the mock provider.
- Added encryption-key corruption/missing-key refusal, static-path boundary validation,
private embedded-media authorization and share-revocation checks.
- Full backups include the generated encryption key and fail on unreadable files.
- Added backup restore, media authorization, key durability, V1 import and failed-migration
rollback tests. The new V1 test checks source bytes are unchanged and state is preserved.
- Added Dockerfile, Compose, .dockerignore, README and deployment/migration/AI documentation.
- Updated obsolete ChatGPT subscription wording after checking official documentation:
account integration exists for eligible clients, but hosted app approval for this private
Unraid web deployment has not been established. API integration remains the working path.
- Terra completed isolated UI/workflow and visual QA; see results below.
- Guarded quiz exit/submission when the latest save failed, and prevented repeated automatic
timer submissions after a failed request.
## Verification status
Baseline: 162 tests passed, TypeScript passed and production web/server builds passed.
Added five regression tests. Full `npm run check` passes: **167 tests**, TypeScript and both
production builds. Tests were run with loopback access for the mock provider.
The earlier agent manually exercised quiz completion/results, flashcards, streak effects,
mock AI generation through the assistant, editable drafts, and a 375px home page without
horizontal overflow. Treat these as historical evidence; record Terra's fresh results below.
Not verified: actual Docker image build/runtime, Unraid filesystem permissions and proxy,
paid provider inference, real ChatGPT OAuth/eligibility. Docker is not installed here. Do not
claim these have been tested. The installable app caches its shell, not private study data;
full offline administrator study is not implemented.
## Remaining work
1. Finish the brief post-fix Terra contrast recheck and public visitor UI check.
2. Record its results, review the diff and commit locally.
3. On Unraid later: execute the deployment/restore checklist in docs/DEPLOYMENT.md.
4. With owner-supplied provider connections: verify live discovery, streamed chat, generation,
OCR and task routing. No real-provider calls should be inferred from mock test results.
5. Future optional work: approved ChatGPT account OAuth, more robust offline studying and
semantic embeddings (current retrieval is lexical FTS5).
## Resume safely
1. `git status --short`, read this file and recent commits. Do not overwrite user changes.
2. The ignored `.env` currently selects `.data/`, containing dev/demo content that the user
has tried. Never print its secrets or reset/seed it casually. Use a new `.test-data/...`
directory and a separate port for destructive QA.
3. `npm.cmd run check` (tests require localhost networking for their mock AI server).
4. `npm.cmd run dev` for Vite + API, or `npm.cmd run build` then `npm.cmd start` for the built
app. See README and .env.example. All automated test databases are disposable copies.
5. Keep regular local commits on `v2`. Do not push until the owner explicitly changes the
original local-only instruction. Publishing later can use `git push -u origin v2` after
reviewing the diff and confirming credentials; no force push is needed.
## Fresh UI QA findings
Terra tested through Edge in an isolated volume on port 3731. Observed successful login,
class creation, quiz/question editing, practice start, save/exit, resume, answer check and
100% results; deck/card creation, browse flip, FSRS review, pasted question import; desktop
and emulated 400×933 mobile layouts in both themes. No obvious clipping or overlap observed
on those screens. The test server was stopped and the temporary password removed.
Visual finding: secondary labels appeared faint, particularly in dark mode. Adjusted the
shared `ink-3` colors. Computed WCAG contrast against paper/surface/sunken backgrounds:
light now **5.15 / 5.38 / 4.76** (previously 3.48 / 3.63 / 3.21); dark now
**7.42 / 6.86 / 7.71**. These ratios cover these token pairs, not a full accessibility audit.
Screenshots remain ignored under `.test-data/ui-terra/`: desktop-dark-quiz.png,
desktop-light-quiz.png, mobile-dark-quiz.png, mobile-light-quiz.png and mobile-light-session.png.
Post-fix visual and anonymous-share recheck pending.