Lands epic #1007 part 2(c): the app-side reference converter, the `audioUrl`
removal, and the `DSL_VERSION` bump as one delivery unit.
`convertDocumentAssetRefs` walks a loaded document (slide canvases, whiteboards,
video-manifest keys, speech actions) and rewrites legacy handles to allocated
pool ids: placeholders and `audioId`s with local bytes are ingested, a co-present
`audioUrl`/`audioId` pair collapses to one asset, a definitively dead URL
converts to an emptied reference, and a transient failure keeps both handles for
a later retry. Unavailable bytes leave the document untouched for a later open,
and a converted document returns by identity with no writes.
Conversion runs lazily on document open and at fetch time for server-generated
classrooms, with conversion and the first document save sharing the per-stage
document lock: once the document commits it owns every allocation, and every
failure exit rolls its pass ledger back. Legacy URL probes are bounded by a
per-probe timeout and a shared 60-second pass budget.
`SpeechAction.audioUrl` is removed from the DSL and every consumer reads the
converted shape; the server classroom generator keeps its derived-id + serving-URL
pair as an explicitly typed pre-conversion transport, consumed before persistence.
`DSL_VERSION` becomes 0.2.0 with the first real ladder entry, and
`@openmaic/dsl` goes to 0.9.0 per the release rule.
Deferred follow-ups are tracked in #1129: production principal derivation with
document/asset ownership aligned, conditional document writes, and hoisting the
aggregate probe budget into the export and video-timeline paths.
Refs #1007
* feat(courses): add folder grouping behind a feature flag
Group courses into user-created folders on the home page. Folders are
device-local organization metadata kept in the existing IndexedDB
database (new folders + course-to-folder mapping tables, Dexie v16);
the course document aggregate owned by the DocumentStore is untouched.
- Create / rename (inline) / delete folders (keep or remove members)
- Move a course between folders via a hover menu
- Navigate into a folder with a breadcrumb back to all courses
- Search flattens the list, annotating each course with its folder
- Deleting a course cleans up its folder membership
- All UI strings internationalized across 9 locales
- Gated behind NEXT_PUBLIC_ENABLE_COURSE_FOLDERS (default OFF)
* test(courses): update db mocks and version assertion for folder tables
The folder feature adds the `stageFolders` table to the deletion cascade
and bumps the Dexie schema to v16. Update the affected test db mocks to
include the new table and bump the version assertion accordingly.
* fix(courses): stop course click-through when selecting from the move menu
The move-to-folder menu is rendered inside the course card's clickable
container. Selecting a folder item could let the click event reach the
card's onClick (opening the course) because only the trigger button
stopped propagation. Stop propagation on pointerdown for the trigger
and on click for every menu item so selecting a destination never opens
the course.
* fix(courses): open a dialog for the move-menu new-folder entry
The move-to-folder menu's inline "new folder" input never worked: a Radix
DropdownMenu is modal, so a raw <input> inside it cannot keep focus —
Radix closes the menu the instant the input is focused, dropping the
field before anything can be typed. Move the new-folder entry out of the
menu: it now asks the caller to open the existing NewFolderDialog and,
on confirm, moves the requesting course into the freshly created folder.
* feat(courses): drag-to-file folders and stacked cover thumbnails
Per review feedback, make folders feel complete:
- Drag a course card onto a folder tile to file it there. The tile turns
into a clear drop target (ring + overlay) while a drag is over it. The
hover 📂 menu remains as the accessible fallback for keyboard/touch.
- Replace the placeholder folder icon with a stable stack of up to three
member course covers (most recently updated frontmost). Empty folders
keep the folder icon; the name and course count are always visible.
* feat(courses): refine folder cover stack to a tidy fanned layout
Tune the folder-tile cover stack per review: front cover centered and
upright, rear covers peek out from alternating sides with a slight tilt
and reduced opacity, soft shadow and hairline ring. Reads as a neat pile
of course covers rather than an exaggerated fan.
* fix(courses): address review — dialog mount, empty-list, rename validation, partial-delete refresh, breadcrumb dedup
Per review (wyuc, CHANGES_REQUESTED):
1. Mount NewFolderDialog/DeleteFolderDialog outside the collapsible Recent
subtree so they are reachable while it is collapsed; the New-folder
button now expands the section before opening the dialog.
2. Keep the Recent/folder surface alive when the course list is empty so
folders remain reachable and a first folder can be created.
3. Enforce folder-name validation (width + uniqueness) on rename as well
as create, at the storage boundary (FolderNameError) and in the UI.
4. Refresh authoritative state on folder-delete both success and failure,
so a partial "remove" failure does not leave stale cards/counts.
5. Drop the duplicated folder breadcrumb from the top section header;
keep a single navigation breadcrumb in the content area.
Add focused storage tests covering rename validation, membership writes,
both deletion modes, and partial-failure propagation.
* fix(courses): address 2nd review — folder-view layout, drop highlight, validation parity, a11y, i18n
Per review (wyuc, CHANGES_REQUESTED on 9f77686f):
P1 — folder view layout: opening a folder compacts the hero and surfaces
the library content; the centered header shows a single path
"Recent > Folder name"; the empty-folder state sits directly below it;
clicking Recent returns to the root grid. The duplicate content
breadcrumb is dropped (kept only for search).
P2 — correctness & a11y:
- Clear the folder drop highlight on every drag exit (dragenter counter)
and gate it on the text/stage-id payload.
- Duplicate-name check in the dialog is now case-insensitive, matching
the storage boundary; FolderNameError is mapped to specific messages.
- Renames report the actual submitted width, not a hardcoded 0.
- createFolder/renameFolder run read-check-write in one read-write
transaction so the uniqueness invariant cannot race across tabs.
- The move-menu trigger is focus-visible and pointer-coarse reachable
(visible on touch / keyboard), not hover-only.
Extra:
- Empty library (no courses, no folders) shows a dedicated hint instead
of the search-empty string.
- Translate all newly added folder strings across ja/ko/pt/ru/ar, fix
Simplified-Chinese text in zh-TW, and add the emptyLibraryHint key.
* fix(courses): address 3rd review — ungate folders, fix empty-library hero, stabilize the bar
Per review (wyuc, CHANGES_REQUESTED on 19729038):
P1 — ship folders unconditionally: remove NEXT_PUBLIC_ENABLE_COURSE_FOLDERS,
the isCourseFoldersEnabled helper, the .env.example entry, and every
flag-on/flag-off UI branch. Folder metadata is always loaded; create,
move, drag, and folder navigation are always available. The IndexedDB
v16 schema stays intact.
P1 — full-screen landing hero only when the library is truly empty: the
hero uses min-h-[calc(100dvh-8rem)] only when there are zero courses AND
zero folders. A `hydrated` flag waits for both async loads before
selecting the layout, so folders arriving from storage do not flip the
hero from full-screen to compact.
P2 — geometrically stable centered bar: the Recent bar gets a fixed
height (h-9) so entering/leaving a folder (which toggles the New-folder
action and the folder path) does not shift the search/import controls.
* fix(courses): single stable library action bar across root, folder, and empty states
Per review (wyuc, CHANGES_REQUESTED on 860a1170):
P2 — remove the duplicate floating import controls. The hero section
rendered a second Import Classroom / PPTX cluster whenever the course
list was empty, duplicating the Recent bar's actions and floating above
it as the hero switched layout modes. Import now lives only in the
Recent action bar.
P1 — keep folder creation reachable for a truly empty library. The
Recent section is now always rendered after hydration (not gated on
having courses or folders), so a new user with zero of each can still
create the first folder or import. The empty-library hint renders below
the single stable action bar.
Invariant: one library action bar across root, folder, and empty
states; state changes alter the path and enabled actions only.
* chore: trigger CI after ready-for-review
* fix(courses): inherit folder context when importing from inside a folder
Per review (wyuc, CHANGES_REQUESTED on 37be4716):
[P1] Courses imported from inside a folder were silently placed at the
root. The import contract now carries the new stageId to the success
callback; the page captures the active folder when the file picker opens
(not when the async import resolves) and files the imported course into
that folder before the list refresh, so the card appears immediately and
the folder count increments. Root imports remain ungrouped. A failed
folder assignment surfaces an explicit error toast instead of silently
falling back.
* fix(courses): stable hero on folder delete, lightweight delete menu, breadcrumb count, empty-name validation
Per review (wyuc, CHANGES_REQUESTED on 5e12984f) + QA findings:
P1 — deleting the last folder must not expand the hero. The full-screen
landing hero is a first-visit treatment only: a session-scoped
"librarySeen" flag latches true once the library bar renders, so the
hero stays compact across all subsequent create/delete transitions.
P2 — replace the heavy two-card delete dialog with progressive disclosure.
Empty folder: an inline confirmation overlay on the card tile (matching
the course-delete pattern), with the empty-folder copy. Non-empty
folder: a compact dropdown beside the delete icon — "Delete folder only"
(courses move to unfiled) executes directly; "Delete folder and N
courses" opens a lightweight destructive confirmation. The full modal is
gone.
QA fixes:
- Breadcrumb count is now contextual (total at root, in-folder count
inside a folder) instead of always showing the global total.
- Renaming a folder to empty/whitespace shows a "name cannot be empty"
error and shakes, instead of silently exiting edit mode.
* fix(courses): cross-review cleanup — dead i18n keys, missing translations, delete-overlay reset
Post-commit cross-review (leak audit PASS, wyuc 19/19 PASS) found:
- Remove 6 dead i18n keys left over from the removed two-card delete
dialog (deleteFolderDesc, deleteFolderUngroupTitle, etc.) across all
9 locales.
- Translate all remaining English folder strings in ja/ko/pt/ru/ar
(newFolderTitle, folderNameLabel, folderCreate, deleteFolderTitle,
etc.).
- Fix zh-TW: convert ~17 simplified-Chinese folder strings to
Traditional (新增資料夾/建立/刪除/etc.).
- Delete the orphaned "feature flag" comment (flag was removed earlier).
- Close the inline delete-confirm overlay before the async delete, so a
failure leaves the card interactive instead of stuck behind the
backdrop.
* fix(courses): clear drop highlight on drag end, map limit error in dialog
Two minor findings from cross-review:
- Escape-cancelled drags may not fire dragleave on every folder target,
leaving a highlight ring. The course card now dispatches a
'course-drag-end' window event on dragEnd (fires for both normal drop
and Escape cancel); folder cards listen and clear their drop state.
- FolderNameError kind 'limit' (thrown at the storage boundary when
FOLDER_COUNT_LIMIT is reached in a cross-tab race) now maps to the
specific folderCountLimit message in the dialog instead of falling
through to a generic hint.
Also fixes an SSR hydration mismatch: librarySeen is now initialized
to false and read from sessionStorage in useEffect (not in the
useState initializer).
* fix(courses): atomic folder removal, always-compact hero, no-cover placeholder
Per review (wyuc, CHANGES_REQUESTED on 470f5fea):
P2 — close the orphan-membership race in 'remove' mode. deleteFolder now
captures members, deletes the folder row, and clears all memberships in
ONE transaction BEFORE the course-deletion cascade. The folder is gone
from the moment the cascade starts, so a concurrent setStageFolder
(which checks existence in its own transaction) rejects the assignment.
P2 — remove the first-visit full-screen hero. The librarySeen flag
caused a visible layout jump on refresh (SSR renders full-screen, then
the effect reads sessionStorage and switches to compact). The hero is
now always compact (mt-[10vh]); no sessionStorage, no hydration
mismatch, no geometry regression.
P3 — distinct no-cover fallback for non-empty folders. A folder with
courses but no cached thumbnails now shows a neutral stacked-card
placeholder instead of the empty-folder icon.
Merged with latest main; no conflicts.
---------
Co-authored-by: Percy <percy@PercydeMacBook-Pro.local>
* feat(media): establish shared asset ownership primitives
Introduce global browser asset-pool ownership, asset-reference collection, stage reclamation planning, and lease-based URL access. Carry allocated media identity through storage and generation boundaries with regression coverage.
* fix(media): enforce safe resolution across every consumer
Route image, video, thumbnail, presentation, and video-export consumers through one resolution state machine. Prevent opaque allocated or generated references from reaching render and export sinks, with fallback and ownership tests.
* fix(media): protect document-owned assets across mutations
Allocate pool bytes before compatibility writes and document commits, then roll back uncommitted generations safely. Preserve document ownership across edits, retries, imports, speech generation, scene changes, and stage deletion.
* fix(media): scope retries and tighten ownership guard
Scope retries to the target scene and slide and refuse ambiguous shared-reference mutations. Expand retry rendering coverage and keep direct pool URL resolution behind the shared lease owner.
* fix(storage): avoid nested lock during stage cleanup
Execute prepared reclamation plans against an explicitly deleted document so the compatibility cascade cannot re-enter the per-document lock. Cover deletion of stage-owned media rows even when the document has no references.
* refactor(media): confine reclamation to stage deletion
Remove inline pool and compatibility-row cleanup from element, speech, scene, and audio replacement flows. Keep whole-stage reclamation behind explicit stage ownership, preserve stage-less legacy audio rows, and document deferred document-truth sweeping.
* fix(media): close retry and resolution gaps
Restore shared source tasks after successful forks, scope retries across both whiteboard locations, and wait for parallel TTS workers before rollback. Resolve background media through import, rendering, and PPTX export paths while keeping retry controls visible over last-good bytes.
* test(media): execute the consumer safety matrix
Replace source-substring checks with resolver seam execution across all six UI consumers, stage hydration, and both exporters. Pin each rollback layer independently and harden the ownership guard against aliased pool imports.
* chore(packages): publish the additive DSL field
Bump the DSL patch version for the optional speech-action field. Keep the transitional reclamation policy app-owned and document the legitimate transaction rollback removals there.
* fix(media): make retry rollback task-safe
Delay allocation task re-keying until final document reconciliation succeeds, restore shared source tasks on failed forks, and require exact stage-whiteboard targets before falling through from a missed scene.
* fix(media): clear private assets and refresh leases
Delete the asset-pool database during the confirmed local-data wipe. Notify the app lease layer after same-id replacement so mounted consumers re-resolve current bytes without reaching into storage internals.
* test(media): pin closure safety guards
Exercise the CSS allocation boundary, unfiltered legacy-row ownership, delete-and-undo byte survival, and real distinct consumer seams. Restore the video-only manifest overwrite condition and share the direct video resolution hook across both element variants.
* test(media): narrow rollback element assertion
Narrow the reconciled slide element to an image before checking its source so the rollback regression remains type-safe under the full root compiler configuration.
* fix(media): close lease refresh races
Gate the first batch publication by unique resolved refs, then publish every replacement snapshot without mutating the prior React state object. Serialize invalidation behind pending releases, evict rejected refreshes, and register replacement observation at the pool boundary.
* fix(media): reopen pool after clear failures
Always evict the singleton once its store has been closed, including blocked and failed database deletion paths. Report blocked deletion as deferred and prove a later write uses a fresh live store.
* fix(media): isolate shared retry progress
Track forked regeneration under the selected element until it receives a fresh asset identity, leaving the shared source task and bytes untouched. Surface targeted failures through renderer task lookup and skip the redundant fork reconciliation lock.
* fix(media): close final asset retry gaps
Keep blocked asset clears fail-loud until a successful retry, with actionable settings guidance.
Clear failed shared-fork state across durable and live key spaces, and pin renderer lookups, lease publication identity, and committed-ref rollback protection.
* fix: preserve actionable retry failures
Localize the blocked cache-clear recovery hint across every supported locale and pin the deferred-error mapping.
Retain durable fork failure rows while retries run, deleting them only after successful generation so unstructured failures survive reload.
* fix(media): hydrate legacy stored video thumbnails
Home-page recent-video thumbnails regressed for legacy Dexie mediaFiles
rows keyed by gen_vid placeholders: the reworked hydration resolved the
row's bytes through the sealed resolver but never surfaced the stored
blob (and its poster) as object URLs for the preview card, so the CI
recent-video-thumbnail e2e specs found no visible element.
Hydration now materializes legacy stored video rows into blob URLs for
both the element src and poster while keeping the resolver invariants:
opaque refs still never reach a DOM src, and concrete addresses are
never blanked. Unit pins cover the seam so the vitest suite catches this
class without a browser.
* fix(media): resolve sole restored legacy video
Classroom playback restored tasks by exact document media references. Legacy gen_vid references can outlive the key used by the one persisted video row, leaving the player on a placeholder even though bytes were restored.
Select the sole completed stage video only for legacy sequential refs after exact and reconciled matches. Keep exact failures authoritative, refuse ambiguous candidates, and cover success, ambiguity, and failure precedence in unit tests.
* fix(media): scope legacy video recovery
Decide restored legacy video recovery once from the complete document and record it through the shared task lookup consumed by playback, editing, and resolved slides.
Keep ambiguous documents as placeholders, apply the same decision to thumbnail hydration, and preserve exact failure precedence.
* fix(media): exclude claimed video recovery tasks
Model restored legacy recovery as a two-pass match across document video elements and task rows. Remove tasks claimed by exact, targeted, or placeholder lookup before applying the sole-candidate fallback, and cover the ownership/cardinality matrix.
* fix(media): unify video element resolution
Centralize source, task, poster, and legacy recovery decisions for every video consumer. Ensure direct URLs win over opaque refs and play_video waits on element-targeted retry tasks.
* refactor(media): route legacy recovery through resolver
Let document-aware consumers request legacy video recovery through the unified element binding API, keeping thumbnail hydration on a single decision path.
* fix(media): preserve import refs and prefer pool bytes
Recognize unambiguous extensionless relative media addresses during classroom import. Resolve allocated export and thumbnail assets from the shared pool before falling back to lagging compatibility rows.
* fix(export): preserve concrete video sources
Route PPTX video elements through the shared media binding resolver so an unresolved opaque reference cannot replace a playable source. Complete browser and persisted-store cleanup when asset-pool deletion is deferred, while retaining distinct hard-failure behavior.
* fix(media): fork retries without exclusive ownership
Enumerate logical asset owners across every persisted document before allowing global pool replacement. Thread explicit targets through fresh-id rewrites and cover cross-document aliases plus unreadable ownership.
* fix(media): guard global asset reclamation
Share a fail-closed persisted-document liveness check between stage deletion and retry replacement. Preserve cross-document pool aliases while deleting stage-owned compatibility rows and cover enumeration failures.
* fix(media): cover complete slide asset references
Route slide media traversal through a shared mutable slot contract so backgrounds participate in export, thumbnail hydration, collection, and rewrite lifecycles. Snapshot complete surviving-document refs once per reclamation and preserve manifest-only owners while retaining fail-closed behavior.
* fix(media): preserve exclusive retry asset ids
Allow targeted retries to replace exclusively owned pool assets in place. Keep shared and unprovable ownership paths on fresh allocations, and pin production-shaped retries plus compatibility-row cleanup.
* fix(media): revalidate asset bindings at completion
Recheck repository-wide ownership before replacing generated media and fork scoped retries when exclusivity changed. Route video export selection through the unified resolver and keep concrete posters independent of task state.
* fix(media): count unflushed owners and broadcast replacements
The completion-time exclusivity proof read only the persisted document, but
slide duplication updates the Zustand aggregate synchronously and schedules
persistence behind a debounce. A retry finishing inside that window saw a
single persisted owner and replaced the bytes behind a reference the
duplicate also held. The proof now also counts owners in the live stage
snapshot when that snapshot represents the stage being retried, so an
unflushed duplicate forks instead.
Same-id replacement notifications were realm-local, so a second tab showing
the same classroom kept its lease pinned to the superseded blob URL. The
notification now travels over a BroadcastChannel; each receiving realm runs
its own observers against its own pool, so a spoofed message can at most
force a re-resolve. A missing or failing channel never fails the replacement.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(media): bind replacement listeners and spare shared audio rows
A realm that only renders never sends a replacement, so binding the channel
from the sender path left passive tabs deaf to peers. Binding now happens
where the observer is registered, when the asset-pool module loads, and the
receiving realm resolves its own pool lazily so a cleared or unavailable
pool degrades to the next resolve instead of throwing.
Observer notifications ran under Promise.all, so a rejection surfaced after
BrowserAssetStore.replace had already committed and turned a durable success
into a reported failure. They are settled individually now; the callback is
wrapped because a synchronous throw would otherwise escape before allSettled
sees the array.
audioFiles rows are keyed globally by audioId, so deleting a stage removed
the sole row for an id a surviving document still referenced — playback and
both export paths read that table directly and cannot fall back to the
preserved pool blob. Rows are now filtered against surviving references,
while a failed enumeration still withholds only the irreversible pool
removal.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(media): serve replaced bytes from the pool everywhere
Unknown survivor liveness deleted every planned audioFiles row. Those rows
are keyed globally by audioId, and playback plus both export paths read the
table directly, so losing one is as irreversible for them as removing the
pool entry. Unknown liveness now preserves the rows too, leaving bounded
garbage for a later pass that can prove exclusivity.
The earlier pool-first change covered PPTX, video collection and thumbnail
hydration but missed classroom ZIP export, which still serialized the stale
compatibility row after a lagged same-id replacement, shipping media the
classroom no longer renders.
Auditing every direct reader of the media and audio tables surfaced the same
gap in playback: speech regeneration also replaces bytes under a stable id
and does not roll the pool back when the compatibility write fails, so the
player kept serving superseded narration. It now resolves the pool first and
falls back to stored rows for legacy and imported audio.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(audio): replace exclusively owned speech clips in place
regenerateSpeechAudio accepted the action's audioId but always passed
undefined as replaceAssetId, so regenerating an exclusively owned
pool-backed clip allocated a new asset every time, rewrote the action and
orphaned the previous pool entry and compatibility row until stage
reclamation — contradicting the stable-id path generateAndStoreTTS already
implements for media.
Ownership is now established before synthesis, and the rule itself moved to
the shared reference module so media retries, poster replacement and speech
regeneration consume one implementation instead of restating it. An
exclusively owned clip keeps its id and has its bytes replaced; a shared
clip, a legacy id with no pool entry, or unprovable ownership still gets a
fresh allocation so other holders keep their audio.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* chore(media): drop the import left behind by the ownership move
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(media): resolve audio pool-first and fence peer realms
Stable-id TTS regeneration commits replaced narration to the pool before the
audioFiles mirror write, so a failed mirror leaves the row stale. AudioPlayer
already resolved pool-first, but audioObjectUrl, collectAudioFiles and the
video timeline dependencies still read Dexie directly and would serve the
superseded clip. All allocated-audio readers now share one resolver, with
Dexie kept as the fallback for legacy and imported rows.
The exclusivity proof modelled unflushed owners in the active realm only, so
another tab duplicating the same asset during its save debounce could still
be observed as a single owner and have its bytes replaced globally. A peer's
pending state cannot be read across realms, so presence is probed instead:
any realm holding the stage forces the fork path.
A deferred asset-pool deletion no longer reloads the page. The database is
still on disk and the guidance asks the user to close the other tab and
retry, which the reload discarded. The decision moved into a shared helper so
the rule is pinned rather than living inline in the component.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(media): fail closed when presence cannot be probed
The presence helper documented that an unanswerable probe must count as a
peer, but every unavailable path — no BroadcastChannel, a constructor that
threw, a send that failed, and the window before the pool's asynchronous
binding completes — returned false, so the ownership proof cleared a single
local owner and replaced globally shared bytes in place.
Probing now returns present, absent or unknown, and only a probe that was
actually sent and went unanswered is absent; the ownership decision treats
unknown exactly like present. The pool declares its binding intent
synchronously so a probe issued during the load-time window waits for the
bind instead of concluding that presence is unavailable, and releases that
gate if the import fails.
Coverage reaches the write boundary: with presence unknown, a
production-shaped targeted retry forks to a fresh id instead of calling
replace, and the original bytes stay intact for a peer's unflushed owner.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* chore(dsl): bump to 0.6.3 after the release dedupe took 0.6.2
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix(i18n): add the deferred-clear guidance to fr-FR
The locale landed on main after this branch added the key, so the alignment
check flagged it as the one missing translation.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
* feat(roster): single-source the generated agent roster on the stage document
The generated agent roster used to live in two places at once: the stage
document carried generatedAgentConfigs, while a per-stage IndexedDB mirror
(db.generatedAgents) was the actual read authority — and the only home of
each agent's voice binding. The split caused real losses: voices vanished on
device switches, exports, and shares (the mirror never travels), the load
path trusted a device-local table over the portable document, and roster
edits persisted through a bespoke debounce with no beforeunload flush.
Make the stage document the single source of truth:
- Contract: add optional voiceConfig/voiceDesign to GeneratedAgentConfig in
@openmaic/dsl (VoiceDesign moves into the contract; the app re-exports it).
Additive optional fields — not a breaking serialized-shape change, so
DSL_VERSION stays put per the version policy.
- Writes: remove every mirror writer (registry saveGeneratedAgents, the
stage store's debouncedSaveAgents bypass, classroom-load hydration, import
direct writes). setStageAgents now only marks the stage dirty for the
shared persistence scheduler plus synchronous in-memory registry/selection
mirrors; generation and import embed the roster on the stage.
- Reads: classroom load hydrates the registry from the loaded stage's
generatedAgentConfigs; export reads the stage roster directly.
- Lazy migration: the mirror is retained read-only. On load, a roster (or
voice fields) missing from the document is backfilled from the mirror,
committed onto the in-memory stage, and persisted by the next flush —
idempotent, and gated on the current stage id after every await so a
classroom switch cannot leak a stale roster into the registry.
- Deletion: deleteStageData discards the deleted stage's pending
persistence work so a queued flush cannot resurrect the document.
- Round trip: classroom ZIP manifests now carry the voice fields, so
export/import preserves agent voices.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(roster): harden deletion, migration, selection, and ingress paths
Review hardening on top of the roster single-source change:
- Deletion vs in-flight persistence: deleting a stage now registers a
session-scoped tombstone (lib/utils/deleted-stages.ts) before the cascade
starts. Every persistence landing point checks it — the scheduled flush and
the departing-stage retry drop their snapshots, and the aggregate/incremental
saves re-check under the document lock, including the incremental path's
full-save fallback that would otherwise rebuild a deleted document from the
in-memory snapshot. A deletion that fails before the document is removed
lifts the tombstone so the still-existing stage keeps persisting.
- Lazy migration termination: a fruitless legacy-mirror probe (nothing to
merge — e.g. server-generated rosters, which are voiceless by design) is
remembered per stage for the session instead of re-querying the mirror on
every load forever. Successful merges are not memoized so a failed flush is
retried on the next load. Docstrings now state the real lifecycle.
- Selection provenance: setStageAgents no longer overwrites a user-set agent
selection with the full roster. Stage-derived selections still track the
roster; a user-set auto selection is only narrowed to surviving agents
(newcomers are not auto-selected, the user-set flag is untouched), and a
user-set preset selection is left alone — matching restoreAgentSelection.
- Mirror hygiene: deleteStageData clears the deleted stage's rows from the
legacy roster mirror (best-effort), and the mirror table's docs now describe
its actual access pattern (migration reads + deletion hygiene).
- Registry persistence: the agent registry's persist snapshot partializes
generated agents out of localStorage, making the stage document the roster's
only durable home; the rehydration merge filter remains as defense in depth.
- Ingress validation: imported manifest voice fields are structurally
validated (malformed bindings dropped per field, the agent survives), and
applyGeneratedAgentsToRegistry validates providerId against the known TTS
provider registry instead of casting, treating unknown providers as "no
bound voice".
- Contract: drop the speculative AgentVoiceConfig.modelId — an audit of every
roster producer, current and historical, found none that ever emitted it.
Contract fields are added once a producer exists, not before.
New tests cover the deletion tombstone at both the store and storage layers
(including the missing-destination full-save pin and the lock-race re-check),
the fruitless-probe memo, the selection-provenance matrix, persistence
exclusion of generated agents, and voice-field sanitization on import.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(roster): close tombstone lifecycle, probe-memo, and selection-intent gaps
Second hardening pass over the deletion/migration/selection fixes:
- Tombstone lifecycle: a deleted classroom id can legitimately come back
(deletion is client-side only). Explicit (re)creation points now lift the
tombstone — server-copy restore in applyClassroomStageAndScenes and backup
restore in importDatabase — so edits after a same-session restore persist
again, while in-flight flushes stay fenced.
- Failed deletion now restores the dirt it discarded: deleteStageData
snapshots the pending map plus the in-flight round before tombstoning, and
re-marks it when the delete fails with the document still present.
- Legacy-mirror probe memo now distinguishes a FAILED read (null, retried on
the next load) from a confirmed-empty mirror (memoized), so a transient
IndexedDB error cannot suppress migration for the whole session.
- Incremental save tail (currentScene KV row + chat sessions) is tombstone-
fenced like the aggregate path, and both paths re-check the tombstone
immediately before every write, with comments scoped honestly for the
lock-free (no Web Locks) best-effort LWW fallback.
- Roster-edit selection mirror: an empty intersection now falls back to the
full roster and clears the user-set flag (matching restoreAgentSelection's
length > 0 gate), and a user-set selection that equals the pre-edit full
roster keeps tracking the roster wholesale so newcomers are not excluded
forever by the AgentBar auto-toggle snapshot.
- TTS/ASR provider lookups use Object.hasOwn instead of `in`/bare indexing,
so prototype-chain keys ('toString', 'constructor', ...) no longer pass the
provider whitelist or resolve to Object.prototype members.
- Documented the per-tab limit of the tombstone set.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(roster): replace the boolean deletion tombstone with a deletion-generation model
A boolean tombstone cannot express the deletion lifecycle once a deleted id
legitimately comes back (server-copy restore on revisit, backup import): after
the restore lifts the flag, a pre-delete flush still in flight is
indistinguishable from a post-restore edit and can overwrite the restored
document with pre-delete content. Two rounds of point fixes kept leaking
variants of this race, so this restructures the fence instead.
deleted-stages.ts now keeps a per-stage monotonic deletion epoch plus a
deleted flag. markStageDeleted bumps the epoch; unmarkStageDeleted clears
only the flag and never rewinds the epoch. Every persistence path captures
the epoch at the moment it captures the data it will write (flush-round
snapshot, departing-stage snapshot, aggregate save entry) and re-checks
"captured epoch is current AND not deleted" immediately before each
individual write. Invariants:
- A write captured before a deletion can never land after it, even when a
same-id restore has lifted the deleted flag (the captured epoch is
permanently stale).
- A write capturing data after a restore observes the current epoch and
persists normally.
- A failed deletion lifts only the flag; the restored pending changes are
re-queued as descriptors, so their flush re-captures current store state
under the current epoch and is neither dropped nor a stale replay.
Also fixed in the same restructuring:
- Incremental tail writes (currentScene, chats) each re-check independently;
a delete landing while the first tail write is awaiting now fences the
chat write instead of riding the earlier check.
- Deleting a classroom evicts it from the warm in-memory store, and
loadFromStorage treats a warm-but-deleted stage as not loaded (discarding
the ghost), so navigating Back to a deleted classroom reaches the
server-restore path instead of rendering an editable ghost whose every
edit is silently dropped.
- importDatabase records each document's pre-import deletion state and
reinstates it when a failed import rolls the document back, so an
outstanding flush cannot recreate the rolled-back document.
- Docstrings on the failed-deletion restore path now state that only dirt
captured before the deletion is restored; edits refused during the
deletion window are not part of the snapshot.
New tests cover the epoch invariants at the storage layer (pre-delete rounds
dropped across restores on the incremental, aggregate, and tail paths;
post-restore captures landing; strictly increasing epochs), the scheduler
layer (departing-retry delete+restore straddle; restored dirt flushing under
the current epoch), the warm-ghost restore driven through the real
loadFromStorage, and the import lift/rollback pair.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(deletion): report fenced drops, gate ghost eviction on cascade settlement
Edge hardening around the deletion-epoch fence; the epoch model itself is
unchanged.
- An epoch-stale drop is now reported, not disguised: saveStageData /
saveStageDataIncremental return a distinct 'stale-dropped' status (entry
check, every in-mutation re-check, and both tail-write re-checks) instead
of a shape identical to success. saveToStorage reacts by skipping all
success bookkeeping - no chatSnapshot rebind to a snapshot that never
landed, no pending-dirt clearing - and returns false, keeping its
"true means verified write" contract honest. persistDirtySnapshot keeps
its existing (correct) semantics explicitly: a drop has nothing to retry.
- Warm-ghost eviction is settlement-gated: the deletion cascade records an
in-flight bit (begun by deleteStageData, settled in its finally), and the
deleted-warm branch of loadFromStorage keeps the warm state while the
cascade is unsettled - a delete can still fail before removing the
document, in which case the warm state plus the restored pending dirt is
the only copy of the pre-delete edits. Once settled, the ghost discard
and server-restore path behave as before.
- Read-side landing re-check: loadFromStorage re-checks isStageDeleted
after hydration, immediately before set(), mirroring the write-side
"re-check immediately before landing" discipline - a lock-free
mid-cascade read can no longer re-materialize a ghost classroom.
- clearStoreForDeletedStage re-checks isStageDeleted at eviction time, so a
same-id restore completing inside the cascade-tail window is never wiped.
- capturedEpoch is now a required parameter on both storage entry points:
the default (call-time capture) silently reopened the capture-point/
validation-point split for future callers; the type system now enforces
the pairing. All production callers already passed it explicitly.
New tests cover the dropped-status contract, the cascade in-flight
lifecycle (including both failure shapes), keep-warm during an unsettled
delete with end-to-end pending restore after a failed delete, settlement-
then-eviction on success, the eviction guard against a tail-window restore,
and the read-side hydration re-check.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(deletion): settle the deleted-warm load by awaiting the cascade outcome
Hardening around the deletion settlement gate introduced previously; the
epoch model is unchanged.
- The deleted-warm branch of loadFromStorage no longer completes the load
while the deletion cascade is undecided (which exposed a classroom whose
edits were refused without being restorable, and left a successful
deletion's eviction with no follow-up reload). It now parks on a per-stage
settlement promise (stageDeletionSettled) and branches on the outcome:
a failed delete keeps the warm, restored classroom; a successful delete
falls through to a full cold load so the server-restore path recovers the
route; a navigation that moved on during the park is stopped by the load
token guard. The eviction (clearStoreForDeletedStage) deliberately stops
claiming a new load token so the parked load stays current - ghost
re-materialization is fenced by the read-side deleted re-checks instead.
No deadlock: a parked load holds no document lock, and the cascade never
waits on a load.
- 'stale-dropped' now propagates through the debounced flush path:
persistDirtySnapshot returns the sentinel instead of an empty failure set,
and startFlushRound skips the chatSnapshot rebind on it (mirroring
saveToStorage) - a falsely rebound baseline would let later chat saves
no-op-skip chats that never landed and corrupt cross-tab conflict
detection. Pending-map clearing keeps its empty-failure semantics
(restored descriptors mint fresh revisions).
- The cascade in-flight state is a counter (begin++/settle--) instead of a
boolean, and deleteStageData is single-flight per stage (a concurrent
second call joins the first cascade), so overlapping deletions can never
expose an undecided cascade as settled.
- The StaleDroppedSave docstring no longer overpromises: a tail
saveCurrentScene can land after the cascade's clearCurrentScene; the
orphaned cursor row is ignored by the load path rather than removed by
the cascade.
Net +8 tests: overlapping-cascade counting, settlement-promise resolution
(success and failure), concurrent double-delete single-flight join, the
parked mid-cascade Back in both outcomes plus the navigation-away guard,
and the fenced flush round keeping an honest chat baseline end-to-end.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(deletion): re-verify store identity on keep-warm resume, re-run joined deletes after a mid-cascade restore
Three hardening refinements on the deletion/persistence fencing:
- loadFromStorage's parked keep-warm branch now mirrors the success
path's store-identity guard: if a tokenless writer (e.g. a database
import) replaced the stage during the park, a failed deletion falls
through to the cold load instead of reporting another classroom as
the kept warm state. The ghost-discard block is correspondingly
gated on the deleted flag so the fall-through does not mislabel a
surviving document as a ghost.
- deleteStageData: a joined call carries its own deletion intent. When
the first cascade fulfills but a same-id restore lifted the deleted
flag in the meantime, the joined caller now runs one fresh cascade
against the restored document instead of reporting the pre-restore
outcome. Exactly one re-check per call (no recursion); a rejected
first cascade still propagates unchanged to every joined caller.
- Narrowed the failed-delete restore-ownership comments: the restore
covers only the pending map plus an in-flight flush round's dirt;
a departing-stage snapshot is outside that capture and is fenced
and dropped by design. Comment-only, no behavior change.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(roster): gate deleted-warm handling on stage identity, keep an explicit empty roster authoritative
Final-audit fixes, three items:
- loadFromStorage keyed its deleted-warm settlement handling (park /
keep-warm / ghost discard) behind the scenes.length > 0 shortcut, so a
zero-scene warm ghost of a deleted classroom skipped it entirely: the
cold load found no document, the ghost stayed in the store, and the
classroom loader's server-fallback gate (!getCurrentStage()) never ran
— the silently-uneditable trap this branch exists to close, in its
scene-less form. Deletion handling now keys on stage identity alone,
before any scene-count shortcut; the non-deleted warm skip still
requires scenes.
- rosterNeedsLegacyFallback collapsed "roster field absent" (document
predates roster persistence) with "explicitly persisted empty roster".
A future writer persisting [] on a device whose read-only mirror still
held stale rows would have its emptied roster resurrected on every
load. The full-lift branch now triggers only when the field is absent
(undefined); an explicit [] is authoritative and never probes the
mirror. No current writer produces [], but the read side no longer
depends on that invariant.
- The GeneratedAgentConfig docstring claimed the voice fields are not a
breaking change; that only holds for this codebase's tolerant
structural validators. The generated stage.schema.json sets
additionalProperties: false, so consumers pinning an older published
schema artifact reject documents carrying the new fields. The
docstring now states both sides honestly.
Tests: a zero-scene deleted warm ghost is restored through the real
loadFromStorage (fails pre-fix), an explicit empty roster does not
resurrect stale mirror rows (fails pre-fix), and the
rosterNeedsLegacyFallback unit matrix covers undefined vs [].
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(deletion): re-queue aggregate persistence when a failed deletion is recovered
Direct aggregate saves (saveToStorage: generation completion, server-restore
hydration) run outside the pending map and the flush round, so the deletion
path's pre-delete dirt snapshot cannot describe them. When a deletion bumped
the epoch while such a save was in flight, the save was correctly fenced
('stale-dropped') — but if the deletion then failed before removing the
document, the recovery only re-queued the snapshotted scheduler descriptors.
The fenced aggregate-only content stayed memory-only with no retry anywhere,
and a later reload lost it.
The failed-deletion restore now merges a full re-mark of the aggregate
(structure / stage / outline / currentScene / chats plus a descriptor for
every current scene) into the recovery set, still guarded on the store
holding the stage. Because the flush recaptures the CURRENT store state under
the CURRENT epoch, this necessarily carries whatever the fenced aggregate
save held — and, for the same reason, edits refused by the scheduler during
the deletion window, which previously stayed memory-only as well; the scope
docstrings now say so instead of declaring them excluded.
New integration coverage drives the real store scheduler and the real storage
layer end to end: a genuinely fenced in-flight saveToStorage (generation
completion) plus a pre-removal deletion failure ends with the completion flag
durable on the next flush; a deletion-window scene edit survives the same
way; and a successful deletion re-marks nothing (control). Both recovery
tests fail against the previous restore logic.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
* feat(runtime): persist quiz attempts in RuntimeStore
* fix(runtime): coalesce quiz draft snapshots
* fix(runtime): recover concurrent quiz attempts
* fix(runtime): handle quiz completion races
* fix(runtime): commit quiz review atomically
* fix(runtime): dedupe concurrent quiz writes
* fix(runtime): drop stale quiz drafts
* fix: harden quiz runtime review recovery
* fix: serialize quiz attempt identity
* feat: read quiz state from runtime store
* fix: persist quiz retries before resetting
* fix: preserve authoritative quiz outcomes
* fix: preserve legacy quiz retries during cutover
* fix: reconcile legacy quiz snapshots safely
* fix: drain rollover quiz write queues
* fix: drain completed quiz retry queues
* fix: reuse concurrent quiz retries
* fix(quiz): preserve drafts across abrupt reloads
* fix(quiz): recover empty retry sessions
* fix(chat): abort stalled runtime state reads
* fix(quiz): expose queued phases to readers
* fix(quiz): retain concurrent writer tails
* fix(quiz): canonicalize retry branches
* fix(quiz): keep retry rollovers monotonic
* fix(quiz): validate skipped retry siblings
* fix(quiz): close read cutover races
* test(classroom): cover legacy quiz summaries
* fix(quiz): reset async consumers on scene changes
* fix(quiz): close scene transition windows
* test(pbl): cover launch freshness guards
* fix(quiz): close cutover concurrency gaps
* fix(quiz): harden retry and context freshness
* fix(quiz): reject malformed legacy answers
* fix(quiz): validate legacy answer values
* test(quiz): cover legacy multi-answer migration
* fix(merge): retire dead ChatRequestTemplate.storeState after quiz read cutover
Main's three call sites built static storeState blocks that runAgentLoopFn
never consumed (it always rebuilds fresh state via getStoreState); the quiz
read cutover replaced that callback with the async two-phase RuntimeStore
read, leaving the template field with zero consumers. Drop it.
* feat(storage): conform HTTP/PG backends and reference server to RuntimeAppendOptions
The quiz write path's expectedLastSeq / sessionTransition / RuntimeAppendConflictError
semantics existed only in the browser backend; server-backed deployments would
silently accept conflicting appends and leave completed sessions active. Forward
the options over the wire, detect conflicts atomically under the PG transaction,
map them to HTTP 409 RUNTIME_APPEND_CONFLICT, and rematerialize the typed error
client-side so quiz retry logic works across every backend.
Co-authored-by: Codex <codex@openai.com>
* fix(chat): Pi single requests build storeState via the async runtime quiz read
Pi bypasses runAgentLoop's per-iteration getStoreState and serializes the
request template straight to /api/chat/pi, which rejects bodies without
storeState. Extract the fresh-snapshot builder (async RuntimeStore quiz read
with the scene-transition guard) and call it on the Pi path too.
* ci: whitelist the runtime-data-cutover integration trunk for PR checks
* feat(runtime): playback cutover — cursor in KV, discussion facts in RuntimeStore (#956)
* feat(runtime): cut playback over to the runtime layer — cursor in KV, facts in RuntimeStore (#869)
The fourth and last runtime family. Consumed-discussion facts become
append-only 'playback' records folded into a set at read (at-least-once
appends, no conflict machinery); the resume cursor is device-scoped
last-write-wins KV per the amended #779/#869 split. sessionStorage keeps
same-tab priority; KV takes over on fresh tabs/reloads. The dead Dexie
playbackState machinery is retired, with a one-time lazy migration of any
legacy row (cursor half + facts half) before deletion, and stage deletion
now clears both the KV cursor and any unmigrated legacy row.
Co-authored-by: Codex <codex@openai.com>
* test(runtime): include playbackState in the stage-delete db mock
---------
Co-authored-by: Codex <codex@openai.com>
* fix(playback): persist discussion facts on every consumption path (#957)
* fix(playback): persist discussion facts on every consumption path (final-review P0+P1s)
- The engine now publishes a progress snapshot the moment a discussion is
consumed (join / skip / unselected-agent auto-skip). onProgress otherwise
fires before the discussion action executes and a discussion is the scene's
last action, so the fact never reached persistence.
- Reads fold records across ALL playback sessions in the learner partition
(mergeLearner deliberately preserves same-kind sessions from both keys).
- Legacy migration appends only not-yet-durable facts, so an interrupted
migration resumes instead of dropping the tail.
- recordConsumedDiscussion reports durability; the component drops failed ids
from its observed set so a later progress tick retries (at-least-once).
* test(e2e): live verification of the playback persistence chain
Seeds a deterministic stage straight into the Dexie DB, starts the lecture
via the canvas overlay, and asserts the full chain: discussion auto-skip
appends a discussionConsumed record to maic-runtime, the device cursor lands
in KV, and both survive a fresh browsing context (empty sessionStorage).
* refactor(playback): consumed-discussion state is volatile by decision — cursor-only persistence (#959)
Product ruling on #869's fourth family: playback learner state is front-end
ephemeral UX, not learner data. A re-shown proactive card auto-skips, joined
discussions' content already lives in chat runtime records, and no replay
export / analytics consumer exists — so durable facts bought nothing over
in-memory + same-tab sessionStorage. Drop lib/playback/runtime.ts and the
RuntimeStore facts wiring; keep the device-scoped KV resume cursor (the half
with real UX value), the engine's consumption-time progress snapshot (cursor
freshness), and the legacy Dexie retirement (cursor half migrates, row
deletes, consumed ids are dropped).
* ci: whitelist the document-cutover integration trunk for PR checks
* feat(document): widened-stage contracts + app document seam (#860 follow-up, PR1) (#961)
Package: MaicDocument/DocumentStore/StageRow gain a TStage parameter
(defaults keep existing users unchanged), BrowserDocumentStore accepts an
injectable validateStage, and a version-guarded putStage closes the rename
read-modify-write race — same current-version gate as putScene.
App: lib/document/ seam — AppDocument types (currentSceneId is device
state, not document data, and the app stage validator rejects it), a
four-kind scene validator (slide/quiz delegate to the DSL; interactive/pbl
validate envelope + discriminant binding only), and pure legacy
canonicalizers (type rebound from content.type, singular whiteboard →
whiteboards, outline envelope). No consumer switches off Dexie yet.
Co-authored-by: Codex <codex@openai.com>
* feat(document): stage-storage cutover + locked lazy migration (PR2) (#962)
* feat(document): cut stage/scene persistence over to DocumentStore with locked lazy migration (PR2)
stage-storage now persists through the lib/document seam: aggregate
saveDocument with a mandatory outline envelope (omission means deletion in
the contract; ordinary saves fall back to the stored envelope), lazy
per-stage migration under a Web Lock (destination authoritative, one
coherent legacy snapshot, save-verify-marker, legacy rows retained
read-only; no-lock environments read legacy without migrating),
currentSceneId in device KV, rename via version-guarded putStage, and a
list that merges legacy-only stages until they migrate. stageOutlines'
second write authority folds into the document service, making the final
scene set and generationComplete one atomic commit.
Co-authored-by: Codex <codex@openai.com>
* fix(document-store): relocate the persistence seam out of lib/document
lib/document/ is the server-side content-extraction domain (sharp, cloud
SDKs); exporting the persistence seam from its barrel dragged node-only
modules into the client bundle and broke the Turbopack build. The seam now
lives in lib/document-store/ with its own barrel, and the extraction barrel
is restored. Client-only guards become capability probes (indexedDB /
localStorage presence) so injected node test environments keep working
while a true server render still fails loud.
* fix(document-store): no-lock write classification + lock-order inversion (PR2 fix round)
Lock order is now per-stage document lock → global runtime epoch (a save
never waits on a document lock while occupying the shared epoch, which
deadlocked against fair-queued maintenance). Without Web Locks, mutation
classifies instead of refusing wholesale: destination-backed and genuinely
new documents accept the product's established lock-free/LWW risk, while a
legacy-only document stays read-only so two authorities cannot fork —
matching the chat-cutover-era acceptance suite, whose save assertions now
verify through the public API instead of legacy Dexie rows.
Co-authored-by: Codex <codex@openai.com>
* style: prettier on document-store seam files
---------
Co-authored-by: Codex <codex@openai.com>
* feat(document): cut secondary consumers over to the document seam (PR3) (#963)
ZIP classroom/video exports read stage metadata through the seam; classroom
import builds one canonical aggregate under the per-stage lock and writes
canonical 'whiteboards' (fixing the import-side singular-alias defect the
manifest never had); backups become versioned document aggregates that
finally include outline envelopes, while old {stages, scenes} backups are
accepted through the legacy canonicalizers; clearDatabase now clears
maic-documents and the seam's KV keys so clear-cache cannot strand
documents; deleteStageWithRelatedData is deprecated in favor of
deleteStageData. Four e2e seeders target maic-documents directly;
classroom-interaction stays legacy-seeded to exercise real-UI lazy
migration.
Co-authored-by: Codex <codex@openai.com>
* fix(document): final-review hardening — restore pre-images, honest markers, clear-race exclusion (3 P1 + 2 P2) (#964)
- Backup rollback restores pre-existing destination documents (and imported
current-scene KV values) from captured pre-images instead of deleting them
- The skip-migration path only writes its marker after reconciling the
legacy snapshot against the authoritative destination; a divergent
snapshot logs and stays discoverable instead of being falsely certified
- Migration's destination write enrolls in the global shared storage epoch
(per-stage -> global order), so clearDatabase's exclusive epoch can no
longer race a lazy migration into resurrecting a document
- listStages drops legacy entries whose snapshot vanished mid-merge
Co-authored-by: Codex <codex@openai.com>
* fix(review): P3 pair from cross-review — scene-id boundary + sessionTransition 400 (#966)
* fix(review): scene-id boundary for quiz context + 4xx for malformed sessionTransition (P3 pair)
Review findings on #955: didActiveSceneRemainUnchanged compared the active
scene by object identity, so a store update reallocating the scene during
the async quiz read dropped the learner's graded answers from that turn's
request — the scene id is the real boundary. The records route now
classifies a malformed sessionTransition as a validation failure instead of
letting the store's throw surface as a 500.
* fix(playback): superseded-engine cursor guard + migration write-window recheck
Second-vendor review of the #959 shrink (requested after the cross-review
noted it had single-vendor coverage) found: an engine orphaned by a scene
switch during async lecture resume could pass the idle-only recheck, be
resurrected, and publish its old scene's progress over the new scene's
debounced cursor — the resume continuation now requires identity with the
installed engine, and onProgress drops snapshots from superseded engines.
The legacy cursor migration also rechecks KV immediately before its write
so a concurrent tab's newer cursor cannot be overwritten and orphaned by
the legacy-row delete.
Co-authored-by: Codex <codex@openai.com>
---------
Co-authored-by: Codex <codex@openai.com>
* fix(review): approval follow-up P3 nits (#967)
* release: v0.3.1
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(review): approval P3 nits — ISO gate on sessionTransition, dead mocks, corrupt-timestamp guard
- The records route's sessionTransition guard now requires an ISO
updatedAt (isIsoTimestamp), matching the sibling PATCH /status route
- Dead vi.mock factories for the deleted playback-storage module dropped
- A corrupt legacy playback timestamp falls back to 'now' instead of
wedging migration into a permanent re-throw that disabled resume
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* fix(document): backup covers no-lock legacy courses; clears fence stale saves (review P1s) (#968)
Backup assembly appends read-only canonicalized aggregates for legacy-only
stages the lazy migration could not persist (no-Web-Locks environments) —
courses visible in the app can no longer vanish from an export. A
device-scoped storage generation now fences document mutations: clears bump
it inside their exclusive section, and any save or migration commit that
entered before the clear re-reads it inside the shared epoch and fails loud
instead of repopulating a wiped store.
Co-authored-by: Codex <codex@openai.com>
* fix(document): review round 2 — legacy-only chat backup coverage + full-width generation fence (#972)
Backups now enumerate runtime chat sessions for every exported document,
not just store-backed ones — a legacy-only course's chat history (the chat
and document cutovers are independent seams) no longer drops out of the
export; the runtime read injects an empty legacy chat store since legacy
rows are collected by direct table reads, which also keeps the export
working without Web Locks. The storage-generation fence now guards every
mutating store method, with the exclusive-epoch delete cascades passing
storageSharedLockHeld so the guard cannot self-deadlock against their own
hold.
---------
Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* feat(runtime): device-anonymous learnerKey + app RuntimeStore singleton (#869)
* feat(runtime): cascade stage deletion into the runtime store (#869)
deleteStageWithRelatedData now cascades into the runtime layer after its
Dexie transaction completes. The runtime data lives in a separate
IndexedDB database (maic-runtime), so it cannot join the transaction, and
the cascade goes through deleteStageRuntimeSafely — a helper that never
throws (warns with context instead): a broken or hung runtime DB must not
brick stage deletion in the main app DB. deleteStageRuntime is idempotent,
so a failed cascade can simply be retried.
Covered at the helper seam with a stub RuntimeStore (success + throwing);
the repo has no Dexie-in-node harness for database.ts and this change
does not invent one.
* fix(runtime): wire the live deletion path, serialize learner-key minting (#869)
Cross-review fixes on the C1 bootstrap:
- The runtime cascade was wired into deleteStageWithRelatedData, which has
zero callers; the UI classroom-deletion flow goes through deleteStageData
in stage-storage. Wire deleteStageRuntimeSafely into that live path too
(after its Dexie work, same isolation rationale), and cover the wiring by
running the real deleteStageData with its module deps mocked — the
repo's established pattern for database-touching code.
- getLearnerKey minted twice under concurrency. Same-bundle callers now
share one in-flight promise on the default path (failures are not
cached), and every path re-reads after writing and returns the PERSISTED
key, so a cross-tab race converges on the stored winner instead of
keeping an orphaned local mint.
- Guard crypto.randomUUID with the house fallback pattern.
- Honest docs: the cascade comment no longer claims a retry path exists
(orphaned rows are inert today; a startup sweep is deferred to Part C2),
and both lib/runtime modules note they are client-only.
* fix(runtime): cross-tab mint lock and bounded deletion cascade (#869)
- Read-after-write alone still let a tab keep an orphaned learner key
when its re-read landed before the other tab's write. Minting now runs
under the Web Locks API ('maic:learner-key') where available: grants
are mutually exclusive across tabs, the loser re-reads the winner's key
inside its grant, and an existing key is never overwritten (so the
per-tab memo stays safe). Without navigator.locks (older browsers,
non-window contexts) the memo + read-after-write behavior remains, with
the residual race named in a comment and accepted — it merely splits
one anonymous learner's local history.
- deleteStageRuntimeSafely awaited without a bound, so a hung runtime
IndexedDB could block the live deletion path — the exact failure the
helper exists to isolate. The cascade now races a 5s timeout: on
timeout it warns and resolves (orphaned rows stay inert), and the still
-pending cascade carries a swallow handler so a late rejection cannot
become an unhandled rejection.
* fix(runtime): probe for the runtime DB before cascading a stage deletion (#869)
deleteStageRuntimeSafely reached openDb() unconditionally, and opening
CREATES the maic-runtime database — so deleting a classroom on a device
that never wrote runtime data paid an open-or-create of a second
IndexedDB DB, and in degraded environments burned the full 5s bound for
zero cleanup value.
Probe first without creating: where indexedDB.databases() is available,
a missing maic-runtime entry returns immediately; where the probe API is
unavailable (older Firefox), fall through to the bounded cascade —
skipping there would strand real cleanup once Part C2 adds writers. The
probe shares the existing try/catch + timeout envelope, so a hanging
databases() cannot brick deletion either. The DB name is a module const
passed explicitly to BrowserRuntimeStore so probe and store can never
drift.
* feat(editor): agent roster edit operations
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(editor): dedupe agent.delete lookup + cover history cap/color/teacherCount
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(editor): materialize agent roster from presets
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(editor): cycle prepended-teacher index + document branch-1 as-is
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(editor): stage store viewMode + agent roster persistence
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(editor): useAgentRoster controller hook
Implements the AgentRosterController hook that bridges the store, history
stack, and agent-ops layer for the agents authoring view.
- Materializes roster from stage on mount via materializeRoster + resolvePreset
- Holds AgentRosterHistory in React state; exposes add/update/remove/reorder
- Guards LAST_TEACHER errors (caught, no-op) in update + remove
- Exposes SurfaceHistory-shaped history object for undo/redo wiring
- Syncs history.present to setStageAgents via useEffect on every change
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(editor): Agents view UI components
Adds AgentsView, AgentRosterGrid, AgentCard, AgentInspector, AvatarPicker.
Layout: full-height panel with a scrollable grid of agent cards on the left
and a fixed inspector panel on the right (opens when a card is selected).
- AgentCard: avatar + name + role badge + persona excerpt; ◀/▶ reorder
buttons; delete button disabled + titled when canRemove=false (last teacher)
- AgentRosterGrid: responsive grid with trailing [+ 添加角色] add tile
- AgentInspector: name input, role select (teacher/assistant/student),
AvatarPicker over AGENT_DEFAULT_AVATARS, persona textarea capped 2000 chars
- AvatarPicker: grid of AGENT_DEFAULT_AVATARS with violet selection ring
- AgentsView: composes the hook + grid + inspector; renders its own
CommandBar (title="Agents", history=hook.history) with leading/trailing slots
Styling follows quiz surface conventions (rounded-2xl cards, zinc palette,
violet accent on selection, same FOCUS ring treatment for inputs).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(editor): [Slides]/[Agents] view toggle wired into Pro-mode chrome
- CommandBar: add optional `leading?: ReactNode` center slot for the toggle
- EditShell/Frame: thread new `commandLeading` prop down to CommandBar
- EditChromeRoot: read viewMode/setViewMode from useStageStore; build a
ViewModeToggle ([幻灯片] / [角色] segmented control) passed as commandLeading
to both EditShell (slides mode) and AgentsView (agents mode)
- When viewMode==='agents', render AgentsView instead of EditShell; leftRail
and bottomRail are naturally absent since AgentsView owns its own layout
- When viewMode==='slides', existing EditShell path is unchanged
- CommandBar history in agents mode binds to useAgentRoster().history;
title = "Agents"
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(editor): functional state updates in useAgentRoster + last-teacher role feedback
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(editor): break infinite render loop in Agents view persistence effect
Remove `stage` from the useEffect dep array in useAgentRoster — setStageAgents
mutates stage (new object ref), which was triggering re-render → effect → loop
(React error #185). setStageAgents already no-ops when stage is null
(lib/store/stage.ts:287), so the `if (stage)` guard is also removed.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(editor): persist agent roster edits to registry + stage snapshot
- Add generatedAgentConfigs to StageRecord (database.ts) so Dexie can
round-trip it through db.stages.
- Include generatedAgentConfigs in saveStageData whitelist (stage-storage.ts)
so editor reloads restore the user's roster edits.
- In saveToStorage (stage.ts), call saveGeneratedAgents(stageId, configs)
after the stage snapshot write; this is already debounced (500 ms) via
debouncedSave, so db.generatedAgents + the in-memory registry are synced
without writing on every keystroke. saveGeneratedAgents clears-then-
bulk-inserts, so deleted agents are fully removed from the registry.
- Add 3 timer-driven tests that verify saveStageData carries
generatedAgentConfigs and saveGeneratedAgents is called with the
correct payload after the debounce fires.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(editor): scope agent-registry sync to real roster edits (cross-review)
- FIX A (P1): remove saveGeneratedAgents from shared saveToStorage; add
dedicated debouncedSaveAgents called only from setStageAgents — scene
advances (setCurrentSceneId etc.) no longer churn db.generatedAgents
- FIX B (P2.1): add isDirtyRef guard in useAgentRoster so opening the
Agents tab without editing does not persist/rewrite the roster; ref is
set in applyOp, add, undo, redo before any setHistState mutation
- FIX C (P2.2): coalesce consecutive agent.update ops on the same
agent+fields into one history entry so undo steps over a whole edit
rather than each keystroke
- Tests: add regression guards asserting saveGeneratedAgents is NOT
called on setCurrentSceneId or plain saveToStorage, IS called after
setStageAgents (new dedicated debounce path)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(editor): clone preset agents to fresh ids on materialization (cross-review P1)
* refactor(editor): move agent roster into right-rail tab beside Edit with AI
The [幻灯片][角色] top toggle + full-canvas AgentsView swap is replaced
by a tabbed right rail (RightRailTabs) with "Edit with AI" and "角色"
tabs. The slide canvas stays visible in all modes; agents are edited in
the 角色 tab of the right rail.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(editor): restyle agent panel to Design B accordion (课堂阵容)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(editor): cross-review — persona draft sync, scoped preset re-id, AI-tab gating, dead-code cleanup
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(editor): avatar click expands card, editable-name affordance, add-button copy
* fix(editor): cross-review — drop blur-level undo coalescing, sync playback selection to edited roster
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* style(editor): prettier format agent panel files (CI fix)
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(agent-edit): multi-session conversation history for the AI editor
The "Edit with AI" panel kept only one thread per stage in localStorage, and
"New conversation" deleted it, so previous conversations were unrecoverable.
Add a per-stage session list backed by IndexedDB (Dexie v12 `agentEditSessions`):
- "New conversation" now archives the current session and starts a fresh one
instead of deleting it; a history popover in the panel header lists past
sessions (auto-titled from the first user message) to switch back to or delete.
- One-time migration of the existing single-thread localStorage entry.
- The active session id is remembered per stage so a refresh restores it,
including a just-cleared empty session (clean slate survives reload).
- saveSession preserves the original createdAt and tombstones deleted ids so an
in-flight save can't resurrect a deleted session; switching stages drops the
previous thread synchronously so it can't leak into the new stage.
- Sessions are pruned to a soft cap per stage and removed when a course is
deleted.
- i18n for all 8 locales; unit tests for title derivation and the store.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(types): drop redundant Window.SpeechRecognition augmentation conflicting with @assistant-ui/core
@assistant-ui/core's speech adapter declares Window.SpeechRecognition and
webkitSpeechRecognition globally as SpeechRecognitionConstructor. Three files
(prompt-input, use-audio-recorder, use-browser-asr) re-declared them as `any`,
which conflicts (TS2717) once that adapter's types are pulled into the program,
and the constructed instance then lacks the event handlers the code sets
(TS2339/2551). Rely on the global declaration and cast the instance to the local
rich shape. Takes `tsc --noEmit` back to zero.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Deleting a slide in Pro/Edit mode removed it from `scenes` but left its
entry in the persisted `outlines` plan. On the next classroom mount the
resume-generation pass treats the now-missing `order` as a pending
outline and regenerates the slide, appending it as the last page.
Rather than prune outlines by `order` (which is rebalanced by Pro-mode
insert/duplicate/reorder, so it is not a stable key and would mis-target
or break delete-undo), gate resume on a persisted `generationComplete`
flag:
- The flag is recorded (alongside outlines, in the stageOutlines record)
when generation finishes — both generateRemaining completion paths, the
retry-to-completion path (markGenerationCompleteIfDone), and the
already-materialized-at-mount path — and restored on load. It is written
only after a verified scene flush, so it never outruns the deck's scenes.
- A finished deck is frozen for editing: loadFromStorage no longer derives
pending placeholders from orphaned outlines, the classroom resume effect
skips generateRemaining, media resume is filtered to materialized
outlines, and isCourseComplete honours the flag — so a deleted slide
neither regenerates nor leaves a phantom pending page.
- Decks generated before the flag existed self-heal on load (every outline
has a scene ⇒ inferred complete). deleteScene additionally records
completion when deleting from a deck that is complete right now, so the
"Course complete" end page and resume-suppression survive even when the
flag was never persisted (e.g. edited without a reload).
`outlines` are never pruned, so order-rebalancing and delete-undo are
unaffected. Genuinely interrupted generations (not complete) still resume.
Fixes#768
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(tts): voxcpm voice-design types + deterministic voice id helpers (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): emit + persist per-agent voiceDesign descriptor (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): voxcpm voice registration backend client (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): voxcpm-voice ensure/register endpoint (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): client auto-voice registration + reference-clip cache (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): reference registered voice id in vLLM-Omni speech (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): thread voiceDesign + backend through tts call sites (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tts): match vLLM-Omni voice registration contract (#670)
Live e2e against the real backend revealed the assumed multipart contract was
wrong: POST /v1/audio/voices needs name + consent + audio_sample (not
voice_id/file), and there is no per-name GET (405) — existence must list
/v1/audio/voices and check membership.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* refactor(tts): make auto-voice register-once pattern provider-neutral (#670)
The descriptor + register-once/reference-by-id pattern is not VoxCPM-specific.
De-couple it into a provider-neutral seam so other registration-capable
providers (ElevenLabs/MiniMax/Doubao voice cloning, …) can plug in:
- lib/audio/voice-design.ts: VoiceDesign + buildVoiceDesignPrompt /
normalizeVoiceDesign / getDeterministicVoiceId (neutral 'auto-<hash>' id,
namespaced by providerId).
- lib/audio/voice-registration.ts: VoiceRegistrationAdapter interface +
providerId->adapter registry + supportsVoiceRegistration.
- lib/audio/voice-registration-client.ts: neutral ensureRegisteredVoice() +
IndexedDB clip cache.
- app/api/generate/voice (replaces .../voxcpm-voice): dispatches by providerId.
- voxcpm-registration.ts becomes the VoxCPM adapter (sole registered provider).
- AgentConfig.voiceDesign + DB cache table renamed neutral.
Behavior-preserving; VoxCPM-specific bits (inline (prompt)text, backend kinds,
capability gate) stay in the voxcpm modules. Full suite green (674).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tts): build the voice clip Blob from an inline Uint8Array (#670)
A factored-out helper returning Uint8Array widened to Uint8Array<ArrayBufferLike>,
which next build (stricter than bare tsc) rejects as a BlobPart. Inline the
buffer like the rest of the repo does.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): managed TTS providers resolve model server-side (#670)
A server-managed TTS provider's model was still client-driven, but the
managed-provider settings UI hides the model field — so a backend whose model
id isn't the client default (e.g. VoxCPM/vLLM-Omni serving the full model path)
always 500'd. resolveTTSModel() makes the model authoritative from server
config (${PREFIX}_MODELS, first entry) for managed providers, like key/baseUrl;
unmanaged/unconfigured providers keep the client model unchanged. Used by the
tts and voice routes.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tts): single agent-voice resolver + stable teacher narration voice (#670)
Route all TTS voice resolution (narration, discussion, preview) through one
resolveAgentVoiceOptions(agent, ...) that reads the agent profile and registers
+ references the voice by id. Eagerly warm up generated agents' voices on save.
Critically fixes the teacher narration drifting (male/female jumps): the registry
is always seeded with DEFAULT_AGENTS, so the old narration lookup
find(role==='teacher') returned the default teacher (no voiceDesign) instead of
the generated one — so narration never registered a voice and fell back to the
inline prompt. pickNarratorAgent() now prefers the teacher carrying a voiceDesign.
Also: drop language from the deterministic voice id (descriptor already encodes
it) so narration (directive) and discussion (locale) resolve the same id; log
the effective registeredVoiceId. Regression tests for pickNarratorAgent.
Verified e2e: agent-profiles -> 1 voice registration -> 16 narration TTS all
referencing the same registeredVoiceId; voice present on the backend.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* feat(tts): fall back to persona as the voice seed for agents without a voiceDesign (#670)
Preset/default agents carry no LLM voiceDesign. Rather than add a static field,
derive the bootstrap descriptor from the agent's persona when voiceDesign is
absent, so they still register one stable reference voice (stable-but-generic;
persona is not a vocal spec). Generated agents keep their LLM voiceDesign.
Also hardens replay: stage snapshots drop voiceDesign but keep persona.
Unit-tested: resolveAgentVoiceOptions uses real voiceDesign when present, persona
otherwise.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tts): match Auto Voice by its localized label in the agent voice picker (#670)
The picker filtered on voice.name ('Auto Voice'), but Auto Voice is shown via
its localized label (自动音色). Searching '自动' returned '没有匹配音色'. Match
the localized label for the Auto Voice option so it's findable in any language.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tts): address code-review round 1 (#670)
- strip parentheses in the voice-design prompt so a paren in the descriptor/
persona can't corrupt the (prompt)text bootstrap delimiter
- gate POST /api/generate/voice on isServerTTSProviderDisabled (#665): a
force-disabled provider was off for the tts route but not this sibling
- check voiceExists before re-registering a client-cached clip, so a cached
voice that's still live isn't needlessly re-uploaded every session
- dedup concurrent ensureRegisteredVoice calls via an in-flight promise map
(eager warm-up + first utterance no longer double bootstrap/register)
- warm up only the narrator (teacher), not every generated agent, to avoid
synthesizing voices at save time for agents that may never speak
- collapse the duplicated vLLM-Omni speech payload into one object
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* chore(tts): prettier formatting (#670)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tts): key auto-voice memo by (voiceId, backend) so a base-URL change re-registers (#670)
Addresses review (cosarah): registeredThisSession/inFlight were keyed by voiceId
alone, so switching the VoxCPM base URL mid-session made ensureRegisteredVoice
short-circuit and return an id registered only on the old backend — TTS then sent
that stale registeredVoiceId and skipped the inline fallback, failing with
voice-not-found on the new backend. Memo key now includes the base URL; the
IndexedDB clip cache stays keyed by voiceId (the reference clip is
backend-independent and reused to re-register elsewhere). Regression test added.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* fix(tts): include API key in the auto-voice memo key (#670)
Addresses review (cosarah, round 2): memoKeyFor was keyed by (voiceId, baseUrl)
but not the API key. Registration/existence checks and speech calls are
auth-scoped, so switching account/key on the same base URL could reuse a
registeredVoiceId from the old credentials and skip re-validation. Memo key now
includes the API key (in-memory only, never persisted/logged). Regression test
covers the key-switch case.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
* feat(stage): add optional Stage.interactiveMode flag
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(db): add optional interactiveMode column on StageRecord
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(stage-storage): pass interactiveMode through save/list
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(generation): persist interactiveMode when creating a classroom
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* i18n: add classroom.deepInteractive across all locales
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(home): show Deep Interactive badge on classroom cards
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(home): move Deep Interactive badge into thumbnail corner
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor(home): slim Deep Interactive badge to icon-only chip
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(home): use Tooltip component for Deep Interactive badge
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor(home): move Deep Interactive badge to bottom-left corner
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(home): tighten Deep Interactive tooltip placement
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(home): close gap between Deep Interactive tooltip and badge
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(home): edge-align Deep Interactive tooltip without overlap
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* refactor: address code review
- Reuse toolbar.interactiveModeLabel instead of adding a duplicate
classroom.deepInteractive i18n key (was identical to the existing
label in zh-CN and semantically the same in the other 4 locales).
- Drop the v0.2.0 version tag from comments (will go stale at release).
- Document on ManifestStage that omitting interactiveMode is intentional
— imports can't faithfully reproduce the original generation branch.
- Add a brief comment on the Tooltip's negative sideOffset explaining
why the standard positive offset does not visually close the gap here.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat: inline language inference in outline generation
Replace manual language selection with automatic inference from user
requirement text. The outline generator now produces a languageDirective
that propagates through the entire generation pipeline.
Key changes:
- Rewrite Language Inference section in outline prompt with decision
rules for foreign language learning, cross-language PDF, proxy
requests, and terminology handling
- Reorder pipeline: outlines before agents, so agent profiles can
use the inferred languageDirective
- Pass languageDirective through scene content/actions generation
- Add SSE streaming of languageDirective from outline generation
- Remove manual language selection UI
Eval test suite:
- 50 test cases covering 9 scenario types: single-language, language
learning, immersive, explicit instruction, code-switching, minimal
input, user profiles, cross-language PDF, locale mismatch
- LLM-as-judge evaluation with configurable inference/judge models
- 50/50 pass rate with gemini-3-flash-preview + gpt-4o judge
- Excluded from CI (requires LLM API keys)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: remove useless attributes in test case
* feat: pass languageDirective to PBL, remove hardcoded zh-CN/en-US
- Remove pblConfig.language field, use languageDirective from outline
inference instead
- Delete all Chinese prompt duplicates in pbl-system-prompt.ts,
agent-templates.ts; keep English templates with languageDirective
injection
- Remove zh-CN/en-US branches in generate-pbl.ts (initial prompt,
post-process context, welcome message)
- Pipe languageDirective through scene-generator → generatePBLContent
→ IssueboardMCP → agent templates
- Remove i18n template wrapping from PBL welcome messages in
pbl-renderer.tsx and use-pbl-chat.ts; use LLM-generated content
directly to avoid language mismatch when UI locale ≠ course language
- Update pblConfig schema in outline prompt (remove language field)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: clean up legacy language fields, pass languageDirective through buildSceneFromOutline
- Add languageDirective param to buildSceneFromOutline, combining with
outline.languageNote via buildLanguageText
- Remove dead types: AudienceProfile, StylePreferences, LegacyUserRequirements,
SceneOutline.language
- Remove Stage.language and all its propagation (storage, stageInfo, prompt-builder fallback)
- Remove GenerateClassroomInput.language and job store inputSummary.language
- Remove unused pdfLanguageSample from outline SSE route
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: persist languageDirective to IndexedDB, fix TTS preview and dead refs
- Add languageDirective to StageRecord and stage-storage write path
- Add DB v9 migration: convert legacy language locale codes to directives
- Use voice.language for TTS preview text instead of dead localStorage key
- Omit empty ## Language section in PBL agent prompts
- Use JSON.parse for extractLanguageDirective unescape (\uXXXX support)
- Remove dead i18n keys: toolbar.languageHint, pbl.chat.welcomeMessage
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: preserve preset agent selection when switching classrooms
When switching from an auto-agent classroom to a preset classroom,
the stale generated agent IDs remained in selectedAgentIds because
the load path skipped setSelectedAgentIds when no generated agents
were found. Add a dedicated presetSelectedAgentIds field to persist
the user's preset preference separately from the runtime selection,
so auto classrooms never corrupt the user's saved preset choice.
Closes#239
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* style: format settings.ts with prettier
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: persist agent IDs in stage instead of global settings
Replace the global presetSelectedAgentIds approach with per-stage
agent storage. Each classroom now saves its selected agent IDs into
stage.agentIds at creation time, and restores them when the classroom
is loaded. This makes agent selection a per-classroom property rather
than a global setting that can be corrupted by auto classrooms.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* ci: retrigger CodeQL analysis
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>