Commit Graph
180 Commits
Author SHA1 Message Date
caa6ef0edc fix(settings): read data.error for image/video provider test results (#1459)
The verify routes return errors via apiError(), which serializes
{ success: false, errorCode, error } — but the image and video
settings panels read data.message, so every failed connectivity
test renders 'failed: undefined' and the real upstream error
(auth failure, model not open, bad base URL, ...) is hidden.

All other settings panels (ASR, PDF, provider-config-panel,
model-edit-dialog) already read data.error correctly.

Fixes #1457

Co-authored-by: SeanLiew <seanliew@SeanLiewdeMacBook-Pro-2.local>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-09-11 12:37:38 +02:00
Percyandwyuc 6eb9492652 fix(classroom): adapt complete page to short viewports instead of clipping (#1461)
The complete page centers its content in an overflow-auto flex section.
When the content is taller than the stage viewport (common on laptops),
the centered overflow clips beyond the scroll origin at the top — the
trophy is unreachable and the page opens mid-content.

Restore an adaptive compact layout: a ResizeObserver with hysteresis
(760/820px) toggles the page between full and compact forms so the
content always fits, and a dedicated inner scroll layer keeps the
decorative background pinned to the viewport when scrolling is still
needed. Add an e2e spec covering both layouts and trophy reachability.

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-09-11 12:37:27 +02:00
9fe650d994 fix(quiz): resolve AI answer keys to option values before grading (#1328)
* fix(quiz): resolve AI answer keys to option values before grading

AI-generated quiz answer keys are unreliable: the model may write the
correct answer as option CONTENT ("(6, 2)"), as a LETTER ("A"), or as a
formatting variant (full-width chars, extra spaces) of either. Grading
compares exact option values, so a learner picking the correct option
was still graded incorrect whenever the key was written as content or
in a different format.

- generation: normalizeQuizAnswer now resolves every answer variant to
  the matching option value (NFKC + whitespace-stripped + letter-prefix
  canonical matching against option values and labels); unknown answers
  pass through untouched
- grading: resolveAnswerKeyToValue retro-fixes already-generated courses
  whose stored keys hold content variants, mapping them to option values
  when exactly one option matches canonically; ambiguous keys are left
  alone instead of being silently re-pointed
- tests: letter/content/full-width/trailing-space/multi-answer/unknown
  cases + end-to-end grading with a content-variant key

* chore(generation): bump version to 0.3.2 for answer-key fix

The repo requires every publishable @openmaic package change to ship with
a version bump (CI check-package-version-bumps).

* style(generation): prettier-format package.json after version bump

* fix(quiz): use resolved answer representation in review renderers; prettier

- QuestionCard + quiz-view review modes highlight the option canonically
  matching the stored answer key (answerIncludesOption), so persisted
  content-variant keys highlight correctly after the grading fix
- prettier formatting on touched files

* test(quiz): guard possibly-undefined answer in multi-choice test

* fix(quiz): narrow answer-key matching to exact unique alignment; project review UI from the same resolver

Per review: matching policy narrows to the DSL option-identity contract.
- Generation: exact value or unique exact label alignment; unknown and
  ambiguous keys stay unresolved (fail closed). Prompt example unified to
  the DSL object-options + value-answer shape.
- Grading: persisted keys resolve via the same exact alignment; the
  resolver returns the option's actual value when exactly one option
  matches canonically-or-exactly; ambiguous keys stay untouched.
- Review UI: QuestionCard and both quiz-view review modes highlight via
  the same resolver projection (answerIncludesOption(q, optionValue)).
- Removed the broader equivalence rules (NFKC, whitespace stripping, case
  folding, wrapped/prefixed-letter probe) — semantic synonyms such as
  正交/垂直 remain uncovered, hence Refs #1326.

* fix(quiz): resolve answer keys for persisted keys only; align quiz template with the DSL

- grading: compatibility resolution (label -> value) now applies to the stored
  answer key only. A learner submission is compared as submitted, so an option
  label can no longer be accepted as a different option's value.
- quiz-content/user.md: replace the string-options/`correctAnswer` example with
  the DSL shape the system prompt defines ({ label, value } options and
  `answer` as an array of option VALUES), so generated keys are values.
- tests: regression that a label submission grades incorrect while the same
  question's value submission grades correct.

* test(generation): update scene-prompt golden snapshot for the DSL-shaped quiz template

The golden test pins the rendered user prompt for every scene kind; the
quiz-content template now emits the DSL shape, so the snapshot follows.

* fix(quiz): read label-stored correct answers in the editor's option rows

`quiz-edit-ops.toRows` decided correctness with raw value equality, so an
existing label-keyed quiz showed A/B as correct (the review UI and the grader
both resolve labels) while every row read as incorrect internally — and the
next option edit or reorder rebuilt `answer` from those rows and silently
dropped the key.

- `toRows` now uses the same resolved projection (`answerIncludesOption`).
- `normalizeQuizAnswer`'s docstring now describes the exact-only behavior it
  has had since the review: formatting variants are not normalized and
  ambiguous entries pass through untouched.
- Regressions: an unrelated option-label edit and an option reorder both keep
  a label-stored answer, and a multiple-choice toggle preserves it. All three
  fail against the previous raw comparison.

---------

Co-authored-by: CrazyPandaP <CrazyPandaP@users.noreply.github.com>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-09-10 23:28:20 +02:00
Yizuki_Ame 9104824b41 fix(slide): keep bottom table rows visible in classroom playback (#1366)
* fix(slide): keep table rows inside playback canvas

* fix(slide): preserve full-cell table alignment

* test(slide): focus table clipping regression

* test(slide): verify wrapped table geometry

* docs(slides): narrow table alignment contract
2026-09-04 06:04:25 -04:00
Rupam Pal 132d01cd04 feat(canvas): add double-click text insertion (#1310)
* feat(canvas): add double-click text insertion

* fix(ci): format canvas double-click text insertion

* fix(canvas): prevent text insertion on double-click of locked elements

- Add guard to check if double-click event target is inside an editable element
- Prevents text box insertion when double-clicking locked elements (backgrounds/watermarks)
- Fixes event-propagation bug where locked element selection handler returns before stopPropagation()
- Add regression test suite for canvas double-click handler covering locked elements and blank canvas cases

Addresses review feedback from CxuPercy on PR #1310

* fix: remove unused import in canvas-double-click-handler test

* fix: improve test implementation to avoid DOM dependency

- Rewrite tests to use mock objects instead of actual DOM elements
- Properly type MockTarget interface to satisfy TypeScript checks
- All tests now pass locally without DOM environment requirement

* test(e2e): add end-to-end tests for canvas double-click text insertion

- Add test for double-clicking blank canvas area to create new text element
- Add test to verify double-clicking existing elements does NOT insert new text
- Tests actual editor interactions, not just mock targets
- Addresses CxuPercy's review feedback for proper regression test coverage

* chore: format code with prettier

* test(e2e): simplify double-click text insertion test

- Remove flaky second test that checks element visibility state
- Focus on core functionality: double-click on blank canvas creates new element
- Use more lenient assertion (toBeGreaterThan) to account for dynamic elements
- Increase wait time for slide editor to fully render (1000ms)

* fix(storage): increase test timeout for replace/release operations

The 'replace retires rather than revokes an issued snapshot; release revokes both'
test performs multiple async operations (put, resolve, replace, release) that can
exceed the default timeout. Increased timeout to 10 seconds to accommodate I/O operations.
2026-09-03 11:35:30 +08:00
Mark Tranandwyuc 55e324768e fix: keep videos playing inline on mobile (#1321)
* fix: keep videos playing inline on mobile

Add playsInline to every playback video path, including the legacy app renderer, renderer-backed playback, and the shared renderer package. This keeps mobile browsers such as WeChat on Android from interrupting inline playback and restarting videos after an interruption.

Add regression coverage for both app renderer modes and the package renderer.

* chore(renderer): bump package version

* chore(renderer): bump package version to 0.1.6

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-09-02 02:36:47 -04:00
Yizuki_Ameandwyuc 3214cead2c fix(workbench): render LaTeX in assistant messages (#1309)
* fix(workbench): render LaTeX in assistant messages

* fix(workbench): harden streamed math rendering

* fix(workbench): preserve streamed math boundaries

* refactor(workbench): use standard math syntax

* fix(workbench): preserve math in course link labels

* fix(workbench): disambiguate single-dollar math

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-09-02 02:21:59 -04:00
Burak Keskinandwyuc 03bd449320 fix(settings): turn TTS and media generation on from the Settings page (#1311)
* fix(settings): turn TTS and media generation on from the Settings page

The global enable flags only auto-set on first provider sync, and Settings
had no switch for them, so a later API key never started narration or
image/video generation. Add the Settings toggles and turn each flag on
when that provider first becomes usable.

* fix(settings): route media enablement through isUsableMediaProvider

A force-disabled image or video provider could still flip the global flag
from a key paste, and keyless providers never did. Use the same usable
transition as TTS, including a baseUrl for lemonade and comfyui.

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-09-02 02:11:39 -04:00
Yizuki_Ame 9d16e68296 fix(workbench): persist Pro conversation titles (#1273)
* feat(storage): persist manual session titles

* feat(agent): add session title patch route

* fix(workbench): preserve renamed session snapshots

* fix: use typed session title store

* style(storage): format session title tests

* test(storage): align agent session schema contract

* fix(workbench): fence stale session title bootstrap

* fix(workbench): close session title races

* fix(workbench): harden session title consistency

* fix(workbench): preserve unconfirmed session titles

* fix: harden session title reconciliation

* fix: finalize session title consistency

* test(workbench): document session title recency
2026-08-31 04:21:01 -04:00
wyuc dfebbcf33f perf(classroom): speed up classroom loading (media hydration, sidebar thumbnails, media range requests) (#1276)
* perf(classroom): defer non-priority media blob hydration off the load path

Entering a classroom awaited the full mediaFiles restore — one object URL
per restored image/video blob — before the loading gate opened. For
video-heavy courses that is hundreds of MB of IndexedDB materialization
blocking first paint.

Split the restore into two phases:

- The awaited phase now builds metadata-complete task entries but only
  creates object URLs for failed rows (none needed) and for media
  referenced by the scene the classroom opens on (persisted cursor, else
  the first scene). buildRestoredMediaTasks gains an optional
  shouldHydrateBlob predicate, defaulting to eager hydration so existing
  callers are unchanged.
- Remaining blob-backed records hydrate in the background, chunked over
  requestIdleCallback (setTimeout fallback). Each deferred task stays
  'done' — so generation resume never re-runs it — but carries no
  objectUrl yet, which the media resolution state machine already renders
  as a pending skeleton until the URL lands.

Background hydration is guarded per record: a task that was replaced
(classroom switch, regeneration, retry) or that belongs to another stage
is skipped and its freshly minted URLs are revoked immediately.

* perf(classroom): lazy-render slide thumbnails in the playback sidebar

The playback scene sidebar mounted a full SlideCanvas for every slide
scene the moment the classroom opened (and every off-screen video element
opened a preload="metadata" fetch), because SlideThumbnail's existing
visible prop was never passed.

Extract the editor nav rail's near-viewport IntersectionObserver hook to
lib/hooks/use-near-viewport.ts and gate the sidebar's slide thumbnails
through it: only scenes within 200px of the viewport render the live
canvas; the rest show SlideThumbnail's existing placeholder until scrolled
near. The placeholder keeps the same box size, so gating never shifts
layout.

The shared hook now starts hidden instead of eager: with the previous
eager-initial state, opening a long deck still mounted every canvas for a
frame before the observer could flip off-screen items off. The observer's
guaranteed initial delivery flips near-viewport items within a frame; the
no-IntersectionObserver fallback (e.g. jsdom) defers to a microtask so
the effect never synchronously re-renders.

* perf(media): lazy image decoding and HTTP Range support for classroom media

Renderer: BaseImageElement's <img> now carries loading="lazy" and
decoding="async", so thumbnail-heavy surfaces (playback sidebar, editor
nav rail, course cards) no longer fetch and decode every slide image up
front. In-viewport images are unaffected — the browser fetches them
immediately. slideToPng forces eager loading inside its permanently
off-screen snapshot tree, where lazy images would otherwise never fetch
and exports would capture blank slides.

Server: GET /api/classroom-media/[classroomId]/[...path] now answers
single byte-range requests with 206 Partial Content (Content-Range,
Accept-Ranges, correct Content-Length), enabling progressive playback and
seeking for hosted video/audio instead of downloading whole files. Suffix
ranges are supported; unsatisfiable ranges get 416 with the full size;
unsupported units or multi-range sets fall back to the plain 200 full-body
response, which is always a legal answer. Existing caching headers are
kept on every response shape.

* chore(renderer): bump version to 0.1.4 for image lazy-loading change

* fix(classroom): guard deferred hydration against restarted tasks and bound idle waits

A deferred record is only ever 'done' without an objectUrl; a task that
regeneration or retry restarted passes through pending/generating, so skip
those instead of attaching stale persisted bytes. Also give the idle
scheduling a timeout so a busy main thread cannot starve hydration.

* fix(classroom): stop superseded deferred hydration before minting URLs

A restore epoch captured at apply time now gates each idle chunk: loading
another classroom or reloading the same one invalidates any older hydration
loop, so it neither keeps scheduling work for an abandoned classroom nor
attaches bytes read by an older load to a newer load's tasks.

* fix(classroom): keep 416s uncached and classify element-keyed media as priority

A 416 with public immutable caching can poison the media URL for later
valid requests, so range errors now send Cache-Control: no-store. Priority
classification also collects the opening scene's media element ids, since
task lookup binds records keyed stage:<elementId> even when the slide slot
carries a different opaque ref.

* fix(classroom): tie deferred hydration liveness to the classroom load token

The restore epoch only advanced when the next load reached apply, so an
abandoned classroom kept hydrating during the next load's storage/network
phase. Compose the epoch with the load's isCurrent (load token plus effect
cleanup) so navigation stops the loop at the next idle boundary.

* fix(classroom): classify legacy-recovered media before deferring it

Legacy singleton video recovery assigns a placeholderRef only at the end of
the task build, so a record keyed by an allocated id without placeholderRef
was deferred even when it backs the opening scene's gen_vid_* element. Run a
metadata-only build first to learn each record's effective ref and classify
against it, keeping the first visible page's legacy video eager.

* fix(action): wait for deferred video bytes before starting play_video

executePlayVideo treated status done as immediately playable, but a deferred
restore is done without an objectUrl: the renderer shows a skeleton, no
<video> exists, and the later hydration never retriggers play, leaving the
action stuck until the safety timeout. Readiness now follows the renderer's
contract (only done-with-bytes is playable) at the initial check, the
subscription exit, and the post-subscription recheck; the failed skip applies
whether or not a wait happened.

* fix(classroom): include the stage whiteboard in priority media refs

The stage-level whiteboard stays open across standalone classroom switches,
so its media can be visible before any scene is. Classifying it as deferred
left visible whiteboard media pending behind idle hydration chunks.
2026-08-30 03:48:04 +08:00
wyuc 64cfb3c90a fix(workbench): handle stale workspace resume memory (#1271)
Remember explicit workspace home visits and validate remembered session entries against the existing workspace session list before resuming. Stale entries now fall back to the workspace home and are forgotten.

Closes #1270
2026-08-29 20:36:10 +08:00
LING DUANandwyuc 9a28ca39d5 feat(chat): add single PPT element references to Pi (#1224)
* feat(chat): add PPT element references to Pi

* fix(chat): include chart values in reference routing

* fix(chat): harden slide element reference evidence

* fix(playback): clear element reference on scene navigation

* fix(pi): preserve element grounding across child retries

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-29 14:38:15 +08:00
c60198cb23 fix(export): recheck script readiness on download (#1159)
Co-authored-by: Bryan Nathan <bryan@users.noreply.github.com>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-28 14:56:15 +08:00
wyuc 67584fe9e8 fix(whiteboard): correct the inverted viewportRatio so boards render 16:9 landscape (#1257) 2026-08-27 20:39:26 +08:00
wyucandClaude Fable 5 04621578de release: OpenMAIC 1.0.0 — the agent workbench (#1228)
* feat(storage): add an agent-session store with PG backend and layered contracts (#1163)

* feat(storage): add agent-session store with PG backend and layered contracts

* test(storage): avoid BigInt literals for pre-ES2020 root typecheck

* fix(storage): close agent-session store review findings

* docs(storage): align hook ordering and contention-probe claims with the code

* ci: run on the agent-workbench integration branch

* chore(storage): bump to 0.5.0 for the agent-session store

* fix(storage): carry replay compaction across page boundaries

* feat(agent): add the driver model contract and stage route dialect (#1165)

* feat(agent): add the driver model contract and stage route dialect

* fix(agent): validate route context windows and clarify dialect precedence

* feat(agent): adapt the agent-session store and runtime foundations (#1167)

* feat(agent): adapt the agent-session store and runtime foundations

* feat(agent): resolve request owner identity via an anonymous cookie

* docs(agent): document the opt-in compaction default and harden edge cases

* feat(agent): add the background session runner (#1169)

* feat(agent): add the background session runner

* feat(agent): wire the runner into startup behind feature flags

* fix(agent): stop clean interruptions from consuming the attempt budget

* fix(storage): charge the attempt budget for abandoned leases but not clean parks

* docs(storage): document the attempt-charging contract and decouple its tests

* feat(agent): add agent session and owner event streams (#1170)

* feat(agent): add agent session and owner event streams

* fix(agent): close the session-existence oracle and document the owner seam

* feat(agent): add agent session lifecycle routes (#1171)

* feat(agent): add agent session lifecycle routes

* fix(agent): validate session-create input and preserve the owner cookie on errors

* refactor(storage): drop the unused active-stage API from the agent-session contract (#1174)

* refactor(storage): drop the unused active-stage API from the agent-session contract

Tools address stages explicitly on every call, so the store keeps no
mutable session-level stage pointer. Removes resolveActiveStage and
setActiveStage from the store interface, their PG implementations, the
active_stage_changed lifecycle event, the session_active_stage owner
event variant, and the contract tests pinning them. The active_stage_id
column and the DDL check constraint stay untouched for schema
compatibility.

* chore(storage): bump @openmaic/storage to 0.7.0 for the contract removal

* docs: document the agent runtime configuration surface (#1176)

* fix(agent): repair orphaned and late tool results across interruption boundaries (#1180)

* fix(agent): repair orphaned and late tool results across interruption boundaries

A crash, shutdown, or provider failure can leave the durable transcript with
tool calls that have no result, or with results ordered illegally for the
provider. Three failure modes were fixed:

- Orphaned tool calls: a run that died between an assistant tool-call frame
  and its result left a dangling call in the entry tree. Resume no longer
  synthesizes and persists receipts for it: interrupted results are a
  read-time provider view owned by a shared read-boundary repair, which
  returns the original array for a healthy transcript and never mutates the
  tree.

- Late parallel results: a parallel tool can finish while pi unwinds an
  aborted assistant frame, leaving result(A), assistant(aborted), result(B)
  in durable order. Strict providers reject non-contiguous results, so the
  read-boundary repair moves existing results next to their owning assistant
  frame (in call order), omits incomplete unwind frames, and synthesizes
  receipts only for genuinely missing calls.

- Interrupted calls at the write boundary: a call still in flight when the
  run winds down (shutdown, lease loss, cancellation, provider failure) had
  no receipt at all. The runner now tracks in-flight calls from their
  assistant frames and, before the terminal flush, appends an
  interrupted-result receipt for each still-orphaned call through the same
  attempt-fenced write chain, so a lease-stealing zombie never writes and
  the next claim sees a provider-safe transcript.

* test(agent): pin the runner wiring for interruption-boundary tool repair

* feat(agent): add neutral tool foundation libraries (#1184)

* feat(agent): register a web_search tool on the session runner (#1185)

* feat(storage): add a per-session URL trust gate (#1186)

* feat(agent): add the skills system (#1189)

* feat(agent): add the skills system (builtin directories and durable user skills)

* fix(storage): serialize the user-skill quota check-and-insert per owner

Two concurrent creates at the 50-skill boundary both counted 49 rows and
both inserted (READ COMMITTED, no lock), overshooting the quota contract.
The create transaction now takes a per-owner pg_advisory_xact_lock first,
and the same-name idempotency check runs before the count check so an
at-least-once retry of the create that committed as the owner's 50th row
still returns its durable receipt instead of a quota error. The 23505
backstop is retained for writes that do not take the lock.

* fix(agent): share unstorable-character validation and align skill lookup

* feat(agent): add session materials and a fetch_url tool behind the URL trust gate (#1190)

* feat(agent): add session materials and a fetch_url tool behind the URL trust gate

* fix(agent): harden session material fetching

* feat(storage): add an ownership scope to stage documents (#1191)

* feat(agent): add material read and search tools (#1192)

* feat(agent): add stage read and patch tools (#1194)

* feat(agent): add page generation and deck editing tools (#1198)

* test(storage): keep the PG contract suite order-independent (#1200)

* fix(agent): revoke deleted-session URL authority and reject private ISATAP endpoints (#1199)

* fix(storage): revoke deleted session URL authority

* fix(ssrf): reject private ISATAP endpoints in strict fetches

* chore(storage): bump to 0.11.1 for the session-URL authority fix

* feat(agent): add roster and voice registration tools (#1201)

* feat(agent): add folder organisation tools (#1202)

* feat(api): add stage and material HTTP routes (#1203)

* feat(workbench): add the client data layer (#1204)

* feat(workbench): add the client data layer

* docs(workbench): write the ported comments in English

* chore(edit): remove the in-editor agent panel (#1210)

* chore(edit): remove the in-editor agent panel

* style: apply prettier formatting

* fix(agent): report the runtime as unusable without a database (#1207)

* fix(agent): report the runtime as unusable without a database

* style: apply prettier formatting

* feat(agent): add image, video and pptx import tools (#1211)

* feat(workbench): add the agent chat surface (#1205)

* feat(workbench): add the agent chat surface

* docs(workbench): write the ported comments in English

* fix(workbench): label the folder and rename tools on the timeline

* fix(workbench): label the roster and voice tools on the timeline

The reconciliation test iterates every tool the runner registers and
requires a display label of its own. The roster and voice-clone tools
(list_voices, set_roster, clip_audio, register_voice) reached the
integration base with the roster/voice-registration tools but never
gained presentation rows, so they fell through to the default branch
and rendered their wire names. Port their rows from the reference
implementation (labels and i18n keys verbatim) and extend the
reconciliation allowlist with ROSTER_TOOL_NAMES and
VOICE_CLONE_TOOL_NAMES, so a future tool cannot enter the product
without a label.

* feat(agent): add the material extraction lifecycle (#1212)

* feat(storage): add material extraction lifecycle

* feat(agent): execute queued material extraction

* style: apply prettier formatting

* style: satisfy prefer-const in the extraction runner

* test: give material fixtures the extraction lifecycle fields

The media-tools slice and the extraction lifecycle slice were each green
in isolation but never compiled together: the lifecycle made derivedFrom
and extraction required on AgentSessionMaterial while the media-tool
fixtures predate them.

* chore: remove stray task notes

* fix(workbench): label the extraction lifecycle tools on the timeline

* feat(workbench): add the workspace shell (#1206)

* feat(workbench): add the workspace shell

* docs(workbench): write the ported comments in English

* i18n(workbench): align workspace keys across locales

* fix(workbench): adopt the landed data layer and label the extraction tools

- replace the sibling-slice seam stubs with the real data-layer modules
- drop ambient declarations now shadowed by landed files
- port timeline labels for the extraction lifecycle tools from the reference
- align the new i18n keys across all locales

* ci: retrigger

* feat(api): folder routes, stage-meta viewer surfaces, and the material upload contract (#1215)

* fix(storage): restore capability-based stage access

* fix(api): bind document access to request owner

* fix(agent): restore three-state stage access on the tool layer

Port probeStageAccess and the three-state StageAccess (owned / foreign /
missing / tombstoned) and gate every stageId-bearing stage tool on an owned
probe, mirroring the reference per tool:

- move_to_folder, rename_stage, read_stage_outline refuse a non-owned stage
  with the single not-yours message before touching the store.
- The course/DSL toolset and the roster toolset are wrapped by
  withOwnerStageAuthorization: read_stage, patch_stage, grep_stage and every
  writer refuse a foreign stage with the same message and refusal shape.
- Scene preview keeps its own probe and its own refusal text, and is
  registered beside the course toolset (never double-gated).
- The runner injects one probe factory at the three call sites.

Tests: the dsl cross-owner test premise (a foreign stage is readable by id)
encoded an invented capability-read policy that the reference does not have
at the tool layer; it now asserts foreign read/patch/grep are all refused
while the owner still reads. Curriculum cross-owner assertions were already
the reference's and now pass with the probes in place.

* docs: correct per-file test counts in the fidelity report

* test: fix type errors in stage-access fidelity test

* test: adapt media-tool and gate suites to the owner-scoped store seam

* feat(api): add owner-scoped course-folder HTTP routes

Port the reference implementation's /api/folders family (list, create,
rename, delete with ungroup/remove modes, and folder membership) onto the
owner-bound document store, replacing its provider-based auth with the
existing withRequestOwnerId / owner-scoped store seams.

The storage package's folder store grows the pieces the routes need:
DocumentFolder.order (schema column + max+1 assignment + ordering),
renameFolder, deleteFolder(mode) with captured member ids, and
setStageFolder(stageId, folderId | null) with idempotent un-filing.
FolderNameError moves into folder-name-validation.ts (stage-storage re-exports
it, keeping import sites intact).

Every route gates on the configured agent runtime (plain 404 when off or
unconfigured), keeps the reference's machine codes and envelopes, and is
covered by gate tests plus a behavior suite.

* feat(api): add stage-meta viewer surfaces for the classroom

Port the reference implementation's viewer-facing stage state — can-edit /
collected / published / generation-complete — on top of the stage-access
base (stage_meta + tombstones). stage_meta gains published_at and
generation_complete columns plus a stage_bookmarks table; the reference's
deployment-specific origin/claimed_at columns are stripped.

New gated routes: GET /api/stage-meta/[stageId] (per-viewer facts, 404 for
absent/tombstoned, never returns the owner id), GET /api/stages/[id]/status,
POST generation-complete / publish / unpublish (owner-only), POST
/api/bookmarks. The resolver lives in lib/server/stage-access.ts.

Wiring: a fetchStageMeta client with the reference's three-outcome contract,
stage-store isOwner/isBookmarked/readOnly fields (upstream single-user
defaults, no-op until the sidecar answers) plus setViewerAccess, the
classroom apply path computing readOnly = !(isOwner || isBookmarked), the
Stage editability gate, and a sidecar probe after each classroom load. A
sidecar 'absent' answer keeps the editable default here because the
classroom also serves local-only courses; server writes stay owner-enforced.

* feat(api): port the reference material upload contract

Rewrite POST /api/materials to the reference implementation's upload shape
so the workbench uploader (uploadWorkbenchMaterial, which posts no session
id and expects a flat 201 view) works unchanged: owner-scoped upload with
mime normalization/validation (415), per-class size caps checked on the
declared content-length and the streamed body (413), empty body (400),
quota (429), sha256 reserve->store->finalize lifecycle with abandon on
failure, flat { materialId, originalName, bytes, mime, extraction } 201,
and an x-request-id echo.

Adds the owner-scoped material library (owner_material table + quota +
24h lazy sweep, bytes in the host's asset registry as the neutral
replacement for the reference's object-storage byte path) and the material
cap configuration. The session-scoped GET list is left as-is; the
reference's owner-material extraction worker is not ported (the branch's
session-material extraction lifecycle already covers extraction).

Gate tests now cover all 23 persistence routes across the three runtime
env states; the materials behavior suite pins the new contract.

* feat(media): add an optional local ffmpeg media extractor (#1213)

Adds a local ffmpeg/ffprobe pipeline as a second media extraction
provider behind the extractor registry, ported faithfully from the
reference implementation: duration probing, keyframe-safe chunking,
per-chunk ASR with timeout and deadline budgets, and timestamped
transcript assembly.

- Availability probing feeds the registry's candidate selection: the
  provider simply is not a candidate when ffmpeg/ffprobe are absent.
- With neither ffmpeg nor a cloud provider configured, extraction fails
  with an actionable message naming both enablement paths.
- Media materials route through the same extraction lifecycle and lease
  fence as documents; no parallel queue.
- Tests inject the executable resolver so the missing-ffmpeg path is the
  default-tested one; the real pipeline test is skip-if-unavailable.
- @openmaic/storage 0.13.0 -> 0.14.0 (media routing in the material
  lifecycle surface).

* feat(storage): per-scene monotonic revisions via database triggers (#1214)

* feat(storage): per-scene monotonic revisions via database triggers

Restore the reference implementation's freshness granularity: a
per-scene monotonic revision maintained by database triggers, so every
writer (HTTP routes, agent tools, jobs, manual SQL) bumps it without
application cooperation.

- Companion revision tables + trigger functions in the storage package's
  idempotent schema bootstrap, with the lock-order invariant, pg_notify
  wakeup and the suppression switch for batch writers.
- ensureDocumentSchema gained a dollar-quote-aware statement splitter.
- The freshness and manifest routes serve per-scene revisions.
- Mutation-verified: dropping the triggers turns the revision tests red.
- @openmaic/storage 0.13.0 -> 0.14.0.

* fix: forward the freshness manifest through the owner-bound store

* feat(workbench): add the Pro entry points and preserve the mode-transition semantics (#1208)

* feat(workbench): add the Pro entry points

* feat(workbench): preserve Pro mode transition semantics

* fix(workbench): drop ambient declarations shadowed by landed slices

* fix(workbench): drop ambient declarations shadowed by the landed shell

* feat: port workspace shell sibling modules

Port the 16 leaf modules the Pro workspace shell imports but that were only
ambient-declared, replacing the compile-time bridge with real implementations
adapted from the sibling-slice reference: pure workbench helpers (session
title, rail tab, course-chat bootstrap, created-course tabs, course-tabs
memory, workspace navigation, pane navigation, pro-edit sizing,
existing-course minting, first-message session), the neutral brand context and
course-rename server API, the server-action session delete, the home
discovery hook, the classroom pane host with its load-policy leaf, the theme
toggle and floating-layer owner, plus the floating-layer-owner wiring the
dialog/dropdown/tooltip portals stamp.

Also add the workbench-shell locale copy for all 12 locales, port the
reference tests for the ported modules, and drop
types/workbench-sibling-slices.d.ts now that every declaration has a real
implementation.

* docs: keep ported comments in English and deployment-neutral

* docs: announce 1.0.0 and refresh the feature overview (#1216)

* docs: announce 1.0.0 and refresh the feature overview

* docs: finalize 1.0.0 README after feature merge

* fix(agent): control-plane routes answer 404, not 500, without a database

The agent control-plane routes gated only on the runtime flag, so an
enabled-but-unconfigured deployment (flag on, DATABASE_URL empty)
answered 500 from a store that cannot connect. Gate them on the
configured check instead, matching the stage/material routes: the
whole surface is cleanly absent until both the flag and the database
are present. The status probe keeps reporting both bits.

* test: mock both runtime gate exports in the control-plane route suites

* fix(agent): abort in-flight TTS on cancel and bound each provider request with a timeout (#1217)

The generate_tts / scene-tts path checked the runner's AbortSignal between
actions but never created the provider HTTP requests with it, so a session
cancel left a hung synthesis fetch in flight until a restart repaired the
tool result. Thread the signal end-to-end: TTSModelConfig carries an
optional signal, generateTTS combines it with a per-request timeout
(TTS_REQUEST_TIMEOUT_MS, default 30s, ported from the reference runtime's
TTS bounds) via AbortSignal.any, and every provider fetch (openai, azure,
glm, qwen incl. voice-clone + audio download, voxcpm, minimax, doubao,
elevenlabs, lemonade) is created with that signal.

A timeout now fails the tool call with TTSRequestTimeoutError (a clear
retryable error) instead of wedging the session; a caller cancel propagates
as the interruption so the runner settles the session as cancelled without
a restart.

Tests: hung-provider simulation rejects at the timeout with the retryable
error; abort mid-flight aborts the captured request signal and surfaces the
interrupted shape; removing the signal wiring makes the abort tests fail
(red), restoring them turns green.

* fix(workbench): PG-mode home listing via owner stages; keep the interrupted terminal course card (#1218)

Finding 1: with server persistence on, listStages resolved to the generic
GET /api/persistence/documents listing, which the capability model
deliberately answers 403 FORBIDDEN_DOCUMENTS for (reads by id, listings
owner-only). The home/workspace library now lists through the owner-scoped
GET /api/stages surface (same anonymous-owner cookie the workbench uses)
when server persistence is enabled; the server-side 403 is untouched.

Finding 2: a run interrupted (session_interrupted) and repaired
(session_resumed) that ends cancelled before agent_end stranded its pending
classroom sightings, so the timeline's terminal card lost the course the
answer produced. session_end (cancelled) now flushes the pending sightings
into the same course card set agent_end paints, before the stopped caption.

* chore(workbench): remove the bookmark concept and the saved-courses drawer (#1219)

* chore(classroom): remove the bookmark ('collected') concept entirely

The stage-meta viewer port introduced a bookmark surface (stage_bookmarks
table, POST /api/bookmarks, the isBookmarked sidecar field, and a
readOnly rule that let a saved course stay editable). The product has no
such concept, so remove it as a closure:

- delete the /api/bookmarks route and the stage_bookmarks table plus its
  query helpers from the persistence bootstrap
- drop isBookmarked from GET /api/stage-meta/[stageId]
- simplify the classroom read-only rule to readOnly = !isOwner across the
  sidecar client, ownership signal, classroom load, stage store and the
  classroom page
- keep publish/unpublish, generation-complete, isOwner and isPublic
  exactly as they were
- update the gate and stage-meta route suites and the README mentions

The workspace rail's Bookmark glyphs and comments describe the upstream
saved-courses (favorites) section, which is driven by isOwner and renders
no collect affordance; they are kept as unrelated homonyms.

* chore(workbench): remove the saved-courses drawer UI

The first pass removed the bookmark data model but kept the rail's
"Saved courses" drawer, judging it a separate surface driven by
`isOwner === false`. The home/workspace listing is owner-scoped, so that
flag can never occur: `allSaved` is permanently empty and the drawer
(plus the collapsed-rail Bookmark mini-button) is a dead affordance.
Remove it: the SavedDrawer component and its mount, the savedOpen /
savedSection state, the allSaved / matchedSaved derivations, the 'saved'
variant of the course-list renderers, the mini Bookmark glyph, the
drawer-only CSS, and the drawer's i18n keys from all 12 locales. The
courses tab is now exactly one folders tree.

The authored/favorites split in workspace-tree.ts goes with it; the tree
module no longer reads `isOwner`. The discovery course type keeps the
field — the shell still reads it for read-only gating.

Upstream has no collect concept; the drawer could only ever render empty
here. The reference implementation HAS this drawer (its favorites come
from its account system), so this removal is a deliberate upstream
product decision, not a fidelity bug.

* fix(workbench): restore the attach entry, add the rail settings entry, pin all three entry points (#1221)

* fix(workbench): restore the composer attach entry by gating it on the live runtime

The AttachButton's rollout probe read a `materialsEnabled` field that this
branch's /api/agent/runtime never answers (the materials routes gate on the
runtime itself, like the stages), so the gate could never pass and the attach
button never rendered — the Pro launch and chat composers showed only the
@-mention and enhance glyphs.

Substitute the field with the runtime's `enabled` value, which IS the upload
action's precondition: POST /api/materials answers 404 whenever it is false,
so the render condition now equals the action precondition (no dead button).

The button's label (`proMode.attach`) is a user-visible string that becomes
visible again; port the reference implementation's own translations verbatim
into the 11 locales that still carried the Chinese copy.

* feat(workbench): add the settings entry to the rail's bottom-left cluster

The reference's rail foot carries a cluster of utilities (its saved-courses
drawer, the language switcher, the display toggle). This branch removed the
drawer — it could only ever render empty here — and the product decision is
to fill that freed spot with the settings entry.

Add a settings trigger to the foot cluster (expanded rail, beside the
language and display toggles, and on the collapsed strip) and mount the
model/provider SettingsDialog in the rail, wired to the trigger. It is the
same dialog the classic home opens from its header pill; the workspace had no
settings entry of its own, so nothing is duplicated within a surface.

* test(workbench): pin the restored upload, attach, and settings entry points

Covers the three restored entry points:

- the courses-tab upload control: rendered beside the course name filter,
  wired to the discovery hook's ZIP import trigger, disabled while an import
  runs, and gated by the same condition as its action (the courses tab);
- the composer attach control: an actual render of AttachButton under both
  probe answers (visible when the runtime says the upload path is live,
  hidden otherwise), its mounts in the launch and chat composers, the
  branch's runtime-field substitution in the probe, and the reference's own
  `proMode.attach` copy in all 12 locales;
- the settings entry: the trigger in the rail's foot cluster (expanded and
  collapsed), beside the language and display toggles, opening the
  SettingsDialog the rail mounts.

* chore(config): the Pro workbench flag implies the MAIC Editor gate (#1223)

A workbench build without the editor toggle has no way to edit a course:
enabling NEXT_PUBLIC_PRO_WORKBENCH_ENABLED while forgetting
NEXT_PUBLIC_MAIC_EDITOR_ENABLED produced exactly that split-brain bundle.
The workbench IS Pro mode, so its flag now implies the editor gate; the
standalone flag remains for deployments that want the classroom editor
without the workbench. Documents both flags in .env.example.

* fix(agent): wake SSE tails and the runner on durable deltas (streaming fidelity) (#1222)

The Pro workbench chat did not stream: the session/owner SSE routes polled
the durable event log on a 5s/30s clock with no wakeup, so message_update
deltas (written at 150ms cadence) reached the browser in poll-sized blocks
and the thinking strip only mounted after the whole reasoning text had
accumulated.

Port the reference's LISTEN/NOTIFY delta path:

- storage: add in-transaction wake hooks (onSessionEventAppended,
  onOwnerEventAppended, onCancelRequested) so a host queues pg_notify in
  the same transaction as the durable append; align readEventsAfterForReplay
  to rank the bounded page so the first delta after the cursor is always
  kept (the live tail can never starve). Bump @openmaic/storage to 0.18.0.
- app: port the process-wide event-notify bus (dedicated LISTEN client,
  self-check probe, reconnect backoff; notify through the storage
  transaction surface), wire the store hooks, subscribe both SSE routes
  before the initial read with the reference's initializing gate, and give
  the runner one {kind:'session'} subscription whose wake runs the cancel
  check and the message drain. Polls stay as the lossy-NOTIFY backstop.
- lifecycle: start/stop the bus from instrumentation.

Tests: storage hook + compaction contract; route wakeup latency; runner
wakeup wiring with a fake agent; bus unit tests; PG contracts proving a
real append wakes the routes and a live SSE route forwards a message_update
on the wakeup, and that a rolled-back append never wakes. Also fix the
pre-existing park-attempt-budget PG test TRUNCATE (missing CASCADE against
newer FK tables).

* fix(storage): asset writes self-deadlocked against pooled PostgreSQL (#1225)

* fix(storage): refuse the non-transactional byte-write deadlock configuration

A byte store whose plain write() runs on its own pooled connection cannot be
invoked from inside a registry write transaction: after the transaction has
claimed the blob-row lock, that write blocks on the lock the transaction just
took while the transaction waits on the write - a self-deadlock PostgreSQL
cannot detect (one side is idle in transaction).

There is no lock-safe ordering for such a writer: bytes must be written after
the row claim (writing before it lets the collector delete the bytes while the
upsert waits), and any second-connection write after the claim is the
deadlock. The configuration is therefore detected and refused:

- AssetByteStore gains writesOutsideRegistryDatabase?: true, declaring that the
  layer's plain byte operations cannot contend for the registry's row locks.
- PgAssetStore refuses put()/replace() up front (and defends coordinatedWrite)
  when the byte store has no writeWith and does not declare the flag, throwing
  a clear configuration error before any row is claimed.
- The collector mirrors the guard on its delete path (deleteWith or a declared
  out-of-registry layer, else a configuration error).
- The object store declares the flag (its out-of-transaction write remains
  legitimate); the in-registry PostgreSQL byte column provides writeWith /
  deleteWith instead.
- Write transactions (put/replace/remove) set SET LOCAL lock_timeout = 30s so
  any future lock-contention variant fails loudly instead of hanging.

Bumps @openmaic/storage to 0.18.0.

* fix(persistence): forward the transactional byte methods through the lazy asset byte-store wrapper

The no-bucket case of lazyAssetByteStore returned a bare { write, read,
delete } and dropped writeWith/readWith even though the underlying
PgAssetByteStore has them. The registry's hasTransactionalWriter duck check
then failed and put() fell back to the byte store's own pooled connection,
which blocks forever on the blob-row lock the registry transaction just took
when the bytes live in the same PostgreSQL - the production self-deadlock.

The no-bucket layer is statically PgAssetByteStore, so its transaction-pinned
methods are forwarded eagerly (typed against the real signatures via
PgForwardedByteStore). The bucket case keeps its lazy-probing semantics: no
transactional writer exists there, the signed-URL method stays absent or lazy
exactly as documented, and the wrapper now declares writesOutsideRegistryDatabase
so the registry may run the plain write inside its transaction.

New tests pin the wrapper's transactional capability red-to-green and assert
put()/resolve() route byte traffic through the transaction-pinned queryable.

* fix(home): cap the generate-prep ingest drain at 3s so Generate never waits the full server budget

The classic home flow's Generate click drained in-flight ingests for the full
15s server budget. Cap the wait at GENERATE_DRAIN_CAP_MS (3000ms, documented as
a UX bound) and reuse the existing timeout fallback: sources that miss the cap
proceed on the legacy byte path and each late-resolving id is released.

* chore(storage): bump to 0.19.0 over the concurrently landed 0.18.0

* fix(agent): bound every tool call with a timeout; never resurrect a cancelled session (#1226)

* fix(agent): bound every tool call with a global timeout and settle it on cancel

A tool await that neither resolves nor rejects wedges the session forever:
the lease keeps heartbeating and the driver never reaches its next cancel
checkpoint. Race every tool execution (in buildAgent) against a hard budget
(OPENMAIC_AGENT_TOOL_TIMEOUT_MS, default 10 min, per-tool overrides for
known long runners) and against the caller's AbortSignal, so even a
signal-ignoring await cannot keep a cancelled session running.

On timeout the call rejects with AgentToolTimeoutError; the agent loop turns
the rejection into a structured error tool-result the agent can retry or
proceed from, and the abort signal is delivered to the tool's in-flight work
through a derived controller. Zombie-tool updates after settlement are
dropped.

* fix(storage): never re-lease a cancel-requested session; settle it as cancelled on claim

The claim scan treated a session with cancel_requested_at set as a normal
claim candidate: after a restart it re-leased the same session for attempt
N+1 and resumed generating despite the pending cancel. claimNextSession now
settles such candidates as cancelled under the claim lock (status cancelled,
attempt reset, lease and cancel request cleared, terminal session_end event
and owner projection) instead of leasing them, then keeps scanning.

Bump @openmaic/storage to 0.18.0.

* docs: takeaway-style 1.0.0 announcement with bilingual guide links

The 1.0.0 head is now a short takeaway block — badge links to the
official user guides (English and Chinese), five one-line highlights,
and pointers into Features and the workbench setup section — instead of
six dense paragraphs. The detailed provider-neutrality and freshness
notes move into the Features workbench section, phrased database-
neutrally (the announcement no longer names a specific database).
Release date corrected to August 27.

* fix(workbench): restore editor chrome, mode transition, streaming, materials, mentions, folders (#1229)

* fix(workbench): wire workspace folder routes

* fix(editor): restore reference workbench chrome

* fix(workbench): persist composer materials and course refs

* fix(workbench): preserve live reasoning frames

* fix(persistence): back off failed streaming saves

* chore(workbench): retire stale slice seams

* test(editor): cover element pin layer

* chore(storage): bump to 0.21.0 for the user-message ref/material fields

* chore(editor): translate ported code comments to English

* fix(agent): fence durable tool writes and consume cancel requests atomically (#1230)

* fix(agent): enforce provider force-off in agent tools and scrub vendor identity from tool results (#1231)

* fix(materials): serialize per-owner quota reservations and make crashed uploads reclaimable (#1232)

* fix(editor): resolve dock-bar i18n keys, remove dock height drag, wire element referencing (#1233)

* fix(workbench): send the opening session message exactly once with refs intact (#1234)

* feat(editor): port timeline TTS preview single-flight and voice-all state latching (#1235)

* fix(media): restore the reference classic media chain (#1236)

* fix(import): adapt imported PPTX canvas size so decks render without overflow (#1237)

* fix(editor): complete element referencing — renderer DOM contract and GenUI picking aligned with the reference (#1238)

* test(providers): reconcile the provider-config vendor-token debt count after the main merge

The integration line's AK/SK fallback for the managed document provider adds
occurrences that main's allowlist snapshot predates. Same mixed-composition
debt category the group already documents; no new vendor behavior.

* test(providers): reconcile vendor-token debt counts with the integration line

The main-merge brought main's neutrality-guard snapshot next to integration
features it predates (media-extractor fallback chain, local voice-profile
deletion semantics, the enabled-TTS helper). Same debt categories the guard
already documents; counts updated to the guard's own tally and two grouped
entries added. No new vendor behavior.

* fix(agent): carry reasoning through the completions dialect so the thinking strip renders (#1239)

* feat(skills): add Feynman and spiral curriculum methods (#1240)

* feat(agent): port missing reference tools and skills (parity audit) (#1241)

* feat(media): retire asset-registry wiring; media and materials follow the reference byte model (#1242)

* fix(classroom): center adapted canvases in the stage and send back navigation home during generation (#1243)

* feat(settings): skill management with real list, download, delete, and upload (#1244)

* feat(settings): skill management section with real list, detail, and zip download

* feat(skills): owner skill delete and upload across storage, API, and settings

* fixup! feat(settings): skill management section with real list, detail, and zip download

chore: neutralize a reference note in the settings header comment

* fix(media): persist origin-independent classroom-media references from the agent runtime (#1245)

* feat(editor): float the insert toolbar in the outer frame with collapse (#1246)

The insert strip was bounded to the slide card, so it could only ever sit on
top of slide content: the card's overflow clipped it and it could not be parked
in the padding beside the slide. Move it into the studio frame the element
picker's panel already roams (CanvasOverlayPortal + the frame selector), so both
canvas overlays share one bounding container and their handles behave the same.
While picking, the strip rises over the picker and goes inert, which is the
z-order CANVAS_OVERLAY_Z already documents.

Add a fold beside the grip: the chevron collapses the strip to that grip row and
back, with the buttons unmounted rather than hidden. The fold is session-local
state owned by EditShell, next to the drag offset, so a surface swap keeps it;
nothing is persisted. Expanding a strip parked at the bottom edge re-clamps
through the same bounds rule the keyboard move uses.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

* fix(workbench): align the chat timeline's left edge with the composer (#1247)

* fix(agent): fence session claims while an ask_user question is outstanding (#1248)

* fix(agent): settle-time rescue tracks real delivery instead of a count offset (#1249)

* fix(persistence): migrate owner_material to oss_key and drop legacy asset_id (#1250)

* docs(readme): surface the 1.0.0 user guide badges at the top (#1253)

* fix(workbench): show newly created folders in the sidebar without reload (#1254)

* docs(readme): add the release version prefix and drop the opt-in framing

* fix(workbench): single-source the chat gutter so timeline and composer share a left edge (#1255)

The transcript and the composer each established their own column: their own
`px-*` gutter and their own `mx-auto w-full max-w-*` centering wrapper. Equal
padding values were never enough, because the two columns are centered inside
different containing blocks — the transcript's is a scroll container, whose
content box is narrower than the composer footer's by the scrollbar's width:

  transcript text left = pad + (pane - 2*pad - scrollbar - measure) / 2
  composer box  left   = pad + (pane - 2*pad             - measure) / 2

The padding cancels out of the difference and what remains is `-scrollbar/2` at
every padding value, so the transcript sat half a scrollbar to the left of the
composer and tuning the two paddings against each other could not move it.

The column is now established once, by the nearest common ancestor of both
(`chatColumn`), and the scroll viewport and the composer footer are siblings
inside it that add no horizontal inset of their own. The cap carries the gutter
on top of the 760px reading measure, so the text column keeps its width. The
handed-over question row drops the padding that indented it past the agent's
prose; framed rows keep their own inner padding, which is what a card's border
sitting on the column edge means.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

* fix(workbench): lock pane-embedded classroom to edit mode (#1256)

The workspace right pane painted the full learning chrome — speed control,
play button, learner avatars, mic bar — for a course the agent had just
created, then flipped to edit once the first scene landed.

resolveStageChromeMode treated playback as the DEFAULT branch for a hosted
classroom, so every shortfall fell into it: a course whose tab opens at
stage_link time has no scenes yet, so currentSceneId is null and
isHostedSceneEditable is false. A folded pane parked the playback root
behind the fold and cross-faded it out over the pane on unfold, and a
failed editor chunk dropped into playback permanently.

Lock it at the pane instead of defaulting per entry path:

- WorkbenchPanelProvider — the single element that mounts a classroom into
  the workspace — publishes editPinned (visible && !playback). Every entry
  path passes through it, so none of them decides.
- The hosted resolution can no longer degrade to playback. Start Learning
  (workbenchLearning, new input, split out from pane visibility) is the one
  door; everything else resolves between the neutral loading shell and edit.
- Stage's chrome dispatch is exhaustive on chromeMode, so the playback root
  is no longer the else-branch of a condition about the current scene.

No flicker: chromeMode is resolved during render, and preloadEditor now
answers synchronously (isEditorPreloaded) so a remount with the chunk
already registered paints edit on the first frame. A failed import is no
longer cached forever, so the lock cannot strand the pane.

Standalone classrooms keep their stored mode unchanged.

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-27 19:26:25 +08:00
wyuc 98904c1c5d fix(providers): three silent-behavior fixes from the provider audit (#1196)
* fix(extract): fail loudly instead of silently falling back to MinerU Cloud

A request that selects the self-hosted MinerU extractor without a
configured base URL used to fall back to MinerU Cloud whenever a cloud
API key was available, sending documents to a third party without the
operator's knowledge. The cloud fallback now requires an explicit
operator opt-in (ALLOW_MINERU_CLOUD_FALLBACK, default off, documented
in .env.example); otherwise the route answers a 422 that names what was
configured (self-hosted MinerU) and what was unavailable (its base
URL), and points at both remedies.

* fix(media): remove the selectable video provider that has no adapter

The Sora entry in the video provider catalog could be selected in the
settings UI and server config, but had no connectivity or generation
dispatch case, so choosing it failed only at execution time. A catalog
entry that cannot execute is worse than an absent one: the entry, its
type-union member, UI names/icons, store defaults, and the VIDEO_SORA
env mapping are removed. A new catalog test pins that every selectable
video provider dispatches to its own adapter in both switches.

* fix(storage): delete the obsolete no-op storage provider abstraction

getStorageProvider() unconditionally returned a NoopStorageProvider and
the module swallowed every operation into silence, so any caller
believing it had storage got neither bytes nor an error. No real caller
exists anywhere in the repo (only lib/storage/client.ts, a separate
module with a documented null contract and a live caller, remains). The
dead entry point, its type file, and the no-op provider are deleted; a
test pins the removal and that the real client upload helper is kept.
2026-08-27 11:49:23 +08:00
wyuc b8fbac1a54 feat(providers): uniform capability force-off and consistent missing-key contract (#1181)
* feat(providers): uniform capability force-off and consistent missing-key contract

* fix(providers): close force-off bypasses found in review
2026-08-26 10:59:43 +08:00
wyuc e3fd494658 feat(tts): add Qwen TTS voice cloning (#1160)
* feat(tts): add Qwen TTS voice cloning via the registration adapter

* feat(settings): add Qwen TTS clone-voice manager

* fix(tts): harden Qwen voice cloning integration

* fix(tts): enforce voice-bound Qwen synthesis

* fix(tts): close Qwen voice clone tail issues

* fix(tts): close final voice clone review issues

* fix(agents): harden voice token parsing

* fix(settings): hide the voice-clone model from manual selection

* fix(agents): pin the narrator voice to the user's selected voice

* fix(agents): keep narrator fallback alive when the pinned voice is unusable

* fix(i18n): correct the narration fallback notice copy

* fix(tts): bound the narrator voice retry to a single fallback hop

* fix(tts): tolerate transient vendor errors in the voice existence precheck
2026-08-24 14:33:43 +08:00
wyuc 7dc51fa0de fix(editor): allow multi-tab edit mode by dropping the cross-tab edit lock (#1161)
* refactor(editor): extract enterEditMode from the Pro toggle

* fix(editor): drop the cross-tab edit lock

* chore(i18n): remove the multi-tab conflict strings

* docs(store): attribute order-rewrite safety to the regen lease
2026-08-24 12:27:35 +08:00
LING DUANandwyuc a0dccbe78d feat(pi): add Native Child additive whiteboard tools (#1156)
* feat(pi): add Native Child additive whiteboard tools

* chore(renderer): bump package version to 0.1.3

* fix(pi): reject invisible whiteboard mutations

* fix(pi): close native whiteboard review blockers

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-24 12:12:07 +08:00
wyucandClaude Fable 5 5a3e81c4d9 feat(document): ingest uploaded sources into the asset pool and extract by id (#1153 part 0) (#1154)
* feat(document): declare a version on every extractor provider (#1153 part 0)

* feat(api): accept asset-id input in the extract-document route (#1153 part 0)

* feat(upload): ingest selected course materials into the asset pool (#1153 part 0)

* fix(document): harden asset-id extraction inputs and close upload ingest leaks (#1153 part 0)

* fix(document): scope extraction fallback and harden the asset-id path (#1153 part 0)

- G1: byte fallback only on pre-extraction failures; PARSE_FAILED
  (422/500) is surfaced without re-running the paid extractor
- G2: freeze the course-material set for the duration of generate-prep
  (guarded add/remove + disabled toolbar affordances, session built
  from the click-time snapshot, belt-and-braces drain)
- G3: bound the pre-generation ingest await (~15s); timed-out ingests
  go byte-path and their late-resolving ids are released
- G4: reject non-object JSON bodies (null/array/string/number) as 400
- G5: JSON-path provider pre-validation with generic messages, generic
  JSON-path PARSE_FAILED/422 responses, control-char-free log values
- G6: size cap enforced via identify() before resolve() materializes
  bytes; too_large maps to the existing 413

* fix(document): mirror provider-hint semantics on the asset-id form and freeze prep-time controls (#1153 part 0)

* fix(document): keep the asset-id form's responses free of caller input (#1153 part 0)

Address review findings: answer the extractor-selection failure with a
generic static message on the asset-id form (the registry's interpolated
message carries the caller's MIME type; multipart keeps it verbatim, both
sides now pinned by tests), dedupe same-batch material additions by content
fingerprint inside the pure updater, document the network-error retry
exception in shouldRetryWithByteUpload's docstring, and fix a test name
asserting 500 but named 400.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-08-24 11:45:31 +08:00
Som SamantrayandCommandCodeBot 5dc023d92d feat(export): download narration script as Markdown or DOCX (#1144)
* feat(export): download narration script as Markdown or Word-compatible .doc

Adds two export-menu entries that download the classroom's TTS narration
text (SpeechAction.text per scene) as a local document for lesson prep,
closing #413. The .doc is a minimal HTML document with the Word MIME type
so no new runtime dependency is introduced; .md is the portable plain-text
sibling. Scenes without speech are omitted, HTML is escaped in the .doc
path, and file names are sanitized.

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>

* refactor(export): simplify narration script export hook

Reads stage store state at click time instead of subscribing per render,
drops unobservable exporting state (the handler is synchronous and the
menu-close is the reentrancy guard), removes a redundant empty-scenes
pre-check, and drops a type cast the discriminated union makes
unnecessary.

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>

* fix(export): apply code review findings for narration script

- Skip whitespace-only speech text when collecting scene scripts, so a
  blank course cannot download a heading-only document with a success toast
- Trim and filter empty paragraphs in the .doc serializer to match the
  markdown path
- Strip only dangerous control ranges in the filename sanitizer so emoji
  and ZWJ sequences survive (the broad \p{C} class was splitting surrogate
  pairs)
- Add unit tests for whitespace-only speech, HTML paragraph normalization,
  the <br> branch, emoji-preserving filenames, control-char stripping, and
  markdown whitespace filtering

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>

* fix(export): address review feedback on narration script export

- Decouple the export menu trigger from full media-readiness gating:
  script export (.doc/.md) now stays usable while media generation is
  still pending. PPTX/Resource Pack/ZIP/Video items keep the existing
  media-dependent gate, now with visible disabled state and a tooltip
  explaining why.
- Document the HTML-as-.doc format as a deliberate zero-dependency
  tradeoff (not an oversight) directly above buildDocHtml.
- Sanitize scene/stage titles before they're interpolated into
  Markdown headings, so embedded newlines or leading # runs can't
  inject extra headings or corrupt document structure.
- Localize the "Slide N" fallback label via the i18n system instead of
  hardcoding English, adding export.slideFallback (plus export.textOnly
  and export.mediaPending for the new UI states) across all 12 locales.

Addresses review from @wyuc on PR #1144.

* refactor(export): dedupe export-readiness derivation in header controls

canExport already implies canExportText once it ANDs the media-readiness
check on top, so the trigger's title/aria-label/readiness ternaries had two
independent copies of the same 3-way branch drifting apart. Derive canExport
from canExportText, and share exportReady/exportLabel between the button's
disabled, className, title, and aria-label props.

* fix(export): escape leading # in markdown headings instead of deleting it

Two issues found in code review: (1) a leading newline could shield a
leading # from the strip regex, then trim() would re-expose it unescaped
-- a real order-of-operations bug; (2) unconditionally deleting the
leading # run silently mangled legitimate titles like "#1 Introduction".
Escaping (\#) instead of stripping fixes both: content is preserved and
the character can no longer be mistaken for heading syntax, regardless
of what precedes it.

* fix(review): apply review findings

* fix(export): remove legacy doc script export

---------

Co-authored-by: CommandCodeBot <noreply@commandcode.ai>
2026-08-22 21:23:33 +08:00
LING DUAN 2cbe4ae293 feat(pi): add Native Child whiteboard tools (#1152)
* feat(pi): add native whiteboard tools

* style(pi): format native whiteboard tests

* fix(pi): clarify whiteboard CAS handoff

* fix(whiteboard): reconcile runtime projection on open
2026-08-21 18:07:49 +08:00
LING DUANandwyuc 0d308ed78d feat(pi): add Native Child Web Search (#1133)
* feat(pi): add native child web search

* fix(pi): align native web search with provider system

* fix(pi): harden native web search configuration and cancellation

* fix(pi): guide Native Child web search selection

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-19 10:35:44 +08:00
0ef3a1d17e fix(editor): prevent class roster cards from shrinking (#1135)
Co-authored-by: tmt <tmt@MacBook-Air-4.lan>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-18 14:25:23 +08:00
wyuc e15780835a feat(media): convert legacy references to allocated asset ids (#1101)
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
2026-08-15 17:38:04 +08:00
131af9c25a fix(access-code): refetch server providers after access code is accepted (#1081)
ServerProvidersInit fetches /api/server-providers on mount, which on an
ACCESS_CODE-gated deployment happens before any access cookie exists. The
middleware answers 401 and fetchServerProviders returns early, leaving the
settings store on its blank defaults. AccessCodeModal calls onSuccess without
reloading and nothing else calls fetchServerProviders, so every
server-configured provider reads as unconfigured for the whole session until
the user manually reloads.

Re-run the fetch from AccessCodeGuard's onSuccess, once the cookie makes the
request authorizable.

Co-authored-by: thanos-openclaw <thanos@openclaw.local>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-12 12:16:32 +08:00
Yizuki_Ame d1eeb95e1c feat(video-export): add deterministic Quiz question-list scrolling (#1102)
* feat(video-export): add deterministic Quiz question-list scrolling

* fix(video-export): bound Quiz layout measurement
2026-08-12 10:31:13 +08:00
969574bee4 feat(storage): wire the asset backend into the app (#1007) (#1089)
* fix(persistence): stop corrupting binary response bodies in the route adapter

The embedded persistence route bridges a Node `RequestListener` to the
Fetch API by hand. Its response object is cast with `as unknown as
ServerResponse`, so the compiler checks none of that surface, and two
parts of it were wrong in ways only a byte-carrying handler would hit.

`end` decoded any `Uint8Array` chunk with `Buffer.from(chunk).toString()`,
which is UTF-8. `ServerResponse.end` accepts a `Uint8Array`, and those
bytes are not necessarily valid UTF-8, so every unpaired byte became
U+FFFD -- silent corruption with no error anywhere. The adapter now
buffers chunks as bytes and builds the response from them.

`write` was absent entirely, making any chunked handler a runtime
TypeError rather than a compile error. It is part of the surface this
object claims to implement, so it is now implemented.

Neither reaches a caller today: the document and runtime handlers only
ever end with JSON strings, which took the string branch. Both are traps
laid for the first handler that carries bytes.

Both cases are pinned by tests that fail before this change -- the
binary one on a byte comparison, the chunked one with a 500 from the
TypeError. The existing adapter round-trip test, whose comment already
called this the most bug-prone code in the route, covered only the
string path.

* feat(storage): wire the asset backend into the app (#1007)

The server asset registry shipped with #1007 but was reachable from
nothing: the persistence route never passed an `assetStore`, and no file
under `app/`, `lib/` or `components/` imported the asset server or client
modules. This connects it, additively -- no DSL change, no version bump,
and no behavioural change when server persistence is off.

The route now builds a `PgAssetStore` on the same pool and transaction as
the document store, with `PgAssetByteStore` by default and
`S3AssetByteStore` when `ASSET_S3_BUCKET` opts a deployment into it. The
AWS SDK stays an optional peer, reached only through a dynamic import on
that branch. The offline collector is deliberately not scheduled here,
and the route says so where a reader would look for it, because leaving
it unscheduled grows storage without bound and scheduling it is the
deployment's decision.

On the browser side the asset pool gains a single-shot configuration seam
modelled on the document store's, so that with server persistence enabled
the pool is an `HttpAssetStore` carrying the same auth headers as the
other stores.

Three browser-specific mechanisms needed decisions rather than
translation:

`clearAssetPool` deletes an IndexedDB database today. In server mode
there is nothing local to delete, and a "clear cache" action must not
remove server-side assets -- that would destroy user data from a button
promising to free space. It now revokes local object URLs and closes the
client, and deletes nothing remote.

The cross-tab replacement broadcast is unchanged. Its job is to make
another tab drop a warm object URL when the bytes behind an id change,
and that need is identical in server mode.

The exclusivity proof that decides whether an in-place `replace` is safe
reasons over this browser only: local documents, unflushed state, and a
cross-tab presence probe. In server mode those cover a strict subset of
the holders, since another device can reference the same id and no probe
can see it -- and asking the server who else references an id would be an
existence oracle over other principals. The proof therefore returns not
exclusive unconditionally in server mode, and regeneration takes the
existing fork path. That is the fail-closed direction and a graceful
degradation rather than a break.

The development authenticator had to grow the asset principal's required
`key`; without it every asset request would have been correctly denied.
It derives from the same learner partition, and a principal without one
still gets no asset access. The route now states plainly that this key
comes from a client-supplied header, so the cross-principal isolation the
asset contract describes is not in force under this authenticator -- that
warning previously lived only in the auth module's own header, where
nobody mounting the route would see it.

* fix(storage): close three defects in the asset app wiring (#1007)

**The S3 branch could not load, and isolated nothing.** The route
dynamically imported the storage package's S3 byte store, but that module
statically imported the AWS SDK, so merely resolving it pulled the SDK
into resolution and bundling. The route then separately performed an
ignored native import of the SDK from the app's own scope, which fails
with ERR_MODULE_NOT_FOUND because the SDK lives under the storage
workspace package -- so a deployment that set the bucket got a broken
store rather than an S3 one. There is now one lazy loader in one
resolution scope, the storage module no longer imports the SDK at module
load, and the bucket is validated at initialization rather than treated
as valid because it is non-empty. A test mocks the SDK to throw on
resolution and asserts that importing the byte-store module never
resolves it.

**A cross-tab replacement could leave a mounted lease stale.** The
broadcast handler re-resolves, and `HttpAssetStore.resolve` coalesces
concurrent calls for one id onto a single in-flight request -- correct on
its own, and required by the contract. Together they meant a resolve
triggered by the broadcast could merge into a GET that started before the
peer's replacement, return the old revision, and leave the consumer on
the old URL with nothing to dislodge it. The client gains an invalidation
that retires its cached snapshot and advances the per-id generation
without revoking any URL already issued; `release` would have been wrong
here, since the contract keeps an issued URL valid until its holder
releases it. Removing the invalidation call fails the new race test.

**Clearing a server-backed pool left the closed client installed.** In
server mode `clearAssetPool` closed the client and returned before
clearing the module singleton, so every later `getAssetPool()` handed
back a closed store until a page reload happened to intervene. Only the
IndexedDB deletion is skipped in server mode now; the singleton is always
cleared so the next call rebuilds through the configured factory.

Also adds the tests whose absence let these through: a route round-trip
carrying invalid UTF-8, the SDK-resolution assertion above, the broadcast
race, and reopening the pool after a clear. The earlier tests were not
wrong so much as aimed past the defect -- the route test used JSON text,
and the S3 test injected a loader rather than exercising the imports.

* chore(storage): bump package version to 0.3.0

* fix(persistence): make the route adapter faithful where it carries bytes

The embedded persistence route bridges a Node `RequestListener` to the
Fetch API by hand, and its response object is cast
`as unknown as ServerResponse`, so the compiler checks none of that
surface. Five divergences are closed here; the first two are the ones
that corrupt data, the last three were raised in review.

**`end` decoded bytes as text.** It ran `Buffer.from(chunk).toString()`
on a `Uint8Array` chunk, which is UTF-8, so every byte outside that
encoding became U+FFFD -- silent corruption with no error anywhere. The
adapter now buffers chunks as bytes.

**`write` was absent**, making any chunked handler a runtime `TypeError`
rather than a compile error.

**`write` callbacks ran inline.** Node invokes them after the chunk is
handed off. A handler that writes its next chunk from each callback
therefore recursed synchronously and could overflow the stack, and a
throwing callback threw in the wrong execution phase. They are now
deferred.

**The encoding argument was ignored.** `write(s, 'latin1')` emitted
`0xc3 0xa9` where Node emits `0xe9`, corrupting the body and potentially
invalidating a `Content-Length` the handler had set. Both `write` and
`end` now parse their full overload set and pass the encoding through.
Node's own behaviour for an invalid encoding was established by probing
`ServerResponse` on Node 22 rather than assumed: it throws
`ERR_UNKNOWN_ENCODING` synchronously, so the adapter validates with
`Buffer.isEncoding` and lets `Buffer.from` raise the native error.

**Bodyless statuses were not suppressed.** Node discards writes after
`writeHead(204)` or `writeHead(304)`; this passed the buffered bytes to
the Fetch `Response` constructor, which throws for those statuses, so the
request became a 500 instead of the intended 204 or 304. Buffered data is
now discarded for 204, 205 and 304, and for `HEAD`.

None of the five reaches a caller today -- the document and runtime
handlers only ever end with JSON strings. They are traps laid for the
first handler that carries bytes, which is why they surfaced while
wiring the asset server backend, whose byte routes hit the first two
immediately.

Each is pinned by a test that fails when its fix is reverted.

* fix(storage): keep { client, bucket } working for the S3 byte store

`S3AssetByteStoreOptions.commands` was required and the store's methods
called it directly, so the published `./asset/s3-bytes` export stopped
accepting the `{ client, bucket }` construction it had always taken.
Anyone not going through `loadS3AssetByteStore` either failed to compile
or hit an undefined command factory at runtime.

Make `commands` optional. Omitted, the store resolves the AWS SDK's own
command constructors through a dynamic import on its first `write` /
`read` / `delete` and caches them, so `{ client, bucket }` works again.
Importing the module and constructing a store still never reach the
optional peer dependency: a deployment that does not select S3 never
resolves it. When the SDK cannot be resolved the call rejects naming
`@aws-sdk/client-s3` rather than crashing on an undefined property, and
the resolution is left uncached so installing the dependency fixes an
already-constructed store.

The lazily bound store is run against the byte-store contract, and the
new isolation tests pin both that construction does not resolve the SDK
and that an unresolvable SDK is reported by name.

With the break gone this branch's change to the package is additive, so
the version becomes a patch above main (0.2.4 -> 0.2.5) rather than the
minor it was carrying.

Refs #1007

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(persistence): run the asset collector in the shipped deployment

`PgAssetStore.remove`, and a `replace` that changes content, only stamp
`asset_blobs.unreferenced_at`. `AssetCollector.collect` is the only path
that deletes anything, and the persistence route deliberately did not
schedule it, on the grounds that scheduling is the deployment's decision.

The deployment this repository ships is docker-compose.yml: the app and
PostgreSQL, and nothing else that could make that decision. "The
deployment decides" therefore meant "it never runs", and ordinary asset
churn retained PostgreSQL bytes or S3 objects forever.

Schedule it from instrumentation.ts, which Next runs once per server
process — a route module can be instantiated more than once and has no
shutdown hook, so a schedule started from one is really started per
instantiation. Next 15 and later pick the file up with no config, so
next.config.ts is unchanged.

Collection is on by default with a 15-minute interval and the package's
one-hour grace period, so the Compose stack is correct with no operator
action. ASSET_COLLECTION_INTERVAL_MS, ASSET_COLLECTION_GRACE_MS, and
ASSET_COLLECTION_ENABLED change or disable it, each documented where it
is read. Without DATABASE_URL nothing is scheduled at all, and a failed
pass is logged and retried on the next tick rather than ending the
schedule or the process.

Several instances may collect concurrently: each candidate blob row is
re-checked and locked FOR UPDATE inside its own transaction, so
collectors serialize on the row rather than racing. The comment says so,
so nobody adds a distributed lock that is not needed.

The byte-store selection moves to lib/persistence/asset-byte-store so the
collector reclaims through the same layer the request path wrote through.
A collector on the PostgreSQL byte store while the route wrote to S3
would drop the blob row and orphan the object permanently.

Refs #1007

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(storage): bound each collector pass and report whether it filled

An unbounded collect() is sized by however long a deployment ran before
collection was scheduled: one statement selecting every eligible blob,
then a transaction and a byte-layer delete each, in a loop nothing
interrupts. The first pass over the Compose deployment that grew a
backlog before collection was scheduled is exactly that pass.

A pass now takes at most batchSize blobs (default one thousand) and
returns. Ordinary churn between two scheduled passes is far below the
cap, so a healthy deployment behaves as it did when a pass was
unbounded; a capped pass costs the remainder one scheduling interval,
which is what the interval is for.

collect() still answers with the count, and the count alone cannot tell
an empty backlog from a full batch -- a re-referenced or concurrently
taken candidate is skipped, so even a full batch can collect less than
batchSize. collectPass() returns the count together with capped, which
is exactly "this batch was full, run again"; a caller draining a
backlog loops while it is true.

Candidates are taken oldest-unreferenced first, with the content hash
as tiebreaker within one timestamp. Ordering by the hash alone would
starve: digests are uniformly distributed, so a high-sorting blob
waits behind every lower digest stamped after it, and under steady
arrivals those keep coming. The tests pin the ordering against a
planner that happens to answer the right rows without an ORDER BY.

Refs #1007

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(persistence): keep asset backend faults off the shared handler

Two review findings on the app wiring.

A concrete asset pool instance is single-lifecycle, but
resolveConfiguredAssetPoolStore handed the same object out again after
clearAssetPool() had closed it, reinstalling a dead store as the live
pool. The second handout now refuses loudly and points at the factory
form, which rebuilds on every resolution.

createPersistenceHandler eagerly awaited the asset byte store, so an
invalid ASSET_S3_BUCKET or an unresolvable AWS SDK rejected the shared
persistence handler and took document and runtime traffic down with an
optional backend. Byte-store construction is now deferred to the first
asset byte operation, and a failed construction is not cached, so the
next asset request retries -- the route's own no-poisoned-singleton
rule.

Refs #1007

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-11 13:01:16 +08:00
xuyuanwei678 c38da84ef6 feat(renderer): decouple editor UI from the app (#1072)
* docs: define renderer editor task 1 integration

* docs: plan renderer editor task 1

* feat: gate renderer slide editor

* feat: adapt renderer editor intents

* feat: connect renderer editor to slide surface

* test: complete renderer intent shape fixture

* fix: restore renderer editor action previews

* fix: render editor alignment guides

* perf: smooth renderer element dragging

* feat: align renderer hidden element behavior

* feat: add renderer canvas host commands

* feat: add renderer canvas context interactions

* test: cover renderer context menu interaction

* fix: preserve renderer canvas interaction semantics

* docs: design renderer text editing

* docs: plan renderer text editing

* feat(renderer): add ProseMirror text core

* feat(renderer): add rich text editor controller

* feat(renderer): render editable text in place

* feat(renderer): enter text editing on click

* feat: connect renderer rich text editing

* feat: finalize renderer text edit lifecycle

* fix: stabilize renderer text edit commits

* fix(renderer): move elements from selected borders

* docs: design renderer editing UI text toolbar

* feat(renderer): publish editing UI contracts

* feat(renderer): add controlled text format toolbar

* style(renderer): format editing UI contracts

* fix(renderer): address Task 2 review findings

* fix(renderer): handle zero font sizes in toolbar

* feat(renderer): add editing UI color picker

* fix(renderer): address Task 3 color picker review

* fix(renderer): commit native color input changes

* fix(renderer): coordinate native color picker interaction

* feat(renderer): anchor text toolbar to canvas elements

* feat(renderer): compose editable canvas with text UI

* feat(editor): use renderer text toolbar UI

* fix(renderer): make editing UI tests type-safe

* fix(renderer): harden editing UI integration

* feat(renderer): add editable text UI

* feat(renderer): add image and shape editing

* feat(editor): extend renderer editing controls

* feat(editor): add renderer chart insertion

* docs: design renderer latex editor

* docs: plan renderer latex editor

* feat(renderer): add latex editor contract

* feat(renderer): add latex editor dialog

* feat(renderer): compose latex insert and edit UI

* feat(editor): integrate renderer latex editing

* fix(editor): consolidate latex toolbar actions

* fix(renderer): show toolbar hover labels

* test(renderer): cover localized latex tooltips

* chore(renderer): hide latex sample palette

* feat(renderer): add video editing controls

* docs: define renderer audio editing

* feat(renderer): render audio elements

* feat(renderer): add audio editing UI

* feat(renderer): add preview audio controls

* feat(editor): add renderer element clipboard

* feat(renderer): decouple editor UI from app

* chore(renderer): release 0.0.6

* fix(renderer): clear editor CI gates

* fix(editor): adapt renderer canvas to media resolution API

* fix(i18n): complete French editor labels

* fix(renderer): hide toolbar vertical overflow

* chore(renderer): address review cleanup

* chore(docs): remove planning artifacts from pr

* feat(editor): add transactional core package

* chore(editor): ignore local test cache

* build(editor): publish core entrypoint

* refactor(editor): route renderer changes through transactions

* refactor(editor): split renderer editing into editor package

* ci(editor): register editor package for release

* docs(editor): document package dependencies

* ci: rerun validation after editor release registration

* test(editor): validate deletion against existing element

* fix(editor): address transaction and package review findings

* fix(editor): validate transactions and restore editor styles

* fix(editor): protect required updates and react styles

* fix(editor): validate required transaction fields

* fix(editor): prevent insert popovers shifting canvas

* refactor(editor): own renderer editing capabilities

* fix(editor): harden editing transaction boundaries

* refactor(editor): modularize editor UI integration

* docs(editor): harden third-party integration

* fix(editor): preserve video resize aspect ratio

* fix(editor): discard text draft before deletion

* fix(editor): preserve renderer picking and line presets

* chore(editor): remove unused pick-layer import
2026-08-10 19:56:24 +08:00
PercyandPercy b8bba7653e feat(courses): add folder grouping (#1005)
* 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>
2026-08-10 17:56:56 +08:00
wyuc 3b4567076f refactor(generation): consume the package everywhere and delete lib/generation (#1090)
Part D of #1057 — the switch. All consumers import @openmaic/generation; lib/generation deleted (net -11,900 lines). PBL wiring preserved (single-call -> classified fallback -> injected loop), streaming outline route deduplicated onto buildOutlinePrompt, serverExternalPackages wired, and the change verified by a real-model four-kind end-to-end run against the production build with a rendered-classroom screenshot check. Closes #1057.
2026-08-10 03:58:33 -04:00
5d5acd6215 feat: claude search (#393)
* Added search tool support for Claude

* New locales for i18n

* Updated translations

* Prevent default web search base URLs from being prepopulated

* fixed coding style issues

* fixed coding style issues

* fixing lint errors

* fix: add SSRF protection to fetchPageContent in claude.ts

Agent-Logs-Url: https://github.com/joseph-mpo-yeti/OpenMAIC/sessions/099e53fb-e1db-49f4-af7f-4f17cb3d364a

Co-authored-by: joseph-mpo-yeti <55380155+joseph-mpo-yeti@users.noreply.github.com>

* fix: address all remaining review feedback from PR review thread

Agent-Logs-Url: https://github.com/joseph-mpo-yeti/OpenMAIC/sessions/e1ab8fe2-fe0d-45a5-a0af-30945b99c268

Co-authored-by: joseph-mpo-yeti <55380155+joseph-mpo-yeti@users.noreply.github.com>

* fix: rename ambiguous variable names in settings store for clarity

Agent-Logs-Url: https://github.com/joseph-mpo-yeti/OpenMAIC/sessions/e1ab8fe2-fe0d-45a5-a0af-30945b99c268

Co-authored-by: joseph-mpo-yeti <55380155+joseph-mpo-yeti@users.noreply.github.com>

* fixing lint errors

* fix: address 5 items from second PR review thread

Agent-Logs-Url: https://github.com/joseph-mpo-yeti/OpenMAIC/sessions/09469d80-8e91-449b-8bc2-9c11f83555df

Co-authored-by: joseph-mpo-yeti <55380155+joseph-mpo-yeti@users.noreply.github.com>

* fixing model verification error

* fix: address 3 items from third PR review thread

Agent-Logs-Url: https://github.com/joseph-mpo-yeti/OpenMAIC/sessions/0aa49d19-df5b-4a08-a7e1-2295ae9cfc38

Co-authored-by: joseph-mpo-yeti <55380155+joseph-mpo-yeti@users.noreply.github.com>

* fixing lint errors

* fix: resolved Copilot review comments

* fix: returning string promise for ssrf-guard

* fix: returning string promise for ssrf-guard

* fix: updated locales, added allowed_callers for claude search tools, handle duplicated claude model keys

* fix: updated locales, added allowed_callers for claude search tools, handle duplicated claude model keys

* updated tests

* using Anthropic SDK for search and connection test in search settings.

* uses @ai-sdk with a custom fetch including allowed_callers in payload instead of adding Anthropic SDK as a direct dependency

* fixed format

* removed @anthropic-ai/sdk as direct dependency

* fix: resolve TypeScript errors in claude web-search tests

Cast mock.calls through unknown to avoid tuple-index type errors on
Vitest mock objects whose parameter types are inferred as empty tuples.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat: add Claude as a web-search provider on the multi-provider framework

Forward-port of the original Claude web-search work onto main's
searchWeb dispatcher, per review guidance on #393:

- lib/web-search/claude.ts: searchWithClaude via the AI SDK Anthropic
  provider and Anthropic's native web_search server tool, called through
  callLLM for usage accounting. Returns the model's answer plus cited
  sources deduplicated by URL. The page-content enrichment fetch from the
  original PR is removed entirely, resolving the P1 SSRF finding (no
  server-side fetches of attacker-influenced result URLs remain).
- allowed_callers: ["direct"] is still injected at the fetch layer; the
  AI SDK's provider-defined web_search tools do not emit it.
- Tool version picked from the model: web_search_20260209 for 4.6+
  Opus/Sonnet, basic web_search_20250305 for Haiku/older; maxResults maps
  to the tool's max_uses.
- Registry/dispatcher/route wiring: claude provider entry, claudeModelId
  passthrough (web-search route, classroom generation, generation
  preview), WEB_SEARCH_CLAUDE_* env config with server-pinned model via
  WEB_SEARCH_CLAUDE_MODELS, and client base-URL allowlisting for
  api.anthropic.com.
- Settings: per-provider modelId with a model selector in the Claude
  panel; locale keys added to all ten languages.
- Tests: new adapter suite plus claude cases in the dispatcher,
  constants, route, provider-config, web-search-config, and settings
  store suites.

Closes #392

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E9KqAGmKCtBwMC4HtT4JKE

* fix(web-search): trim whitespace around the Claude API key and base URL

Keys are pasted by hand into Settings, and nothing in the client key
path trimmed them: a trailing newline or space was sent verbatim as the
x-api-key header value and came back from Anthropic as 'invalid
x-api-key', with nothing in the message pointing at whitespace.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(web-search): correct Claude adapter tool selection, base URL, and timing

Addresses the four P2 review findings on #393:

- Route dated Claude 4.0 ids (claude-sonnet-4-20250514,
  claude-opus-4-20250514) to the basic web_search_20250305 tool. The
  blocklist regex missed them, so they were sent web_search_20260209,
  which pre-4.6 models reject. Replaced with an allowlist of the models
  that have dynamic filtering, so unrecognized ids also fall back to the
  basic tool -- the safe direction, since 4.6+ models accept both.

- Pin allowed_callers: ["direct"] only on web_search_20250305. Injecting
  it into every request disabled the code-execution caller that provides
  dynamic filtering on web_search_20260209.

- Normalize the bare Anthropic root to /v1 before handing the base URL to
  the SDK, which appends /messages verbatim and would otherwise 404. The
  adapter is the single choke point for the client allowlist, the server
  env var, YAML, and the default; other hosts pass through untouched.

- Return responseTime in seconds, matching every sibling adapter's
  WebSearchResult contract instead of exposing milliseconds for Claude.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-08-09 07:34:12 -04:00
wyuc 0ae21aa559 refactor(pbl): retire v1 write path and dead UI, converge on v2 (#1060)
* refactor(pbl): retire v1 write path and dead UI (#1058)

Remove the legacy generator, renderer branches, chat API, and compatibility mirror writes.

Keep stored v1 scenes readable through documented legacy adapters, and surface ordinary PBL planner double failures instead of degrading.

* fix(pbl): contain planner failure to the scene, support legacy scenes in action regeneration, tighten legacy guards

- Contain typed planner failures per scene while preserving retry and skip behavior.
- Upgrade legacy PBL content before regenerating scene actions.
- Apply video-export import boundaries to legacy readers.
- Harden legacy rendering and empty-state handling.
- Restore legacy upgrade compatibility coverage.
- Remove retired translations and refresh fallback narration and legacy cover documentation.

* fix(pbl): keep tolerant legacy configs renderable, guard invalid chat timestamps

* chore(dsl): bump to 0.6.3 for README accuracy fix

The README no longer references the deleted PBLProjectConfig symbol; the version gate requires a bump for any publishable package input change.

* fix(pbl): harden legacy upgrade and persistence contract

* fix(pbl): align action prompt with v2 workflow and validate project containers

* fix(i18n): remove retired PBL v1 keys from the new fr-FR locale

The fr-FR locale landed on main after this branch removed the v1 UI key families; prune the same 38 keys so all 10 locales align with en-US.

* fix(generation): sync packaged pbl-actions template with the v2 wording

The generation package that landed on main carries a byte-identical copy of the app's pbl-actions template; sync the v2 rewording and bump the package version.

* fix(pbl): normalize legacy content and preserve planner status

* fix(pbl): propagate provider status and ground action prompts

* fix(pbl): classify planner failures for retry, default the project summary prompt input

* fix(pbl): fall back to legacy data when v2 payloads are damaged, harden summary building

* refactor(pbl): resolve hybrid content through a validity-aware resolver

* fix(pbl): keep one v2 acceptance criterion across validator, resolver and persistence

Persistence gates on the same container predicate as the validator and the renderer's resolver: payloads the renderer will not treat as v2 are inert bytes everywhere, avoiding runtime side effects for documents the write barrier would reject. An explicit null proficiencyAssessment stays processable.

* fix(pbl): require runnable projects and harden legacy fallback

* test(pbl): exercise the real save reload and hydration chain

* fix(pbl): require an instructor and usable microtasks before v2 takes precedence

* fix(pbl): fall back to the loop planner unless the provider failed or the user cancelled

* fix(pbl): require role and task identities before v2 takes precedence

Runtime normalization can repair status and create the instructor thread, but it cannot synthesize the role id that binds the thread, the microtask ids used by lookup and update paths, or the labels the workspace renders. The runnable predicate and its video-export mirror now require them, so identity-less payloads fall back to usable legacy data.
2026-08-08 23:26:17 -04:00
ceb05adb41 feat(media): allocate generated assets through the registry (#1007 part 2, step b) (#1039)
* 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>
2026-08-06 18:49:34 +08:00
wyuc 3f5c51bdba refactor(pbl-v2): split the planner core from the loop; inject the LLM call path (#1069)
Implements #1062. Pure planner-core extracted from the loop's file; both planners receive their LLM entry as a parameter (call sites pass the real callLLM unchanged); operations/ split into kernel vs runtime with a lint-enforced boundary; planner prompts pinned byte-identical via fixtures generated from the pre-refactor implementation.
2026-08-06 05:28:56 -04:00
zhifu gaoandLauraGPT 2b3f2eaa37 feat(asr): add local FunASR provider (#1044)
Signed-off-by: LauraGPT <199134975+LauraGPT@users.noreply.github.com>
Co-authored-by: LauraGPT <199134975+LauraGPT@users.noreply.github.com>
2026-08-05 03:03:56 -04:00
xppcnnandwyuc 378579e9df fix(slide-renderer): keep arrowheads visible when toggling thumbnails… (#1045)
* fix(slide-renderer): keep arrowheads visible when toggling thumbnails or fullscreen

* fix(renderer): bump version to 0.0.5

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-04 22:57:04 -04:00
Nguyễn Lê TrườngandClaude Opus 5 4f20c5151a fix(i18n): translate ASR provider names in the generation toolbar (#1028)
The provider dropdown in the media popover rendered `p.name` straight from
`ASR_PROVIDERS`. That field is a registry label, not a UI string, and
several entries are written in Chinese:

    browser-native  →  浏览器原生 ASR (Web Speech API)
    qwen-asr        →  Qwen ASR (阿里云百炼)

So a user on any non-Chinese locale saw Chinese in the toolbar, while the
settings dialog showed the same providers correctly — it resolves the name
through `t('settings.providerBrowserNative')` and friends.

The id→i18n-key tables move to `lib/audio/provider-display.ts` and both
surfaces use them, so they cannot drift apart again. The settings dialog
keeps its own handling of custom providers, which carry a user-supplied
name rather than an i18n key.

TTS is included in the shared module for symmetry (`doubao-tts` and
`qwen-tts` have the same problem), though the popover's TTS tab is
currently a toggle with no provider list.

Image and video groups in the same popover also render `p.name`, but those
registry labels are already English, so no user-visible string changes;
left alone to keep this focused.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-03 06:04:49 -04:00
杨慎 6f6b6eca07 fix(editor): localize Pro mode right rail labels (#1023)
* fix(editor): localize pro mode right rail labels

* fix(i18n): translate AI editor title

* fix(i18n): localize Korean roster classmate label
2026-07-31 05:30:02 -04:00
f378c25a53 feat(storage): route settings/user-profile persist through KVStore (no legacy migration) (#1001)
* feat(storage): route zustand persist through KVStore

The settings and user-profile stores persisted through zustand's default
`localStorage` storage, while the rest of the app's small keyed values had
already moved to `@openmaic/storage`'s `KVStore` — two unrelated mechanisms
over the same browser API, which is the split-brain the storage RFC set out
to remove. `kvPersistStorage` shipped with the package but had no importer.

Add `lib/store/kv-persist.ts`, the app seam that adapts a `KVStore` into a
zustand `PersistStorage`, and wire both stores to it under an explicit
`account` scope. Store logic is unchanged: `version` / `migrate` / `merge`
still belong to the stores, only the bytes' destination moves.

Existing installs are adopted rather than orphaned. On first read the seam
moves the raw `localStorage` entry into the KV scope — write first, then
drop the raw key, so an interrupted migration leaves the value readable
from one side or the other but never from neither. Once KV holds the entry
it is authoritative, so a stale raw entry reappearing cannot roll back
newer state, and re-running can neither duplicate nor resurrect anything.
An entry that is not a readable persist envelope is left exactly where it
is.

Hydration is now asynchronous, because a `KVStore` may be remote. The
browser backend resolves within a few microtasks of the store module being
evaluated, so nothing user-visible changes, but tests that assert on
persisted state now await `persist.rehydrate()` instead of relying on a
synchronous read.

The four pre-persist keys (`llmModel` / `providersConfig` / `ttsModel` /
`selectedAgentIds`) are deliberately untouched: they are read-only inputs
to a migration that never owned them, and `providersConfig` is still read
independently by `lib/ai/providers.ts`.

Part of #857.

* fix(storage): close the async-storage failure modes in the KV persist seam

Cross-review found that routing `persist` through an asynchronous store
opens failure modes a synchronous `localStorage` never had. Each one below
is now covered by a test that fails without its fix.

Data loss on a failed or empty hydration. A KV read that threw was
indistinguishable from an empty scope, so the store stayed on defaults
while an always-on initializer's `set()` persisted those defaults; the
next load then read them as a completed migration and deleted the raw
original, leaving nothing. Reads now separate "nothing there" from "the
backend could not answer": a failed read serves the raw entry read-only,
adopts nothing and deletes nothing, and leaves the key unwritable for the
session so no un-hydrated state can be persisted over an original. Raw
entries are additionally only dropped against a recorded completion
marker, so a KV entry of unknown provenance can never authorize deleting
the only copy of the user's data.

Lost adoption across tabs. A reader whose KV read answered before another
tab's adoption write, and whose localStorage read landed after that tab's
delete, saw nothing in either place and hydrated defaults. Against a
remote backend that interleaving is ordinary rather than rare, so an
apparent "nothing anywhere" is now re-checked before it is believed.

Out-of-order writes. Two rapid `setItem`s could complete in either order
and let the older value win. Reads and writes are serialized per key.

Pre-persist migration resurrecting on every load. `migrateFromOldStorage`
was guarded by the existence of the raw `settings-storage` key — the very
key the migration removes — so once the blob moved into the KVStore it ran
on every load and republished whatever the pre-persist keys still held,
including API keys the user had since deleted, into first-frame state. It
is now the persist layer's last-resort source instead of a synchronous
read in the store initializer: its result is adopted like any other
migration, so the adopted entry is the marker that stops it. Initial state
is plain defaults, and nothing stored reaches observable state before the
storage layer has vouched for it. The source keys are still only read,
never deleted, since `lib/ai/providers.ts` remains a reader.

Also: KV reads and writes are guarded so a corrupt entry surfaces instead
of throwing through zustand's silent catch; clearing the cache now clears
the migrated stores through their own storage, which a server-backed
scope would need and a blanket `localStorage.clear()` would only appear to
do; `removeItem` drops the KV copy before the raw one; and the e2e suite
gains post-migration steady-state coverage, which every existing spec
missed by seeding the pre-cutover key.

Part of #857.

* fix(storage): scope migration bookkeeping to the device, gate writes on call

Second review round. The findings shared one root cause: two of the three
sentinels recorded a fact about *this machine's* files but were stored
beside the data, in the store's own scope. Under a syncing `account`
backend that is a category error with teeth — one device's history would
travel to another and authorize deleting files it says nothing about.

Sentinels are now always `device`-scoped and carry a reserved `__` prefix,
whatever scope the store uses. The worst combination this closes: device A
migrates, its marker syncs, device B — which has never run this build —
loads and deletes the raw entry that is still the only copy of its own
settings. A test drives exactly that sequence against two devices sharing
one account scope and nothing else.

The pre-persist fallback gains a device sentinel of its own. Its source
keys are device-local and deliberately left in place, so "KV and raw are
both empty" was not a safe trigger: clearing the account entry, from the
cache button or a server-side wipe, let any device re-read those keys and
republish credentials the user had rotated. It is now consulted at most
once per device, and `removeItem` deliberately does not clear that
sentinel — clearing the entry is precisely the case it exists for. The
fallback also no longer writes the adoption marker: that marker is a
licence to delete a raw persist entry, and the fallback has adopted no
such thing. Were it written, a raw entry later restored by an older bundle
would be deleted unread.

The write gate is now read when `setItem` is called rather than when its
queued turn arrives. Evaluated inside the queue, a write issued during
hydration waited behind `getItem`, found the gate opened by the very read
it raced, and persisted its pre-hydration snapshot on top of the stored
value.

Refused writes are no longer a dead end: the first one asks the store to
rehydrate, since the backend may have recovered, and if that does not work
the user is told through a durable notice rather than losing every change
on reload. Each refusal is logged, not just the first — a once-per-session
warning hides how long a session has been silently unsaved.

`removeItem` now propagates backend failures, so clearing the cache cannot
report success for a clear that did not happen, and that flow reloads
immediately instead of leaving a window in which a background `set()`
re-persists the credentials just deleted.

Also: the recovery hook is bound after each store is constructed, because
naming the store inside its own definition made its type circular and
silently widened every selector to `any`; the `serial` comment no longer
claims an unreachable rejection handler; and the pre-persist version stamp
documents that it skips `migrate`'s unversioned normalization too, which
`merge` redoes anyway.

Part of #857.

* refactor(storage): make the KV persist seam a per-key state machine

Three review rounds kept turning up the same defect class in new places:
a backend failure read as "there is nothing there", and the result of an
operation that nobody looked at. Patching instances of it was not working,
because both are possible whenever a call site is free to decide for itself
what a failed operation meant. This makes that decision unavailable to
call sites.

Every backend call now returns an `Outcome` whose payload is a private
field and whose only reader demands a `KeyState`. Feeding the machine is
not a convention to remember; it is the only way to get the value out.
What comes back is the value or `UNAVAILABLE` — deliberately not `null`,
so "the backend could not answer" is not spellable as "nothing is there".
The machine then decides, in one place, what failure means: any read
failure is unavailability, any write failure closes the key, and either
raises the health signal and asks for recovery.

The scattered closure flags (a settled set, a warned set, a recovery
latch) become one explicit phase per key — unhydrated, settled,
unavailable, clearing — with the transition table written out in the
docstring and a test per row.

What that consumes:

- A write failing after the key settled used to be ignored; its outcome
  now closes the key, signals, and the value is remembered for replay.
- `removeItem` enters `clearing` synchronously at call time, so a `set()`
  racing a clear cannot be admitted, queue behind the delete, and write
  the just-deleted value back. Nothing is replayed across a clear.
- The pre-persist sentinel is recorded by *every* settling path, not only
  the one that consults the old keys. A device that had only ever loaded
  an already-populated account entry recorded nothing, and so stayed
  eligible to republish its own stale credentials the moment that entry
  was cleared — which the docstring already claimed it would not.
- Two places treated a failed read as an answer: the sentinel read that
  decides whether the fallback runs, and the confirming re-read before
  adopting. Both now stop.
- An adoption whose marker did not land no longer settles, and never
  deletes the raw entry: no proof, no licence.
- Refused and failed writes are remembered and replayed once storage
  recovers, but only when the store was holding real data at the time —
  replaying a snapshot taken over defaults would overwrite the stored
  value, which is the failure this seam exists to prevent. When a
  snapshot cannot be replayed the user is told, because rehydration is
  about to discard those edits.
- Health notices publish on a later task, so a recovery that lands
  moments later cancels a warning nobody should have seen, and a
  subscriber mounting after the failure is caught up once its toast host
  exists. `StorageHealthNotice` now sits after the `Toaster` for the same
  reason.

Also: adoption re-reads before committing so a concurrent write is not
rolled back; a shadowed raw entry is only deleted if it parses, matching
the promise never to delete bytes we could not read; the unavailable copy
points at the control that resolves it rather than suggesting a reload
that cannot; and the version pin, the pre-persist retention rationale, and
the cache-clear comment say what is actually true.

Part of #857.

* fix(storage): separate the contexts settle() was conflating

Convergence round on the state machine. The findings share a root: settle()
treated every read that concluded as licence to open the key, without
asking what else was true at the time.

- A read finishing while a clear is outstanding no longer settles. Under a
  remote backend a recovery rehydrate in flight during a clear is ordinary,
  and opening the gate there admits a write that queues behind the pending
  delete and restores the credentials just removed. Only finishClear opens
  a cleared key.
- The raw entry served read-only after a failed read no longer counts as
  the authoritative value. A shadowed raw entry is by construction the
  older copy — long-term coexistence with a newer KV value is a designed
  state — so an edit taken against it must never be replayed, or one
  transient read failure on one device rolls the whole account back.
- A write that lands supersedes an earlier failed one. Both were admitted
  before the key closed, so the queue ordered them; replaying the older
  snapshot on recovery would undo the newer value.
- Unreachable browser storage is a failure, not an empty store. Privacy
  modes make localStorage throw; treating that as "nothing stored" hydrated
  defaults, refused every write and said nothing until the user reloaded
  and found the work gone. SSR stays a silent no-op.
- The recovery latch re-arms when storage answers, so the three recovery
  transitions are not empty promises from the second failure onward.
- A refusal carries the phase it happened in. Cold-start timing — an
  always-on initializer writing before the first read resolves, on a
  backend that never failed — is a log line, not a sticky red toast; only
  a refusal under `unavailable` reports lost changes.

The health channel stops delivering stale catch-ups: its timers are
cancellable and re-read the current state when they fire, so a recovery
cannot be overtaken by a warning with nothing left to dismiss it. And
`changes-lost` is now a fait accompli rather than a condition — a later
recovery has nothing to retract and leaves it standing.

Also: a throwing `localStorage` is unavailability rather than absence
wherever the raw entry is read; clearing records the pre-persist sentinel
like every other settling path, making that docstring true; the raw entry
is dropped before the marker so a failed marker clear leaves something
inert; and the pre-persist fallback and its four source reads can no
longer throw into zustand's silent catch.

Part of #857.

* fix(storage): hold a replay until it lands, and prove a raw copy before deleting it

Three failure-path corners.

A replay was retired the moment its write was attempted. Readable but not
writable is a real state — a quota-exhausted backend answers reads
perfectly — so a recovering read could succeed, the replay write fail, and
the snapshot be gone with nothing owed: the next rehydrate served the older
stored value over the user's edit and said nothing. The snapshot is now
held until the write is durable; a failed replay goes back to being a
refused write, so the next recovery tries again and a permanent failure is
eventually reported.

The adoption marker was treated as proof that a raw entry is the
migration's leftover. It proves only that a migration happened on this
device once. A rolled-back deployment, or a tab still running the old
bundle, writes the raw key again with settings the migration never saw, and
the next load on the new bundle deleted them unread. A raw entry is now
dropped only when its content equals the value shadowing it — anything else
is data, and keeping a copy beats deleting an original here as everywhere
else in this file.

`changes-lost` was being cancelled by a later recovery. The two statuses
answer different questions: "storage is down" describes the world now and
stops being true when storage works, while "your edits were lost" describes
something that already happened and no amount of recovery undoes. They are
now tracked on independent lines per key and rendered as two toasts with
distinct ids, so retracting the fault cannot take the acknowledgement with
it; the loss notice goes away only when the user closes it.

Part of #857.

* fix(storage): bound recovery, keep a live store from walking backwards

Three interactions the state machine did not have an answer for.

Recovery had no budget. A backend that reads but cannot write — a
quota-exhausted one does exactly that — turned it into a treadmill: the
recovering read succeeds, the key settles, the replay write fails, and that
failure asks for recovery again, forever. Attempts now follow a backoff
schedule whose length is the cap, and the budget is re-armed only on real
progress: a settle that left nothing owed. A settle reached *by* a recovery
with a replay still queued is not progress, and counting it as such is
precisely what made every lap look like a fresh start. When the budget runs
out the key is left read-only and the loss is reported, rather than
retrying where nobody can see it failing.

A failed read could walk a live store backwards. Once a session has loaded
the authoritative value, a transient read failure was still falling back to
the shadowed raw copy — which is legitimately older, and legitimately
long-lived now that a differing raw entry is kept rather than deleted — and
handing it to zustand overwrote a live store with stale data. Worse, the
store had already latched "holding real data", so edits made on top of that
stale value counted as replayable. A failed read after an authoritative one
now returns nothing, which is exactly "keep what you have", and the raw
fallback stays where it belongs: the case where nothing authoritative has
been seen at all.

Dismissing a lost-changes toast only closed the UI. The key stayed in the
lost set, so the same store losing changes a second time was swallowed as a
duplicate and any later subscriber resurrected a notice the user had
already dealt with. The close button now clears the latch, so a second loss
is reported and an acknowledged one stays gone.

Part of #857.

* fix(storage): close the last two provisional and clear-ordering gaps

An abandoned migration was handing back an authoritative value. When the
confirming re-read fails, or the adoption write does, `adopt` returns the
raw envelope unadopted — the same footing as the raw copy served after any
other failed read — but it was returned bare, so the store latched "holding
real data" and an edit taken on top of it counted as replayable. Another
device publishing to the account scope in that window would have been
rolled back. `adopt` now reports provisionality like every other read path,
and the shape is a named `LoadedValue` so the next path cannot forget.

Clearing swallowed a failed raw-entry deletion. The account entry was
already gone by then and the marker was cleared afterwards, so the
operation reported success while leaving an empty scope beside a live raw
entry — precisely the shape the next hydration re-adopts, handing back the
settings the user had just deleted. The raw entry now goes first and its
failure propagates, which also fixes the ordering: failing before anything
is removed leaves the KV value authoritative and the clear simply
unperformed, which the caller can retry. Adoption keeps the tolerant
variant, where a leftover raw entry is a duplicate rather than a loss.

Part of #857.

* fix(storage): make the shadowed-raw delete atomic against a concurrent tab

cosarah reproduced a data loss: both raw-entry deletes verified the value,
then awaited (reading or writing the adoption marker), then removed the key
by name. A tab running an old bundle — which takes no Web Lock, so a lock
could not have helped — overwrites the raw key with newer settings during
that await, and the unconditional `removeItem` then deletes the newer value.

The raw side is synchronous `localStorage`, so the fix needs no lock. Both
deletes now finish every await first, then run a single synchronous
compare-and-delete: re-read the raw bytes, and remove only if they still
equal the exact string that was verified. A competing tab is a separate
context whose writes surface here only at event-loop boundaries, so its
write lands wholly before the re-read (seen — bytes differ — kept) or after
the remove, never in between. A changed value is newer data, not a
migration leftover, and is kept.

Both sites cosarah named are covered: the shadowed-cleanup path
(`dropShadowedLegacy`) and the adoption cleanup in `adopt`. `readLegacyEntry`
now carries the exact bytes alongside the parse so the re-check is
byte-exact rather than comparing a re-serialized value. The clear path's
delete is unchanged: it is a deliberate full delete, not a conditional
leftover cleanup.

Part of #857.

* fix(storage): stop deleting the raw entry — adopt by copy (Plan B)

Maintainer decision after cross-vendor + red-team review: `localStorage`
has no cross-process atomic compare-and-delete (the storage mutex was
dropped from the spec), so a tab on an old bundle can insert a write
between our re-read and our removeItem in a genuinely parallel process. The
synchronous compare-and-delete narrowed that window but could not close it
— as its own comment admitted. Since the raw-cleanup cannot be done safely
on localStorage while an old bundle may be live, this stops doing it.

Adoption is now a copy: the value is written to KV and the raw entry is
left in place. The delete race is therefore impossible — there is no
delete. KV stays authoritative (once it holds the value, reads take the KV
path and never consume the raw one), so the shadow duplicate is inert,
left for a wholesale raw-cleanup at migration exit.

Removed with the two deletes:
- `dropShadowedLegacy` (its only job was the gated delete) and its three
  call sites.
- `deleteLegacyIfUnchanged` and the `{raw,value}` shape of the legacy read
  (`readLegacyEntry` → back to `readLegacy` returning the value).
- The adoption marker (`__persist-adopted:`), whose only reader was that
  delete gate. It did not prevent re-adoption — the presence of the KV
  value does — so removing it breaks no invariant. `dropRaw` / `expectedRaw`
  on `adopt` and the marker-clear step in the clear path go with it.

The clear path (user deletes all data) still deletes the raw entry
strictly — that is a deliberate full delete, not a migration cleanup.

Tests: the delete/marker cases become "the raw shadow always survives, KV
is authoritative"; a two-device and an old-bundle-concurrent-write case
guard it, and re-adding a delete on either adoption path turns them red.

Part of #857.

* fix(storage): add a monotonic migrated marker to stop shadow resurrection

Cross-vendor + red-team review independently caught a P1 the previous
"adopt-as-copy" revision introduced. Because the raw entry is now kept and
writes only ever reach KV, the raw copy becomes a frozen pre-cutover value.
If the account KV is later emptied by something other than a local clear —
a server-side wipe, an account switch, KV eviction — the next load saw
`stored === null` beside a live raw entry and re-adopted that stale copy,
refilling the wiped account with ancient settings/credentials and syncing
them to every device. Deterministic, not a race; it would fire once a
server-backed account backend exists.

Root cause: "keep the raw entry" inherently requires a record that it has
already been migrated, so an empty-KV load can tell "first migration" from
"external wipe". Removing the old delete-authorization marker in the copy
revision dropped that record — Plan B was only half done.

Adds a monotonic, device-scoped `__migrated:<name>` marker:
- Read on every load. `stored === null` + raw present + marker set ⇒ respect
  the wipe, do not adopt (fall through to the confirm re-read, so a
  concurrent repopulation is still served). Only a genuine first migration
  (no marker, raw present) adopts.
- Written best-effort after a successful KV write. A failed write degrades
  to the KV value's own presence check, so resurrection needs both a failed
  marker write and a later external wipe.
- Read failure fails closed (do not adopt), never "assume not migrated".
- Monotonic: only ever set true, cleared only by a deliberate full clear —
  no compare-and-delete race, which is why it is safe where deleting the raw
  entry was not. Live state with a real reader, not the delete-authorization
  marker removed earlier.

The clear path clears the marker too (back to a genuine first-load state);
best-effort, since with the raw entry already gone a leftover marker is
inert.

Tests: resurrection guard (external wipe does not re-adopt; concurrent
post-wipe write is served; first migration records the marker; marker read
fails closed) + the clear-path marker clearing. Mutation-checked: removing
the gate resurrects the shadow, dropping the record leaves it unguarded.
P3: the inert `__persist-adopted:` test rot is retargeted to the real
`__migrated:` path.

Part of #857.

* refactor(storage): remove automatic legacy migration — pure KV wiring

Maintainer decision (terminal): after repeated review rounds kept finding
new P1s in the legacy-adoption path — its state space is too large to keep
correct — the PR is narrowed from "migrate + wire" to "wire only". Settings
and user-profile persist through the KVStore; pre-cutover data is not
migrated; an upgrading user reconfigures once (the data is reconstructable
and the cost is one-time).

Removed the entire legacy-adoption subsystem from the adapter:
- `adopt()`, `readLegacy()`, the `legacyStorage` dep, and the raw-fallback
  read on a failed KV read.
- The `__migrated:` marker and its resurrection guard, the confirm-re-read,
  and the `provisional`/`LoadedValue` machinery.
- The `prePersistFallback` dep, `recordPrePersistHandled`, the
  `__pre-persist-consulted:` sentinel, and `readSentinel`/`writeSentinel`.
- In settings.ts, `readPrePersistSettings` (the llmModel/providersConfig
  reader wired as that fallback) — reading legacy keys is migration, which
  this PR no longer does. `lib/ai/providers.ts` still reads `providersConfig`
  independently, so those source keys are left in place.

The adapter now reads and writes the KV scope and touches no legacy key: an
empty scope hydrates the store to defaults (ordinary zustand). `load()` is a
single KV read; a failed read stays unsettled so defaults are never
persisted over an unread value; the clear path removes only the KV entry.

Kept, because they are async-storage *steady state* a remote KV backend
needs, not migration scaffolding: the KeyState machine (hydration gate,
write gate, recovery, replay), the Outcome discipline, per-key
serialization, and the persist-health channel.

Added `purgeLegacyPersistKey`: a best-effort, fire-and-forget removal of the
old raw persist blob, called once by each store. Never read, so a leftover
is pure garbage — and the old settings blob held plaintext provider API
keys, so clearing it is a small security win.

Net: the adapter drops ~460 lines. Tests are rewritten to steady-state KV
coverage plus an explicit "old raw key is ignored, not migrated" proof at
the store level; the e2e seed fixtures move from the raw key to the KV scope
key.

Part of #857.

* docs(storage): align README and comments with the no-migration behavior

Follow-up requested on the approved PR: the migration/adoption logic was
removed, but a few comments and one README roadmap line still referred to
those deleted concepts. Documentation only — no behaviour change.

- README roadmap: the settings/user-profile line said "adopting their
  pre-cutover raw keys"; it now states there is no automatic migration
  (legacy keys ignored and best-effort purged, users reconfigure once).
- kv-persist.ts: the per-key serial chain comment no longer claims to keep
  "adoption" from interleaving; it serializes a key's read/write/clear.
- settings.ts: `SETTINGS_PERSIST_VERSION` no longer documents a
  "pre-persist fallback" that no longer exists.
- Test/fixture headers that described seeding "the pre-cutover raw key" for
  "one-time adoption" now describe seeding the KV `account` scope, with no
  legacy-key migration.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(storage): bump version to 0.1.1 for README doc alignment

The README is a publishable input, and the no-migration doc alignment
changed it, so the package version must increase. Patch bump: documentation
only, no code or API change.

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>
Co-authored-by: wyuc <zdq1204@gmail.com>
2026-07-30 15:12:51 +08:00
Yizuki_Ame 23a9e757d5 refactor(choreography): drive overlays from descriptors (#947)
* feat(choreography): add Motion descriptor adapter

* fix(choreography): harden descriptor lookups

* fix(choreography): preserve descriptor special keys

* refactor(choreography): drive overlays from descriptors

* fix(choreography): preserve spotlight fade easing

* fix(choreography): align descriptor consumers

* docs(choreography): clarify spotlight easing
2026-07-29 09:12:37 -04:00
LING DUAN 61a7154f07 feat(pi): add evidence-aware Director context runtime (#971)
* feat(pi): add evidence-aware Director context runtime

* fix(web-search): require completed native search

* fix(orchestration): preserve whiteboard across agent handoffs

* fix(pi): remove wrap-up turn bypass
2026-07-27 11:38:41 -04:00
xuyuanwei678andwyuc ff95e6683d feat(renderer): add optional playback canvas (#958)
* feat(renderer): add optional playback canvas

* style(renderer): format playback tests

* fix(renderer): center text by default

* fix(renderer): address playback review feedback

* docs(renderer): align playback canvas API docs

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-07-27 04:15:07 -04:00
杨慎andClaude Opus 4.8 6d29241bb0 feat(video-export): fidelity polish — spotlight geometry, video clips, formulas, subtitles (#952)
* fix(video-export): bridge play_video element id → media ref

Generated-media records are keyed by the element's media ref (gen_vid_…),
but a play_video action targets the slide element by its .id. The app-side
compiler deps looked media/durations up by the raw element id, so every
generated video missed → present:false → no <video> emitted, no bytes
collected → the clip vanished from the export (only its static first frame,
baked into the base PNG, remained).

Build an elementId → mediaRef bridge across all slide scenes in
createVideoTimelineDeps (mirroring the live engine's resolveMediaPlaceholderId)
and resolve both media() and videoDurationMs() through it.

Refs #867.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): re-measure KaTeX fit-scale after fonts settle

KaTeX sizes large delimiters (\left\{, \begin{cases}) from its KaTeX_Size
faces, which load asynchronously. KatexContent measured its shrink-to-fit
scale once on mount, against the fallback font, and never recomputed — so a
cold slide snapshot baked a stale scale and the big brace desynced from the
piecewise body ("大括号后面的分段函数与大括号错位").

- Re-run the fit-scale measurement on document.fonts.ready and on each
  `loadingdone`, keeping the shrink-only (cap-at-1) behavior.
- slideToPng waits two extra frames before capture so the font-triggered
  React re-measure commits into the DOM html2canvas reads.

Refs #867.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): place spotlight/laser/video on the rendered content box

The pure geometry helper resolves an element's authored outer box against a
fixed 1000×562.5 base, but the live overlays — and the exported frame PNG —
measure the element's `.element-content` box, which for horizontal text is
auto-height plus 10px content padding. So a spotlight/laser sat offset from
where the text actually renders ("spotlight 与对应元素的位置有偏差", #867 item 5).

Add an optional GeometryProbe to the compiler's DI boundary: when supplied, the
geometry pass prefers each element's measured content-box geometry (video keeps
its rotation from the authored element), degrading to the pure authored-box calc
on a miss so the compiler stays deterministic in unit contexts.

App side: measureSlideElementGeometry (new, in @openmaic/renderer/snapshot)
mounts the slide off-screen and reads the same `.element-content`-against-
container box the live SpotlightOverlay uses; createVideoTimelineDeps
pre-measures every spotlight/laser/play_video target per scene and serves the
probe as a synchronous table lookup.

Tests: geometry.test.ts quantifies the outer-box vs content-box delta and proves
probe-wins / fallback / rotation-preservation; timeline-deps.test.ts covers the
pre-measure wiring.

Refs #867.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): decode a first-frame poster for posterless videos

A play_video clip only shows during its play window; the rest of the time the
static base-frame PNG backs that spot. But html2canvas can't draw a <video>, so
the snapshot swaps it for its poster <img> — and generated videos usually carry
no poster, leaving the video area blank whenever the clip isn't playing.

When a video record has no stored poster bytes, decode the video blob's first
frame (seek slightly off 0, draw to a canvas) and set element.poster before the
base snapshot, so that spot shows the first frame — the "paused on frame one"
look — instead of blank. Falls back to no poster on decode failure / timeout /
CORS taint, never failing the export.

Refs #867.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(video-export): split subtitles, make burn-in optional, centered modal

Burned-in captions used one cue per whole narration paragraph, so a long cue
became a 4–6 line block covering the lower half of the slide, and there was no
way to turn it off.

- Split cues (pure, compiler layer): lib/video-export/split-cue.ts splits each
  cue on sentence → clause → hard-wrap to ≤~40 CJK-equiv units, distributing the
  parent window by character weight (last piece pinned to the parent end, sub-1.2s
  slivers merged). Wired into the timeline pass, so the burned-in overlay and the
  SRT/VTT sidecar share one split track and can't drift.
- Burn-in optional (default off, #867 item 2): emitHyperframes gains
  burnInSubtitles; off → clean video + sidecar SRT/VTT only. Caption layout hard-
  clamped to 2 lines so an outlier can't grow tall again.
- Download subtitles without rendering: compileSubtitles() runs only the compiler
  (no assets/zip/service); new useDownloadSubtitles saves an .srt.
- Centered modal: video-export-dialog.tsx replaces the cramped dropdown section,
  grouping Output / Subtitles / Actions / Progress with a stable lifecycle for
  multi-minute renders. header-controls opens it from an "Export Video" entry;
  old video-export-menu.tsx removed. i18n keys added across all 8 locales.

Refs #867.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* style: prettier format video-export fidelity changes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test: drop unused playVideo helper in timeline-deps test

The media-bridge tests assert via deps.assets.media(...) directly, so the
playVideo helper (and its PlayVideoAction import) were dead. Flagged by the
code-quality bot on #952.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): resolve cross-review findings + lower subtitle band

- emit-hyperframes: drop duplicate `display:-webkit-box` on subtitle cues so
  they start truly `display:none` (a second declaration overrode the `none`,
  showing every cue stacked at t=0 when burn-in was enabled).
- geometry: don't feed the measured content-box AABB to a rotated video clip —
  it already encloses the rotation, so re-applying `rotate` doubled it. Rotated
  elements fall back to the authored box (one, un-doubled source of truth).
- build-export-zip: extract shared `compileStageIr` so buildExportZip and
  compileSubtitles can't drift on the timing/assets/geometry wiring.
- split-cue: join merged CJK cue pieces without a spurious ASCII space.
- subtitles: lower the caption band (bottomRatio 0.055 → 0.01) and hoist the
  band's magic numbers into a named SUBTITLE constants block.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): stop the snapshot onclone override from reshaping KaTeX

The export snapshot injects a neutral-kerning / geometricPrecision style over
`.slide-renderer-prose *` to keep CJK prose+table glyphs from mis-advancing
under html2canvas-pro. KaTeX formulas (output:'html') also live inside
`.slide-renderer-prose`, so the override was reshaping their math glyph
advances — a burned-in formula rendered subtly differently from the live
canvas, which applies no such override.

Empirical check (Playwright + system Chrome, cases+fraction formula, native
paint vs html2canvas): the override raised the formula's mean per-pixel delta
vs the live paint from 120.1 to 139.2 (~16%) and moved ~75% of inked pixels.
Restoring native font-kerning/text-rendering for `.katex` subtrees brings the
formula's delta back to 120.1 (bit-identical to the no-override capture) while
prose and table text keep the override. The residual 120.1 is the deeper
html2canvas rasterization gap (vlist/frac-line/delimiter), a separate track.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): render slides via native paint, bundle KaTeX font embed

Root-fix the exported-vs-live formula distortion (and the filter/mask/video
gaps) by rasterizing slides with native Chrome paint instead of html2canvas's
reimplementation.

- slideToPng now captures via html-to-image (foreignObject → the same Chrome
  engine that paints the live classroom rasterizes the same DOM). KaTeX
  formulas, CSS filter, soft-edge masks, and mixed CJK/Latin text come out as
  the classroom shows them. html2canvas-pro stays as a fallback (with the
  filter/mask bakes + KaTeX text-rendering reset) for when native paint can't
  run — e.g. a cross-origin image taints the canvas.

- A foreignObject SVG can't reach the document font registry, so fonts must be
  inlined. KaTeX math faces are prepended from the bundled woff2
  (KATEX_FONT_EMBED_CSS, generated by scripts/generate-katex-fonts.mjs), NOT
  left to runtime getFontEmbedCSS — which reads cssRules and silently drops a
  cross-origin KaTeX stylesheet, collapsing a large brace to a fallback glyph
  (the observed "formula render failure" on e.g. a \begin{cases} with \text{}).
  A per-face guard verifies every KaTeX face the formula references is embedded,
  falling back to html2canvas otherwise.

Verified in a Playwright spike (native vs html2canvas vs html-to-image): formula
inked-delta 143→53; filter/mask/video match native; and with getFontEmbedCSS
forced empty, the bundled embed alone still renders the failing formula
correctly. Renderer package tests: 226 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): prettier-format the generated KaTeX font-embed module

The generator emitted an unformatted TS file (double quotes, long unwrapped CSS
literal) that failed CI `prettier --check`. Run the generated output through the
repo's Prettier config before writing, so every rebuild produces CI-clean,
stable output. Regenerated the committed file to match.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(lint): rename reserved `module` var in katex-fonts generator; ignore .scratch

- generate-katex-fonts.mjs assigned to a variable named `module`, tripping
  @next/next/no-assign-module-variable (the one hard eslint error). Renamed to
  `fileContents`; generated output is byte-identical (deterministic).
- Add `.scratch/**` to the eslint globalIgnores (alongside .claude/.worktrees)
  so local throwaway verification scaffolding doesn't pollute `pnpm lint`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): address PR #952 review — scene-scoped media bridge, safer cue splitting

Resolves the two blocking correctness issues and three follow-ups from the
cross-review on #952.

- Scope the elementId→mediaRef bridge by scene (was deck-wide/last-writer-wins):
  slide-local ids like `video_001` now resolve within their own scene. `assets.media`
  uses its scene arg; `timing.videoDurationMs` resolves via action object identity.
  Adds a cross-scene collision test.
- Stop treating every ASCII period as a sentence boundary: a lone `.` splits only
  when not between word chars (3.14, v1.2) and not an abbreviation dot (e.g.),
  collapsing repeated-punctuation runs. Adds decimal/version/abbrev/ellipsis tests.
- Share the module-level in-flight guard across ZIP export and subtitle download
  (extracted to export-in-flight.ts); dialog `busy` folds in `downloading`.
- Skip the off-screen geometry render for the subtitles-only path (skipGeometry);
  duration probes are kept so sidecar cue timing stays in sync with the video.
- Align measure.ts font settling with slideToPng: force-load each used face before
  fonts.ready so measured content-boxes don't bake fallback advance widths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* style(video-export): prettier-format split-cue test

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* perf(video-export): enable beginFrame capture via PRODUCER_BROWSER_GPU_MODE=hardware

The producer defaults to `software` GPU mode, which silently force-enables the
CPU-bound `Page.captureScreenshot` fallback: SwiftShader pins every core on
rasterization and caps frame capture at ~10 fps. Selecting `hardware` keeps
Chromium's `HeadlessExperimental.beginFrame` capture active instead.

Measured on a 900-frame (30s) clip, no real GPU on the host:
- capture ~10 -> ~19 fps, total 100s -> 62s (~38% faster)
- CPU peak ~810% -> ~98%; peak mem 2.2 GiB -> 0.9 GiB
- static frames pixel-identical; animation frames differ only in sub-pixel
  edge antialiasing (same-path re-render is deterministic/inf PSNR)

No real GPU is required — the win is the faster capture API, not hardware
rasterization; beginFrame falls back gracefully if the host lacks a GPU. Also
eases the RENDER_JOB_DEADLINE_MS timeout risk on long videos.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(video-export): sentence splitting via Intl.Segmenter + abbreviation merge

Addresses the PR #952 follow-up: separate sentence-boundary detection from cue
shaping and stop growing a custom punctuation heuristic.

- splitSentences now delegates boundary detection to Intl.Segmenter (locale-
  agnostic ICU), the multilingual/CJK baseline. It already preserves 3.14, v1.2,
  e.g., U.S., ellipses, and CJK 。!?… without any hand-rolled period scan.
- ICU still ends a sentence after a titlecase abbreviation before a capitalized
  word (Dr. Smith, Fig. 3) — the edge case the reviewer flagged. A small
  abbreviation-aware post-merge re-joins those, driven by an ABBREVIATIONS set.
- Semicolons are no longer sentence ends (they join clauses); moved ;; into the
  clause-level SECONDARY splitter so over-budget sentences still break there.
- Cue shaping (budget / clause / hard-wrap / weighted timing) is unchanged, so
  detection and shaping are now distinct stages.

Not using `sbd` as suggested: lib/video-export/*.ts sits behind the machine-
enforced eslint purity boundary (imports limited to @openmaic/dsl, zod,
../choreography, siblings), so a new npm dep is rejected. Intl.Segmenter is a
pure Node >=20.9 builtin, matching the reviewer's "small abbreviation-aware
post-merge layer" alternative.

Tests: add Dr. Smith / Fig. 3 / U.S. coverage; the rhetorical ellipsis now stays
one under-budget cue (was split); add a semicolon over-budget case. 22/22 pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* style(video-export): prettier-format split-cue sentence refactor

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* i18n(es-MX): add 7 subtitle/video export keys to align with en-US

main added the Spanish (Mexico) locale (#942) after this branch's subtitle
keys landed, so es-MX was the only locale missing export.subtitles* and
export.videoBurnSubtitles* — which failed the i18n key-alignment CI check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): restrict title post-merge so it never deletes real boundaries

Addresses the blocking re-review on the Intl.Segmenter change: the abbreviation
post-merge unconditionally rejoined the next ICU segment whenever the previous
one ended in a listed abbreviation, which erased genuine sentence boundaries —
`It was made by Acme Inc. Next point.` collapsed into one cue, and even an
explicit newline (`Acme Inc.\nNext topic`) was rejoined.

The merge now fires only for the case ICU actually mis-splits — a title
(Mr/Mrs/Ms/Dr/Prof/Sr/Jr) before a capitalized proper noun — and only when:
  - the previous segment does not end at a newline (hard boundary), and
  - the next segment starts with a capital letter.

Sentence-trailing abbreviations (Inc./Ltd./etc./vs./No.) are dropped from the
set entirely: they legitimately end sentences, and ICU already keeps a title
before a number (No. 5, Fig. 3) or a lowercase continuation (etc. and…) whole
without any merge, so nothing there needs rejoining.

Regression tests: Inc./etc. boundary preserved, newline-after-title preserved,
lowercase continuation kept whole, plus the retained Dr. Smith / Fig. 3 / U.S.
cases. 26 split-cue tests pass; full video-export suite 123 pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-27 02:58:04 -04:00
b4e3145c90 feat(roster): single-source the generated agent roster on the stage document (#994)
* 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>
2026-07-27 14:39:19 +08:00
3eea9dc542 feat(runtime): complete the #869 learner-data cutover — quiz + playback onto RuntimeStore (#955)
* 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).

* 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>

---------

Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-22 15:28:04 +08:00
杨慎andClaude Opus 4.8 84b1907255 feat(video-export): service-backed MP4 render + in-app one-click export (#866) (#937)
* feat(video-export): service-backed MP4 render + in-app one-click export (#866)

Adds the last mile of classroom video export: turning the self-contained
Hyperframes project ZIP (#865) into an MP4 via an isolated render service,
one-click in-app.

- render-service/: standalone Node 22 + Chromium + FFmpeg container wrapping
  @hyperframes/producer's library API. Async job model (POST /render -> 202
  jobId, GET poll, GET download, DELETE cancel). Swappable JobStore /
  ArtifactStore seams (in-memory + local-disk now; Redis/S3 + presigned-302
  download later) so it scales horizontally without changing the HTTP contract.
  Concurrency + per-user guards are config knobs.
- App integration: thin Next proxy routes under app/api/export-video/* (forward
  only, no rendering) + capability probe. use-render-video.ts uploads the ZIP,
  polls via runPolledTask, downloads the MP4; shared buildExportZip prefix with
  the existing ZIP path. Export menu gains resolution/fps/quality selectors and
  a progress bar; degrades to ZIP download when RENDER_SERVICE_URL is unset.
- docker-compose: render-service under an opt-in "video-export" profile.
- Entry is main.ts (not server.ts): the producer auto-starts its own server on
  :9847 when the process entry path ends with /src/server.ts.

Verified end-to-end in the container: rendered a real 640s (10.7 min) classroom
ZIP to a valid H.264 720p + AAC MP4 (duration matches source) in ~9.6 min
(~0.9x realtime, 4-worker frame capture). Degrade path, queued-cancel + cleanup,
and per-user 429 guard all exercised. pnpm check / lint / tsc / i18n pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(video-export): global render progress store, percent+ETA UI, ring on export button (#866)

Addresses two UX issues found while driving the in-app MP4 export:

1. Progress display was raw and unfriendly (showed producer's English stage
   strings like "Capturing frame 5130/19220") and had no time estimate. Now the
   menu shows only "<percent>% · about <remaining> left". ETA is computed from a
   recent-speed estimate (percent-per-ms over the last sample), EMA-smoothed —
   which tracks the render's non-uniform pace (prep -> frame capture with a
   4->1 worker drop -> encode) far better than a whole-run average, and never
   shows a stale/rising ETA.
2. Switching scenes mid-render unmounted the export menu and lost the progress
   (and reset the local "already rendering" ref, allowing a duplicate submit).
   The whole render lifecycle now lives in a global store
   (lib/store/video-render.ts), so progress survives menu close / scene switch
   and duplicate submits are guarded by status. A persistent CircularProgress
   ring on the export button shows live progress whether or not the menu is open.

Also fixes the progress scale: the producer reports progress as 0..100, but our
HTTP contract (and success path) is 0..1 — the service now normalizes it, so the
client no longer showed "2000%".

- lib/store/video-render.ts: new global store owning submit->poll->download,
  recent-speed ETA, duplicate-submit guard.
- lib/video-export-app/use-render-video.ts: thin facade over the store.
- components/ui/circular-progress.tsx: lightweight SVG progress ring.
- components/stage/{header-controls,video-export-menu}.tsx: ring on the export
  button; menu shows percent + ETA, subscribes to the store.
- render-service/src/render-manager.ts: normalize producer progress 0..100 -> 0..1.
- i18n: percent/ETA strings across all 8 locales (drops the stage-based string).
- render-service/package-lock.json: complete integrity hashes (reproducible npm ci).

Verified: ETA logic checked against the real segmented render curve (worker drop
raises ETA, encode speedup drives it to ~0); progress scale fix confirmed live
against the container (0.2 -> 20%). tsc / lint / prettier / i18n pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): persist render options in the store, not the menu component

Selecting 720p/24fps/draft, switching scenes, and reopening the export menu
showed the defaults again (1080p/30/standard). The selections lived in the
VideoExportMenu component's local state, which reset when the menu unmounted on
a scene switch — the running render still used the chosen options, but the UI
misrepresented them.

Move resolution/fps/quality into the global video-render store (with a
setOptions action). The menu now reads/writes the store, so selections survive
menu close / scene switch, and while a render runs the selectors reflect the
options that render is actually using. startRender() reads options from the
store instead of taking them as an argument.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): deployment correctness + resource/isolation controls (PR #937 review)

Addresses the blocking findings from wyuc's review. Output fidelity was fine;
these harden deployment and production resource/isolation boundaries.

#1 Compose advertised MP4 but couldn't render in prod:
- Capability now probes the service's /health (checkRenderServiceHealth), so a
  configured-but-absent service reports disabled and the UI degrades to ZIP
  instead of 502-ing.
- RENDER_SERVICE_URL is operator-supplied trusted config, so the proxy no longer
  runs it through the SSRF guard — the one-command `docker compose --profile
  video-export up` now works without globally weakening SSRF via
  ALLOW_LOCAL_NETWORKS. resolveRenderServiceUrl() is now synchronous.
- Client degrades to ZIP on any failed submit (not only 501).

#2 Unbounded upload/queue (ZIP-bomb / DoS):
- unzip.ts bounds the archive via fflate's filter BEFORE decompression: entry
  count, per-entry and total expanded size, and compression ratio.
- Proxy rejects oversized uploads (413) by Content-Length before forwarding.
- RenderManager enforces a global queue-depth cap (RENDER_MAX_QUEUE).
- All limits are env-tunable knobs in config.ts.

#3 Per-user guard was ineffective + admission ran after extraction:
- Identity is derived server-side (client IP) and forwarded as x-openmaic-client;
  the service ignores any client-supplied userId, and the proxy strips it.
- Admission is split into reserve()/submit()/release(): the slot is reserved
  BEFORE extraction, so a rejected caller never triggers a decompression.

Additional risks:
- Per-job wall-clock watchdog (RENDER_JOB_DEADLINE_MS) aborts + fails a hung
  render so it can't hold a slot/scratch forever.
- Download proxy bounds only the time-to-headers, not the body stream, so large
  MP4s over slow links no longer truncate.
- Client cancels the server job (DELETE) when a started render fails/times out.
- Compose puts render-service on an internal:true network (no host/internet
  route), sandboxing the Chromium that runs the uploaded HTML; the export ZIP is
  self-contained so no outbound is needed. README documents the standalone caveat.

Not closing #866: the smoke/golden-render CI acceptance criterion remains a
follow-up (see PR description).

Verified in-container: legal render 202; ZIP-bomb (entry-count + compression-
ratio) rejected 400 before any decompression; per-identity guard 429 with a
spoofed multipart userId ignored; reserve-before-extract leaves no scratch dir
on rejection; watchdog aborts an overrunning job and frees the slot. tsc / lint /
prettier / i18n pass; render-service tsc passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): real audio durations + burned-in subtitles (PR #937 review)

Two export-fidelity issues found in wyuc's deeper E2E:

A. Narration was scheduled from estimated durations, cutting audio off mid-
   sentence and advancing the timeline early. The scheduler trusted
   AudioFileRecord.duration (recorded only since #861), so the many existing
   classrooms without it fell back to text-length estimates — measured 4.35s
   average / 10.23s max underestimate across 47 clips. timeline-deps now probes
   the real duration from each narration blob via an off-document <audio>
   (symmetric to the existing video probe), preferring it over the stored
   duration, then the estimate only when no audio asset exists. Everything
   downstream (narration starts, scene/total duration, subtitle cues) re-derives
   from the corrected value in the pure compiler — no compiler change needed.

B. The final MP4 had no subtitles (only H.264+AAC), and the ZIP's SRT/VTT used
   the same estimated boundaries. The emitter now renders a burned-in subtitle
   overlay: one caption box + a hidden div per cue, revealed/hidden by the paused
   GSAP timeline at each cue's start/end (corrected timings from A), so Chromium's
   frame capture bakes them in. The producer has no subtitle track of its own, so
   burn-in is the v1 approach.

Verified: emitter unit tests + snapshot updated (subtitle overlay + toggle
statements, escaped text, hidden-by-default); 82 video-export tests pass incl.
the determinism red-line proxy. Rendered a synthetic subtitle project through the
container and confirmed by pixel analysis that captions appear only within their
cue window (2429 near-white px in the caption band at t=1.5s vs 0 at t=0.05s).
tsc / lint / prettier / i18n pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): subtitle layout + upload/admission hardening (PR #937 review)

Address the three P1 blockers plus actionable P2s from the 6a585c29 review.

P1:
- emit-hyperframes: stack every subtitle cue in one grid cell and toggle
  display:none/inline-block, so inactive cues leave the flow instead of
  pushing the active cue up into the slide title. Adds a multi-cue
  regression test the single-cue snapshot couldn't catch.
- render route + service: cap the upload by actual bytes (capBodyStream),
  not the spoofable Content-Length; the app now streams the multipart body
  through instead of buffering it via formData(). maxUploadBytes is now read.
- render-service: move makeProjectDir() inside the release()-guarded block
  so an ENOENT/ENOSPC no longer permanently leaks the admission slot; mkdir
  the scratch root at startup for the standalone path.

P2:
- config: allow RENDER_MAX_JOBS_PER_USER=0 to disable the per-identity guard.
- timeline-deps: per-probe timeout + bounded concurrency so a stuck audio
  blob can't wedge export in "compiling" forever.
- render route: only trust x-forwarded-for/x-real-ip under
  TRUST_PROXY_HEADERS=true; otherwise all callers share one "direct" bucket.
- render-service: add vitest tests (unzip limits/traversal, reservation
  arithmetic, body cap, config zero-disable) and a dedicated CI job.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): sync render-service lockfile so `npm ci` passes in CI

The vitest devDependency's transitive esbuild@0.28.1 (and its platform
optionals) were missing from package-lock.json, so the new CI job's
`npm ci` failed with EUSAGE. Regenerated the lockfile from a clean install.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): dedupe esbuild so render-service `npm ci` installs on linux

@hyperframes/core pins esbuild@0.25.12 exactly, hoisting it to the top and
forcing vite@8 (via vitest) to keep a nested esbuild@0.28.1 copy. npm fails to
flag that nested copy's platform-specific optionals as optional, so `npm ci`
tried to install @esbuild/aix-ppc64 on linux and died with EBADPLATFORM.

Add an `esbuild: 0.28.1` override so a single copy is shared (satisfies tsx
~0.28 and vite ^0.27||^0.28); esbuild is build-time only, so pinning the
producer's bundled build tool is runtime-inert.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): resource/isolation hardening (PR #937 round-2 review)

Address the round-2 P1/P2/P3 findings (P1#1 lockfile EBADPLATFORM was already
fixed by the earlier esbuild-dedupe commit; CI Render Service job is green).

P1:
- Admission before buffering (#2): the render service now reserve()s the slot
  from the header identity BEFORE parsing/buffering the multipart, so concurrent
  near-cap uploads are bounded by the queue depth, not just each body by the cap.
- Chromium egress lockdown (#3): the producer exposes no browser-arg hook and the
  render shares the internal network with the app, so a container entrypoint
  installs an iptables egress lockdown (drop all outbound except loopback +
  established replies) then drops privileges. Needs CAP_NET_ADMIN (added in
  compose); graceful warn-and-continue if unavailable. The self-contained ZIP
  needs no outbound.
- Default one-render bottleneck (#4): with no trusted proxy every caller is
  "direct", so RENDER_MAX_JOBS_PER_USER=1 throttled the whole deployment. Default
  compose now sets it to 0 and relies on concurrency + global queue caps.
- Non-blocking bounded extraction (#5): unzipSync -> fflate async unzip (worker,
  off the event loop), keeping the pre-decompression filter; default expanded
  ceiling 1GB -> 512MB; a semaphore caps concurrent extractions; compose adds a
  container mem_limit.

P2:
- Raise the app submit timeout/maxDuration (300MB upload can't finish in 60s).
- video-render store: only degrade to ZIP when the service is genuinely
  unavailable (501/unreachable); surface real 429/413/5xx instead of an
  unsolicited download.
- useExportVideo dedupe guard moved to module scope so it survives the menu
  unmounting (no second concurrent ZIP pipeline).
- .env.example: RENDER_SERVICE_URL bypasses SSRF; drop the ALLOW_LOCAL_NETWORKS note.

P3:
- Deadline overruns are marked failed (not cancelled).
- submit() decrements the identity slot if jobs.create throws (no leak).
- CI sets PUPPETEER_SKIP_DOWNLOAD; unzip tests use tiny fixtures + low env limits.

Tests: render-service now 22 tests (unzip limits/traversal, admission incl.
create-leak, body cap, semaphore, config); app video-export suite unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(video-export): buffer under the extraction permit + fail-closed egress (PR #937 round-3)

Address the two remaining round-3 P1 boundary blockers.

P1#1 — buffering was outside the gate: `bounded.formData()` materialized the
whole uploaded file into memory BEFORE `extractionGate.run()`, so up to
RENDER_MAX_QUEUE (20) admitted bodies could each buffer ~300MB (≈6GB vs the 4g
mem_limit) before the 2-permit gate. Move the entire RAM-heavy section —
formData buffering, file read, and unzip — INSIDE the permit; the queue
reservation still runs first (a rejected caller consumes nothing). Requests
beyond the permit wait with their body unconsumed (socket backpressure), so at
most maxConcurrentExtractions bodies are buffered at once. Refactored main.ts
into a testable `createApp(deps)` factory and added an integration test proving
peak concurrency in the buffering+extraction section never exceeds the permits.

P1#2 — egress lockdown failed open: the entrypoint warned and started normally
if iptables setup failed, so /health stayed green while Chromium could reach the
app. With RENDER_EGRESS_LOCKDOWN=true (default) it now FAILS CLOSED — exits
non-zero if not root, iptables is missing, or the rules don't apply. Operators
accepting an unisolated setup opt out with RENDER_EGRESS_LOCKDOWN=false. Added
scripts/egress-smoke.sh to assert the boundary (lockdown active, loopback works,
new outbound blocked).

Verified: image builds; container boots as `render` with lockdown active and
serves /health; fail-closed exits 1 without CAP_NET_ADMIN; egress smoke passes
(outbound blocked); 23/23 render-service tests + tsc; app tsc + root prettier clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-20 11:28:34 +08:00
bb8d4f30e7 feat(chat): add experimental Pi classroom runtime behind a flag (#914)
* feat(chat): add experimental Pi classroom runtime

* fix(chat): harden Pi whiteboard action sequencing

* style(chat): format session retirement flow

* style(playback): format async scene transition

* fix(chat): retire actions on session errors

* fix(chat): close Pi runtime lifecycle gaps

* fix(chat): avoid replaying historical whiteboard actions

* fix(chat): prevent Pi structured-output residue from leaking and inflating turns

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(chat): expose whiteboard element/line ids and bound code-line context

Surface each element's id (and code line ids) in the Pi whiteboard context so
later child agents can target wb_delete / wb_edit_code, and cap the rendered
code lines with a shared character budget so a code-heavy board cannot grow the
prompt without bound. Return only the current turn's whiteboard ledger from the
Pi director loop instead of carrying history forward across requests.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(chat): bound Pi whiteboard code context

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(chat): prioritize newer persisted whiteboard code in budget

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(chat): enforce whiteboard boundaries across Pi sessions

* feat(chat): refine soft-closing discussion controls

* fix(chat): make whiteboard clearing model-directed

---------

Co-authored-by: apple <apple@GigideMacBook-Air.local>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: LING-6150 <duan.lin@northeastern.edu>
2026-07-17 11:22:02 +08:00
wyuc 65bf20a84b feat(runtime): cut chat sessions over to RuntimeStore (#926)
* feat(runtime): persist chat sessions in RuntimeStore

* fix(runtime): harden chat persistence ordering

* fix(runtime): protect cross-tab chat snapshots

* fix(runtime): compare structured chat values safely

* fix(runtime): preserve chat backup and reset semantics

* fix(runtime): restore imported chat snapshots

* fix(runtime): isolate chat load failures

* fix(runtime): make cache clearing lossless

* fix(runtime): normalize empty chat saves

* fix(runtime): serialize legacy chat migration

* fix(chat): serialize backup restoration

* test(chat): cover multi-stage restore locking

* fix(chat): coordinate fallback migrations across tabs

* fix(chat): harden cross-tab migration locking

* fix(database): retire abandoned chat lease schema

* fix(chat): preserve monotonic local edits

* fix(chat): protect unseen runtime sessions

* fix(chat): order lifecycle transitions monotonically

* fix(chat): serialize runtime maintenance

* fix(chat): order queued writes before maintenance

* fix(chat): preserve cross-version lock compatibility

* fix(chat): preserve streamed and backup data

* fix(chat): isolate empty no-lock saves

* fix(chat): isolate partial runtime snapshots

* fix(runtime): close cross-store cutover races

* fix(runtime): close remaining cutover races

* fix(chat): retain caller-visible conflict baseline

* fix(chat): preserve read-only legacy autosaves

* fix(chat): avoid restore lock inversion

* fix(runtime): enroll writes before maintenance

* fix(runtime): retain maintenance ordering

* fix(runtime): close restore and deletion races

* fix(chat): order partition queues within lock epochs

* fix(chat): preserve recovery and deletion intent

* fix(runtime): recover interrupted chat restores

* fix(backup): scope chat deduplication by stage

* fix(backup): stage chats by runtime partition

* fix(backup): clear staged chats with stages
2026-07-16 18:30:40 +08:00