Restore study gestures and shuffle progress; harden note autosave and record V1 comparison

This commit is contained in:
Elijah 2026-11-11 20:00:17 -07:00
parent 4bf121728b
commit d7e19db468
8 changed files with 236 additions and 37 deletions

View file

@ -89,8 +89,11 @@ to open a newer schema.
## Verification still required on Unraid
Docker is unavailable in the development VM. Before production use: build the image, confirm
Docker Desktop is now installed in the development VM. The image builds, and a disposable
container passed non-root startup, login, class/card/document persistence across restart,
full ZIP download, anonymous deck sharing and private API denial. These checks used a new
test volume, which was removed afterward. Unraid has not been tested. Before production use: confirm
health status and non-root volume permissions, complete setup over HTTPS, upload a PDF and
PPTX, restart and check persistence, test public links from a private browser, confirm proxy
streaming and upload limits, and perform the restore drill above. The Dockerfile and Compose
configuration are implemented, but container deployment has **not** been executed here.
configuration are implemented and verified locally; no production deployment has occurred.

93
docs/V2-COMPARISON.md Normal file
View file

@ -0,0 +1,93 @@
# V2 versus V1 and the rebuild brief
Source review on 2026-11-11, comparing `main` V1 at 7bd0a9a with local V2.
This distinguishes implementation from verification. Passing mocked AI tests does not
establish real-provider compatibility, and sampled desktop/mobile QA is not exhaustive.
## Original requirements
| Area | Current state |
| --- | --- |
| New architecture and UI | Rebuilt: React/Vite, Hono, built-in SQLite; distinct responsive light/dark design |
| Single administrator and public visitors | Implemented: secure local login, revocable links, isolated visitor progress |
| Classes and organization | Classes/folders, edit/move/search/delete, quiz/deck duplication; manual ordering and duplication are not equally exposed for every content type |
| Quizzes | MC/SATA, per-option explanations, question rationale, partial credit, practice/exam, shuffle, resume, missed review and history implemented |
| Flashcards | Decks, browse/self-assessment, persistent FSRS, reviews, undo and class/deck scoping implemented |
| Imports/templates/export | Preview/validation/editing, JSON/text bulk input, reusable templates and exports implemented |
| Documents | Required common formats, extraction/chunks/FTS search, optional provider OCR, private storage and AI generation implemented |
| AI providers and models | Five adapters, encrypted keys, discovery/manual models, routing/settings/usage; live provider verification remains |
| Integrated AI actions | Search/read content, weak-area generation, editable drafts, confirmed modifications implemented |
| ChatGPT account | No configured account OAuth. Hosted-client eligibility/approval remains unresolved; conventional API access is available |
| Docker/persistence/backups | Single-container image now builds and passes disposable runtime checks; Unraid proxy/volume validation remains |
| Accessibility and polish | Keyboard shortcuts, focus styles, reduced-motion rules, responsive layouts and state components exist; full keyboard/screen-reader audit remains |
The nursing-specific AI features are prompt-based tools using the same single/multi-choice
question engine. Dedicated interactive case-study/NGN question types and an adaptive NCLEX
exam engine are not implemented; the brief listed additional types as optional.
## V1 features that are not equivalent in V2
- **Named spaced-repetition sets:** V1 could collect selected decks into named sets with
independent schedules and new-card limits. V2 schedules each card once, with a global
daily new-card limit and deck/class/all review scopes. A practical simplification, but
it cannot reproduce separate course/exam review sets or independent per-set schedules.
- **Manual material order:** V1 supported drag/drop ordering of decks within material groups.
V2 class lists sort by recent update or title; the visible drag/drop is for file upload.
Some reorder APIs exist without matching UI. Quiz questions do have move-up/down controls.
- **Migration fidelity:** V2 imports source content, completed attempts and one selected
schedule per card. V1 interrupted StudyProgress sessions, named sets and their independent
schedules are not recreated. Historical reviewSnapshotJson is not consumed: imported
attempts reconstruct questions from current source content rather than preserving every
historical question version. Existing V1 share links are deliberately not reused.
These are not all mandatory requirements in the rebuild brief, but they matter when replacing
a V1 workflow. Extra visual effects should not obscure these functional tradeoffs.
## Issues found and addressed in this pass
- Card entrance utility overrode swipe-away CSS. Entrance and exit classes are now mutually
exclusive, restoring the intended grading transition.
- Added horizontal touch-to-grade after revealing a flashcard, while retaining vertical
scrolling. Browse uses learning/known; FSRS uses Again/Good. Desktop buttons/keys remain.
- Shuffle now rearranges only remaining cards, retaining completed cards and assessments.
Browser check confirmed the session stays at card 2/4 and 25% after shuffling.
- Review now remounts when its query scope changes, avoiding a stale deck queue when selecting
global Review from a scoped review screen.
- Note saves are serialized; navigation/read-mode waits for a successful save, and unsaved
changes trigger the browser's unload protection. Verified editing then immediately
navigating away and reopening retains the latest text.
## Rationale check requested by the owner
Created an isolated three-question quiz with a separate explanation on every option plus
each question's overall rationale. Through the actual internal browser, verified a correct
single-choice answer, an incorrect single-choice answer and partially correct SATA answer.
Practice reveals each option's explanation **under that option**, including unselected
distractors and missed correct options. The overall rationale follows that question's choices.
Results retain the same per-option/per-question grouping. Exam mode intentionally delays
feedback until submission. The stored option explanation field is `why`; a legacy import
with only a question-level rationale cannot invent separate option explanations.
Screenshot: ignored local `.test-data/rationale-check/correct-inline.png`.
## Remaining usability/feature priorities
1. Restore selected-deck named review collections if replacing that V1 workflow is important.
2. Expose consistent ordering and duplication controls across content types.
3. Make timed exams use an explicit wall-clock deadline. The current runner is an active-study
clock: it pauses when hidden, and server completion does not enforce a deadline.
4. Preserve shared quiz question snapshots if scores must remain stable across owner edits;
public saved sessions currently rebuild against the latest published quiz content.
5. Add better import reporting/preservation for V1 history and interrupted sessions.
6. Improve large scanned-document OCR: currently sent as one native vision/PDF request with
a 30 MB scanned-PDF limit and an output cap, rather than paginated OCR. Lexical retrieval
and sampled long-document generation are implemented; comprehensive textbook coverage
and semantic matching are not guaranteed.
7. Full offline private studying, rich-text WYSIWYG authoring, study-plan generation and
additional case/question types remain optional future enhancements.
No obvious missing basic flip/streak/quiz-answer feedback remains by source review. Visual
polish still needs targeted long-content/mobile/empty/error-state passes beyond the sampled
screens already checked. Prioritize those user-visible improvements over expanding a test
count for its own sake.