# Teacher annotation editor POC8 — implementation plan
Goal: make human verification a required, practical step between broad text-first
annotation proposals and generated teaching guidance. Preserve POC7 as a checkpoint.
## Design and scope
Use a script-first symbolic editor. Compared with a table editor, this keeps the
teacher looking at the words and hearing the corresponding fragment. Compared
with freehand drawing, typed marks preserve meaning for downstream generation.
The palette remains flexible through editable labels, spoken forms and notes.
The first POC imports both existing recordings and their proposals. No new paid
calls are needed to test editing. The canonical transcript and word alignment
remain fixed. Click selects a word; shift-click or drag selects a contiguous phrase
inside one thought. Selecting a mark opens its editable record. Teachers can add,
change, accept or reject marks, edit a single-word character target, adjust phrase
playback, and preview the accepted result. Local contextual suggestions are possible
patterns, never claims about what is heard. Automatic -ing ending suggestions are
excluded. Smooth pitch curves retain measured evidence; manual pitch has teacher
provenance and independent direction/intensity controls.
Maintain immutable original proposals beside working annotations. Any edit clears
approval and the affected thought's completed review. Pending/rejected/accepted
remain separate from the model's listening assessment. Require all marks decided,
all thoughts explicitly reviewed, and at least one accepted mark before exporting
the accepted-only handoff. This export is ready for guidance generation, not a
published final lesson. A later guidance/audio revision must reference its accepted
annotation revision and become stale on edits.
## Tasks and interfaces
- [x] Snapshot current POC6/7 and hub after tests and secret review.
- [x] Create editor-model.mjs and tests: importLesson(lesson), selectedWords(doc,
first,last), saveMark(doc,input), decideMark(doc,id,status), reviewGroup(doc,id),
updateGroup(doc,id,start,end), completion(doc), handoff(doc), restoreDraft(raw,
lesson), createHistory(doc), transact(history,doc), undo(history), redo(history).
Each document contains version=1, lessonId, revision, words, groups, annotations.
Each mark has id, wordIds, kind, label, title, level, spokenForm, detail, start,end,
reviewStatus, original, source, optional charStart/charEnd and pitch direction/
magnitudeSemitones. Edits are immutable and validate types/ranges/anchors.
- [x] Create suggestions.mjs and tests. suggest(doc,wordIds) returns title, reason,
kind, label, level, spokenForm and wordIds; local rules cover weak forms,
contractions, stop/release and flaps, contextual -ed and -s ending alternatives,
useful connections. Generic palette remains available; suggestions are optional.
- [x] Create script-renderer.mjs: renderScript(container,doc,selection,onSelect,
onMark,{preview,level}) and redraw with ResizeObserver. Use SVG geometric marks,
measured-label lanes and smooth pitch with arrows. No source document mutation.
- [x] Create app.mjs/index.html/styles.css: script with selected phrase, transport,
seven typed palette tools, editable inspector, phrase queue, undo/redo, browser
save, backup/import, accepted preview, completion and accepted JSON handoff.
Display storage failures. Import is validated, never silently discards edits.
- [x] Add POC8 to hub catalog/server whitelist and retain earlier links. Test new
route and existing hub expectations; restart only local hub server if necessary.
- [x] Verify model/suggestion tests with coverage, previous POC regression tests,
hub links, browser editing + saving + undo + phrase selection + preview, and
code review. Document actual limitations and remaining stages.
## Follow-on stages
1. Phrase segmentation editing, visual timeline, keyboard review shortcuts and
real teacher timing study. Target ten minutes; do not present it as measured.
2. Text generation controls (5–10 sentences default, topic/level/style) and existing
ElevenLabs recording/prediction pipeline integrated as a draft creation job.
3. Accepted-revision-only LLM teaching guidance per phrase, teacher review of that
guidance, then short generated recordings with tracked voice and prompt versions.
4. Final lesson publication gate: annotations accepted, guidance reviewed, audio
generated and verified. Shared drafts, attribution and multi-teacher conflict
handling require a server rather than browser-only persistence.
## Delivered checkpoint — 2026-09-15
The pre-editor POC7 snapshot is local commit `4a7d128`. POC8 is linked from the hub.
It reuses both existing recordings. No OpenAI or ElevenLabs calls were made for
this editor milestone.
Implemented: word, Shift-click phrase and native drag selection; seven symbolic
primitives; contextual suggestions; actual label, pronunciation, note and level
editing; clickable single-word letter targets; smooth manual pitch including
rise/fall and two-part contours; phrase playback adjustment; accept/reject/pending;
local draft persistence, validated import/backup, undo/redo and reversible reset;
accepted-only learner preview; and completion-gated accepted JSON export.
Export is `ready-for-guidance`. It includes only accepted working annotation fields
and separate trace references. Obsolete AI practice text is excluded; it remains
in the draft audit history. Every content change has a unique contentVersion, so
undo branches cannot reuse the same downstream guidance identity. An edit clears
approval and affected phrase review. Browser storage errors and cross-tab conflicts
are surfaced without overwriting a newer draft.
Verification: 24 editor tests, 13 hub JavaScript tests, and 22 Python hub/provider
checks passed (14 additional subtests). Model, suggestions and persistence modules
have 100% line coverage and 96.62% combined branch coverage; this coverage figure
excludes DOM rendering. Hub check: 426 links, no failures. Browser checks covered
symbol editing and saved reload, approval invalidation, undo/redo, Shift-click
phrase selection, manual pitch creation, letter targeting, recording playback,
validated draft import, the final phrase-confirmation gate, and 390px layout
without horizontal overflow. Test approvals were reset before handoff.
Known first-POC boundaries: transcript and thought segmentation are fixed; the break
symbol does not split alignment groups. Suggestions use local context rules and
still need a teacher's ear. Drafts are local to one browser; they are not shared
server records. Guidance generation, its own review, short explanation recordings,
and final publication remain the next milestones. Ten minutes is a target to test
with teachers, not a measured result of this POC.