# Session reconstruction and workshop walkthrough — 15 October 2026

## Delivered behavior

- The teaching tool has optional **Local session recall / 本机会话回看** controls. Capture begins only after **Start local session / 开始本机会话**, autosaves meaningful view changes and playback/recording checkpoints every two seconds, and ends explicitly. Reopening never resumes capture.
- A snapshot stores selected take, playback offset/state, analysis status, language, speed, tonic override/automatic choice, zoom, classroom mode, selected phrase boundaries, notes and sampled pitch contour. New v2 sessions also pin the tool build and record bounded viewport size/pixel ratio, scroll coordinates and supported open panels; resize/scroll/toggle changes are debounced by 200 ms. Titles, lyrics and typed reflections are excluded. Sound-color analysis and continuous screen pixels are not reconstructed.
- The researcher workspace keeps the horizontal timeline above the vertical steps and central reconstruction. Steps, playhead, settings, bookmarks and timestamped notes share one session time. At 1×, recorded playing intervals restore audio offset and captured speed. Paused/hidden intervals remain silent; 4×/16× review is muted. “Listen from this step” is an explicit audition with the session clock paused.
- Missing audio does not prevent reconstruction. A metadata-only export deliberately omits audio; inclusion is unchecked by default. Nothing uploads from the local replay workspace.
- Researcher sign-in opens the data workspace; teacher sign-in opens workshop/tools and consent controls. Researcher teacher-preview is visibly marked and cannot submit teacher events. The server rejects researcher mutation requests, independent of hidden controls.

## Storage taxonomy

| Layer | Identifier / location | Write process | Recovery / sharing |
|---|---|---|---|
| Original take | Existing Singing Notebook IndexedDB | Original audio chunks and edits | Existing take export/import; unchanged by review |
| Captured session | `rgf-local-capture-v1`, `packages`, `local-<UUID>` | Explicit opt-in; serial atomic writes of immutable frames and settings revisions; copied local media asset per take | Last committed checkpoint after interruption; no automatic resume |
| Research review | `rgf-local-recall-v1`, `packages` + `review_positions` | Explicit Save review; annotations and reviewer position separate from captured history | Resume or deliberate portable export/import; source capture cannot overwrite notes |
| Synthetic demonstration | `rgf-synthetic-recall-v1` | Separate demo namespace, generated-fixture provenance | Excluded from participant analysis |
| Cloud usage | Existing protected teacher-pilot service | Finite metadata only after consent; researcher reads require server grant and current + original research consent | No audio, lyric text or local reconstruction snapshots sent |

New local package schema: `rgf-local-recall-v2`; legacy `rgf-local-recall-v1` remains readable without fabricated context. The existing database names stay unchanged so previous captures/reviews remain available. Local state renderer: `mirror-recall-v1`; pinned interface adapter: `performance-interface-recall-v1`; frame provenance: `captured_local`. Each frame links to an immutable settings revision, stable event ID and monotonic elapsed time. Reviewer annotations reference session time/event ID and never change source snapshots. Local packages remain excluded from participant analysis by default. Active status means “last saved checkpoint; may be interrupted or still open”, not proof of a completed session.

Limits: 30 minutes, 1,500 frames, 12 take descriptors, 24 MiB per audio blob, 48 MiB encoded audio total; import maximum 64 MiB. Browser quota failures leave an explicit export path. Refresh/termination can lose pending writes; no fabricated recovery of missing intervals. Imported audio codecs may be unsupported in another browser.

## Workshop rehearsal — English

1. Open the teaching tool without sign-in. Expand **Local session recall** and choose **Start local session**.
2. Choose **Try an example**. Play, pause, move to another position, change playback speed or tonic, select another take, and select a phrase.
3. Choose **End local session**, then **Review latest saved session**. The original recordings stay local.
4. Click a vertical step or scrub the horizontal timeline. Check the selected take and settings. Play the session at 1×; use **Listen from this step** to audition independently while discussing.
5. Choose **Note this moment**, enter a recall note, add a bookmark, then **Save review**. Clicking a note/bookmark returns to its original moment.
6. Export a session. Include audio only when intended. Open **Files & help → Open replay package** on the researcher machine; verify audio before relying on that copy.
7. Before the workshop, download the standalone offline viewer and export a synthetic session with audio. Open the downloaded HTML and import that JSON. No sign-in is needed for this fallback. The first visit to the hosted teaching tool still requires a network connection; there is no service-worker offline cache.

## 工作坊演练 — 简体中文

1. 无需登录，打开教学工具。展开“本机会话回看”，点击“开始本机会话”。
2. 点击“试一个示例”。播放、暂停、移动播放位置，调整速度或主音，切换录音并选择乐句。
3. 点击“结束本机会话”，再点击“回看最近保存的会话”。原录音仍留在本机。
4. 点击纵向步骤或拖动横向时间线，核对录音与设置。1倍回看会按已存状态同步原声；“从此步回听”会暂停会话时间，便于讨论。
5. 点击“记录此刻”，填写回忆笔记并添加书签，然后保存回看。点击笔记或书签可返回原来的时刻。
6. 主动导出会话；仅在需要时包含原录音。在研究者电脑中，通过“文件与帮助 → 打开回看数据包”导入。使用前请确认音频可以播放。
7. 工作坊前下载离线回看页面，并导出一个含音频的合成会话。打开本地HTML后导入JSON，即可不登录回看。首次访问在线教学工具仍需网络；本次没有增加离线缓存。

## Interface reconstruction and provenance

Performance Mirror is the first supported interface. The viewer embeds its pinned HTML/CSS without application scripts, restores saved state and draws only stored pitch values. Controls are disabled. No permissions, original app actions or network requests run inside the preview. The participant's recorded language and viewport remain separate from the researcher's language and Fit width / Whole view / Actual size controls.

The source identity is a content hash of the tool sources plus local capture code, generated by `build_tool_assets.py`. Tool identity, viewport, scroll and panel context contain bounded fields only: no URLs, HTML, selectors, account identifiers or private text. Unknown tool revisions produce an explicit unavailable-view message. Legacy local captures show a reference layout labeled approximate; original version/viewport/scroll are unknown. Old synthetic packages remain readable without an assertion that the original interface is available.

Scroll restoration is bounded by the available reconstructed document. A requested position outside that layout is reported, not silently described as exact. Saved text is excluded, so text-dependent page height and unsupported dynamic panels can still differ. Waveform, spectrogram, pointer/focus, private text and sound-color results are not recreated. This is state reconstruction, not screen video or pixel-identical replay.

## Evidence and limits

The recall test suite uses existing Node, jsdom, fake IndexedDB and synthetic media. It covers v1 compatibility, v2 capture through the opt-in UI, resize/scroll/panels, backward seeking, notes/bookmarks, storage recovery, missing audio, export/import and unsupported tool revisions. No microphone or camera access is enabled. Browser rehearsal uses only **Try an example** on local loopback.

Physical iPhone/tablet behavior, acoustic singing accuracy and perceived audio/visual timing still need a human workshop rehearsal. Public workshop URLs are unlisted, not access-controlled. Only application code, instructions and generated demonstration fixtures belong in publication; real session packages and notes are never committed or uploaded.

Build the pinned assets and portable reviewer with `python3 workbench/teacher-pilot/review/build_dashboard.py workbench/weekend/review-c3829dfe2aeda8a7/index.html`. Run `npm run test:recall` with the declared development dependencies available. This change does not require new runtime dependencies or cloud infrastructure.