Study/PROGRESS.md
Elijah f0aabe4d5d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m2s
First revision: DeepSeek, numeric questions, background assistant, UI fixes
Providers and pricing
- Add a DeepSeek provider: thinking mode with low/high/max effort, reasoning_content
  replayed between tool steps, cache-hit usage, /models discovery and catalog prices.
- Fix "does not support tool calling": a rejected forced tool_choice (DeepSeek thinking
  mode) now asks for the call in the prompt; only a genuine no-tools 400 is "unsupported".
- Seven reasoning-effort levels (Off to Max) mapped per adapter.
- Cached-input price per model, cache-write and DeepSeek off-peak aware cost estimates.
- Built-in bge-small embedding model (transformers.js) as the semantic search default.

Quizzes
- Numeric (type-the-answer) questions: units ignored, optional ± tolerance; editor,
  runner, importer, templates and generation prompts.
- Quiz start screen instead of showing answers; navigator ring no longer clipped and
  key legend removed; clock only for timed exams; 7-point letter grades.

Assistant and generation
- Assistant turns run on the server independently of the browser, with re-attach and
  an explicit stop; drafts tray shows generations in progress.
- Per-chat model switcher, @-tagging of class materials, full-width assistant page and
  a smaller assistant button.
- Editable generation instructions and built-in presets, separate from the chatbot
  import instructions.

Other
- Dialog footer padding, keyboard hints removed, copy buttons work over plain HTTP,
  class and folder shares include documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 12:48:17 -07:00

11 KiB
Raw Blame History

Study Desk V2 — progress and resume notes

Updated 2026-11-12. Branch: v2. Original V1: main, preserved at 7bd0a9a. The owner authorized publishing progress and v2 now tracks Forgejo origin/v2. No 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, static-path traversal, 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.
  • Preserved the V1 card elapsed-days scheduling field during import.

2026-11-12 additions

  • .forgejo/workflows/build-v2.yml: pushes to v2 run typecheck + tests inside the Node 24 image (new Dockerfile test stage), build and smoke-test the production image, then publish study:v2 and study:v2-<sha>. Never :latest. Verified locally with Docker Desktop; the workflow itself has not run on the Forgejo runner yet (nothing pushed).
  • Drag-to-reorder (web/src/ui/Sortable.tsx, pointer events so touch works, keyboard with arrows/Home/End and live announcements) for class materials, folders, questions and cards. New endpoint POST /api/classes/:id/items/reorder.
  • Timed exams use a wall-clock deadlineAt stored in attempt settings. The server refuses late answers (409 time_up), submits overdue exams lazily and before every authenticated GET, and caps time used at the limit. Shared exams use a local wall-clock deadline too.
  • Shared quiz sessions freeze their questions (with option order) in browser storage, with a fingerprint to tell the visitor when the owner has since edited the quiz.
  • Scanned PDFs are read in 8-page batches split with pdf-lib, cached per batch, with real page numbers. OpenAI-compatible adapter now sends PDFs as Chat Completions file parts when the model is marked as PDF-capable.
  • Semantic search: migration 2_embeddings (chunk_vectors), embedding support in the OpenAI/Gemini/Ollama/compatible adapters, server/services/semantic.ts (background indexing, in-memory cosine search, reciprocal-rank fusion with FTS), Settings → AI section.
  • Browser QA on an isolated .test-data/qa instance (port 3742, study-qa launch config): drag and keyboard reorder persisted; 375px class page has no overflow; semantic search enabled from Settings and indexed; a 1-minute exam counted down on the wall clock and auto-submitted at 60 s; a shared session kept original questions after the owner edited them.

2026-11-15: first revision (owner's 21-item list)

Implemented and verified on an isolated instance (.test-data/rev1, port 3743): DeepSeek provider (server/ai/providers/deepseek.ts); 7 reasoning-effort levels mapped per adapter; the "does not support tool calling" errors were DeepSeek rejecting forced tool choice in thinking mode: compatible servers now get the call requested in the prompt, and only a genuine "no tools" 400 reports unsupported. Cached-input prices (migration 3) and cache-write /off-peak aware costs. Built-in embeddings (server/ai/localEmbed.ts, bge-small, default when nothing is chosen). Assistant turns run server-side independent of the browser (re-attach via GET /api/ai/chat/:id/stream, stop via POST /api/ai/chat/:id/stop); drafts tray in the sidebar/Today. Quiz start screen, navigator ring/legend fix, timer only for timed exams, 7-point letter grades, numeric questions (migration 3 rebuilds questions for the new type; answers are compared numerically, units ignored, optional ± tolerance). Dialog footer padding (safe-pb-3), keyboard hints removed, small assistant button, full-width assistant page, model switcher and @-tagging. Editable generator instructions and built-in presets (builtin = 2 marks an edited built-in), separate chatbot import instructions. Copy buttons work over plain HTTP inside dialogs. Class/folder shares include processed documents.

Live DeepSeek (deepseek-flash only) checks passed: discovery, quiz generation at default and Max effort (numeric items produced, answer keys correct with thinking on), multi-step tool turns, follow-up turns, tagged quiz to flashcards, an answer finishing after disconnect; zero errors in Usage. Docker image builds; ONNX Runtime and the embedding model run in the container. The image grew to about 1.3 GB because of ONNX Runtime.

Verification status

Baseline: 162 tests passed, TypeScript passed and production web/server builds passed. Added six regression tests. Full npm run check passes: 208 tests (2026-11-15; 181 on 2026-11-12), TypeScript and both production builds. The Docker test stage runs the same 181 tests on Node 24. 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.

Docker Desktop is now installed. Image build and a disposable non-root container passed login, document/card persistence across restart, full-backup ZIP, anonymous sharing and private API denial. Still unverified: Unraid filesystem permissions/proxy, paid-provider inference and real ChatGPT OAuth/eligibility. The installable app caches its shell, not private study data; full offline administrator study is not implemented.

Remaining work

  1. On Unraid later: execute the deployment/restore checklist in docs/DEPLOYMENT.md.
  2. 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.
  3. Future optional work: approved ChatGPT account OAuth, more robust offline studying and (semantic embeddings were added on 2026-11-12, the built-in model on 2026-11-15).

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 focused commits on v2. The owner has now authorized pushing progress to this branch; Git Credential Manager works. Never force push or publish/deploy to production implicitly.

V1 comparison and follow-up usability work

See docs/V2-COMPARISON.md for the requirement matrix, V1 differences and remaining priorities. Fixed the flashcard entrance/exit CSS conflict; restored touch grading and shuffle-remaining; reset review queues on scope changes; serialized note autosaves, protected navigation with unsaved edits and added an explicit retry action. Verified a note survives immediate navigation and reload, and shuffling keeps browse progress at 2/4 rather than restarting.

The owner's rationale check passed using a synthetic three-question quiz with per-option explanations: correct, incorrect and partial SATA feedback all show explanations inline under their options. Results group explanations with each question. Screenshot is ignored at .test-data/rationale-check/correct-inline.png. The temporary test server is stopped after QA.

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 Terra recheck: desktop light/dark screenshots show improved secondary-text legibility (postfix-dark-desktop.png, postfix-light-desktop.png). An Edge InPrivate visitor opened the isolated shared quiz without login, completed practice, saw its rationale and reached 100% results. Shared-deck UI, long-label layout stress tests and post-fix mobile contrast were not revisited in this follow-up. Public deck data isolation/revocation is covered by API tests. No known functional failures were found in the UI paths exercised. This is sampled QA, not an exhaustive audit of every layout and browser. Terra's isolated server is stopped.