Commit Graph
92 Commits
Author SHA1 Message Date
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
9d2689439e feat(i18n): add French (fr-FR) locale (#1068)
Translate all 1,533 leaf keys with exact parity against en-US.json and
register the locale in supportedLocales.

Two extra files are required and could not be split out: LOCALE_RESOURCES
in lib/video-export-app/cover-config.ts and the expected-labels map in its
test are both typed Record<Locale, ...>. That file landed on 2026-08-04
via #995, nine days after #942 (es-MX) merged, so no previous locale PR
had to touch it. Without these two edits tsc --noEmit fails with TS2741.
Seven added lines outside lib/i18n, no logic change.

Conventions: formal register (vous); French typography (typographic
apostrophes, ellipsis, U+00A0 before : ; ! ? % and inside guillemets);
all {{var}} and {var} markers preserved verbatim; settings.lang_* left in
their native scripts, matching every existing locale.

Co-authored-by: momo2lajoie <209366801+momo2lajoie@users.noreply.github.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-06 04:44:48 -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
de95350516 feat(video-export): deterministic Quiz/PBL cover cards (#985) (#995)
* feat(video-export): add deterministic Quiz/PBL cover cards

Replace unsupported placeholders with authored-metadata cover cards that
stay independent of learner progress, and pin dense-layout evidence for
720p/480p.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(video-export): add configurable localized cover CTA

Replace the inert Start Quiz affordance with a destination-configurable
CTA (NEXT_PUBLIC_VIDEO_EXPORT_CTA_DESTINATION), including Unicode/bidi
display guards.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(ci): require Hyperframes video-export gates

Lock CI/Docker contracts so cover materialization and Hyperframes sample
lint stay required for export changes.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(ci): move HF_E2E_DIR onto e2e steps

GitHub rejects runner.* in job-level env, which aborted the CI workflow
with zero jobs. Keep the sample dir on the materialize/lint steps only.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore(video-export): tidy CI invoke and panel-box export

Run the Hyperframes materialize step through pnpm exec vitest like the
cover-card guardrail above it; the e2e job already pins Node 22. Stop
re-exporting PBL_PANEL_DESIGN_BOX from the public barrel — only the
layout browser test needs it, and it can import the emitter module
directly.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-04 15:43:38 +08:00
littlebullGitandwyuc 3d85525665 [codex] Add Amazon Bedrock LLM provider support (#538)
* Enable AWS-hosted text models without exposing ambient credentials

Rebase the Bedrock provider onto current main and close the review-requested security, credential lifecycle, usage attribution, configuration, and metadata gaps.

Constraint: Bedrock may use ambient AWS credentials only when explicitly enabled by the server operator
Rejected: Trust client-supplied provider types | permits built-in keyless IDs to reach Bedrock credentials
Confidence: high
Scope-risk: moderate
Directive: Keep provider ID/type validation at both request resolution and model construction boundaries
Tested: targeted Bedrock/resolver/config/usage tests; TypeScript; ESLint; i18n alignment; production build
Not-tested: Full suite has 27 failures in unchanged quiz/runtime and runtime/chat-storage tests

* Give Bedrock a recognizable provider identity

Use the official AWS architecture service icon so Bedrock no longer falls back to the generic provider cube in settings and model selection.

Constraint: Preserve the AWS-provided artwork without redesigning the service mark
Confidence: high
Scope-risk: narrow
Tested: SVG XML validation; provider unit test; TypeScript; ESLint; production build

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-08-03 23:10:50 -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
杨慎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
davidmedel 1466a55eef feat(i18n): add Spanish (Mexico) locale (#942)
Spanish is not among the supported locales, so browsers sending es/es-MX
fall through resolveLocale to the default (zh-CN) and Spanish-speaking
users get the UI in Chinese.

- lib/i18n/locales/es-MX.json: complete translation (1,504 keys), following
  TRANSLATION_GUIDE.md including the design-intent notes (greetingWithName
  as CTA, defaultNickname warm and gender-neutral, readyToLearn inviting).
- lib/i18n/locales.ts: register es-MX at the end of supportedLocales per the
  guide, making it the default for the bare 'es' prefix.

Rebased onto current main and translated the 17 keys added since the branch
diverged (15 export.video* + chat.softClosing + roundtable.softClosing), per
@wyuc's review. Key parity and {{interpolation}} variables verified with
scripts/check-i18n-keys.mjs (passed: 9 locale files aligned).
2026-07-26 01:52:17 -04: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
珀西andPercy 4c92111160 fix(export): resource pack unresponsive for interactive-only decks (#933)
A deck with only interactive scenes (no slide scenes) was silently
no-op when clicking Export Resource Pack: withExportGuard rejected
all export actions on slides.length === 0 with no toast or log, even
though the resource pack's own semantics (PPTX + interactive pages)
should still ship the interactive pages alone.

Changes:
- withExportGuard gains a requireSlides flag (default true). When it
  rejects it now toasts instead of returning silently.
- exportResourcePack passes requireSlides=false; the PPTX builder now
  runs only when slide scenes exist, with a toast when skipped.
- Assembly logic extracted into buildResourcePackZip (pure async fn)
  so it is unit-testable without a React harness.
- Regression tests cover: interactive-only deck ships a ZIP with the
  HTML page and no PPTX, and never calls the PPTX builder.
- New i18n keys (noSlides / noSlidesSkipped / nothingToExport) across
  all 8 locales.

Co-authored-by: Percy <percy@PercydeMacBook-Pro.local>
2026-07-16 11:03:47 +08:00
d8a0081c7d feat(video-export): L1 Hyperframes emitter + browser collection + export ZIP (#865) (#931)
* feat(video-export): L1 Hyperframes emitter + browser collection + export ZIP (#865)

Consume the VideoTimeline IR (#864/#913) and produce a self-contained
Hyperframes composition project that `npx hyperframes render` turns into an
MP4 (render execution itself is #866).

- lib/video-export/emit-hyperframes: pure IR → Hyperframes project emitter
  (one flat composition, one paused GSAP timeline on window.__timelines,
  spotlight/laser overlays from lib/choreography descriptors). Stays under
  the purity boundary; emits HTML/JS strings only.
- lib/video-export/subtitles: SRT/VTT serialization of the IR subtitle track.
- lib/video-export-app: impure app glue (DI adapters over Dexie, slide-snapshot
  collection lifted from #849, streaming ZIP packaging, useExportVideo hook).
- Vendor GSAP locally (public/vendor/gsap.min.js) — determinism red-line.
- Export menu entry with resolution select + i18n across all 8 locales.

Verified end-to-end against the real hyperframes CLI: lint passes 0 errors on
a real classroom export, and a rendered slice produces a valid H.264+AAC MP4.

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

* feat(video-export): gate Export Video menu behind NEXT_PUBLIC_ENABLE_VIDEO_EXPORT flag

The video export UI is experimental until the render pipeline (#866) lands, so
hide the "Export Video" affordance behind an off-by-default feature flag.

- Add isVideoExportEnabled() to lib/config/feature-flags (NEXT_PUBLIC_, so it
  inlines at build time for the client-side export menu).
- Gate the Export Video block in header-controls on the flag.
- Cover the new flag in tests/config/feature-flags.test.ts.

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

* fix(video-export): ossKey fallback for evicted blobs + emitter dedup

Address code-review findings on #931.

- collect: resolveBytes() prefers the local Dexie blob and falls back to
  the record's CDN ossKey (audio) / ossKey+posterOssKey (media/poster) so a
  live-mode classroom whose local blobs were LRU-evicted still exports a
  self-contained ZIP. timeline-deps presence checks widened to
  `blob.size > 0 || !!ossKey` so the compiler keeps these entries instead of
  marking them absent; video-duration probe stays local-only.
- emit-hyperframes: extract one shared escapeHtml + sec into format.ts,
  dropping the two divergent escapers (attr vs escapeHtml) and the two sec()
  definitions with different rounding, plus the middle-man escapeAttr. Output
  is byte-identical (snapshot unchanged).
- Add tests/video-export/collect.test.ts (ossKey fallback, local-first,
  fetch 404/throw, video+poster).

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

* fix(video-export): restore evicted generated media into base-frame snapshots

Address review blocker (P1) on #931: the ossKey fallback covered standalone
audio/video/image/poster asset entries but not the slide base-frame path.
resolveGeneratedMedia only accepted a non-empty local blob, so a live-mode
record with an evicted blob + valid ossKey had its image src cleared (and
video/poster not restored) before slideToPng snapshotted the slide — the frame
PNG lost the generated media even though the standalone asset was fetched.

- resolveGeneratedMedia now resolves bytes via resolveBytes (local blob first,
  then ossKey / posterOssKey) before creating the snapshot object URLs.
- Add frame-collection tests: evicted image restored via ossKey, evicted
  video+poster restored, and image with no ossKey still cleared. The renderer
  snapshot is mocked so the frame path runs in plain Node.

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

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-07-15 18:22:59 +08:00
cc5a6ab152 feat(agent): edit_elements — NL → EditIntent vertical (#895) (#896)
* feat(agent): add edit_elements NL → EditIntent vertical (#895)

Give the editing surface its first real consumer: natural-language
per-element style/geometry edits flow through the same EditIntent
vocabulary as pointer gestures, with an all-or-nothing validation gate
and one undo entry per instruction.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(agent): harden edit_elements against CR findings (#895)

Re-validate intents at apply time (atomic refuse on missing/locked ids),
type-check prop values, require an open edit session for undo, clamp line
stroke width correctly, enforce group cohesion, nest shape text chrome,
and surface refuseReason on the tool card.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(agent): close remaining edit_elements CR residuals (#895)

Feed apply outcomes into next-turn history and post-run chat corrections,
phrase tool success as proposed-not-applied, and tighten gradient/filters/
enums/per-type value validation plus label-less shape text refusal.

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(agent): derive edit_elements prop validation from the DSL schema (#895)

Three review rounds each found a hand-written validator disagreeing with
the DSL contract (a gradient pos range pinned at [0,1] against the
percent contract, a textType enum matching the DSL in neither direction,
per-type ownership gaps like vertical-on-shape and color-on-everything).
Replace the class instead of the instances:

- The gate now loads the dsl-generated JSON schema
  (@openmaic/dsl/schema/scene.schema.json) and validates every proposed
  prop value against the target element type's subschema via a compact
  schema-subset checker — per-type ownership, enums, and structured
  shapes (outline/shadow/gradient/filters) come from the single source
  of truth and stay correct as the DSL evolves.
- Explicit policy layers stay on top: the content/identity blocklist
  (schema would allow what policy forbids), geometry clamps (coords,
  min sizes, line stroke width), and a numeric-range overlay for what
  plain number types cannot express — gradient stop pos is a percent in
  [0,100] (the previous [0,1] check refused canonical gradients and the
  unit test pinned the wrong contract), fontSize/lineHeight/radius
  bounds, filter value length, stop-count cap.
- Consequences: color is refused on types that do not render it, with
  prompt guidance steering text color to defaultColor and shape body to
  fill; fill on charts is now allowed (the schema has it; the inventory
  already advertised it); textType accepts the full DSL enum.
- Apply-time revalidation also refuses element-type drift via a
  gate-time targetElementTypes map carried in the tool details.
- Refusal reasons render as visible card text, not only a hover title.
- Test pins added for all of the above plus selection scoping, coord
  bounds, non-finite rotate, and empty batch/props.

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

* fix(agent): harden the schema-derived gate — fail closed, assert schema source, unify numeric clamping (#895)

- A schema construct the subset checker cannot judge (unresolved $ref,
  malformed anyOf, unsupported keywords) now refuses instead of
  accepting — the gate fails closed on the unknown.
- A module-load assertion verifies the loaded dsl schema carries every
  definition the gate maps and a sane TextType enum, so a stale or
  missing build artifact fails loudly with a rebuild hint instead of
  validating an outdated contract silently.
- Numeric-overshoot convention unified and documented: structural,
  enum, or ownership mismatches refuse (teaching the model the
  contract); numeric overshoot on a valid prop clamps (matching gesture
  behavior) — opacity now clamps like geometry.

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

* fix(agent): localize edit element refusals (#895)

* fix(agent): preserve partial element edit semantics (#895)

* fix(agent): prevent stale element edit application (#895)

* fix(agent): preserve live canvas edit invariants (#895)

* fix(agent): close element style contract gaps (#895)

* fix(agent): reject non-persistent element styles (#895)

* fix(agent): preserve rigid group geometry (#895)

* fix(agent): tolerate decimal group translations (#895)

* fix(agent): constrain line height edits (#895)

* fix(agent): reject stale or shadowed element edits (#895)

* fix(agent): close renderer contract gaps (#895)

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
2026-07-14 18:24:35 +08:00
Yanpeng Wangandwyuc 9670100363 feat(extraction): media (audio/video) extraction + AliDocMind provider (#887)
* feat(extraction): add AliDocMind provider + media extraction abstraction

Adds AliDocMind (Aliyun Document Mind LLM version) as a new vendor
alongside unpdf/MinerU, and introduces the media (audio/video) extraction
layer that mirrors the document extraction one.

Document side (file: pdf/docx/pptx/xlsx/images):
- PDF_PROVIDERS gains an `alidocmind` entry; parseWithAliDocMind() maps
  layouts[] -> ParsedPdfContent. Flows through the existing document
  extractor registry, so AliDocMind is selectable anywhere MinerU is.
- PDFParserConfig / DocumentExtractorConfig gain accessKeyId/accessKeySecret
  (AliDocMind uses AK/SK, not a single apiKey); env fallback via
  ALIDOCMIND_ACCESS_KEY_ID / ALIDOCMIND_ACCESS_KEY_SECRET.

Media side (mp4/mp3/wav/... -> MediaArtifact):
- New lib/media-parse/ domain mirroring lib/pdf/ (types/constants/providers).
  parseMedia() maps AliDocMind segments[]/audio_frames/video_frames ->
  MediaArtifact (transcript + keyframes).
- MediaExtractorProvider interface + media registry + extractMedia() entry,
  symmetric to DocumentExtractorProvider / extractDocument().
- MediaArtifact and the ExtractionResult/Artifact/Error/Job envelope live in
  lib/document/types.ts (re-exported from @/lib/document).

Shared AliDocMind SDK wrapper (lib/pdf/alidocmind-client.ts) handles the
submit -> poll -> get flow for both sides via @alicloud/docmind-api20220711.

Tests: env-gated smoke test (tests/document/alidocmind.smoke.test.ts) drives
a real PDF and a real video through AliDocMind; media-artifact type test;
extractor-registry test updated for the new provider.

Part of #621 (MAIC ETL). Media extraction is the sibling to the document
extraction landed in #741.

* feat(extraction): wire AliDocMind AK/SK through settings UI + routes

Surfaces AliDocMind in the (post-#837) Document Parsing settings panel as a
peer of unpdf/MinerU — one panel, one credential entry, more supported
formats. Threads Aliyun AccessKey ID/Secret from the store through the
extraction routes.

- Store: pdfProvidersConfig + setPDFProviderConfig gain accessKeyId/accessKeySecret;
  default alidocmind entry added.
- pdf-settings.tsx: AliDocMind branch renders AccessKey ID + Secret inputs
  (secret masked with show/hide) and a Test Connection button; request-URL
  preview shows the DocMind endpoint. Provider auto-appears in the panel via
  PDF_PROVIDERS; supported-format badges come from #837's registry
  (ALIDOCMIND_MIMES added to lib/document/mime.ts).
- verify-pdf-provider route: alidocmind branch verifies AK/SK via a lightweight
  authenticated probe (verifyAliDocMindCredentials) — auth-level errors fail,
  anything else passes.
- extract-document route + generation flow (app/page.tsx, generation-preview):
  accessKeyId/accessKeySecret carried through session → FormData → config.
- i18n: alidocmindAccessKeyId / alidocmindAccessKeySecret in 8 locales.
- Icon: reuse /logos/bailian.svg (Aliyun family) instead of a missing asset.

Verified end-to-end against the running app: AliDocMind panel renders,
Test Connection returns "连接成功" through the real Aliyun API.

Part of #886.

* feat(extraction): route audio/video uploads through extractMedia() (reuse document path)

Media uploads now flow through the same upload picker, /api/extract-document
route, and generation pipeline as documents — no separate upload area. Only
the extraction differs: media mimes dispatch to extractMedia() -> MediaArtifact,
which is flattened to the text shape the generation pipeline already consumes.

- mime.ts: register audio/video formats in DOCUMENT_FORMATS (accept string,
  extension map, badges resolve for them); add MEDIA_PROVIDER_SUPPORTED_MIME_TYPES
  + SUPPORTED_MEDIA_MIME_TYPES, kept separate from PROVIDER_SUPPORTED_MIME_TYPES
  so the document drift-guard stays document-only. mimesForProviders() folds in
  a provider's media mimes, so the existing upload helpers
  (getAcceptStringForProviders / isMimeSupportedByProviders / format badges)
  cover media automatically when the provider supports it.
- extract-document route: media mimes dispatch to extractMedia(); MediaArtifact
  flattened to timestamped text (synopsis + transcript + keyframes).
- Tests: 6 media cases in mime.test.ts (accept/validation/badges/normalization).

Verified: uploading a real video through the route returns synopsis +
timestamped transcript/keyframes as text (curl, real AliDocMind key).

Part of #886.

* feat(extraction): use Alibaba Cloud icon for AliDocMind provider

Replace the placeholder bailian.svg with a dedicated Alibaba Cloud icon mark
(the square symbol from the official wordmark, text removed) so the provider
reads as Aliyun rather than Bailian. Square aspect matches the other provider
icons. Source: Alibaba Cloud / Alibaba Group brand assets.

* style: prettier format AliDocMind + media extraction files

* fix(extraction): harden AliDocMind — SSRF guard, cred verify, env gate, table text

Addresses review findings on the AliDocMind provider:

- SSRF (high): the media branch of /api/extract-document now runs the same
  validateUrlForSSRF check on a client-supplied baseUrl as the document branch,
  so an audio/video upload can't point the server's Aliyun SDK at an internal
  host.
- Credential verify (high): verifyAliDocMindCredentials now whitelists success
  signals instead of blacklisting auth errors. Probed against the real API:
  valid creds + bogus job returns a no-throw "BizIdNotExistOrResultExpired"
  body; invalid creds throw InvalidAccessKeyId.NotFound. Only a no-throw
  response or a "biz-not-found" business error counts as valid — an unreachable
  endpoint, a localized error, or throttling now correctly reports failure
  instead of a false "connection successful".
- Env-fallback gate (med): resolveCredentials no longer reads
  ALIDOCMIND_ACCESS_KEY_ID/SECRET unconditionally. Env fallback is opt-in via
  allowEnvFallback, which the route sets only for a server-managed provider, so
  an unauthenticated client request can't silently run on the server account.
- getDocParserResult error body (med): fetchResult throws on a non-200 result
  envelope instead of returning {} (empty text presented as success).
- Media pagination (med): stop after the first page when segments[] are present
  — layoutNum/layoutStepSize address layout blocks, not media segments, so
  re-requesting would loop over the same segments to the safety cap.
- Table content (med): tables/charts carry content in llmResult, not
  markdownContent; the layouts→text mapping now prefers llmResult for those
  types so table content isn't dropped (tables: true was advertised).
- Dead code: remove getCurrentMediaParseConfig (referenced non-existent store
  fields; the single-panel UI reuses pdfProvidersConfig).
- Dedup: media MIME list lives only in lib/document/mime.ts
  (ALIDOCMIND_MEDIA_MIMES); the media registry imports it.
- Tests: smoke test asserts durationMs is in ms (>1000 for a ~52s clip) to
  guard a ms/s unit mismatch; uses allowEnvFallback for the env-cred path.

Verified with the real key: PDF + video smoke tests pass; verify classifies
valid vs invalid creds correctly.

Part of #886.

* feat(extraction): extract AliDocMind images to base64 (parity with unpdf/MinerU)

AliDocMind embeds figure/picture image URLs inside each layout's
markdownContent (markdown `![](oss-url)`), not a dedicated field, and the URLs
are short-lived OSS signed links. Previously we emitted `images: []` and left
the expiring URLs inside the extracted text.

Now, for figure/picture layouts we:
- parse the OSS image URL out of markdownContent,
- fetch it at extraction time (before the signature expires) and re-encode to
  PNG base64 via sharp — the same base64 `images[]` contract unpdf/MinerU
  produce, so downstream storeImages → IndexedDB → slide works unchanged,
- populate metadata.pdfImages + imageMapping (the generation flow prefers
  pdfImages),
- strip the remote-URL markdown from the emitted text so expiring links don't
  leak into the prompt.

Downloads run concurrently; a failed/`sharp` image is dropped, never failing
the whole parse. Also fixes the prior over-broad table handling: only `table`
blocks read llmResult; `figure` is treated as an image (chart-figure llmResult
still kept in text).

Verified with the real key: a sample PDF yields 24 base64 images in both
images[] and metadata.pdfImages, and no oss-cn-hangzhou URLs remain in text.

Part of #886.

* docs(test): note AliDocMind video smoke test is non-deterministic server-side

* fix(extraction): correct AliDocMind pageCount (pageNum is 0-based)

Verified against a real response: AliDocMind reports pageNum 0..13 and
pageCountEstimate 13 for a 14-page document — both are 0-based. The metadata
pageCount previously used pageCountEstimate directly, undercounting by one.
Use the already-1-based maxPage, falling back to pageCountEstimate+1 only when
no blocks were seen. Document the 0-based convention at the normalization site.

* fix(extraction): address AliDocMind review — verify/SSRF/config/media (P1+P2)

Resolves all P1/P2 findings from the cross-review on #887.

P1 (blocking):
1. verifyAliDocMindCredentials now inspects the no-throw response body.code.
   An OSS-only key returns NoPermission without throwing; previously that was
   green-lit as "connection successful" then failed at extraction. Only a
   success/200 or the job-not-found probe code is accepted. Deterministic
   mocked test added (tests/document/alidocmind-verify.test.ts).
2. verify route trust boundary: managed → server-owned AK/SK + default endpoint
   only (ignore client values); unmanaged → client creds only, never env
   fallback, and the client endpoint is SSRF-validated before signing.
3. image fetch hardened: restricted to Aliyun OSS hosts, redirects disallowed,
   per-image byte cap, image-count cap, bounded concurrency (was unbounded
   Promise.all over provider-returned URLs).
4. AliDocMind is now selectable in the generation toolbar — availability
   recognizes the AK/SK pair, not just apiKey.

P2 (correctness):
5. Explicit server-config for the AK/SK pair (applyAliDocMindFallback +
   resolveManagedAliDocMindCredentials); verify and extract now resolve
   managed/env identically instead of verify-uses-env / extract-rejects.
6. Poll loop checks body.code before status, so a body-level error (e.g.
   NoPermission) fails fast instead of retrying for the full 15 min.
7. Image page numbers preserved through fetch/filter — no longer hard-coded to
   page 1, so multi-page image→page association is correct.
8. Empty media extraction (no synopsis/transcript/keyframes) returns 422
   PARSE_FAILED instead of HTTP 200 with empty text.
9. Format matrix trimmed to the official contract: images JPG/JPEG/PNG/BMP/GIF
   (dropped WebP/JP2), media MP4/MKV/AVI/MOV/WMV/MP3/WAV/AAC (dropped M4A).
10. A document-only provider (unpdf/mineru) uploaded with a media file now
    returns a clear 4xx instead of an opaque 500.

P3: credential-verify failures return INVALID_CREDENTIALS 4xx (not
INTERNAL_ERROR 500); formatTimestamp emits HH:MM:SS past one hour.

Verified with the real key: verify classifies valid→ok and invalid→fail; PDF
(24 images, correct page numbers) and MP4 extraction pass end-to-end.

* fix(extraction): make AliDocMind selectable + correct analysis label for media

Two UI/UX fixes found while manually testing the AliDocMind flow end-to-end:

- Persisted-state backfill: add ensureBuiltInPDFProviders so a PDF/document
  provider added after a user's settings were persisted (AliDocMind) is
  backfilled into pdfProvidersConfig on rehydrate. Without it the provider
  never appeared in the store, so it couldn't be selected and never picked up
  its server-configured flag. Wired into both persist migrate() and merge(),
  mirroring the existing image/video/web-search backfills.

- Analysis step label: getGenerationStepText showed "解析 document 文件" for
  audio/video (the type map fell through to the literal "document"). Documents
  keep their precise token (PDF/DOCX/PPTX/XLSX/images); audio/video now use a
  dedicated, locale-correct string (generation.analyzingMediaMaterial, added to
  all 8 locales) instead of forcing a format token into the "{{type}} 文件"
  template.

Manually verified end-to-end (real key): PDF, MP4, and MP3 (audio extracted
from the sample video) each extract and drive full course generation; a
DocMind-restricted AK/SK (OSS-only) now correctly fails verification with
NoPermission (400) instead of a false "connection successful".

* fix(extraction): address 2nd-round AliDocMind review (managed creds, stream cap, empty verify)

Resolves the three follow-up findings on #887:

1. [P1] YAML-managed AliDocMind creds now reach extraction. Both extract paths
   (document + media) previously cleared the managed AK/SK and relied on an
   env-only fallback, so a YAML-only deployment verified but failed to extract.
   They now resolve server-owned creds via the shared
   resolveManagedAliDocMindCredentials() (env OR YAML), matching the verifier.
   Regression test added for YAML-only creds with no ALIDOCMIND_* env.

2. [P1] Image download is now size-capped while streaming. Instead of buffering
   the whole response and checking length afterward, the body is read chunk by
   chunk with a cumulative byte count that aborts the moment it exceeds the cap
   — a missing/false Content-Length can no longer exhaust memory. Host allowlist
   tightened to oss-*.aliyuncs.com. Tests: non-OSS host refusal, no-Content-Length
   overflow abort, declared-oversize rejection.

3. [P2] Empty verification body no longer counts as success. Removed the
   codeStr === '' branch from the positive-signal whitelist (a working key
   always returns the job-not-found business code for the bogus probe id).
   Regression test added for empty and absent bodies.

Rebased onto main (package.json: kept @openmaic/storage + AliCloud deps).
Verified with the real key: PDF + MP4 extraction still pass end-to-end.

* fix(extraction): merge AliDocMind AK/SK into a baseUrl-configured YAML entry

Follow-up to the YAML-managed credential fix. When a YAML `pdf.alidocmind`
entry also specifies `baseUrl`, the generic loadEnvSection() (pdf requires a
baseUrl) creates the pdf.alidocmind entry copying only apiKey/baseUrl/models/
proxy — never AK/SK. applyAliDocMindFallback() then returned early because the
entry already existed, so the provider was "managed" but had no usable
credentials, and resolveManagedAliDocMindCredentials() returned undefined
(verify + extract both silently lost the creds).

Merge the AK/SK into the existing entry instead of returning early. Added a
regression test with baseUrl + accessKeyId + accessKeySecret together (the
previous test omitted baseUrl, so the generic loader skipped the entry and the
bug was masked).

* fix(extraction): don't mark AliDocMind managed without AK/SK; align poll code check

Two edge cases from a follow-up adversarial pass:

- [MED] A YAML `pdf.alidocmind` entry with `baseUrl` but no AK/SK (and no env
  AK/SK) made the generic loader create the entry → isServerConfigured=true
  (managed) → but resolveManagedAliDocMindCredentials() returned undefined, so
  the provider was locked out AND client-entered AK/SK were silently dropped.
  applyAliDocMindFallback now deletes a credential-less entry so the provider
  stays UNMANAGED (clients supply their own creds). Regression test added.

- [LOW] verify accepted a `code: "success"` body but the extraction poll loop
  threw on any non-"200" code — a success-shaped status would pass verification
  then fail extraction. The poll loop now treats "200"/"success" as benign,
  matching verifyAliDocMindCredentials.

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-07-14 18:12:31 +08:00
wyucand杨慎 40ff80ab63 feat(editor): add draggable insert toolbar (#912)
* feat(editor): add draggable insert toolbar

* fix(editor): improve toolbar accessibility

* fix(quiz): update empty-state guidance

* fix(settings): sanitize retired toolbar state

* fix(editor): keep hints from blocking controls

* fix(editor): refine toolbar and hint interactions

* fix(editor): preserve toolbar position across scenes

---------

Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
2026-07-14 11:57:51 +08:00
c56929510c feat(web-search): add SearXNG provider support (#842)
* feat(web-search): add SearXNG provider support

Enable self-hosted SearXNG via SEARXNG_BASE_URL, with server-side provider
fallback, settings sync, and tests.

Co-authored-by: Cursor <cursoragent@cursor.com>

* style: fix Prettier formatting in web-search files

Restore pnpm check by applying Prettier to imports, headers, and test assertions.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(web-search): keep SearXNG base URLs server-managed only

Close the SSRF primitive by ignoring client-supplied SearXNG URLs at the
route boundary and rejecting them in resolveSafeClientWebSearchBaseUrl.
Add negative route/config tests and an opt-in live smoke test for the
JSON API.

Co-authored-by: Cursor <cursoragent@cursor.com>

* style: fix Prettier formatting for SearXNG web-search changes

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: 徐松 <song.xu@aieshanghai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-13 23:12:31 +08:00
3b63710376 feat(ai): add Azure OpenAI provider (#916)
* feat(ai): add Azure OpenAI provider

Add deployment-based Azure OpenAI configuration for both client and server-managed setups, normalize Azure portal endpoints, and expose the provider in settings.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b0d3a94f-089a-470e-9987-608f1506ca6f

* style: format Azure provider type

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: b0d3a94f-089a-470e-9987-608f1506ca6f

---------

Co-authored-by: MarshellOnMoon <121332425+MarshellOnMoon@users.noreply.github.com>
2026-07-13 23:12:23 +08:00
jackefnandRowan_lxb baff0998bb Feat/document bundles milestone 3 (#844)
* feat(document): support document bundles

* fix(document): avoid server extractor imports in client bundle

* fix(pdf): default mineru backend to pipeline

* fix(document): address bundle review findings

* fix(document): harden extraction limits and storage errors

* fix(document): make analysis step format agnostic

---------

Co-authored-by: Rowan_lxb <Lxb_savior@163.com>
2026-07-13 23:01:40 +08:00
Yizuki_AmeandClaude Fable 5 e136c81c03 chore(generation): remove dead legacy pipeline chain (#904) (#905)
Remove the generation-pipeline leftovers orphaned since the old
/api/generate route was deleted in 0610053:

- pipeline-runner.ts (runGenerationPipeline / createGenerationSession)
- generateFullScenes + generateSingleScene in scene-generator.ts
- unreachable callbacks param of generateSceneOutlinesFromRequirements,
  including its five hardcoded Chinese statusMessage strings
- generating-progress.tsx (never imported since the initial commit)
- orphaned GenerationCallbacks / GenerationProgress / GenerationSession
  types, 5 unused i18n keys across all 8 locales, and stale
  generateFullScenes references in DESIGN-regenerate-scene.md

Found while investigating #884. Verified against a pre-change baseline:
tsc --noEmit diff clean, vitest failure set unchanged (1956 passed),
check:i18n-keys passes, zero residual references repo-wide.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-11 21:56:35 +08:00
b4c1c580f8 fix(generation): localize scene generation errors (#894)
Co-authored-by: wsun1 <wsun1@users.noreply.github.com>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-07-11 11:57:17 +08:00
PhillLittlewoodandwyuc a2886af92a Added ComfyUi to has Image Provider (#850)
* feat: integrate comfyui workflows into image provider selection

* style: format code with prettier

* fix: align i18n keys for russian locale

* feat: implement requested changes and format code

* feat: implement requested changes including renaming default workflow

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-07-10 18:49:28 +08:00
Yanpeng Wang b5e1963e48 feat(document): rename to Document Parsing, show supported formats, extend MinerU support
Squashed from PR #837 after review approval and green CI.
2026-07-09 04:29:58 -04:00
danishsshaikh d00795094c feat(playback): add action-level navigation (#843)
Squashed from #843. Adds Notes click-to-jump action navigation and action-level playback resume/restore, with visible toolbar sentence controls removed after review.
2026-07-08 00:02:39 -04:00
wyucandClaude Opus 4.8 6b93980f82 feat(editor): redesign the narration timeline (action picker + inline insert) and enable it for interactive/PBL scenes (#834)
* feat(editor): enable narration timeline for interactive/pbl scenes

* docs(editor): fix stale timeline-gating comment in EditChromeRoot

* i18n(editor): add action-picker + addAction strings

* feat(editor): pure pickerOptions filter for the action picker

* feat(editor): ActionPicker popover (shared by header pill + inline +)

* feat(editor): header add-action pill opens ActionPicker; drop drag-chips

* feat(editor): inline + insert between cells opens ActionPicker

* style(editor): reskin SpeechClip + TTS footer to Pro Mode v2

* style(editor): align discussion dash tint to neutral primary token

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

* style(editor): reskin CueMarker (bound label) + DiscussionClip + NodeDot

* fix(editor): complete picker i18n locales, label inline insert button, use primary token

- Add edit.timeline.addAction and edit.picker.{title,speechDesc,spotlightDesc,laserDesc,discussionDesc}
  to zh-TW, ja-JP, ko-KR, ru-RU, pt-BR, ar-SA locale files, mirroring the
  existing en-US/zh-CN structure.
- Give the inline "+" insert button in ActionsBar's DropZone an accessible
  name (aria-label + title) by threading an insertLabel prop from the root
  component, which already has the translator.
- Replace the raw bg-violet-500 active-divider glow in DropZone with the
  bg-primary token.

* chore(editor): drop dead drag-to-add path and orphaned i18n keys, explain disabled discussion option

* style: format picker-options with prettier

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-03 03:26:38 -04:00
Yanpeng Wang d54e62f5c4 feat(token-plan): one-click token-plan setup + deployment usage dashboard (#784)
* feat(usage): add usage normalization, pricing, model-fetch, balance, storage

Foundational layer for token-plan usage tracking (cc-switch-modeled):
- lib/usage/normalize.ts: AI SDK v6 usage → four-class token shape
- lib/usage/pricing.ts + defaults: per-class USD pricing table
- lib/server/model-fetch.ts: /models candidate-URL multi-fallback (ported)
- lib/usage/balance-providers.ts: built-in balance queries + detection
- lib/server/usage-storage.ts: fire-and-forget jsonl logging to data/usage

All pure/storage logic covered by vitest (32 tests).

* feat(usage): capture token usage at the callLLM/streamLLM chokepoint

- callLLM records result.usage before returning
- streamLLM wraps onFinish to record totalUsage on stream completion,
  preserving any caller-supplied onFinish
- provider/model derived from the model instance (no route changes)
- fs-backed storage imported dynamically; fire-and-forget, never throws
- include_usage is already sent by @ai-sdk/openai, so streaming is covered

* feat(usage): add probe-models, balance, and usage API routes

- POST /api/provider/probe-models: discover chat models via /models with
  candidate fallback; SSRF-guarded; filters non-chat ids; 401/404 typed
- POST /api/provider/balance: built-in balance detection + billing fallback
- GET /api/usage: aggregate jsonl by model/day/source with costIncomplete flag

Verified e2e against the live MAIC gateway: 16 chat models (6 filtered),
balance detected, and a real callLLM writes a costed usage row.

* feat(settings): add token-plan preset picker to provider dialog

- lib/config/token-plan-presets.ts: data-driven vendor presets (Huawei/MiniMax/
  Xiaomi token plans, OpenRouter/SiliconFlow gateways, DeepSeek/GLM/Qwen/Hunyuan/
  Doubao direct) with baseURL, protocol, optional modelsUrl, category
- add-provider-dialog: '选择厂商/自定义' tabs; picking a preset auto-fills
  baseURL+protocol+modelsUrl, custom tab unchanged
- ProviderSettings.modelsUrl carries the optional /models override
- i18n keys added across all 8 locales

Verified in-browser: preset picker renders grouped by category.

* feat(settings): add Fetch Models button and balance bar to provider panel

- 拉取模型: probes /models, merges discovered ids into the model list
  (dedupe, keeps manual additions), with success/no-endpoint/auth messages
- 查询余额: queries /api/provider/balance, renders a balance bar or a
  'check console' hint when unsupported
- index.tsx: handleModelsFetched merges probe results into provider config
- i18n keys across all 8 locales; removed a now-unused eslint-disable

Verified in-browser against MAIC gateway: 16 models fetched, balance shown.

* feat(settings): add usage dashboard to System Settings

- usage-dashboard.tsx: echarts dual-axis daily trend (tokens + cost),
  totals cards, by-model table, refresh; reads GET /api/usage
- mounted at the top of GeneralSettings (系统设置)
- honest disclaimer + costIncomplete marker when a model lacks pricing
- i18n keys across all 8 locales

Verified in-browser: shows 1 request / 31 tokens / $0.0003 from a prior call.

* feat(token-plan): multi-modal one-click setup in System Settings

- token-plan-presets.ts: presets now declare per-modality targets
  (llm/image/video/tts/webSearch); MiniMax is the full-set template,
  others LLM-only — extend by adding entries (at-our-best adaptation)
- apply-token-plan.ts: fills one key into every declared modality via
  injected store setters, isolating per-modality failures (TDD, 4 tests)
- token-plan-settings.tsx: new sidebar page — pick plan, enter key,
  one-click apply lights up adapted modalities (+LLM model probe),
  shows 'not adapted yet' for the rest, balance bar reused
- reverted add-provider dialog to plain custom form (preset picker moved here)
- i18n across all 8 locales

Verified in-browser: Token Plan page renders, MiniMax shows all 5
modalities, apply/balance UI wired. 859 tests pass, build clean.

* feat(token-plan): add custom token plan entry to Token Plan page

- Custom card at the bottom of the provider list: pick it to manually enter
  name + protocol + baseURL (LLM-only), then key + one-click apply via the
  same applyTokenPlan flow (mirrors cc-switch's custom provider)
- effectivePreset unifies preset vs custom for apply/balance/probe
- i18n keys (customGroup/customName/customHint) across all 8 locales

Verified in-browser: custom card expands the manual form; preset flow intact.

* feat(token-plan): reflect persisted config on the Token Plan page

Other settings panels read the store directly, so they survive section
switches; the Token Plan page only wrote the store, so it looked blank on
return. Now it also reads providersConfig:
- selecting a preset prefills its saved API key
- configured presets show a '已配置/Configured' badge

State persistence was never broken (apply writes zustand→localStorage);
this fixes the missing read-back so the page reflects it.

* fix(settings): isLLMProviderConfigured crashed on providers without models

Root cause of 'token plan config disappears': applyTokenPlan writes a new
LLM provider with no models yet (probe fills them later). isLLMProviderConfigured
did config.models.length unguarded → threw inside setProviderConfig's resolver
→ the whole set() aborted → key/baseUrl/type never persisted.

- guard models in isLLMProviderConfigured (shared validator; affects any
  provider written without a models array)
- seed models:[] in applyTokenPlan's LLM write for a valid initial shape
- regression tests: validator no longer throws; apply+probe write keeps apiKey

Verified in-browser: DeepSeek persists key and shows 已配置 after section switch.

* feat(token-plan): add remove/teardown for a configured token plan

Apply had no inverse. Add removeTokenPlan: clears the API key and disables
(enabled:false) every modality the plan declared; a custom LLM provider is
deleted entirely (removeProvider), built-ins keep the cleared shape.

- removeTokenPlan in apply-token-plan.ts (mirrors applyTokenPlan, isolated
  per-modality, injected setters; 3 tests)
- trash button on configured preset cards in the Token Plan page; resets
  page state if the removed plan was selected
- i18n 'remove' across all 8 locales

Verified in-browser: removing DeepSeek empties its key and drops the
已配置 badge.

* feat(usage): track multimodal usage, drop cost/pricing

Reframe usage stats as pure usage (no cost), per user decision:
- usage-storage: drop all cost fields; add kind (llm/image/video/tts/asr)
  + quantity + unit; LLM keeps token counts, others store quantity
- delete lib/usage/pricing.ts + pricing-defaults.json + its test
- instrument image/video/tts at the server-only API routes (not in the
  provider dispatch — those files are in the client graph and importing
  fs-backed usage-storage broke the client bundle)
- /api/usage: aggregate by model/day/modality, no cost
- dashboard: per-modality usage (tokens/images/seconds/chars), token-only
  daily trend, no '$'; i18n cost keys replaced with modality/unit keys
- backward compatible: legacy rows (no kind, stray cost fields) read as llm

912 tests pass, build clean.

* feat(usage): per-modality dashboard layout + softer dark-mode chart

- group usage into per-modality sections (LLM/image/video/tts/asr), each
  table's usage column uses one consistent unit (token/image/sec/char) —
  no more mixed units in a single column
- summary chips per modality with their own unit
- trend chart now plots daily REQUESTS (unit-agnostic, works for any
  modality) instead of LLM-only tokens
- theme-aware chart: faint thin line + soft gradient area, muted axis/grid
  colors via useTheme — fixes the harsh solid stroke in dark mode

Verified in-browser (dark): TTS shows '字符', LLM shows 'Token', separate
sections; chart no longer has a hard line.

* refactor(usage): dedupe model/fetch/usage helpers, parallel balance probe

Review cleanups on the token-plan/usage branch:
- extract modelInfoFromId() (shared vision heuristic + ModelInfo shape)
- extract fetchWithTimeout() shared by model-fetch and balance-providers
- extract recordGenerationUsage() to dedupe the image/tts/video routes
- queryBalance: fetch billing subscription + usage in parallel
- parseOneApiBilling: report quota without remaining when usage endpoint
  is unavailable, instead of implying zero spend (full balance)
- split the two jammed imports in settings/index.tsx

* feat(token-plan): drop custom token-plan support

Custom token plans (manual baseURL/protocol entry) added complexity for
little gain — a one-off provider is better configured directly on the
Providers page. Token Plan is now preset-only:
- remove custom mode, manual fields, and the custom card from the UI
- collapse effectivePreset back to the selected preset
- drop the now-dead removeProvider action + custom-id branch in
  removeTokenPlan
- remove orphaned customGroup/customName/customHint i18n keys (8 locales)

* feat(token-plan): add Volcengine/Tencent/Bailian plans, drop balance feature

Add three vendor token-plan presets (all map to existing built-in LLM
providers, so it's data-only — no new adapters):
- 火山方舟 Volcengine Ark → doubao, OpenAI /api/v3
- 腾讯 TokenHub Token Plan → tencent-hunyuan, OpenAI /plan/v3 (the
  plan-specific base; /v1 is the pay-as-you-go gateway)
- 阿里百炼 Token Plan → qwen, cross-model plan (Qwen + DeepSeek/Kimi/
  GLM/MiniMax) on one key; model list is probed/entered

Remove the balance/quota feature entirely — we now track usage, not cost,
and every vendor's balance query needs its own cloud AK/SK + signature
(Volcengine SigV4 / Tencent TC3 / Aliyun BSS), which the Bearer-key
billing-endpoint probe never supported anyway:
- delete lib/usage/balance-providers.ts, /api/provider/balance, its test
- strip the Check Balance button + balance bar from the token-plan page
  and the provider config panel
- remove the 4 balance i18n keys across all 8 locales
- restore an eslint-disable the branch had dropped in provider-config-panel

* feat(token-plan): use cloud-brand logos for vendor token plans

The three vendor plans are cloud offerings, not single-model products, so
icon them with the cloud brand rather than a model logo:
- 火山方舟 → volcengine.svg (was doubao.svg)
- 腾讯 TokenHub → tencentcloud.svg (was hunyuan.svg)
- 阿里百炼 → alibabacloud.svg (was bailian.svg)

Logos are the colored brand variants from lobehub/lobe-icons, matching the
existing colored-logo style (plain <img>, no dark:invert needed).

* feat(token-plan): keep only MiniMax and Volcengine presets

Trim the token-plan list to the two we want to ship: MiniMax (full-set
template) and 火山方舟 Volcengine Ark. Drop the Tencent/Bailian plans and
the OpenRouter/SiliconFlow/DeepSeek/GLM/Qwen entries.

- remove the now-unused tencentcloud.svg / alibabacloud.svg logos
  (volcengine.svg stays; the other logos are still used by the provider
  registry)
- retarget the LLM-only apply test from the deleted deepseek preset to
  volcengine-ark

* feat(token-plan): restore aggregator/third-party presets

Previous commit over-trimmed: the intent was to drop only the Tencent and
Bailian token plans, not the OpenRouter/SiliconFlow/DeepSeek/GLM/Qwen
entries. Bring those back; keep only Tencent/Bailian removed.

- token_plan: MiniMax, 火山方舟 Volcengine Ark
- aggregator: OpenRouter, SiliconFlow
- third_party: DeepSeek, GLM, Qwen

Revert the apply test back to the deepseek fixture (restored).
tencentcloud.svg / alibabacloud.svg stay deleted (their plans are gone).

* fix(token-plan): point Volcengine plan at the Coding Plan endpoint

The plan's ark--prefixed API keys authenticate only against
/api/coding/v3, not the general /api/v3 endpoint — the latter rejects them
with "The API key format is incorrect", so model probing returned nothing.
Switch the base URL to https://ark.cn-beijing.volces.com/api/coding/v3.

* fix(token-plan): Volcengine is an Agent Plan (Anthropic /api/plan)

Per the Ark Agent Plan docs, the ark--prefixed keys authenticate ONLY
against the dedicated Anthropic-compatible base https://ark.cn-beijing.
volces.com/api/plan ("其他 Base URL 无法在 Agent Plan 中使用"). The general
/api/v3 and the Coding Plan /api/coding endpoints both reject the key as
"API key format is incorrect", which is why model probing kept returning 0.

- baseUrl → https://ark.cn-beijing.volces.com/api/plan/v1 (the /v1 lets the
  Anthropic SDK land on /api/plan/v1/messages)
- apiFormat → anthropic
- rename to 火山方舟 Agent Plan

Probe still targets /api/plan/v1/models (the path exists); if the Anthropic
gateway doesn't return an OpenAI-shaped list, users fall back to typing a
model id like ark-code-latest.

* fix(token-plan): Volcengine Agent Plan = OpenAI /api/plan/v3 + ark-code-latest

Settled after probing the real key and reading cc-switch's approach:
- The ark- plan key works on the OpenAI-compatible /api/plan/v3 endpoint
  (chat/completions returns 200); switch apiFormat back to openai.
- The plan exposes NO /models list (every /api/plan/*/models is 404), which
  is why probing kept returning 0. cc-switch handles this by hardcoding a
  single ark-code-latest (an auto-routing alias valid on any tier) and does
  NOT use AK/SK for model listing — so we do the same.
- Seed defaultModels: ['ark-code-latest'] only; users add specific ids by hand.

Supporting machinery (kept, general-purpose):
- applyTokenPlan seeds models from defaultModels instead of wiping to []
- handleApply uses defaultModels and skips the doomed probe when present
- drop stray .playwright-mcp/ debug artifacts and gitignore them

* style: fix prettier formatting in usage files

CI runs prettier on the whole repo (prettier . --check); these four files
predate this branch's formatting pass and tripped the check.

* feat(token-plan): verify Volcengine Agent Plan's published model set

The Agent Plan publishes a fixed model set but exposes no /models endpoint,
so carry the documented models as CANDIDATES and verify each on apply:

- add verifyModels flag to TokenPlanModalityTarget
- new /api/provider/probe-chat-models route: sends a minimal chat request per
  candidate (OpenAI /chat/completions or Anthropic /messages) in parallel,
  returns the subset that succeeds; SSRF-guarded, auth-failure short-circuits
- handleApply gains a verify branch (before the fixed-defaultModels fast path),
  falling back to the seeded list if verification fails
- Volcengine preset now carries the 12 published Agent Plan text models
  (doubao-seed-2.0-*/deepseek-v4-*/minimax-m*/glm-5.2/kimi-k2.*) as candidates

This auto-prunes retired (docs flag deepseek-v3.2/glm-5.1 as 即将下线) and
tier-gated models without code changes. Verified all 12 resolve against a real
plan key.

* feat(token-plan): wire Volcengine Agent Plan image + video modalities

Make the Ark seedream/seedance adapters path-configurable and light up the
image/video modalities on the Volcengine plan:

- seedream/seedance adapters: resolveArkRoot() uses baseUrl verbatim when it
  already carries an /api/... path (token plan's /api/plan/v3), else appends
  the standard /api/v3 — no regression for the pay-as-you-go default host.
- applyTokenPlan: image/video branches inject a modality's defaultModels as
  customModels and set them as the active provider+model, so generation works
  out of the box. New optional setImageProvider/ModelId + setVideoProvider/
  ModelId actions (UI passes the store setters; tests omit them).
- Volcengine preset declares image (doubao-seedream-5.0-lite, verified 200 on
  /api/plan/v3/images/generations) and video (doubao-seedance-2.0/1.5-pro —
  Medium+ tiers only; lower tiers reject at call time, no code change needed
  to upgrade).

Applying the plan overwrites the shared seedream/seedance slot with the plan
config (same overwrite model as LLM); switching back to pay-as-you-go is a
manual edit or plan removal. Verified image end-to-end with a real plan key.

* feat(token-plan): verify image/video models on apply, disable unsupported tiers

The Volcengine plan lit up video optimistically, but lower tiers (Small) don't
include video — so using it 404'd with UnsupportedModel. Probe media models on
apply and only keep what the tier actually supports:

- generalize /api/provider/probe-chat-models with a `kind` (chat|image|video):
  image hits /images/generations, video hits /contents/generations/tasks with
  empty content. The model-support check (404 UnsupportedModel) runs before any
  billable work, so probing never starts a real image/video job; for media,
  "supported" = any non-404 response.
- handleApply: after lighting up image/video, probe each verifyModels modality;
  prune to the verified model set + re-select a working model, or disable the
  modality entirely if none pass (no false "available").
- Volcengine preset: image/video targets gain verifyModels: true.
- add settings.tokenPlan.tierUnsupported across 8 locales.

Verified with a real Small-tier key: image (seedream-5.0-lite) passes and is
kept; video (seedance-2.0/1.5-pro) 404s and is disabled.

* feat(web-search): add Doubao (豆包搜索) provider

Doubao Search (Custom 版) over its REST endpoint
POST open.feedcoopapi.com/search_api/web_search with Bearer auth — the
same endpoint the askecho-search-infinity MCP server wraps, so the
Volcengine Agent Plan key authenticates directly. Mirrors the MiniMax
adapter: maps Result.WebResults to WebSearchSource (prefers Summary, the
query-relevant excerpt, over Snippet for LLM use) and surfaces errors
from ResponseMetadata.Error.

- register 'doubao' in WebSearchProviderId + WEB_SEARCH_PROVIDERS
- searchWithDoubao adapter, searchWeb dispatch, store default config
- SSRF allowlist entry for the search host

* feat(audio): support Agent Plan single-key auth for Doubao TTS

generateDoubaoTTS now picks auth + endpoint from the key shape, since
Volcengine exposes Seed-TTS as two products with separate credentials
(verified: a plan key 401s on the normal endpoint, and the plan endpoint
rejects appId-style auth):
  - single key (no colon) -> X-Api-Key, for the Agent Plan /plan endpoint
  - appId:accessKey        -> X-Api-App-Id + X-Api-Access-Key (unchanged)
A malformed pair (empty half) fails clearly instead of sending an empty
header. Reuses the existing NDJSON/base64-mp3 parsing and voice list.

* fix(media): map MiniMax video 720p to its real 768P tier

normalizeVideoOptions defaults minimax-video to '720p' (the first
supported resolution), but Hailuo 2.3 only accepts 768P/1080P and rejects
720P with '2013 ... does not support resolution 720P'. MiniMax's mid tier
is 768P, not 720P (the adapter already falls back to 768P, as does the
connectivity test), so map the shared enum's '720p' to 768P. Regression
tests lock the mapping.

* feat(token-plan): add web search + TTS to Volcengine Agent Plan, widen image tiers

Extend the volcengine-ark preset now that the adapters exist:
  - webSearch -> doubao (own host open.feedcoopapi.com, not the ark endpoint)
  - tts -> doubao-tts on the /api/plan/tts endpoint (single-key auth)
  - image defaultModels widened to a best-first Seedream 5.0/4.5/4.0 list so
    a higher tier keeps the strongest model while verifyModels prunes the
    rest; video keeps the 2.0 + 1.5-pro candidates

Comments record the verified host/auth quirks of each modality.

* feat(token-plan): show result panel only after probing, with two clear states

Addresses review feedback that a green check implied generation works
when it only meant 'configured'. The panel now renders after probing
finishes (gated on results && !applying) so it reflects the final set,
and uses two states: green when the modality is configured/usable, muted
when a live probe proved it unavailable (e.g. video on a tier without it).

* feat(token-plan): scope presets to true multi-modal token plans

Drop the single-modality LLM presets (OpenRouter, SiliconFlow, DeepSeek,
GLM, Qwen) from Token Plan. A token plan's defining trait is one key
spanning many modalities; those entries are ordinary LLM API providers
already covered by the add-provider flow, and listing them here muddied
the 'one key, every modality' promise. Only MiniMax and the Volcengine
Ark Agent Plan remain. The UI already hides categories with no entries.

apply-token-plan's LLM-only test now uses a local fixture instead of the
removed deepseek preset.

* feat(token-plan): progressive reveal of probe results on apply

The result panel previously rendered all at once after probing finished,
reading as dead air during the model probe. Now rows appear immediately on
Apply: modalities with a live probe in flight show a spinner ('pending')
and resolve to lit/failed independently as each probe returns, while
non-probe modalities show lit right away. Probes run in parallel
(Promise.all) instead of sequentially.

A row only turns green once its own probe confirms, so this reveals
structure + live progress without a premature green — complementing the
earlier 'render only after probing' intent rather than reverting it.

Per review feedback from @wyuc on #784.

* fix(token-plan): enrich seeded models with built-in thinking capability

Token Plan built ModelInfo objects from probed ids via modelInfoFromId(),
filling only streaming/tools/vision — so a model that supports configurable
thinking lost capabilities.thinking and InlineThinkingControl was hidden.

modelInfoFromId now takes an optional providerId and overlays the catalog
thinking capability for that (provider, model) pair; applyTokenPlan does the
same for its synchronously-seeded list. Added the Ark Agent Plan's dotted
aliases to the metadata table:
  - native Doubao Seed 2.0 family (doubao-seed-2.0-pro/code/lite/mini)
  - cross-vendor models the plan serves through its OpenAI-compatible endpoint
    (deepseek-v4-pro/flash, glm-5.2, kimi-k2.7-code/k2.6, minimax-m3/m2.7,
    ark-code-latest)

All verified against a live plan key: each accepts the gateway's unified
reasoning_effort field (low/medium/high) and actually reasons. They share the
doubao effort adapter, which disables via 'minimal' (not 'none') — matching
what the plan endpoint accepts (it rejects reasoning_effort:'none').

Addresses review point #1 from @wyuc on #784.

* Improve token plan capability setup UI

* fix token plan setup flow

* chore: prettier format tts-providers.ts
2026-07-03 11:03:12 +08:00
jackefnandYanpeng Wang 3b7a0ca0c0 feat(document): add multi-format course material upload (#741)
* feat(document): add multi-format course material upload

* fix(document): support office uploads with mineru cloud

* fix(document): handle mineru cloud office edge cases

* fix(document): align mineru cloud artifact metadata

---------

Co-authored-by: Yanpeng Wang <yanpg.wang@gmail.com>
2026-07-02 17:58:58 +08:00
wyuc 5daf3e5a6e fix(editor): keep emptied/zero-action scenes playable, bind outline by stable id, surface incomplete content (#814)
Editor empty-state robustness: dwell on zero-action scenes (engine + PlaybackChromeRoot) so emptied/blank slides stay playable; bind a scene's outline by stable outlineId (reorder/insert/duplicate-safe, allOutlines in scene order); clear the cue preview on glyph unmount; surface incomplete content calmly (amber dashed frame on clips, amber dot on blank outline titles + rail, neutral N/M-ready generate gate). Cross-reviewed (Codex + Claude), 5 rounds to a clean pass.
2026-06-30 05:57:26 -04:00
wyucandClaude Opus 4.8 b93434ae2c feat(agent-edit): multi-session conversation history for the AI editor (#801)
* feat(agent-edit): multi-session conversation history for the AI editor

The "Edit with AI" panel kept only one thread per stage in localStorage, and
"New conversation" deleted it, so previous conversations were unrecoverable.

Add a per-stage session list backed by IndexedDB (Dexie v12 `agentEditSessions`):

- "New conversation" now archives the current session and starts a fresh one
  instead of deleting it; a history popover in the panel header lists past
  sessions (auto-titled from the first user message) to switch back to or delete.
- One-time migration of the existing single-thread localStorage entry.
- The active session id is remembered per stage so a refresh restores it,
  including a just-cleared empty session (clean slate survives reload).
- saveSession preserves the original createdAt and tombstones deleted ids so an
  in-flight save can't resurrect a deleted session; switching stages drops the
  previous thread synchronously so it can't leak into the new stage.
- Sessions are pruned to a soft cap per stage and removed when a course is
  deleted.
- i18n for all 8 locales; unit tests for title derivation and the store.

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

* fix(types): drop redundant Window.SpeechRecognition augmentation conflicting with @assistant-ui/core

@assistant-ui/core's speech adapter declares Window.SpeechRecognition and
webkitSpeechRecognition globally as SpeechRecognitionConstructor. Three files
(prompt-input, use-audio-recorder, use-browser-asr) re-declared them as `any`,
which conflicts (TS2717) once that adapter's types are pulled into the program,
and the constructed instance then lacks the event handlers the code sets
(TS2339/2551). Rely on the global declaration and cast the instance to the local
rich shape. Takes `tsc --noEmit` back to zero.

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

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-28 23:08:23 -04:00
wyuc a88ee3d119 feat(editor): add discussion authoring to the script timeline (#798)
Add an append-only 'Add discussion' control + inline editor (topic/prompt/initiating agent) to the script timeline, respecting the action-parser invariant that a discussion is the scene's last action and at most one per scene. Yellow terminal-anchor styling; agent picker (with avatars) sourced from the selected agents the playback engine gates on. Runtime unchanged.
2026-06-26 04:21:35 -04:00
杨慎andwyuc 0f44e9a46f Add PBL v2 runtime APIs and classroom UI (#799)
* feat: add PBL v2 runtime UI

* fix: ship PBL v2 instructor avatar

* fix: ship PBL v2 workspace logo

* fix: prevent scenario PBL legacy fallback

* chore: restore package lint comments

* test: cover ordinary PBL legacy fallback

* fix: front-load PBL single-call validation

* fix: preserve PBL v2 content when assembling scenes

---------

Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-06-26 11:56:02 +08:00
杨慎 09863af421 Add PBL v2 core schema and generation path (#795)
* feat: add PBL v2 core planner

* chore: restore unrelated lint comments

* fix: document PBL v2 scenario outline flags

* fix: expose PBL scenario subtype in outlines

* chore: clear PBL v2 completion stats lint warning

* chore: address PBL instructor code quality comments

* fix: address PBL v2 review findings

* chore: restore unrelated lint comments
2026-06-25 18:44:46 +08:00
wyucandClaude Opus 4.8 dcf8a63333 fix(generation): make outline type changes take effect (interactive/PBL no longer downgraded to slide) (#772)
* feat(generation): changeOutlineType total constructor for valid type switches

Switching a scene outline's type in the editor only flipped `type` and left
the new type without its required config, so applyOutlineFallbacks silently
downgraded interactive/pbl back to slide. changeOutlineType returns a new
outline that strips foreign per-type config and seeds the target type's
required config from the shared fields, valid by construction.

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

* i18n(generation): keys for interactive widget kind and PBL project config

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

* feat(editor): make outline type changes take effect with config forms

TypePill now builds a valid outline via changeOutlineType (replace, not
partial-merge) so a type switch drops stale config and seeds the new type's
required config — no longer silently downgraded to slide by applyOutlineFallbacks.
Adds InteractiveConfigDisclosure (widget kind + concept) and PblConfigDisclosure
(topic / description / target skills), mirroring QuizConfigDisclosure, so users
can configure interactive and PBL scenes that previously had no input UI.

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

* fix(editor): move type-specific config under the type pill

The quiz/interactive/PBL config disclosure rendered as a detached chip at the
bottom-left of the card, reading like a stray key point. Pin it to the
bottom-right of the key-points row instead, so it sits directly under the
TypePill it configures (type top-right -> its config bottom-right, same edge),
with key points flowing on the left.

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

* fix(editor): cascade type config as a connected segment left of the type pill

Replace the standalone config chip with a cascading control in the header: the
type-specific config (quiz count / interactive widget kind / PBL project) renders
as a themed segment joined to the left of the TypePill, the two clipped into one
rounded pill split by a hairline divider. Reads as a single 'config › type'
cascade and groups the config with the selector it refines.

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

* fix(editor): address cross-review — preserve widget config, drop stale fields

- changeOutlineType: preserve an existing procedural-skill widget config
  instead of replacing it with a seeded simulation (codex P2 — task-engine
  fields were silently dropped on Interactive re-select).
- InteractiveConfigDisclosure.setWidgetType: reset widgetOutline to the shared
  concept only, so switching widget kind drops the previous kind's fields
  (claude P2 — language/gameType/etc. leaked across kinds).
- i18n locale-coverage test now also checks ko-KR and pt-BR.
- Drop a redundant WidgetType cast; add tests for procedural-skill preservation
  and pbl targetSkills dedupe/cap.

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

* fix(editor): round 2 cross-review nits — procedural-skill label + skill a11y

- InteractiveConfigDisclosure: when an outline carries a preserved
  procedural-skill widget, surface it as the current (selected) kind with its
  own label instead of mislabeling it 'Simulation', and make a same-kind
  re-select a no-op so its task-engine fields are never silently clobbered.
- PBL target-skill remove button uses a dedicated removeSkill aria-label.
- Add widgetProceduralSkill / removeSkill i18n keys (8 locales) + test coverage.

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

* fix(generation): make re-selecting the current outline type a no-op

changeOutlineType rebuilt the outline on every type-menu click, so re-selecting
the already-current type dropped fields it doesn't re-seed — legacy
interactiveConfig, or a partial pblConfig whose projectTopic is empty — turning a
harmless click into data loss. Short-circuit same-type selections to return the
outline untouched (codex P2).

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

* chore(format): prettier --write files left unformatted on main

These 14 agent/edit files (not part of this PR's feature) fail the repo-wide
`prettier . --check` in the required Lint job — they landed on main unformatted,
turning main's CI (and therefore this PR after a branch update) red. Formatting
them here unblocks the required check; pure formatting, no logic changes.

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

* fix(lint): suppress intentional set-state-in-effect in reasoning timer

The reasoning timer does a deliberate one-shot setState in its effect to show
the right elapsed value before the first 1s interval tick. main's CI fails the
required Lint job on the new react-hooks/set-state-in-effect rule here; suppress
it with a justification (no behavior change). Unblocks the required check.

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-06-23 17:48:07 +08:00
wyuc 1d1ce80e04 feat(maic-agent): editor-agent line (v0) — Pro-mode "Edit with AI" (#777)
Promote the editor-agent line to main: read-then-act editor agent (read_scene_content, regenerate_scene, regenerate_scene_actions, edit_interactive_html), a routable maic-agent model stage, the agent sidebar UI, interactive-scene runtime-error capture, and the timeline/script editor. Cross-reviewed and smoke-verified; see #777.
2026-06-23 16:56:37 +08:00
moduvoice 85395c0e4b feat(i18n): add Korean (ko-KR) translation (#733)
Add a full Korean locale (lib/i18n/locales/ko-KR.json, all 1018 keys translated
from en-US.json) and register it in lib/i18n/locales.ts per TRANSLATION_GUIDE.md.
i18next {{interpolation}} preserved; AI provider/model brand names kept per the
existing ja-JP convention.

Signed-off-by: moduvoice <moduvoicr77@gmail.com>
2026-06-14 16:55:42 +08:00
7bb9e864ae feat(packages): introduce maic-import and maic-renderer workspace packages (#668)
* feat(import): add pptxtojson-pro workspace package and stage-1 PPTX import

Vendor the TypeScript pptxtojson-pro parser as a workspace package, sync its
bundle to public/vendor at install time (avoids Turbopack dynamic require
issues), and wire a home-page import hook that parses files for inspection.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(import): extend pptxtojson-pro with PPTX → Slide[] pipeline

`importPptx` now turns a .pptx file directly into canvas `Slide[]`,
optionally uploading every base64 image and blob-backed media via a
caller-supplied OSS callback before resolving.

- Vendor OpenMAIC slide types and shapes config into `src/openmaic/`
  so the bundled dist is self-contained and loadable via `/vendor/`
  URL under Turbopack; add stubs for `resolveFont`, `getSvgPathRange`
  and `parseVideoCodec` until the real PPTist helpers are ported.
- Move `import-pipeline/` under `src/` and re-export `importPptx`,
  `parsedToSlides`, `OssUpload`, `ImportPptxOptions` and `CanvasSlide`
  from the package main entry.
- Add `nanoid`, `katex` and `pptxtojson` as runtime deps of the package.
- Update `useImportPptx` to accept `upload` / `onImported` and return
  the converted `Slide[]`.
- Document the new API surface, error semantics and Turbopack workaround
  in the package README.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(slide-renderer): package skeleton (rollup + tsc + empty index)

Workspace package scaffolding: package.json with peer deps (react/react-dom/motion/tailwindcss),
rollup ESM+CJS config, tsconfig (strict, jsx react-jsx), and empty entrypoints under src/.

Verified: pnpm --filter slide-renderer build produces dist/{index,elements/index,types/index}.{js,cjs,d.ts}
(empty chunks are expected at this stage).

* docs(slide-renderer): DESIGN.md + README.md

* feat(slide-renderer): copy Slide/Element types + add effects types

* feat(slide-renderer): add utils (geometry simplified to elements API, element ranges, cn)

* feat(slide-renderer): shared element hooks (fill/outline/shadow/flip) + ElementOutline

* feat(slide-renderer): BaseTextElement

* feat(slide-renderer): BaseShapeElement + GradientDefs + PatternDefs

* feat(slide-renderer): pure <img> BaseImageElement, decouple OpenMAIC media business

The base component drops:
- useMediaGenerationStore / isMediaPlaceholder (AI media generation polling)
- useSettingsStore (imageGenerationEnabled toggle)
- useMediaStageId / retryMediaTask (classroom-scoped retry orchestration)
- useI18n (placeholder/error/disabled copy)
- skeleton / error / disabled render branches

Retains: clip / filter / outline / shadow / colorMask, output <img src={elementInfo.src}>.

Adds a `renderImage` slot so consumers can re-inject business behavior (placeholders,
retry buttons, custom src resolvers) without modifying the package.

* feat(slide-renderer): Line / Table / Latex / Code base elements

- Line + LinePointMarker: copied with stroke-draw animation intact
- Table + StaticTable + tableUtils: copied with getTableSubThemeColor moved to package utils
- Latex: katex HTML + legacy SVG fallback, no business deps
- Code: shiki-based syntax highlighting (dynamic import); shiki added as optional peer
  dependency so consumers without code slides pay zero install cost

* feat(slide-renderer): BaseChartElement + Chart + chartOption (echarts as optional peer)

* feat(slide-renderer): pure <video> BaseVideoElement, decouple OpenMAIC media business

Drops:
- useCanvasStore (playingVideoElementId / pauseVideo)
- useMediaGenerationStore / useMediaStageId / retryMediaTask / getVideoMediaRefForElement
- useSettingsStore (videoGenerationEnabled)
- useI18n, motion/react animate scope
- skeleton / error / disabled / placeholder branches

Retains <video src controls preload=metadata>. Adds a `renderVideo` slot so
consumers can re-inject orchestrator-driven playback or placeholders.

* feat(slide-renderer): canvas hooks (useSlideBackgroundStyle, useViewportSize simplified)

- useSlideBackgroundStyle: copied as-is (no business deps)
- useViewportSize: rewritten to take viewportSize/Ratio/canvasPercentage as args,
  drop useCanvasStore, drop editor-only canvasDragged/dragViewport, return fitScale
  instead of writing to a store

* feat(slide-renderer): 4 effect overlays (Highlight/Spotlight/Laser/Zoom), props-driven

All overlays now receive element/geometry/options through props instead of reading
useCanvasStore. SpotlightOverlay uses a configurable element-id prefix
(default 'slide-element-') to locate DOM nodes for measurement, matching the
convention SlideElement will set in T14.

HighlightEffectOptions extended with color/opacity/borderWidth/animated to surface
the original visual knobs through the public API.

* feat(slide-renderer): SlideElement dispatcher with renderImage/renderVideo slots

* feat(slide-renderer): SlideCanvas v1 main entry (props-driven, auto-fit viewport)

Mirrors ScreenCanvas structure but reads from props: slide.elements, slide.theme,
props.background ?? slide.background, props.scale ?? autoFit, props.effects.

Auto-fits viewport into container by default via useViewportSize+ResizeObserver;
pass scale=1 to opt out and render at slide-native dimensions.

* feat(slide-renderer): SlideRendererProvider + useSlideContext (props or context)

SlideCanvas now reads from context as a fallback when props are omitted. Allows
the wrap-then-compose pattern from spec §3.2: provider holds shared data,
sibling overlays read via useSlideContext.

* feat(slide-renderer): aggregate public exports

Main entry exposes SlideCanvas, SlideElement, Provider/hooks, effects, hooks,
utils. `slide-renderer/elements` re-exports all 9 Base*Element + shared
ElementOutline/useElementXxx for granular composition. `slide-renderer/types`
already lived in src/types/index.ts.

* docs(slide-renderer): complete README (install / quickstart / API / effects / Tailwind setup)

* feat(demo): /slide-renderer-demo route exercising the workspace package

Hand-written single Slide with shapes + text demonstrates the v1 API end-to-end:
- props-driven SlideCanvas
- auto-fit viewport via parent container
- gradient background, shape outline + text fill

Wires slide-renderer as a workspace dep and registers its dist as a Tailwind
@source so utility classes inside the package get picked up by the host PostCSS
pipeline.

* feat(pptxtojson-pro): align imported Slide JSON with renderer contract

- Drive `viewportWidth` from the deck's actual pixel width (json.size.width
  × ratio) instead of the legacy 960 default, so 16:9 widescreen decks no
  longer get text element widths clamped to 4:3 dimensions (e.g. titles
  truncated to 842px and forced to wrap). Per-slide `viewportSize` now
  reports the same value, keeping transform-time and render-time aligned.
- Replace the pass-through font STUB with real resolution: 22-font
  self-hosted whitelist + alias map (微软雅黑/等线/宋体/楷体/仿宋/Arial/etc.)
  → 5-category primary font mapping, so unknown PPT fonts fall back to a
  rendered open-source equivalent and the pipeline can surface the
  replacement via `replacedFonts.fallback`.
- Translate cell `vAlign` from PPT-native (`up`/`mid`/`down`) to CSS-native
  (`top`/`middle`/`bottom`) at the importer boundary, so the renderer can
  transparently pass it through to `vertical-align` / `justify-content`
  without per-component conversion.

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

* feat(slide-renderer): drop Tailwind defaults, data-drive styles, ship fonts

Three intertwined changes that together make the package self-contained
and align it with the "slide JSON is the single source of visual truth"
contract.

1. Remove Tailwind utility classes from every element renderer.
   - Replace `className="absolute ..."` / `className="rounded ..."` etc.
     with inline `style={{ position: 'absolute', borderRadius: ... }}`.
   - The few rules that can't be expressed inline (descendant selectors,
     keyframes, browser-default <p> margin reset) move to a new
     `src/styles.ts` injected once by `<SlideCanvas>` via `<style>`.
     Named animation classes (`slide-renderer-pulse` / `-ping`) replace
     `animate-pulse` / `animate-ping` so consumers don't need Tailwind.

2. Strip renderer-level positive defaults; surface them as data fields.
   - `BaseTextElement`: drop hardcoded `overflowWrap: 'break-word'` and
     the `paragraphSpace ?? 5` fallback. `--paragraphSpace` is only set
     when defined in data; CSS `var()` fallback is 0.
   - `StaticTable`: drop hardcoded `padding: '5px'`, `verticalAlign:
     'middle'`, `wordBreak: 'break-word'`. Extend `TableCell` with
     `padding?: string` and `vAlign?: 'top' | 'middle' | 'bottom'` so
     PPT-extracted padding / vertical alignment flow through unchanged.
   - `PPTTableElement` gets `rowHeights?: number[]` (per-row min-height;
     content can still grow rows).
   - Reshape `<td>` to match the classroom Vue layout: outer `<td>` carries
     only border + textStyle; inner `slide-renderer-cell-text` <div> is
     a flex column with `min-height = rowHeight - 4`, `padding =
     cell.padding`, `line-height: 1`, `justify-content` from `cell.vAlign`.
     Add `.slide-renderer-cell-text p + p { margin-top: 0.4em }` to give
     adjacent paragraphs breathing room without breaking the reset.

3. Self-contained font shipping.
   - Move the 22 woff2 files into `packages/slide-renderer/fonts/`.
   - Ship a sibling `fonts.css` with @font-face declarations using
     relative `./fonts/<name>.woff2` URLs.
   - Expose both via `package.json` exports (`./fonts.css`, `./fonts/*`)
     and the `files` array.
   - Consumer adds one import (`import 'slide-renderer/fonts.css'`); the
     bundler resolves the relative URLs against the package and emits
     each woff2 as a static asset. Removes the dependency on consumer-
     owned `app/globals.css` @font-face blocks and `public/font/` copies.

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

* feat(demo): wire slide-renderer fonts and swap demo to a table-heavy slide

- Import `slide-renderer/fonts.css` in the root layout so consumer apps
  pull the package's self-hosted @font-face declarations and woff2 assets
  through Next.js' static-asset pipeline.
- Replace the hardcoded `demoSlides` array (24 mixed-element slides) in
  `/slide-renderer-demo` with a single 5×7 table-heavy slide so the demo
  exercises the new `TableCell.padding` / `TableCell.vAlign` /
  `PPTTableElement.rowHeights` fields and the flex-based cell layout.
  Convert the legacy `vAlign: 'up' | 'mid' | 'down'` values to the
  CSS-native `'top' | 'middle' | 'bottom'` form the renderer now expects.

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

* feat(slide-renderer): add slideToPng standalone snapshot util

Exposes a new `slide-renderer/snapshot` sub-export with `slideToPng(slide,
options)`, the foundation for the AI-driven visual diff loop (snapshot
the rendered slide, compare against PowerPoint's own PNG export, decide
whether a discrepancy belongs to the import algorithm or the renderer).

Implementation notes
- Mounts `<SlideCanvas>` into an off-screen container sized exactly to
  the slide's native pixels, so `useViewportSize` collapses to a 1:1
  render (no scale offset).
- `flushSync` for the initial commit so the snapshot doesn't fire on an
  empty container; `requestAnimationFrame` × 2 to let the ResizeObserver
  settle; then waits for `document.fonts.ready` and every `<img>` in the
  container (with a configurable `timeoutMs`, default 5s).
- Snapshots the SlideCanvas root (`container.firstElementChild`) rather
  than the outer wrapper — html2canvas-pro's bounding-box math otherwise
  leaves white edges or drops absolutely-positioned children.
- Uses `html2canvas-pro` instead of `html-to-image`: the latter's SVG
  `<foreignObject>` path loads embedded woff2 asynchronously, so the
  drawImage fires before fonts decode and text re-wraps in the fallback
  font. html2canvas-pro walks the DOM and inherits the parent document's
  font registry, keeping wrap positions identical to the on-screen render.
- `onclone` hook injects a small CSS reset (`font-kerning: none`,
  `font-feature-settings: normal`, `font-variant-east-asian: normal`,
  `text-rendering: geometricPrecision`) scoped to the slide tree, to
  prevent html2canvas-pro's CJK text measurement from clipping
  full-width punctuation (e.g. `(` / `)`) past cell boundaries.
- Default `pixelRatio` follows `window.devicePixelRatio` for retina-sharp
  output; consumers can override.
- Optional `debugVisibleMs` briefly shows the off-screen container after
  snapshot so callers can compare what was captured vs the live render.

Wiring
- Sub-export added to `package.json` (`./snapshot`) and Rollup `entries`
  for tree-shaking — apps that don't use snapshot don't pay the
  `html2canvas-pro` bundle cost.
- Demo route adds an "导出 PNG" button that calls `slideToPng` on the
  active slide and triggers a browser download.

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

* chore: build slide-renderer in root postinstall

Without this, fresh installs leave packages/slide-renderer/dist
missing and Next.js fails to resolve the `slide-renderer` import.

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

* fix(parser+renderer): iteration-0601-002 fidelity fixes

Parser (pptxtojson-pro):
- shapeSerializer: stop painting parent fill on grpFill children; honor
  explicit <a:ln><a:noFill/></a:ln> over theme lnRef (master logo dots
  were rendering as visible green rings).
- imageSerializer: detect custGeom ellipses and 8-vertex chamfered-rect
  photo frames; resolve to 'ellipse'/'octagon' instead of falling back
  to 'rect'.
- textSerializer: emit text-shadow from rPr effectLst > outerShdw, and
  compensate the half-leading PowerPoint puts above the first line for
  unitless lnSpc > 1 (cover-title gap regression).
- border/tableSerializer: pass rgba()/hsla() colors through ensureHex
  untouched so '#rgba(...)' never reaches the DOM.
- transformParsedToSlides: drop the 1.1 SAFE_PADDING wrap-fudge and
  thread bodyPr@anchor through as vAlign.
- font config: add 思源黑体/思源宋体 + Source Han aliases and a trailing
  region/weight suffix stripper so 'SourceHanSerif CN Light' resolves.

Renderer (slide-renderer):
- SlideCanvas: new chrome prop (default true) to opt out of the
  preview-only card shadow + rounded corners; snapshot pipeline passes
  false so html2canvas output matches PPT edges.
- BaseTextElement: flex-column + justifyContent driven by the new
  vAlign field; width/height stay 100% so the box anchors correctly.
- BaseImageElement: maxWidth/maxHeight 'none' to prevent host CSS from
  shrinking absolutely-positioned <img>.
- snapshot: render with chrome=false.

Docs: SKILL.md expanded with the iteration workflow + OOXML traps.

* fix(parser+renderer): iteration-0605-001 fidelity fixes

slide-renderer:
- PPTImageElement: add `softEdge` field (feather radius that fades image
  alpha to transparent at every edge, per a:softEdge@rad).
- TableCell: add per-side `borders` so cells with partial dividers render
  each side independently instead of falling back to the table-level
  uniform outline.
- BaseTextElement: hoist `fill`/`opacity` to the outer wrapper so the
  background covers the full shape rectangle, matching PowerPoint behavior
  for short text inside tall shapes.
- Misc tweaks across image/latex/shape/video base elements, StaticTable
  and the standalone snapshot util.

pptxtojson-pro:
- Parser/serializer fidelity improvements for text, math, image, shape
  and table (notably ~500 lines in textSerializer and ~127 in
  mathSerializer).
- Refinements in GroupNode, MathNode and ShapeNode models; richer Theme,
  StyleResolver and RenderContext plumbing.
- Expanded shape presets and customGeometry utilities, plus adapter and
  import-pipeline updates to surface the new fields.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: stop tracking local slide-renderer-demo sandbox

`app/slide-renderer-demo/page.tsx` is a personal scratchpad used for
ad-hoc rendering tests; it shouldn't ship with the package. Remove it
from the index (file stays on disk locally) and ignore the directory so
future tweaks don't show up in `git status`.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: rename packages pptxtojson-pro→maic-import and slide-renderer→maic-renderer

Align workspace package names with the MAIC product family:
  packages/pptxtojson-pro  → packages/maic-import
  packages/slide-renderer  → packages/maic-renderer

Functional references updated end to end:
- Root package.json: workspace deps + postinstall/sync scripts
- next.config.ts: transpilePackages
- app/globals.css: Tailwind `@source` for renderer dist
- app/layout.tsx: `maic-renderer/fonts.css` import
- lib/import/use-import-pptx.ts: imports + runtime URL
  (`/vendor/maic-import/index.js`) + script comment
- scripts/sync-maic-import.mjs: renamed and pointed at the new dist
- .gitignore: vendor path and sync-script comment
- Package package.json `name` fields and cross-link in READMEs

Also re-include the gitignored `app/slide-renderer-demo/` in Tailwind's
source detection via an explicit `@source` so its classes (e.g.
`bg-violet-600`) keep getting generated — Tailwind v4 skips gitignored
paths by default, which was making the demo's import button render
white-on-white after the demo was excluded from version control.

CSS class names (`slide-renderer-prose` / `slide-renderer-cell-text` /
`slide-renderer-pulse` / `slide-renderer-ping` / `slide-renderer-code-
cursor-blink`) and internal source comments that still reference the old
package names are intentionally left untouched to keep the rename
diff minimal; they can be updated separately as the codebase evolves.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(dsl): extract @maic/dsl contract package and adopt @maic/* scope

Establish the SDK family's contract keystone and align package naming with
the planned @maic/* scope, per PR #668 review.

1. New @maic/dsl package (packages/maic-dsl)
   - Pure, zero-runtime-dependency spec: the canonical slide object model,
     pure type-guards, and DSL version/migration scaffolding.
   - Seeded from lib/types/slides.ts but reconciled into a *superset* of the
     three previously-drifted copies (app / renderer / importer); merged
     fields are annotated @since-merge. README documents the divergence and
     the acyclic dependency arrows (renderer/importer -> dsl -> nothing).
   - Enums are regular (not const) so consumers compiling with
     isolatedModules can import them across the package boundary (TS2748).

2. Wire @maic/importer to @maic/dsl
   - Import all slide types from @maic/dsl; delete the vendored
     openmaic/types/slides.ts copy.
   - Eliminate the Slide drift at the root: transformParsedToSlides now fills
     viewportSize/viewportRatio/theme at construction and emits a complete
     DSL Slide, removing the partial "draft slide" + post-fill step in
     parsedToSlides (no DraftSlide type needed).
   - Add @maic/dsl to the root postinstall build chain before the importer.

3. Adopt @maic/* scope (agent-noun names)
   - maic-import  -> @maic/importer
   - maic-renderer -> @maic/renderer
   - Update all package-name references (deps, app imports, transpilePackages,
     fonts.css subpath import, Tailwind @source node_modules path, READMEs).
   - Directory names and /vendor paths are intentionally left unchanged.

Note: @maic/renderer still vendors its own slide types; wiring it to
@maic/dsl is the next step.

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(renderer): consume slide types from @maic/dsl, drop vendored copy

Wire @maic/renderer to the @maic/dsl contract keystone, completing the
de-duplication of the slide object model across the SDK family.

- Delete packages/maic-renderer/src/types/slides.ts (the vendored copy) and
  repoint all ~30 internal imports at @maic/dsl. SlideElement's runtime
  `ElementTypes` value import now resolves to the DSL enum.
- Re-export the DSL types from src/types/index.ts so the public
  `@maic/renderer/types` entry keeps exporting the full slide contract
  (alongside the renderer-only effect types).
- Add @maic/dsl as a regular dependency and mark it external in the rollup
  build so consumers share a single copy (enum not inlined); the emitted
  .d.ts references @maic/dsl directly.

@maic/dsl is a superset of the renderer's former types, so this is
non-breaking; the renderer additionally gains `script` and the
importer-origin fields it didn't previously declare.

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(renderer): serve fonts from OSS, drop the 43.6MB bundled woff2

Move the 22 CJK fonts off the repo and onto object storage to fix the
PR #668 blocking repo-weight concern.

- fonts.css now points every @font-face src at
  https://file.maic.chat/fonts/<name>.woff2 instead of bundled local files.
- Extract the CDN origin + font whitelist into fonts.config.mjs (single
  source of truth) and generate fonts.css from it via
  scripts/generate-fonts-css.mjs. `genfonts` runs first in the build, so the
  CSS always reflects the config; changing the domain is now a one-liner.
- Delete packages/maic-renderer/fonts/*.woff2 (22 files, ~43.6MB) and drop
  the now-unused "./fonts/*" export and "fonts" files entry from package.json
  (fonts.css is kept).

Font names are unchanged, so consumers and the importer font whitelist are
unaffected. Note: this removes the files going forward only; purging them
from git history (LFS / filter-repo) is a separate follow-up.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(home): gate the unwired PPTX import button behind a feature flag

The PPTX import flow is still scaffolding — `useImportPptx` has no
`onImported` consumer, so clicking it only logs the parsed slides. Hide both
PPTX import entry points (and the hidden file input) behind
NEXT_PUBLIC_ENABLE_PPTX_IMPORT (default off) so the UI doesn't expose a
no-op. The classroom import button is unaffected.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(import): harden the runtime URL-loaded PPTX parser

The PPTX parser is loaded at runtime from /vendor/maic-import/index.js — a
gitignored artifact synced into public/vendor during postinstall. If a deploy
skips that step the URL 404s and import() fails with an opaque SyntaxError
(404 HTML parsed as JS). Add guards on both ends plus docs.

- Build-time assertion: scripts/assert-vendor-maic-import.mjs verifies the
  bundle exists and is non-empty; wired into `build` so a misconfigured deploy
  fails early with an actionable message instead of shipping a broken runtime.
- Runtime guard: use-import-pptx.ts HEAD-probes the URL before import() and,
  on a non-ok response, throws a clear error surfaced to the user via the new
  import.error.parserUnavailable string (added to all 6 locales).
- Docs: document the postinstall deploy dependency and the pull-without-install
  type/runtime drift in @maic/importer's README.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: unify the @maic/* license policy to AGPL-3.0

Pick one license for the SDK family and apply it uniformly, matching the
OpenMAIC root, per PR #668 review.

- @maic/dsl and @maic/importer: relicense MIT -> AGPL-3.0 (package.json +
  full AGPL-3.0 LICENSE text).
- @maic/renderer: already AGPL-3.0; add the LICENSE file its package.json
  `files` already referenced.

@maic/importer is derived from pptxtojson (MIT); MIT permits relicensing a
derivative under AGPL, and the upstream MIT attribution is retained in the
package README/index.html, so this is compliant.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: rename packages/maic-import dir to maic-importer

Align the importer's directory with its @maic/importer package name and the
maic-* sibling dirs (maic-dsl, maic-renderer). Package name is unchanged, so
imports/transpilePackages/node_modules resolution are unaffected.

- git mv packages/maic-import -> packages/maic-importer (history preserved).
- Rename the vendor sync/assert scripts and the runtime vendor path to match:
  scripts/{sync,assert-vendor}-maic-importer.mjs, public/vendor/maic-importer,
  URL /vendor/maic-importer/index.js.
- Update all path references: root postinstall/build/sync scripts, .gitignore,
  use-import-pptx.ts, and doc links in the dsl/renderer/importer READMEs.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: nest the @maic packages under packages/@maic/

Mirror the @maic/* npm scope in the directory layout: move the three family
packages into packages/@maic/{dsl,importer,renderer}. Package names are
unchanged, so imports / transpilePackages / node_modules resolution are
unaffected.

- git mv packages/maic-{dsl,importer,renderer} -> packages/@maic/* (history
  preserved).
- pnpm-workspace.yaml: add packages/@maic/* glob.
- Recompute the root postinstall cd chain for the nested layout.
- Update dir-path references: sync script srcDir, .gitignore comment, the dsl
  source comment, and the renderer/importer README/SKILL cross-links.

Unchanged: the @maic/* package names, the runtime vendor path
(public/vendor/maic-importer) and its sync/assert scripts.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore(renderer): clear font licenses, drop non-redistributable faces, remove importer font remapping

Address the PR #668 blocking font-license-clearance review.

Font licensing (renderer):
- Reduce the self-hosted whitelist to 6 clearly-redistributable faces:
  SourceHanSans/SourceHanSerif/LXGWWenKai/ZhuQueFangSong (SIL OFL 1.1),
  ZcoolHappy (ZCOOL free-use), WenDingPLKaiTi = AR PL KaitiM GB (Arphic PL 1999).
- Drop AlibabaPuHuiTi: free to *use* commercially but its license grants no
  explicit redistribution/re-host right, unlike OFL — dropped to keep public
  CDN serving unambiguous.
- Add FONTS.md (per-face attribution/clearance record, separate from the
  package's AGPL LICENSE) and bundle the verbatim license texts under
  font-licenses/ (OFL.txt, ZcoolHappy-LICENSE.txt, ARPHIC-PL.txt); ship both via
  package.json `files`. Regenerate fonts.css from the trimmed config.

Importer font remapping removed:
- The importer no longer rewrites font-family names (alias -> category ->
  primary). It passes each slide's original font-family through unchanged, so
  it can never target a face the renderer doesn't ship. Delete configs/font.ts,
  the resolveFont/replaceFontFamilyInHtml helpers, and the now-unused
  FontReplacementBucket / ImportContext.replacedFonts plumbing.

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs(renderer): document the CDN font runtime dependency

Add a "Fonts" section to the renderer README per PR #668: the optional
`@maic/renderer/fonts.css` loads woff2 from an external host
(https://file.maic.chat), which must be reachable + CORS-enabled or the
browser silently falls back to system fonts. Note that the import is optional
and that the origin is configurable via fonts.config.mjs + `pnpm run genfonts`.

Co-authored-by: Cursor <cursoragent@cursor.com>

* docs(renderer): verify WenDingPLKaiTi == AR PL KaitiM GB from the font name table

Record the embedded-name-table evidence (Family/Copyright/Trademark/Designer =
Arphic, nameID 13 = the full Arphic Public License) so the
WenDingPLKaiTi ⇄ AR PL KaitiM GB correspondence is provable, and correct the
copyright year to 1994–1999 to match the font metadata.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore: fix `pnpm check` (prettier) after merging main

main added a `prettier . --check` CI step that flagged 180 files. Resolve it
consistently with the existing convention (vendored/workspace packages are
excluded from root Prettier):

- .prettierignore: exclude `packages/@maic/` (own rollup/tsc/eslint toolchains;
  dist is generated, importer/src1 is a vendored oracle), matching how
  pptxgenjs / mathml2omml / docs are already handled.
- Format the three root-level files we added/edited that root Prettier does
  cover: lib/import/use-import-pptx.ts and the two scripts/*-maic-importer.mjs.

`pnpm check` now passes.

Co-authored-by: Cursor <cursoragent@cursor.com>

* style: align @maic/{dsl,renderer,importer} source to root Prettier

Per review preference, the @maic packages are our own code and should follow
the repo style rather than be ignored wholesale. Narrow .prettierignore to only
the generated build output (packages/@maic/*/dist/) and the vendored legacy
reference (packages/@maic/importer/src1/), then `prettier --write` the package
sources. Formatting-only; all three packages still build.

`pnpm check` passes.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(lint): scope ESLint to @maic source and clear all errors

- eslint.config.mjs: replace blanket packages/** ignore with precise
  rules so @maic/{dsl,importer,renderer} source is linted, while skipping
  third-party packages, dist output, importer/src1 and public/vendor
  (the generated bundle was producing thousands of false errors in CI).
- importer: replace `any` with concrete narrowings/types, fix prefer-const.
- renderer: drop manual useMemo that React Compiler could not preserve.
- remove leftover debug console.log + stale eslint-disable in use-import-pptx.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(i18n): add missing PPTX import keys to pt-BR

pt-BR.json was missing import.{pptx,parsingPptx,pptxSuccess} and
import.error.{invalidPptx,parserUnavailable}, failing the i18n key
alignment check against en-US.json.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-09 03:25:05 -04:00
3e1e9f083b feat(tts): unify provider-enablement model, default browser-native off (#665) (#666)
A single TTS provider-enablement model honored everywhere (picker,
auto-assignment, fallback, lecture/playback, server).

Model
- lib/audio/provider-enablement.ts: isTTSProviderConfigured /
  isTTSProviderEnabled / listEnabledTTSProviderIds. Availability drops the
  registry defaultBaseUrl fallback (fixes Lemonade's always-shown voices),
  honors the per-provider `enabled` flag, server-disable overrides (server
  precedence).
- voice-resolver: getEnabledProvidersWithVoices (enabled server/custom
  providers) and getSelectableProvidersWithVoices (the ONE client source of
  truth = enabled providers + opt-in browser-native when the browser exposes
  voices). resolveAgentVoice picks deterministically among the given providers,
  honors a voiceConfig only while its provider is present.
- Picker + discussion build their list from getSelectableProvidersWithVoices, so
  the AgentBar and the live discussion agree on selectable voices (fixes
  student agents going silent in auto mode). Students resolve via
  resolveAgentVoice; the teacher uses the global lecture voice verbatim (same
  voice the pre-generated lecture sends), so lecture and discussion never
  diverge.
- Voice assignment vs fallback: an agent's voice is bound at generation (the
  agent-profile LLM picks from availableVoices; preset uses the user's pick).
  The fallback for a missing/invalid/unavailable voice is applied only at the
  live TTS calls, not baked into the saved agent — so it reflects current
  provider availability.

Defaults / opt-in
- Browser-native: first-class, default OFF, opt-in. Built-in providers default
  enabled:true (only surface once configured).
- TTS master toggle defaults OFF; first server-sync auto-enables it when a
  provider is configured (mirrors image/video).
- Persist v3->v4 migration normalizes the never-user-editable flags.

Server/admin disable (server precedence): server-providers.yml `enabled:false`
and env `TTS_<P>_ENABLED=false` (incl. browser-native). Surfaced as a per-provider
`disabled` flag on /api/server-providers; merged as serverDisabled; enforced at
the /api/generate/tts trust boundary, classroom media generation, and /api/health.

UI
- Settings TTS panel: per-provider enable toggle, disabled (with a hint) when the
  provider is unavailable, locked off (with a note) when server-disabled.
- AgentBar voice pills render disabled with a "No voice" placeholder when no
  provider is enabled. The toolbar media-popover TTS tab keeps its existing
  on/off toggle (no picker/CTA).

Tests: predicates, resolver determinism + unified selectable list, server
force-disable, store merge + migration + TTS auto-enable, i18n parity. Verified
in a real browser (Playwright): settings toggle states + a full Gemini classroom
generation whose TTS requests used the picked voice.

Found on main @ 2586cb5.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
2026-06-07 17:25:57 +08:00
wyucandClaude Opus 4.8 47d28145b4 feat(maic-editor): slide surface — MAIC Editor v0 (epic #562) (#615)
* feat(maic-editor): framework primitives + edit StageMode (#564)

* feat(maic-editor): framework primitives + edit StageMode

Phase 1 framework foundation for the MAIC Editor (RFC #547,
tracking #560). Plumbing only — no UI consumers ship in this
sub-PR; the EditShell chrome and slide surface registration
land in follow-ups.

- StageMode gains 'edit' alongside 'autonomous' | 'playback';
  setMode resets canvas selection when leaving 'edit'.
- <Stage> auto-exits 'edit' whenever the current scene becomes
  uneditable (no scenes / pending generation / no current
  scene) so a follow-up Pro toggle can never strand the user
  in an empty edit shell.
- SceneEditorSurface contract + tiny registry under lib/edit/
  so each SceneType plugs in a surface without the shell
  importing surfaces directly. Surfaces declare CanvasComponent,
  useSurfaceState(), insert palette items, floating actions,
  commands, and (reserved for AI) inline coach hints.
- Slide kernel (lib/edit/slide-ops.ts): immutable, history-aware
  operations covering slide-update, element add / update /
  updateMany / delete / deleteMany / reorder / duplicate / align /
  removeProps, and text content edit.
- Slide element factories (lib/edit/slide-edit-elements.ts) for
  default text / shape / image elements + HTML <-> plain-text
  helpers.
- i18n: stage.editCourse + stage.doneEditing across all 6
  locales, consumed by the header toggle in the next sub-PR.
- Vitest coverage for the slide kernel (operations + history)
  and the edit-mode store transition (entry + canvas reset on
  exit).

PBLRenderer's mode prop is widened from the literal pair to
StageMode so <SceneRenderer> (which already passes StageMode)
type-checks. The prop is unused inside the renderer.

* style(maic-editor): apply prettier to lib/edit + tests/edit

CI runs on PRs to main only, so the prettier check did not fire
for this PR's target branch — applying formatting locally before
the merge train reaches main avoids a follow-up style commit.

* ci: also run on PRs targeting feat/maic-editor-v0

The MAIC Editor lands as a series of stacked sub-PRs against
the long-lived feat/maic-editor-v0 branch. Without this entry,
none of those sub-PRs get a CI gate — style/lint/type/test
regressions only surface when feat/maic-editor-v0 finally
merges back to main, at which point fixing them is a lot more
disruptive than catching them per sub-PR.

Push trigger is intentionally left main-only: nobody pushes
directly to feat/maic-editor-v0, every change arrives through
a PR that now runs the gate.

* fix(maic-editor): address kernel review on #564

Addresses cosarah's review against #561 scope:

Important:
- element.align now uses the canonical lib/utils/element.ts geometry
  helper instead of a forked copy. The local fork ignored
  PPTLineElement start/end and rotation, so bounds were wrong for
  lines and rotated elements.
- Cap slide-edit history at MAX_HISTORY = 50; drop oldest on overflow.
- Narrow slide.update patch to Partial<Omit<Slide, 'elements' |
  'animations'>> via a new SlideMetaPatch alias, so element /
  animation collections can only be mutated through their dedicated
  ops.
- element.add throws on id collision; element.duplicate throws when
  idMap is missing entries or when new ids would collide with
  existing elements.
- scene-editor-registry dev-warns on overwriting a *different*
  surface for the same SceneType (HMR re-register of the same
  instance stays silent); add unregister() for HMR cleanup and tests.

Minor:
- Unify on structuredClone over JSON.parse(JSON.stringify(...));
  inside immer's produce, un-proxy with current() first.
- Skip history push when produce returns the same content reference
  (true no-op detection). element.delete / deleteMany pre-check
  membership so their unconditional filter assignments don't break
  the ref-equality signal.
- Drop redundant cloneSlideContent calls in undo/redo/push paths;
  immer's structural sharing already guarantees immutability of the
  produced output. createSlideEditHistory keeps its defensive clone
  since the initial value comes from outside immer.

Coverage:
- Extract auto-exit predicate into lib/edit/stage-mode.ts so the
  policy can be unit-tested without rendering <Stage>.
- New tests: every align direction, line / rotated element align,
  no-op paths for update/delete/reorder/removeProps/text/align,
  element.add index clamping + id collision, element.duplicate
  default offset + contract errors, history future cleared after
  branching, history capped, registry register/unregister/HMR-safe
  re-register, and the auto-exit predicate.

371 vitest tests pass (was 335). tsc/lint/prettier/i18n/build all
green locally.

* fix(maic-editor): close kernel escape hatches (subagent CR follow-up)

Two defense-in-depth fixes flagged by independent review after the
prior commit:

- element.duplicate now deep-clones the source via
  structuredClone(current(element)). The previous shallow spread
  shared nested mutable references (start/end tuples, outline,
  points) with the source; immer's COW would have handled most
  mutations but ops that operate on nested arrays in place
  (sort/reverse/splice) would silently leak between source and
  duplicate. The deep clone keeps the kernel's invariants
  independent of how downstream op consumers write their recipes.

- slide.update gains a runtime guard that throws when patch
  contains elements / animations. The type-level SlideMetaPatch
  narrowing already forbids these keys, but the runtime guard
  closes the `as any` escape hatch for callers that might bypass
  the type system.

New tests cover both paths: meta-only slide.update succeeds, an
elements-containing patch throws, and a duplicated line element's
start/end/points tuples are independent from the source.

* feat(maic-editor): EditShell chrome and Pro mode toggle (#565)

* feat(maic-editor): EditShell chrome and Pro mode toggle

Adds the scene-type-agnostic editor chrome (EditShell + CommandBar +
FloatingToolbar + HintRail), an edit-mode sidebar, and the header Pro
toggle that flips into the 'edit' StageMode from #561.

No scene editor surfaces are registered yet — the next sub-PR wires up
the slide surface. In this PR every scene type falls through to the
i18n unsupportedScene placeholder, which is the verifiable visible
behavior.

- canEdit gating reuses the canonical isCurrentSceneEditable predicate
  shipped in #561 so the toggle and the auto-exit effect are in
  lock-step.
- handleToggleEditMode tears down live session / engine / TTS before
  entering edit mode.
- ChatArea slides out in edit mode for a full-width canvas.
- reorderScene extracted from EditModeSidebar with unit tests; the
  positional-order preservation is the part worth a guard test.
- i18n scoped to keys this PR's components actually reference;
  surface-specific keys deferred to the slide-surface PR.

* test(reorder-scenes): single-element + reference-inequality cases; zh-CN newSlide distinct from addSlide

CR follow-ups:
- reorderScene tests now cover a 1-element array (both directions
  return null) and explicitly assert the returned array is a new
  reference, not the input.
- zh-CN edit.sidebar.newSlide was duplicating the addSlide label
  ("新建幻灯片" both); using "未命名幻灯片" for the default new-slide
  title to match the English Add slide / New slide distinction.

* refactor(maic-editor): drop EditModeSidebar; clean Pro mode chrome (#568)

Course-correct on #565. EditModeSidebar was rejected by the design
owner as inappropriate for Pro mode (#560 wording is "minimal top
bar + slide thumbnail rail", not a file-list panel). #565 also left
the playback chrome wrapped around the editor — Header / sidebar /
Roundtable / ChatArea all stayed mounted with only the sidebar
swapped, and EditShell's CommandBar/FloatingToolbar/HintRail were
never visible since no surface registers yet.

Drop EditModeSidebar + reorder-scenes helper + tests + the edit.sidebar
i18n block (8 keys x 6 locales) + the CommandBar sidebar-toggle.

Stage keeps Header mounted in both modes — it owns the global Pro
toggle Switch, which is the entry AND exit affordance (closing the
Switch exits; no separate Done-editing button). In edit mode:
SceneSidebar / Roundtable / ChatArea are not mounted, and the canvas
slot renders <EditShell scene> instead of <CanvasArea>. EditShell
internally resolves the surface via sceneEditorRegistry; when none
is registered it falls through to edit.unsupportedScene. With no
surfaces registered, every scene type lands on that placeholder —
the visible v0 behavior.

New optional EditShell.leftRail slot reserves the spot for a
redesigned slide-navigation surface; v0 ships with the slot empty.

SceneRenderer is now playback-only — the mode === 'edit' branch and
its sidebarCollapsed / onToggleSidebar props moved up to EditShell /
Stage.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

* feat(maic-editor): enablement infrastructure (pre-slide-surface) (#571)

* feat(maic-editor): enablement infrastructure (pre-slide-surface)

Pre-requisite for the slide surface (#562). Ships the safety
infrastructure so each subsequent surface PR is small and
recoverable:

1. Feature flag NEXT_PUBLIC_MAIC_EDITOR_ENABLED, default OFF —
   gates the Pro toggle in Header. StageMode unchanged.

2. SlideContent.schemaVersion + pure idempotent migrateSlideContent
   / migrateScene; setScenes / addScene funnel legacy data through
   the migrate at the store boundary.

3. tests/edit/round-trip/ harness: apply ops -> buildPptxBlob ->
   JSZip parse -> assert content survived. No PPTX -> Slide reimport
   exists in the codebase, so the full reimport-diff shape isn't
   doable; per-op assertions extend the harness in #562.
   buildPptxBlob is now exported (hook is still the only runtime
   caller).

4. Per-scene slide-history persistence helpers (persist / load /
   has / clear, keyed maic-editor:slide-history:${sceneId}, swallow
   storage failures) + standalone SlideHistoryRestorePrompt dialog
   + 4 new i18n strings x 6 locales. Stage wiring deferred to #562.

5. Concurrency guards: isSceneEditLocked predicate (defensive; no
   current call path structurally hits it); localStorage-backed
   multi-tab edit lock with tryAcquire / refresh / release / heldByOther,
   stale-lock takeover after 3x heartbeat; standalone
   MultiTabEditConflictPrompt + 3 new i18n strings x 6 locales.
   Stage wiring deferred to #562.

The slide-surface PR owns the edit-entry effect machinery (where
the history-state lifecycle and per-tab tabId ref naturally live),
so shipping half-wired dialogs here would speculatively build Stage
state we know we'll restructure on contact with the surface.

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

* fix(maic-editor): migrateSlideContent forward-compat — no silent downgrade

CR follow-up: previously, content with schemaVersion newer than
CURRENT (e.g. v2 written by a future client) was silently truncated
back to the current version. Now: if schemaVersion >= CURRENT, return
the content untouched. The slide may not render correctly on an older
client, but its on-disk shape stays intact for the next compatible
client to read.

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

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

* feat(maic-editor): slide surface skeleton + #571 wiring + geometry (#562) (#579)

PR1 of the slide-surface work (infra-first slice). Registers the slide
SceneEditorSurface so EditShell lights up Pro mode for slide scenes.

- SceneEditorSurface impl + sceneEditorRegistry registration; the surface
  owns a SlideEditHistory via the #564 kernel.
- Reuse the unmodified slide renderer Canvas through a surface-owned
  scene context; geometry drag/resize/rotate commits funnel into
  element.update ops (scene-edit bridge), one gesture = one undo step.
- Geometry numeric x/y/w/h/rotate popover as the precise fallback; gated
  off for line elements (PPTLineElement omits height/rotate).
- Wire #571 infra: cross-tab edit lock + conflict prompt, slide-history
  persistence + restore prompt, regen-lock guard.
- Renderer-commit classification: a real geometry gesture commits
  synchronously inside a pointer interaction; the renderer's
  ResizeObserver text-normalization commits with none, so it is folded
  into the baseline (no undo step / no persist / no spurious restore
  prompt on entry) instead of being staged as a user edit.
- Per-op round-trip test for element.update geometry; bridge + session
  unit tests; edit.geometry i18n across all 6 locales.

Upstream-shared changes are kept minimal and additive: an optional
`controller` prop on SceneProvider (uncontrolled/playback path
unchanged) so staged edits don't write through to the live stage store,
and a FloatingToolbar trigger-nesting fix (it wrapped PopoverTrigger
around <Tooltip>, a provider, so no popoverContent action could open).

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

* test(maic-editor): lock data-URL image PPTX round-trip (PR2 R1 gate)

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

* feat(maic-editor): insert palette — text box + image (data-URL/URL)

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

* refactor(maic-editor): address Task 1 review — spy cleanup, popover-only comment, ImagePicker error log

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

* refactor(maic-editor): drop PR1 debug geometry toolbar; element-aware floating bar

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

* refactor(maic-editor): drop redundant PPTTextElement cast (Task 2 review)

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

* feat(maic-editor): additive ProseMirror command bridge for the property bar (C1)

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

* refactor(maic-editor): exhaustiveness guard + tidy C1 adapter (Task 3 review)

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

* feat(maic-editor): refresh property-bar attrs on caret/keyboard selection (C2)

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

* test(maic-editor): satisfy no-explicit-any in PR2 test stubs (Task 1+4 review)

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

* feat(maic-editor): compact text property bar in the reused floating slot

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

* refactor(maic-editor): Task 5 review — uniform selection-guard, Lucide icons, JSX, memo

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

* i18n(maic-editor): edit.text.* + edit.insert.* across 6 locales

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

* test(maic-editor): round-trip gate for formatted text + inserts

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

* docs(maic-editor): clarify remote-URL image round-trip scope (Task 7 review)

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

* chore(maic-editor): drop stale scaffolding comment + orphaned geometry i18n keys

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

* style(maic-editor): prettier --write PR2 files (pre-push check)

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

* test(maic-editor): make no-explicit-any suppression prettier-robust

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

* fix(maic-editor): CommandBar insert popover never opened (PopoverTrigger wrapped a Tooltip provider)

Insert→Image was unreachable: InsertButton wrapped <PopoverTrigger asChild>
around <Tooltip> (a context provider, no DOM node), so Radix's Slot bound
no element. Chain both triggers onto the real <button>, exactly mirroring
the PR1 fix already in FloatingToolbar's ActionButton. PR2's insert-image
is the first popoverContent InsertButton consumer to exercise this path.

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

* fix(maic-editor): text property bar no longer clips/overflows in the floating popover

The ~450px single-row bar was jammed into FloatingToolbar's fixed w-72
(288px) PopoverContent and clipped. Let the popover size to content
(w-auto, max-w-[92vw], Radix handles edge collision) and harden the bar
row (w-max + no child shrink, fixed-width font select) so it renders as
one clean line. Chrome/surface layout only — no renderer change.

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

* fix(maic-editor): property bar stays open across consecutive formatting steps

execCommand refocuses the editor after every command; the uncontrolled
Radix popover treated that focus-shift as focus-outside and dismissed,
forcing a re-open of the Text bar for each format action. Prevent
onOpenAutoFocus (don't steal the canvas selection on open) and
onFocusOutside (editor refocus must not dismiss); Escape and pointer-down
truly outside still close it. Chrome-only, no renderer change.

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

* fix(maic-editor): editor canvas now resolves gen_img_* media placeholders

The editor's interactive ImageElement rendered elementInfo.src raw,
so entering Pro mode on any slide whose image was a generation
placeholder showed a broken-image icon (while playback's read-only
BaseImageElement correctly resolved the placeholder to the generated
objectUrl). Extract the resolution into a shared useResolvedImageSrc
hook so both variants stay aligned. Strictly additive: for any
non-placeholder src (legacy / direct URL / data URL) resolvedSrc ===
elementInfo.src and the media store is not subscribed to. Pre-existing
upstream gap surfaced by PR2 as the first real-user editor consumer —
same shape as the CommandBar popover-trigger fix.

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

* test(maic-editor): unit-test gen_img placeholder resolution (9 cases)

Splits useResolvedImageSrc into a pure resolveImageSrc function (no
hooks) wrapped by the hook, so the resolution logic can be unit-tested
in vitest's plain node environment (no jsdom/RTL needed in this repo).
Covers: done→objectUrl; no task→raw; pending/generating/failed→raw;
done with no objectUrl→raw; cross-stage isolation; no-stageId path;
non-placeholder src passes through (the additive contract).

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

* refactor(maic-editor): auto-save edits to stage store, drop staging UX

Reverses PR1's "staged edits don't write through to the live lesson"
design. The slide-edit-session now writes through every history move
(applyOp / user commit / ResizeObserver normalization / undo / redo)
to useStageStore.updateScene as the canonical source of truth, which
Dexie already auto-persists. The renderer reads from the stage store
via the controller's getSnapshot.

Removes the entire staging surface that has no place in a modern
editor (Figma/Notion/Google Docs have no "unsaved changes" concept):

- DEL  lib/edit/slide-history-persistence.ts  (localStorage layer)
- DEL  tests/edit/slide-history-persistence.test.ts
- DEL  components/edit/SlideHistoryRestorePrompt.tsx  (restore dialog)
- DROP pendingRestore field + restore() action from slide-edit-session
- DROP restorePrompt branch + handlers from useSlideCanvasController
- DROP edit.history.restore.* keys across all 6 locales

Edits now flow: user input → renderer onUpdate → controller.updateSceneData
→ slide-edit-session.commitContent → writeThrough(useStageStore.updateScene)
→ Dexie. There is nothing "unsaved" to restore, by design.

The session retains its in-memory undo/redo history (per Pro session)
and the user-vs-ResizeObserver gesture classification (so reflow
doesn't push undo steps).

Test suite rewritten to assert write-through on every history move and
no write-through on seed (the stage already has that content).

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

* fix(maic-editor): address PR review — element delete affordance + cross-platform fonts

Two issues from review on #586:

1. A selected image/text element couldn't be deleted — the renderer's
   delete lives only in a right-click menu, undiscoverable in Pro mode.
   Add a Delete button to the FloatingToolbar for any single selected
   element (text or image), dispatching the existing element.delete op.
   Button-only, consistent with #560's keyboard-shortcuts deferral.

2. Switching fonts had no effect on macOS Chrome — the property bar's
   font list was a hardcoded SimSun/SimHei set (Windows-only system
   fonts the renderer never loads). Use OpenMAIC's canonical FONTS
   registry (configs/font.ts) — the web fonts the renderer actually
   loads, so a pick renders identically on every platform.

Adds edit.delete × 6 locales + the parity-test key; floating-actions
unit tests for the delete action.

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

* feat(maic-editor): selection-anchored text editing for the slide surface (#590)

* feat(maic-editor): add resolveEditingElementId text-editing policy

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

* feat(maic-editor): drop text-format floating action (moves to anchored bar)

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

* feat(maic-editor): surface hooks to derive and sync editingElementId

Add useResolvedSlideContent / useEditingTextElementId / useSyncEditingElementId.
Realign the PR2 buildFloatingActions tests with the new behavior (text
formatting moved off the FloatingToolbar) and co-locate the editing-state test.

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

* chore(ui): export PopoverAnchor from the popover wrapper

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

* feat(maic-editor): add useTrackedRect for element screen-rect tracking

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

* feat(maic-editor): add AnchoredTextBar selection-anchored format bar

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

* feat(maic-editor): wire anchored text bar + editing flag into SlideCanvas

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

* feat(maic-editor): draw a clean solid frame for the text element being edited

Gated on the canvas store's editingElementId (default ""), so the dashed
select frame is unchanged for multi-select and for any consumer that never
sets the flag. Editor-path only; playback never renders Operate.

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

* fix(maic-editor): drop the editor focus ring so text editing shows one frame

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

* style(maic-editor): prettier-format the editing-state test import

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

* fix(maic-editor): anchor the bar to the text element node, not the wrapper

Code review caught that #editable-element-{id} is a zero-size absolute
wrapper — measuring it would pin the bar to the canvas origin. Measure the
.editable-element-text child, which carries the real geometry. Also correct
the dismiss-behavior comment: the bar is purely selection-driven.

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

* feat(maic-editor): modernize the text format bar UI

Replace the native <select> font picker with the design-system Select,
rebuild the size control as one cohesive stepper pill, swap the color "A"
for a swatch chip, and unify every control to a single height and hover/
active language (violet accent, matching the editor's Pro-mode accent).
Behavior and the text commands are unchanged.

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

* fix(maic-editor): curate the font picker to fonts the app actually loads

configs/font.ts listed 29 fonts but the app only ever loads Inter (via
next/font); the other 28 had no @font-face or bundled file, so picking them
silently fell back with no visible effect — and nothing but the format bar
even imports the registry. Trim it to what genuinely renders; the file's
comment records how to restore the rest (wire up font loading first).

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

* feat(maic-editor): load the picker fonts via @fontsource

The font registry listed 29 fonts the app never loaded. Wire up a curated
set that genuinely renders — 思源黑/宋, 霞鹜文楷, 站酷快乐体, and 9 Latin
families — via @fontsource packages (npm-managed, no font binaries in the
repo; CJK faces are unicode-range-subsetted so they download lazily per
glyph range). app/editor-fonts.ts registers the @font-face CSS from the
root layout; configs/font.ts is now the real, honest 14-entry list.

The ~14 commercial decorative Chinese fonts are intentionally left out —
they need self-hosting + subsetting + a licensing review, separate work.

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

* fix(maic-editor): quote font-family names so spaced/numeric ones work

Picking a font whose family name has spaces or a trailing digit (e.g.
"Source Sans 3") threw `Failed to execute 'check' on 'FontFaceSet'` —
`document.fonts.check(\`16px ${name}\`)` needs the family quoted — and the
fontname mark's toDOM emitted an invalid unquoted `font-family`, so the
font silently never applied. Quote the family in both spots; the mark's
parseDOM already strips quotes, so the attr still round-trips clean.

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

* fix(maic-editor): make the editing frame pointer-events-none

The clean editing frame is a purely visual full-size overlay, but it was
pointer-events: auto — so it masked the text element's own move cursor,
text cursor, click-to-place-caret and drag-to-move; only a thin uncovered
sliver at the edges still triggered them. The dashed BorderLines it
replaced are thin edge lines, so they never had this problem. Mark the
frame pointer-events-none; the resize/rotate handles are separate and
keep their own pointer events.

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

* chore(maic-editor): drop the "font is loading" toast

With @fontsource fonts and font-display: swap, a picked font swaps in
smoothly on its own — the "Font is loading, please wait..." toast was
noise (and fired on most CJK picks while a unicode-range chunk loaded).
Remove it along with the now-unused document.fonts.check and toast import.

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

* feat(maic-editor): move the delete action onto the anchored text bar

A text element's contextual actions now sit together on the anchored bar —
format controls + delete, hugging the element — instead of delete sitting
alone in the top-center FloatingToolbar. buildFloatingActions returns
nothing for text (its FloatingToolbar then renders null); non-text
elements still get their delete there. Delete logic is shared via a new
deleteSlideElement helper.

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

* feat(maic-editor): anchor the delete action for image elements

A selected image element now gets a selection-anchored bar hugging it —
just a delete button (image replace/crop/flip stay in a later sub-PR) —
the same way text elements do. The anchoring shell is extracted out of
AnchoredTextBar into a reusable AnchoredBar, and the delete button into a
shared DeleteButton; AnchoredTextBar and the new AnchoredImageBar are thin
wrappers. useTrackedRect now measures .editable-element-text or
.editable-element-image. buildFloatingActions returns nothing for image
elements too (other element types still get their delete there).

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

* style(maic-editor): tighten the anchored bar padding (p-2 → p-1)

p-2 left a chunky white margin around the content — most visible on the
image bar, a lone delete button in an oversized box. p-1 (4px, the value
the FloatingToolbar used) makes both bars sit snug to their controls.

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

* feat(maic-editor): anchor the delete bar for every element type

The selection-anchored delete bar now covers all non-text element types
(shape, line, table, chart, …), not just image — so every element's
editing chrome is anchored uniformly. AnchoredImageBar becomes the
type-agnostic AnchoredDeleteBar; useTrackedRect matches any
.editable-element-{type} content root; buildFloatingActions is dropped —
the surface no longer contributes top-center FloatingToolbar actions,
everything is on an anchored bar.

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

* fix(maic-editor): show legacy font names in the picker trigger

When a text element's `fontname` was a value not in the curated FONTS
registry (e.g. `Microsoft YaHei`, `PingFang SC`, theme defaults), the
Select couldn't match it and `<SelectValue/>` rendered a blank trigger —
both reviewers (cosarah Important, xuyuanwei678 #1) caught this. Add a
placeholder fallback so the raw family name surfaces in the trigger.

Also clean up the dead `'默认字体'` label that `text-format-bar.tsx`
overrode unconditionally: introduce an optional `labelKey` field on
`FontEntry`, use it for the default entry, and let the picker prefer
the i18n key when present — no more by-value special case.

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

* chore(maic-editor): address cr minors

- `marks.ts` fontname `toDOM` rejects `"` or `\` instead of interpolating
  them: a hand-crafted mark with `fontname: 'X"; background:url(...);'`
  could otherwise close the quoted string and inject arbitrary CSS.
- `AnchoredBar` gains `onOpenChange` (clears the canvas selection on
  Radix-initiated dismiss): silences the controlled-without-handler dev
  warning, and brings back Esc / SR dismissal that our focus-outside
  hardening had cut off.
- `useSyncEditingElementId` folds two `useLayoutEffect`s into one with
  a cleanup; the previous unmount-only effect was structural noise.

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

* fix: pin body padding-right so popovers don't reflow the page

Radix Select / Popover wrap with `react-remove-scroll`, which adds a
compensation `padding-right` to <body> when they open. Our <html>
already reserves the scrollbar gutter (`scrollbar-gutter: stable` +
`overflow-y: scroll`), so the compensation added a visible ~15px shift
on every dropdown open. Pin body's padding-right with `!important` so
the page stays still. (xuyuanwei678 review #2.)

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

* fix(maic-editor): surface legacy font names via SelectValue children

The earlier placeholder approach didn't work — Radix's `placeholder` only
fires for an empty `value`, not for an unmatched non-empty one. So an
element with a legacy fontname (e.g. `Microsoft YaHei`, `PingFang SC`,
theme defaults) outside the curated FONTS registry still rendered a blank
trigger. Render the trigger text via `SelectValue` children instead — the
new `currentFontLabel` helper covers all three cases: matched → entry's
i18n / fallback label, unmatched non-empty → the raw family name, empty
→ the default-font label. Unit tests cover each case.

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

* fix(maic-editor): preventDefault on pointer-down-outside so drag/resize work

The onOpenChange handler added to silence the Radix dev warning + restore
Esc dismissal also fired on pointer-down-outside — i.e. on every mousedown
on the selected element to drag it or grab a resize handle. That cleared
the selection before the drag could start, so nothing on the canvas could
be moved or resized. preventDefault on `onPointerDownOutside` (matching
the existing `onFocusOutside` hardening) keeps the bar selection-driven
while leaving Esc as the legitimate onOpenChange path.

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

* feat(maic-editor): arm-and-place insertion for text boxes

Replaces the "auto-insert at a hidden default position" UX. Click
`Text box` → arms text-insertion: the button takes the violet active
style, and the renderer's existing ElementCreateSelection overlay turns
the canvas cursor into a crosshair. On the canvas:

  - click  → 300×60 box at the click point
  - drag   → a box at the dragged rect

Either way the new box is auto-selected (addElement defaults that on),
and the surface's existing useEditingTextElementId picks it up so the
AnchoredTextBar opens on it. Esc disarms; clicking the armed button
again disarms (toggle).

Completes the text branch in the renderer's `useInsertFromCreateSelection`
(pptist scaffolding left it TODO) and bypasses the 200² square fallback
in `ElementCreateSelection` for the text type (a square wouldn't suit a
text box). `InsertPaletteItem` gains an `active?` field so `CommandBar`
can render the armed style.

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

* fix(maic-editor): render list bullets in slide text

Tailwind's preflight resets `list-style` to none, so the format bar's
`bulletList` toggle wrapped selected text in `<ul><li>` but no marker
ever appeared — the button looked inert. Scope a list-style restoration
to `.editable-element-text ul/ol/li` so bullets / numbers render in the
slide text without leaking into the rest of the app.

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

* feat(maic-editor): editable font-size input in the text format bar

The size was a read-only `<span>` between the −/+ steppers. Replace with
an `<input type=text>` that mirrors `attrs.fontsize` locally, commits on
Enter / blur (clamped to [8, 96]; non-numeric reverts), and reverts on
Escape. Adds the `edit.text.fontSize` aria-label key in all 6 locales.

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

* fix(maic-editor): force list markers visible (defeat preflight specificity)

The earlier list CSS didn't survive Tailwind's preflight (which also
resets `padding: 0` on `<ul>`/`<ol>`, so with `list-style-position: outside`
the markers had no room to render). Add `!important` on `list-style` and
`padding-inline-start`, and broaden to also match `.prosemirror-editor ul`/
`ol`/`li` in case the markup ever nests differently than expected.

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

* fix(maic-editor): reset richTextAttrs when the editing element changes

`richTextAttrs` is a single shared store updated by whichever ProseMirror
was last focused. Switching from one text element to another visibly
carried the previous element's toggle states (bold / italic / alignment /
list) on the format bar for a moment — until the new element's
ProseMirror took focus and repopulated the attrs. `useSyncEditingElementId`
now resets the attrs to defaults whenever the editing id changes, so the
bar shows a neutral state during the transition instead of stale.

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

* feat(maic-editor): replace OS color dialog with a curated palette popover

Clicking the text-color swatch opened the browser's native `<input type=color>`
dialog — off-brand and inconsistent across platforms. Swap it for a
`ColorPicker` popover: a 12-swatch grid covering the common slide-text needs
(4 neutrals + warm + cool) plus a hex input for anything else. Closes on
pick. Selected swatch gets the violet outline; hex input commits on Enter /
blur (reverts if invalid).

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

* feat(maic-editor): replace flat swatch popover with a real color picker

The previous popover was a chunky 12-swatch grid plus a hex input nobody
types into. Rebuild on `react-colorful` (3KB, well-tested):

- SV pad + hue slider for free-form picking, with scoped CSS overrides to
  keep the picker tight (128px pad height) and rounded — not stock.
- OS eyedropper via the EyeDropper API, feature-detected (Chrome / Edge;
  hidden on Safari / Firefox).
- Row of 10 small (18px) common colors at the foot for one-click reach.
- Current-color preview + read-only hex display.
- Hex input dropped entirely — picking is meant to be tactile.

Live preview while dragging; the popover closes on a swatch / eyedropper
commit (not on drag).

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

* fix(maic-editor): keep the color popover open while dragging the picker

Each SV-pad / hue-slider drag tick fires onChange → dispatches the color
command → `editorView.focus()` pulls focus out of the popover into
ProseMirror. Radix's default onFocusOutside path was treating that as a
dismiss, so the popover closed the instant a drag started — clicking
anywhere on the picker shut it. preventDefault on `onFocusOutside`
(mirrors the AnchoredBar hardening) keeps it open; the popover still
closes on swatch / eyedropper commits and on outside-click / Esc.

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

* fix(maic-editor): scope body padding override + gate ColorPicker mid-drag sync

Two follow-ups from a self-CR on the branch:

- `body { padding-right: 0 !important }` was global, overriding Radix's
  `react-remove-scroll` compensation for every Dialog / Sheet / Select /
  Popover across the app. Scope it to a `body[data-maic-editor='true']`
  selector; `SlideCanvas` sets the attribute while mounted. Non-editor
  pages get Radix's default behavior back.
- `ColorPicker`'s `useEffect(() => setColor(value), [value])` mirror
  could race a stale `value` against the user's current pointer position
  mid-drag — a single late round-trip would snap the picker back. Gate
  the re-sync on `isDragging.current` (cleared on `pointerup`); external
  commits (swatch / eyedropper) still sync immediately because they fire
  while no drag is in flight.

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

* chore(maic-editor): polish from self-CR

- Gate the `richTextAttrs` reset in `useSyncEditingElementId` to only
  fire on element-to-element transitions (track previous editing id via
  a ref). The unconditional reset on the first selection briefly flashed
  neutral defaults (color #000, fontsize 16px) before the focusing
  ProseMirror repopulated the real values.
- Doc-comment the text-insertion add-element asymmetry: text uses the
  renderer's `addElement` (because the rect math lives there and we get
  auto-select for free), image uses surface-side `applyOp` (its source
  is the ImagePicker, not a canvas gesture). Both commit through the
  same store, but the text lane doesn't show as a typed `element.add`
  op in the session history — acceptable, now explicit.

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

* chore(maic-editor): listen to every gesture-end channel in ColorPicker

CR round-2 residual nit: the single `pointerup` listener that clears the
drag-gate would silently keep the gate stuck on any browser / emulator
that only emits the older mouse/touch families. Listen on all four
(`mouseup`, `touchend`, `pointerup`, `pointercancel`) — belt-and-suspenders,
no behavior change on the common path.

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

* fix(maic-editor): preserve image aspect ratio on insert

`createDefaultImageElement` hardcoded the new image's box to 360×220, so
anything not ~1.6:1 (which is almost everything users upload — photos,
screenshots, logos) ended up squashed or stretched the moment it landed
on the slide. Wrap the factory in `insertImageElement` that measures the
source via `new Image()`, then dispatches `element.add` with dimensions
scaled to fit MAX 600×400 while preserving the natural ratio. Load
failure falls back to the factory default so insertion always succeeds.

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

* chore(maic-editor): drop the now-dead addElement helper

`addElement` was only ever used by the inline image-insert which became
`insertImageElement`; text uses `armText` (toggle). PPTElement-typed
parameter was already unused after the text refactor — removing the dead
helper resolves the lint warning.

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

* chore(maic-editor): drop now-unused PPTElement import in use-slide-surface

After `addElement` was dropped (55a9a71), the `PPTElement` type import has
no remaining consumers in this file.

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

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

* feat(maic-editor): nav rail, scene management, Pro mode chrome rework (#601)

* feat(maic-editor): slide nav rail + scene management (3/3)

PR3a Phase 1 ships the Pro mode left rail + slide-level management, the
last user-visible block of #562. Closes the gap where Pro mode locked
the user on the current scene with no way to navigate or manage the
deck.

SlideNavRail (Studio Editor aesthetic, mirrors playback `SceneSidebar`
visually — index badge + title above an aspect-video thumbnail card —
so the two sidebars read as the same component family across mode
toggle):

- Vertical thumbnail strip via `motion.dev` `Reorder.Group` with
  drag-to-reorder. `Reorder.Item layout="position"` keeps the layout
  animation on y-axis only; width changes from rail resize don't fight.
- Drag-to-resize handle on the right edge writes `style.width`
  directly on the DOM during the gesture and commits to settings store
  only on mouse-up; matches playback drag feel exactly and skips the
  per-frame `persist` serialization that would otherwise burn the
  frame budget at 60 Hz.
- Collapsed and expanded modes; width and collapsed flag persist in
  `useSettingsStore` (`editRailWidth`, `editRailCollapsed`).
- All scene types are first-class — slides render a live
  `ThumbnailSlide` (now with optional `size` prop → self-measures via
  `ResizeObserver` when omitted, so the rail width is the single source
  of truth), non-slide scenes render the same stylised mockups
  playback `SceneSidebar` uses (extracted to `SceneThumbnailContent`).

Slide management:

- `+ Add` in the rail header inserts a blank slide after the current
  scene; new store action `useStageStore.insertSceneAfter` validates
  stage id, migrates the scene, splices, rebalances `order`, and
  triggers `debouncedSave`.
- Three-dot menu per tile: Rename / Duplicate / Delete. Rename also
  reachable via double-click on the title; Enter commits, Escape
  cancels, blur commits, empty input reverts.
- Duplicate deep-clones slide content with fresh element IDs (avoid
  React key collisions) and a `(copy)` title suffix.
- Delete uses a toast with Undo action; deleted scene is held in a
  small `useDeletedSceneRecycle` zustand store and re-inserted at its
  original index on Undo. Deck-empty guard at the rail layer.
- Inter-thumb `InsertionZone` reveals a violet `+` badge on hover,
  right-anchored, with a popup motion (`cubic-bezier(0.34,1.56,0.64,1)`)
  + drop shadow + `z-20` so it lifts above the active tile's violet
  ring. Zero layout shift.

Chrome bar:

- `HeaderControls` (settings pill + Pro Switch) extracted from
  `Header` so Pro mode can mount it in the CommandBar's trailing slot
  — single top chrome bar in Pro mode instead of stacking Header +
  CommandBar.
- Back-to-home button in CommandBar mirrors the playback Header's
  leftmost button.

i18n: new `edit.nav.*` namespace across en-US / zh-CN / zh-TW / ja-JP
/ ar-SA / ru-RU.

Tests: vitest for `insertSceneAfter`, `useDeletedSceneRecycle`,
`createBlankSlideScene` / `duplicateSlideScene`.

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

* refactor(maic-editor): split Stage chrome into mode-specific roots

Bug-driven architectural rework. Two symptoms motivated this:

1. Switching from a slide scene to a non-slide one (interactive / quiz
   / pbl) flickered the entire edit chrome — CommandBar and SlideNavRail
   remounted along with the canvas. Root cause: EditShell returned a
   different component type (EditShellWithSurface vs EditShellReadOnly)
   based on whether a SceneEditorSurface was registered for the scene
   type, so React reconciled the change as an unmount/remount of the
   whole subtree.

2. `components/stage.tsx` had grown to 1391 lines — playback engine
   state, chat / TTS / discussion wiring, presentation/fullscreen,
   keyboard handling, AND the edit-mode dispatcher all in one place.
   Any change to mode coordination meant touching this god component.

Changes:

- New `NOOP_SURFACE` (`lib/edit/noop-surface.tsx`) — a no-op
  SceneEditorSurface used as a fallback when a scene type has no
  registered editor surface. `SurfaceState.history` is now optional so
  read-only surfaces can omit undo/redo cleanly. EditShell falls back
  to NOOP for unregistered types.

- EditShell now mounts a single Frame across all scene types. Surface
  state is published from a child `SurfaceStateRunner` keyed by
  `scene.type` (so it remounts only when the runner's hook signature
  changes — rules-of-hooks compliant), with a custom shallow
  equality so the chrome doesn't re-render every render cycle for
  reference-fresh state objects. Result: slide ↔ interactive no longer
  remounts the CommandBar or the leftRail.

- `stage.tsx` → 113 lines. Mode dispatch + cross-tab edit-lock
  coordination + Pro-Switch toggle wiring + multi-tab conflict prompt
  only. Everything else moved into one of two new components:

  - `PlaybackChromeRoot` (`components/edit/PlaybackChromeRoot.tsx`):
    owns the entire playback / autonomous chrome — PlaybackEngine,
    chat, discussion TTS, presentation mode, keyboard shortcuts,
    SceneSidebar, Header, CanvasArea, Roundtable, ChatArea,
    AlertDialog. Exposes `teardown()` via forwardRef so the toggle can
    `await` SSE / engine / TTS shutdown before unmounting it.

  - `EditChromeRoot` (`components/edit/EditChromeRoot.tsx`): the Pro
    mode chrome wrapper — EditShell + SlideNavRail + HeaderControls
    trailing slot. Owns `body[data-maic-editor]` lifecycle (lifted from
    SlideCanvas so it covers read-only Pro-mode scene types too).

- New `StageGrid` (`components/edit/StageGrid.tsx`) — CSS-Grid named-
  slot layout shell with top / left / center / right / bottom areas
  for the Pro mode chrome. Future right panel (properties / AI) and
  bottom timeline plug in as props with no structural code change.
  EditShell's Frame now uses StageGrid internally.

- Deleted `components/edit/SlideTransitionBridge.tsx` (dead code from
  the original A3 transition plan that this rework supersedes).

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

* refactor(maic-editor): cross-fade chrome roots on Pro mode toggle

Wrap the chrome-root dispatch in `AnimatePresence mode="wait"` with a
180 ms opacity fade-out / fade-in. The outgoing root fully exits before
the incoming one mounts, so:

- The single-canvasStore-writer guarantee from the chrome split is
  preserved (ScreenCanvas and Editor/Canvas never coexist).
- Mode toggle reads as a smooth fade instead of a hard cut.

Stage's outer wrapper now carries the stable `bg-gray-50 dark:bg-gray-900`
background so neither root reveals raw page colour while it passes
through opacity 0. `initial={false}` skips the entry animation on first
mount so the initial playback render is instant.

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

* feat(maic-editor): drawer-style mode swap transition

Pro toggle was a hard cut — playback chrome vanished, edit chrome
popped into place. Now wraps the swap in `AnimatePresence` with the
two chrome roots layered via `absolute inset-0` so they coexist for
~280ms:

- Edit chrome enters from above (`translateY: -32 → 0`) + fades in,
  giving a "drawer drops down" feel that matches the inner
  CommandBar/leftRail stagger choreography.
- Playback chrome cross-fades opacity-only; no transform so its
  active slide canvas stays put underneath while edit drops over it.

Both roots keep rendering during the overlap, so `canvasStore`'s
scale writer doesn't briefly read zero and snap the slide to a stale
size when one root exits ahead of the other. Duration 280ms /
`CHROME_EASE` matches the inner Frame timing source.

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

* feat(maic-editor): Pro Switch as a shared layout element across modes

The Pro Switch is the click anchor for the mode swap, but it lives in
two different positions: the 80px playback Header (top-right) vs the
56px edit CommandBar trailing slot (also top-right but at a different
y and with different padding). After the click the switch "jumped" —
it visibly moved + restyled — which felt unsmooth even though the
chrome itself was cross-fading.

Tag the Pro Switch label (and the settings pill) with `motion.layoutId`
so motion treats them as shared elements across the AnimatePresence
swap. During the ~280ms transition, motion measures both instances
and morphs position + size between them — the user's click target
slides into its new home instead of teleporting. Same easing source
as the chrome cross-fade so the two animations stay locked together.

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

* refactor(maic-editor): unify chrome shell across modes

Pro Switch + settings pill + download icon are the user's mode-toggle
"anchors" — they need to sit at the same screen pixel across
playback ↔ edit. They didn't, because the two chromes had different
shapes:

  Playback: SceneSidebar (left, full height) | Header (h-20, 80px)
            on top of CanvasArea + Roundtable
  Edit:     CommandBar (h-14, 56px, FULL width) on top of a row of
            (SlideNavRail | content), so the rail sat *below* the bar

So when the user clicked Pro, the bar collapsed by 24px AND the rail
shifted down by 56px AND the right-side controls re-styled (compact
variant) — three simultaneous moves. layoutId masked some of it but
the underlying structure was wrong.

Unify the shells:

- `StageGrid` template flipped from `top top top / left center right /
  bottom bottom bottom` to `left top top / left center right / left
  bottom bottom`. The left column now spans all rows so the sidebar
  always reaches the absolute top edge, matching playback exactly.
- `CommandBar` grows h-14 → h-20 + px-5 → px-8, identical to playback
  Header.
- `EditChromeRoot` drops the `variant="compact"` flag on
  `HeaderControls` so the settings pill renders at the same h-9 pill
  it does in playback.
- `SlideNavRail` header replaces the "SCENES" label with the OpenMAIC
  logo (click → home), matching `SceneSidebar`'s shape so the sidebar
  top reads as the same component family in both modes.
- Download / Export dropdown moves out of `Header` and into
  `HeaderControls` so it's present in both playback and edit chrome at
  the same right-cluster position (was previously playback-only).

`Header.tsx` slimmed accordingly. Net effect: the right-edge cluster
(EN, theme, settings, download, Pro Switch) lives at the same screen
pixel across modes; the cross-fade transition only animates the
*contents* inside the bars + sidebar lists, not the bar/rail
positions themselves.

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

* feat(maic-editor): drop sidebar header + button, add insert-before-first zone

The header `+` was a duplicate affordance — every gap between thumbs
already has its own `InsertionZone`. Remove the header button; insert
flows entirely through the gap zones now (with hover-popup + and
right-anchored visual).

Add one extra `InsertionZone` rendered BEFORE the first thumb so the
top padding of the rail is also clickable / hoverable. Insert-before-
first is implemented inline via `setScenes([blank, ...scenes])`
because the `insertSceneAfter` store API only handles insertion after
an existing anchor.

`PlusCircle` import dropped (no longer used).

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

* fix(maic-editor): move Download out of settings pill, place right of Pro Switch

Download isn't a settings function (it's an export/share action), so
it shouldn't sit inside the pill that hosts language/theme/settings.
Move it back to a standalone button on the right side of the Pro
Switch — both in playback and edit chrome. Right cluster now reads:

  [ EN · theme · settings ]  [ PRO switch ]  [ Download ]

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

* feat(maic-editor): floating insert toolbar above canvas (collapsible)

Text box / Image / future shape buttons no longer share CommandBar
with global stage controls (back / undo / redo / title / settings /
Pro Switch / Download). Insert is a content-creation action, not a
stage-navigation one — mixing them blurred the chrome's role.

Lift insert items into a new `FloatingInsertToolbar` that floats
centered ~12px above the slide canvas card. Default expanded; collapse
arrow tucks it into a small chevron handle at the same anchor. State
persists in `settings.editInsertToolbarCollapsed`. Reuses the existing
`InsertButton` (extracted from CommandBar into a sibling module so
both surfaces — the now-removed CommandBar slot and the floating bar —
can share styling).

CommandBar drops its `insertItems` prop / middle slot entirely;
right-side controls collapse to a single `flex shrink-0` cluster
matching playback Header's shape.

i18n: `edit.insert.expandToolbar` / `collapseToolbar` across 6 locales.

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

* fix(maic-editor): auto-focus text element after toolbar insert

Inserting a Text box via the FloatingInsertToolbar + click/drag on
the canvas left the user one click short — the new element was
selected and the AnchoredTextBar opened, but the ProseMirror editor
never received focus, so the first keystroke went nowhere and the user
had to click inside the element again before typing.

`useEditingTextElementId` already mirrors the surface's editing-target
choice into `canvasStore.editingElementId`. Have `ProsemirrorEditor`
watch that flag in an effect: whenever its own elementId becomes the
editing target (insert, programmatic selection, etc.) and it doesn't
already have focus, push focus into the view. `hasFocus()` guard keeps
this from re-focusing on every re-render of an already-active editor.

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

* chore(maic-editor): prettier + drop ThumbItem rename sync effect

- prettier --write on three files touched by the recent edits.
- ThumbItem: drop the `useEffect(() => { if (!renaming) setDraft(...) })`
  external-title sync that tripped `react-hooks/set-state-in-effect`.
  Idle display now reads from `scene.title` directly (derived rather
  than mirrored); `startRename` seeds `draft` at session start and
  `cancelRename` resets it so the next session starts clean. Rename
  e2e still passes the menu + double-click + Escape paths.

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

* fix(maic-editor): CR-loop pass — pointer capture, stage-scoped recycle, equality docs

PR #601 reviewer feedback.

**Drag handle uses Pointer Events with `setPointerCapture`** so the rail
no longer gets stuck in "still dragging" state when the cursor leaves
the window, the OS reclaims focus, or a tab interrupt suppresses the
mouseup that the old document-bound mousemove/mouseup pair relied on.
The handle's onPointerMove/Up/Cancel are now bound directly on the
element; capture guarantees event delivery for the lifetime of the
gesture. Drag tracking e2e still PASS (1 px cursor lock).

**Toast Undo guards stage identity** before re-inserting the deleted
scene. If the user navigated to a different stage while the toast was
up, the recycle entry belongs to the previous stage and
`insertSceneAfter` would reject it on stage-id mismatch — silently
losing the deleted scene. New check drops the undo cleanly when stage
ids don't match. The `stageId` field was already captured on
RecycleEntry; just wasn't consulted.

**`surfaceStateEqual` extended** to compare per-item `id` / `disabled`
/ `label` on `floatingActions` (was length-only) and per-item
`id`/`severity`/`message` on `hints` (was length-only). Today's slide
surface returns `floatingActions: []` and `hints: []` so this is
dormant, but PR3b's z-order actions land in `floatingActions` — pinning
the equality semantics now keeps a future state field from silently
going stale in the chrome. SurfaceState gets a maintenance note
cross-linking to the equality function.

**Header.tsx mode guard comment** updated. The `mode !== 'edit'` guard
around the title block isn't dead — it covers the ~280ms
AnimatePresence exit window where playback chrome is still rendering
its exit animation while mode has flipped to 'edit'. Without the
guard, this title would briefly stack on top of the incoming
EditChromeRoot's CommandBar title during the cross-fade.

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

* docs(maic-editor): CR-loop round 2 minors — sharpen JSDocs

Round-2 reviewer flagged two doc-only refinements:

- `surfaceStateEqual`: clarify that callback identity (`onInvoke`,
  `popoverContent`) is intentionally NOT compared, and that today's
  safety comes from slide-surface returning `floatingActions: []`
  rather than the per-item compare covering callbacks. A future
  surface that emits closure-capturing actions must fold its own
  change signal into the comparison or the stale callback fires at
  click time.
- `setPointerCapture` catch: spell out that this is paranoia, not a
  real fallback — if capture genuinely fails the gesture still
  tracks for in-window moves but out-of-window `pointerup` won't
  route here. Acceptable degradation; the catch exists only because
  the spec permits an `InvalidPointerId` throw that browsers we ship
  to don't actually emit on same-pointer `pointerdown`.

No functional changes.

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

* fix(maic-editor): undo restore at index 0, reset mode on classroom load

Two issues from PR #601 manual-verification review:

**Undo of the first slide restored it as the second.** The toast undo
handler clamps `entry.index - 1` to 0 then calls
`insertSceneAfter(scenes[0], entry.scene)`, which lands the entry at
position 1 instead of position 0 — no scene exists before scenes[0] to
anchor on. Fall back to `setScenes([entry.scene, ...live])` when
`entry.index === 0` (or when the deck is empty). The store's existing
non-rebalancing `deleteScene` keeps the surviving scenes at orders
2..N, so the prepended entry's original order=1 lines up naturally;
StageGrid auto-selects the restored scene as current.

**`mode` survived SPA navigation between classrooms.** Refresh reset
mode to 'playback' via the initial store value, but switching
classrooms via Next.js navigation kept the zustand singleton intact;
entering Pro mode in A and then opening B left B in edit mode.
`loadFromStorage` and the server-side classroom-load path both now set
`mode: 'playback'` on every classroom load, normalising the SPA path
to match the refresh path. Mode stays transient UI state, not
persisted with the stage.

e2e: delete Slide 1 → Undo → restored to position 1 (was position 2
before fix).

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

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

* feat(maic-editor): gate slide scene creation until inserted scenes are playable (#612)

* feat(maic-editor): gate slide scene creation until inserted scenes are playable

Editor-created slide scenes (blank insert + duplicate) ship without
playback actions, so the playback engine gives them zero dwell and skips
straight past them — a freshly inserted slide is effectively unplayable.
Seeding default actions on new scenes is a separate change; until then,
hide the two scene-creation entry points so the editor stays coherent as
an in-place "fine-tune the generated deck" tool.

- add lib/edit/scene-creation-enabled.ts (SCENE_CREATION_ENABLED=false)
- hide inter-thumb "+" insertion zones (SlideNavRail)
- hide per-slide Duplicate menu item (ThumbItem)
- keep reorder / delete / rename, which are playback-safe

Re-enable by flipping the flag once new scenes get default actions.

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

* test(maic-editor): e2e guard for slide scene-creation gate

Adds an e2e that generates a classroom (mocked), enters Pro mode, and
asserts the slide rail exposes no insertion "+" zones and the per-slide
overflow menu has only Rename + Delete (no Duplicate). Fails if
SCENE_CREATION_ENABLED is flipped back on without removing the gate.

Two stable test ids support locale-independent assertions:
- slide-nav-insert  (InsertionZone button)
- slide-nav-more    (ThumbItem overflow trigger)

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

* test(maic-editor): enable editor flag for the e2e webServer

The scene-creation gate e2e needs the Pro Switch, which only renders when
NEXT_PUBLIC_MAIC_EDITOR_ENABLED is on. It's a build-time NEXT_PUBLIC_* flag,
so set it in the Playwright webServer env (applies to `pnpm build` in CI and
`pnpm dev` locally). Fixes the e2e failure on CI.

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

* test(maic-editor): attach gate screenshot to report instead of fixed path

CR: e2e-artifacts/ is not gitignored, so writing the screenshot to a fixed
path left an untracked file that could be committed by accident. Use
testInfo.attach so the image lands in the (ignored) Playwright report.

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

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

* i18n(maic-editor): add pt-BR translations for edit.* / stage.* keys

pt-BR locale (added on main post-stack) lacked the 51 editor keys, so
check:i18n-keys failed after rebase onto main.

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

* fix(maic-editor): defer editor-only side effects behind Pro mode mount

editor-fonts (~23 @fontsource CSS tables) and slide-surface registration
were top-level static imports in app/layout.tsx and components/stage.tsx,
so flag-off classroom/playback users paid the font-face CSS + slide-edit
module-init cost on every page load.

Move both to a dynamic import in EditChromeRoot (mounts only when
mode==='edit', which requires NEXT_PUBLIC_MAIC_EDITOR_ENABLED). Hold the
EditShell render until the slide surface registers to avoid a NOOP/
read-only flash on first Pro mode paint.

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

* fix(maic-editor): CR-loop correctness fixes (redo/groupId/edit-lock)

Three confirmed issues from the rebase code-review pass:

- slide-edit-session: a non-user (ResizeObserver auto-height) commit
  updated history.present while preserving a now-stale future, so a
  redo after undo silently resurrected pre-undo content. Clear future
  on the non-user path (present has diverged from the redo branch);
  past is left untouched so no spurious undo step is created.
- slide-defaults: duplicateSlideScene reassigned element ids inline,
  leaving grouped elements pointing at the source slide's groupId.
  Use the existing createElementIdMap so clones get a new shared
  groupId. (Path is gated off today via SCENE_CREATION_ENABLED; fixes
  a latent defect.)
- stage: wrap playback teardown on Pro-mode entry in try/catch and
  release the just-acquired cross-tab lock on failure, so a rejected
  teardown can't strand the lock with the UI stuck in playback.

Adds regression tests for the redo-stale and groupId cases.

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

* fix(maic-editor): scope editor list-marker CSS to Pro mode

The .editable-element-text ul/ol/li rules used a bare selector, but
that class is the playback text wrapper rendered for every classroom
user — so the !important list-style overrides leaked into normal
playback. Scope them to body[data-maic-editor='true'] (set only while
Pro mode is mounted) so flag-off playback rendering stays unchanged;
markers still show while editing.

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

* fix(maic-editor): smooth Pro mode transition and stabilize header controls

The Pro mode enter/exit animation janked and the right-side header
controls (settings pill + Pro Switch) drifted in width/position across
the swap. Three causes, all addressed:

- The flag-gating dynamic import gated EditShell behind surfaceReady, so
  the chrome animated in empty and content popped in once the slide-surface
  chunk loaded. Preload the editor chunk (fonts + surface registration) in
  the Pro Switch handler BEFORE flipping mode (lib/edit/preload-editor.ts),
  and drop the render gate — content is present when the animation starts.
- Mode-swap layers and EditShell chrome layers used translateY/translateX
  slides; with backdrop-blur on the rail and pills that forced a per-frame
  backdrop-filter recompute (dropped frames) and, as transform ancestors,
  distorted the layoutId measurement. Switched all chrome enter animations
  to pure opacity fades.
- HeaderControls rendered a fragment whose children were spaced by the
  host's flex gap (Header gap-4 vs CommandBar trailing gap-2), so the
  control cluster changed width/anchor between modes. Wrapped it in a
  self-contained gap-4 container and dropped the cross-bar layoutId morph
  so the cluster is pixel-stable across the swap.

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

* fix(maic-editor): address review — image insert race, scene migration, i18n staleness

Review feedback from @cosarah on the integration PR:

- Image insert resolved size via Image.onload then applied the op to
  whatever slide session was current at callback time, so switching
  slides before the image loaded inserted it into the wrong slide. Bind
  the insert to the scene active at click time and drop the op if the
  session changed before onload fires.
- Classroom scenes loaded from IndexedDB (loadFromStorage) and from the
  server API (classroom page) bypassed migrateScene, so legacy slide
  content was not normalized with schemaVersion. Both load paths now
  migrate on the way in, matching setScenes/addScene.
- surfaceStateEqual compared insert-item/command id/active/disabled but
  not label/tooltip, so the Pro-mode insert toolbar text stayed stale
  after a language switch. Compare label/tooltip too.

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

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-31 21:54:04 +08:00
35d36905d1 Make server-configured providers admin-managed, not client-overridable (#620) (#624)
* refactor(providers): make server-configured providers admin-managed, not client-overridable

A server-configured provider is now authoritative: the operator owns its API
key and base URL, and the client cannot override either. This collapses the
tri-state (server key / client base URL / client key) that was the root of a
recurring "missing API key" bug class — when the settings UI echoed a base URL
with an empty key, routes that treated "any base URL ⇒ fully client-configured"
dropped the server key. #533 patched that per-route via canUseServerApiKeyForBaseUrl;
this removes the guard entirely by fixing the design.

Server:
- resolve*ApiKey/BaseUrl ignore client values when the provider is server-
  configured; add isServerConfiguredProvider(section, id); drop
  canUseServerApiKeyForBaseUrl + normalizeProviderBaseUrl.
- getServer*Providers() no longer return base URLs — only allowed models
  (LLM/image) and the managed flag (presence) — so an internal gateway/proxy
  endpoint is never exposed to the client.
- routes (chat/image/video/tts/asr/pdf + verify-*) resolve managed providers
  purely server-side; SSRF validation now applies only to unmanaged (client)
  base URLs.

Client:
- drop serverBaseUrl from ProviderSettings, the settings store, request-building
  (TTS base URL no longer echoes the server URL) and voice resolution.
- settings UI renders managed providers read-only: the key/base-URL override
  inputs and region toggles are hidden, leaving the "managed by server" notice.

Tradeoff: overriding a server provider's key with your own for the same provider
is removed; add a separate custom provider instead. Closes #620.

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

* chore(providers): refresh managed-provider copy, drop dead audio-settings, add #620 e2e

- serverConfiguredNotice now says the provider is managed and not editable here,
  pointing users to add a separate provider for their own credentials (7 locales).
- delete components/settings/audio-settings.tsx — unreferenced dead code.
- add e2e/tests/managed-provider-620.spec.ts: managed provider hides the
  key/base-URL inputs; unmanaged provider keeps them.

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

* feat(providers): lock the model catalog for managed providers with a pinned list

When the operator pins an allowed model list (MODELS env/yaml ⇒ serverModels),
the model catalog is admin-managed too: the LLM provider panel shows the pinned
models read-only with a "Server" badge and no add / reset / edit / delete
affordances. Without a pinned list the server manages only credentials and the
user keeps curating models.

This removes the prior inconsistency where the settings panel let you add models
to a pinned managed provider that the generation toolbar then filtered out.

e2e: the managed-openai case now also asserts the catalog is locked.

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

* fix(providers): ignore (not reject) client overrides for managed web-search; clear legacy serverBaseUrl

Addresses review feedback on #624:

1. Managed web-search providers now ignore a client-sent key/baseUrl instead of
   validating and rejecting it. A server-configured provider is admin-owned, so
   the server config is authoritative and a stale client base URL is dropped
   rather than 400-ing the request. The allowlist validation still runs for
   unmanaged providers, where the client base URL is actually used.

2. Drop the removed `serverBaseUrl` field from persisted localStorage on
   rehydrate (settings version 2 -> 3, stripped in both migrate and merge), so
   old clients don't keep a stale server URL in client state.

Tests: web-search route test split into unmanaged-rejects-allowlist and
managed-ignores-client-baseUrl; settings rehydrate test asserts a legacy
serverBaseUrl is stripped. Full suite 381 pass; e2e 2 pass.

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>
2026-05-31 21:28:22 +08:00
86c8e0c543 feat: inline external assets at export for offline classrooms (#596) (#613)
* feat(export): add external-asset reference scanner for HTML inlining

* feat(export): add cached asset fetcher and data-uri encoder

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

* feat(export): recursively inline url() refs inside stylesheets

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

* feat(export): orchestrate inlining of links, scripts, images, and inline css

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

* refactor(export): drop dead escapeAttr, harden importmap skip in scanner

* feat(export): inline importmap modules incl three/addons graph closure

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

* refactor(export): extract shared module to break inline-assets import cycle

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

* feat(export): inline interactive-scene assets into .maic.zip at export

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

* feat(export): inline interactive assets in Resource Pack export too

* docs: document offline export asset inlining

* style: prettier formatting

* fix(test): resolve tsc type errors in export-classroom-inline test

* fix(export): keep importmap prefix fallback on partial failure, chunk base64, preserve media attr, log pptx inline failures

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

* perf(export): parallelize asset fetching, share fetcher across scenes, promise-cache

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

* fix(export): retry transient asset fetches, bound concurrency, warn user on partial inline

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

* perf(export): inline only woff2 fonts, drop woff/ttf siblings to halve size

Within @font-face blocks that have a woff2 url(), rewrite sibling woff/ttf/otf/eot
refs to url(about:invalid) instead of inlining them. Falls back to full inline for
ttf-only blocks. Drops katex output from ~1.79MB to ~0.71MB (~3x fewer font fetches).

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

* i18n(export): translate partial-inline warning and surface failed asset hosts

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

* feat(proxy-media): follow redirects with per-hop SSRF revalidation (#398)

Replace blanket redirect rejection with a bounded 5-hop follow loop that
re-validates every Location target through validateUrlForSSRF before
fetching, preventing redirect-to-internal SSRF while allowing CDN
redirects (e.g. cdn.tailwindcss.com 302→/3.4.17).

* feat(export): route asset inlining through proxy-media to bypass CORS

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

* fix(export): keep importmap prefix fallback, forward proxy 4xx, cap proxy size, re-export FetchAsset

* style: prettier formatting for proxy-media + proxied-fetch

* fix(export): report CSS-nested asset failures in inline report

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
2026-05-31 18:36:39 +08:00
wyuc f064590a5e test+fix(orchestration): rip maxTurns; restore answer-the-user's-question behavior (#598 follow-up) (#599)
* test(orchestration): add premature-END regression eval (#598 follow-up)

Adds eval/orchestration/ following the outline-language pattern: a runner
that A/B-tests the director against the same scenario with two prompt
variants — current main (post-#554) and a synthesised pre-#554 baseline
that strips the role-aware summary labels AND the new system.md rules
10/11/12 together.

Pass criterion is now framed as a regression guard rather than a fixture
discrimination test: every scenario's post-fix END rate must stay below
EVAL_END_THRESHOLD (default 20%). The pre-vs-post Δ is reported as
informational data, since #554's reviewer feedback was that earlier
fixtures didn't discriminate.

Empirical finding across 7 shipped model configs (gpt-4.1-mini,
gpt-4o-mini, gpt-5.4-nano, qwen-plus, qwen3.5-flash, deepseek-chat,
deepseek-v4-flash, gemini-2.5-flash, claude-haiku-4-5) with 5 scenarios
modelled on #511 (incl. the exact Tiananmen-3D objection trace, soft
pushback after a long resolved-looking discussion, topic pivot, brief
acknowledgement, and explicit teacher-signals-end-then-user-objects):
no scenario produced a non-zero END rate in either variant. Useful
data for the #554/#598 discussion — the prompt-layer rules don't
measurably change behavior on these shipped models with these prompts,
but the eval is now wired so future regressions show up.

* test(orchestration): add director question-answering eval (#598 follow-up)

Adds an A/B eval probing whether the director routes correctly when the
conversation contains an unanswered user question — both in the first-turn
drift case (agents started answering but drifted onto adjacent topics,
no frustration yet) and in the escalated frustration case (user has
already complained multiple times).

The prod symptom this targets ("答非所问"): agents reply on adjacent
topics rather than answering the literal question, and the director
keeps picking peer agents for "variety" instead of routing back to
the teacher to actually answer.

Scenarios: 5 synthesized cases across math, biology, English grammar,
physics, and calculus. 3 are first-turn drift (no frustration yet),
2 include frustration signals. Each captures: user asks specific
question, agents reply on adjacent topics, director is asked to pick
the next move.

Decision rule-judged into USER | TEACHER | OTHER_AGENT | END:
  - USER       → ✓ valid (cue user to clarify)
  - TEACHER    → ✓ valid (re-route to teacher to answer)
  - OTHER_AGENT → ✗ wrong (peer-agent "variety" routing — the bug)
  - END        → ✗ wrong

A/B:
  - baseline  : current director template with rule 13 stripped
  - with_rule : current director template as-shipped

Pass = with_rule.correctRate ≥ EVAL_PASS_THRESHOLD (default 0.7).
Pre-vs-post Δ is reported as informational only.

Note this commit only adds the eval; the rule it strips/restores in
the A/B is injected in the next commit.

* fix(orchestration): inject director rule for answering user questions

Adds rule 13 to lib/prompts/templates/director/system.md so the director
recognizes when the conversation contains an unanswered user question
and routes appropriately — to the teacher (literal role match) by
default, or to USER cue when the question is ambiguous or the user
has already complained multiple times.

This addresses the "答非所问" symptom: when agents drift onto adjacent
topics, the director keeps picking peer agents for "variety" rather
than routing back to the teacher to actually answer. The rule is
preventive (applies whenever the question is unanswered, including
the first turn after drift) rather than reactive-only (waiting for
the user to express frustration).

Rule wording uses constrained-output framing: literal `role: teacher`
match (not "best fit" / "highest priority" / "most knowledgeable"),
and an explicit list of forbidden choices (peer agents, END). Earlier
softer wordings let the model pick the assistant when it seemed more
topically relevant; the literal-match wording prevents that.

Validated by the question-answering eval added in the previous commit.
On google:gemini-3-flash-preview, 5 samples per variant across 5
synthesized scenarios:

| Scenario                                           | baseline | with_rule |
|----------------------------------------------------|----------|-----------|
| math_quadratic_axis_drift_no_frustration           | 100%     | 100%      |
| bio_dark_reaction_drift_no_frustration             | 80%      | 100%      |
| english_team_isare_drift_no_frustration            | 20%      | 100%      |
| physics_inertial_mass_escalated_frustration        | 0%       | 100%      |
| calculus_product_rule_drift_no_frustration         | 60%      | 100%      |
| **mean**                                           | **52%**  | **100%**  |

3 of 5 scenarios reproduce the bug at baseline (correct rate ≤ 60%);
the rule lifts every scenario to 100%. The remaining 2 baselines are
already high — the rule doesn't regress them.

* fix(orchestration): teach agents to answer the user's literal question

Adds an "Answering the User's Question" section to the agent system
prompt. Before this, the agent SP had no rule for direct-answering — the
persona, role guideline, current-state context, and length guidelines all
pushed the agent to advance the lesson and inspire thought, with no
explicit directive to first answer the user's literal question.

The result observed in prod ("答非所问"): when the user asks a specific
question (a formula, a yes/no, a term), agents reply with adjacent
concepts, examples, or follow-up questions — but never the literal
answer.

The new section directs the agent, on every response where the user
message contains a question, to:
- lead with the concrete answer to the literal question,
- not pivot to an adjacent topic even when it seems pedagogically
  richer,
- treat "inspire thought" and peer-differentiation guidance as
  applying only AFTER the literal question is answered,
- say "I don't know" directly when uncertain rather than answering
  a different question,
- on frustration signals from prior turns, look back at the original
  question (before the frustration) and answer THAT specifically.

This is the agent-side counterpart to the director rule landed in the
previous commit. Director routes to the teacher when the question is
unanswered; the teacher now has explicit guidance for what to do when
dispatched.

* refactor+fix(orchestration): rip maxTurns end-to-end; distinguish errors from completion

Two coupled cleanups in one commit since the outcome-handler rewrite
naturally falls out of removing the client-side max-turns loop.

The director graph used `maxTurns: turnCount + 1` to force "one
director→agent cycle per request" — a hack expressing the single-round
contract as a turn limit. This commit removes the hack and the
surrounding user-facing setting, replacing implicit intent with explicit
graph topology.

Server:
- `director-graph.ts`: drop `maxTurns` from state, drop the hard-cap
  check at the top of `directorNode`, change `agent_generate → director`
  edge to `agent_generate → END`. Single-round contract is now expressed
  by topology.
- `lib/types/chat.ts`: drop `maxTurns` and `currentTurn` from
  `SessionConfig`; drop `maxTurns?` from `CreateSessionRequest.trigger`.

Client:
- `lib/store/settings.ts`: drop `maxTurns` state, `setMaxTurns` action,
  the `'10'` default, and the localStorage migration path.
- `components/agent/agent-bar.tsx`: drop the entire compact-stepper UI
  block plus the unused MessageSquare/Minus/Plus lucide imports.
- `components/settings/agent-settings.tsx`: drop the AgentSettings prop
  and the multi-agent-only Input block.
- `lib/chat/agent-loop.ts`: drop `maxTurns` parameter, change
  `while (turnCount < maxTurns)` to `while (true)` controlled by inner
  exits, drop `'max_turns'` reason from `AgentLoopOutcome`.
- `components/chat/use-chat-sessions.ts`: drop the maxTurns lookup, drop
  the trailing arg to runAgentLoop, drop vestigial `maxTurns: 0` /
  `currentTurn: 0` from session creation.
- `eval/whiteboard-layout/runner.ts`: drop unused MAX_AGENT_TURNS plus
  the trailing arg.

i18n: drop `settings.maxTurns` and `settings.maxTurnsDesc` from six
locales (en-US, zh-CN, zh-TW, ja-JP, ar-SA, ru-RU).

Motivation for removing the user-facing setting: the LLM director
controls round length via cue_user / END decisions, so a numeric
"max discussion turns" knob is redundant with rule-driven routing.
When the director prompt was buggy, the cap masked the bug by force-
ending; once director routing is fixed, the cap just removes user
agency.

Before, every non-`cue_user` outcome of the agent loop mapped to
`status: 'completed'` in `use-chat-sessions.ts`. That conflated four
distinct paths:
- `end`: director chose END (legitimate completion)
- `empty_turns`: two consecutive agents returned no text or actions
  (parser failure, model timeout, etc.)
- `no_done`: SSE stream ended without a `done` event (infrastructure
  failure)
- `aborted`: user pressed stop (handled elsewhere)

The new switch routes `end` to completed, `empty_turns` and `no_done`
through `clearLiveSessionAfterError` so the user sees an inline System
message describing what went wrong instead of a quiet "completed".

- `lib/types/chat.ts`: add `'error'` to `SessionStatus`.
- `components/chat/use-chat-sessions.ts`: rewrite the outcome handler
  as a switch; have `clearLiveSessionAfterError` set `status: 'error'`
  so all entry points (the runAgentLoop outcome AND existing throw
  paths from fetchChat / SSE error events) converge on the same
  visible state.
- `components/chat/session-list.tsx`: add `AlertCircle` red icon for
  the new error status.
- i18n: add `chat.error.emptyAgentResponses` and
  `chat.error.streamInterrupted` strings to all six locales.

This is the in-product fix that the prod investigation surfaced as
an independent root cause of the #511 "discussion ended unexpectedly"
symptom — separate from the director and agent prompt fixes in the
earlier commits of this PR.

* fix(chat): drop dead settingsState binding; wire eval:orchestration:answering script

Two minor CR follow-ups:

- components/chat/use-chat-sessions.ts: the `settingsState` lookup at the
  top of runAgentLoopFn was the entry point for the maxTurns lookup
  ripped in the previous commit; with maxTurns gone, the binding is
  unused and ESLint flags it. Drop the line. (Other uses of
  useSettingsStore.getState() elsewhere in this file are unaffected.)

- package.json: the answering eval runner had no convenience script,
  while the premature-end runner did. Add eval:orchestration:answering
  for symmetry and discoverability.

* fix(orchestration): route ambiguous/unaddressed user turns to teacher, never USER cue

Addresses reviewer issues 2 & 3 (ambiguous "帮我看一下这个" / "Can you take a
look at this?"): the director was cueing USER for vague input, which makes no
agent speak — the user faces dead air with nothing to react to ("nobody
responds"); and when an agent did speak it guessed a topic instead of asking
what the user meant.

Root cause was the previous rule 13, which offered `{"next_agent":"USER"}` as
a valid response to an ambiguous user turn. A USER cue is the wrong tool here:
it returns control to the user without any agent speaking. The right behavior
is to dispatch the teacher, who either answers or — if the message is too
vague — asks a clarifying question out loud.

Director (`director/system.md` rule 13):
- When the most recent user turn is unaddressed (clear question, vague
  request, OR frustration signal), the only acceptable output is the literal
  `role: teacher` agent id.
- USER cue is now explicitly forbidden as a response to a user turn (reserved
  for rule 7, where an agent has just asked the user something).
- Tightened the END prohibition: a high turn count or a thoroughly-discussed
  topic does NOT mean the specific question was answered. Added rule 5
  (don't-drag-on) to the override list, since that pressure was driving the
  director to END on well-discussed-but-unanswered turns.

Agent (`agent-system/system.md`):
- Added a clause to "Answering the User's Question": if the user's message is
  too vague to answer (no clear referent), ask ONE short clarifying question
  with a concrete option or two — do not guess a topic and lecture, do not
  stay silent.

Eval (`answering-runner.ts` + `scenarios/answering.json`):
- Reclassified USER as wrong (dead air); only TEACHER counts as correct now
  (teacher answers, or asks a clarifying question for vague input).
- Added two ambiguity scenarios: a bare "帮我看一下这个" opener, and a vague
  "再帮我看看这个吧" follow-up after a real Q&A.
- Made the rule-13 strip regex match by rule number rather than heading text,
  so it survives heading rewrites.

On google:gemini-3-flash-preview, 10 samples per variant, all 7 scenarios
PASS (with_rule mean ~97%, baseline ~57%). The two ambiguity scenarios:
ambiguous_look_at_this 100%/100%, ambiguous_vague_followup 20%→100%.
Manually verified the agent side: for "帮我看一下这个" the teacher now replies
"…你想讨论的是具体的代码逻辑,还是 Agent 的决策流程图呢?" (clarifying question +
concrete options) instead of guessing.

Note: reviewer issue 1 (follow-up not answered) could not be reproduced on
this branch across 7 configurations; it is consistent with the deployed
environment running older code and/or provider API flakiness, which the C7
error-vs-completion distinction in this PR already surfaces instead of a
silent 已结束.

* docs(eval): fix stale physics scenario description after USER→wrong reclassification

The physics_inertial_mass scenario description still said "USER-cue signal —
but TEACHER re-answer is also valid", which contradicts the new classifier
(USER is dead air = wrong; only TEACHER is correct). Cosmetic only — the
description field is printed into the report, never used in classification.
2026-05-29 10:52:30 +08:00
Ismail Ariyan 07115dff17 feat(asr): add Azure STT (Fast Transcription) provider (#175)
* add Azure ASR config and localization

* add transcribeAzureASR func

* fix(settings): prevent Azure STT crash in ASR modal

* feat(i18n): add Azure STT provider support in language locales
2026-05-27 22:38:49 +08:00
hemanzandClaude Opus 4.7 448c1e4850 feat(i18n): add Brazilian Portuguese (pt-BR) locale (#602)
Adds Português (Brasil) as a supported UI language for Brazilian users.
All ~280 keys translated from en-US.json with attention to UX-sensitive
keys (default nickname, greeting, encouragement messages). Language
autonyms (lang_*) follow the existing convention of keeping each
language's native form. Voice display names kept in English while
descriptions are translated.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-27 14:37:02 +08:00
wyucandClaude Opus 4.7 d9aecf8052 fix(settings): enforce "usable provider ⇒ concrete model" invariant (#580) (#581)
* fix(settings): enforce "usable provider ⇒ concrete model" invariant (#580)

Layer 1 — resolve provider AND model atomically at every source:
- add resolveSelectedModel(): like validateModel but no empty-input
  short-circuit, so it returns '' only when the provider has no models
- fetchServerProviders: symmetric LLM/image/video provider recovery +
  resolveSelectedModel; remove the asymmetric #577 isServerConfigured-gated
  LLM tail and the separate first-load auto-select block (now subsumed,
  and covers client-API-key providers too)
- setProviderConfig: entering an API key for the active/unset LLM provider
  resolves a concrete model in the same set()
- setVideoProvider: resolve a model on switch (was id-only); setImageProvider
  routed through the shared resolver

Layer 2 — remove states unreachable under the invariant:
- add shared isLLMProviderConfigured / hasUsableLLMProvider; gate the
  landing-page generate button on a usable provider (state A vs B) and drop
  the modelNotConfigured toast + forced SettingsDialog
- generation-toolbar: use the shared predicate; drop the dead "Select Model"
  label/tooltip fallback
- delete dead components/settings/model-selector.tsx (zero refs) and the
  now-orphan settings.selectModel i18n key (6 locales)

Note: generation-toolbar's `providerEntries.length === 0` branch is KEPT —
it is reachable via search (search-no-results), not the dead no-provider
state the issue assumed. modelNotConfigured i18n key kept (still used by
the chat path in use-chat-sessions).

Tests: resolveSelectedModel + hasUsableLLMProvider unit tests; server-sync
invariant tests (client-key resolution, atomic API-key entry, provider
switch, serverModels-preference + first-load regression guards).

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

* fix(settings): address code review — symmetric image/video config resolution

Code review Important #1: fold atomic model resolution into
setImageProviderConfig / setVideoProviderConfig (design doc Layer 1 step 2
scoped these). Deleting the selected custom image/video model on the active
provider now resolves to a valid model in the same set() instead of leaving
it stale until the next server sync — restores LLM/image/video symmetry.

Minor #2/#3: document the deliberate store-level (credential path) vs
UX-level (incl. ≥1 model) "usable" split on isProviderUsable; clarify that
setProviderConfig also adopts providerId on the first-load API-key path.

Tests: +2 invariant tests (delete selected custom image/video model →
falls back to a valid model). 89/89 store tests pass, tsc clean.

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

* fix(settings): keyless providers need explicit baseUrl to count as usable (#580)

Code-review/e2e follow-up. ollama/lemonade ship requiresApiKey:false +
a registry defaultBaseUrl, so the old isLLMProviderConfigured counted them
as configured on a fresh install — but buildFallback/reconcile never
auto-selects keyless providers, so hasUsableProvider could be true while
modelId stayed '', re-enabling generation with no model (the exact #498/#580
class of bug, just via the keyless path).

Narrow isLLMProviderConfigured to be consistent with isProviderUsable:
keyless ⇒ usable only once the user sets an explicit baseUrl (registry
defaultBaseUrl alone is not user intent); server-config and key-requiring
paths unchanged. Now gate + toolbar + reconcile agree, and genuine State A
(no usable provider) is reachable again.

Add e2e/tests/model-invariant-580.spec.ts: State A (no provider → generate
disabled + single "Set up model" affordance, no toast/forced dialog) and
State B (server-configured → concrete model auto-resolved, generation
enabled). +3 keyless unit tests. 92/92 store tests + 2 e2e pass, tsc clean.

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

* fix(settings): re-resolve selection on bulk provider-config change (#580)

Self-test found: deleting the selected provider in Settings left the model
selector pointing at the deleted/invalid provider (or, via the component's
hand-rolled fallback, at an unusable built-in like openai with no key).

Root cause: setProvidersConfig (the bulk setter behind delete-provider /
delete-model) did ZERO re-resolution — Layer 1 covered setProviderConfig
(singular) + image/video setters + the reconcile, but not this path. The
component's confirmDeleteProvider then picked Object.keys()[0] (always a
built-in, ignoring usability), the exact per-call-site hand-rolled shape
#580 condemns.

Fix at the source: setProvidersConfig now re-resolves (providerId, modelId)
via the canonical isLLMProviderConfigured + resolveSelectedModel — keep the
current provider if still usable, else first usable, else State A. Removed
the brittle confirmDeleteProvider override (kept only its local Settings-tab
selection). Now every bulk config mutation (delete, import, reset) holds the
invariant.

Tests: +2 store tests (delete selected/only-usable provider → State A, not
the deleted/invalid one; delete non-selected → keep usable selection).
94/94 store tests, full suite green (only pre-existing ssrf DNS), tsc/eslint clean.

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

* fix(settings): one shared LLM-selection resolver for all config edits (#580)

Clarified repro: the realistic case isn't deleting a custom provider — it's
clearing the SELECTED provider's API key so it becomes invalid. setProvider
Config only re-resolved when the edit made a provider *usable*; the
"became unusable" transition fell through (return base) → the now-invalid
provider stayed selected. The previous commit fixed only the bulk path.

Root-cause fix: extract one shared `resolveLLMSelection(config, providerId,
modelId)` — keep current provider if still usable, else first usable, else
State A; then resolve the model. Use it in BOTH setProviderConfig (single
edit: key add/clear, model-list edit) and setProvidersConfig (bulk: delete,
import, reset). The two paths can no longer diverge — exactly the per-call-
site asymmetry #580 set out to eliminate. Drops the now-unused
isProviderUsable import.

Tests: +2 store tests (clear selected provider key → drops stale selection;
clear non-selected key → keeps usable selection). 96/96 store tests, full
suite green except pre-existing ssrf DNS; tsc + eslint clean.

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

* style: prettier-format #580 test specs

CI 'Lint, Typecheck & Unit Tests' ran prettier . --check and failed on the
two added test specs (only tsc/eslint/vitest were run locally). Pure
whitespace reformat, no logic change — 96/96 store tests still green.

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

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-18 16:04:23 +08:00
Helck 679130a6b9 feat(ai): add Xiaomi MiMo Token Plan support (#578) 2026-05-17 15:24:30 +08:00
Yizuki_Ame 47cc2a510c feat: add Brave Search and Baidu Search integration
Add Brave Search and Baidu Search providers with Baidu sub-source support, provider configuration updates, tests, and docs links.
2026-05-13 20:28:56 +08:00
wyuc a5209d747e feat(outline-review): clickable streaming card morphs into editor (#558)
* feat: add outline review preview flow

* style: refine outline review editor

* fix(home): make draft cache survive round-trips through generation flows

The `useDraftCache` hook initialised state via `useState`'s lazy
initialiser. Under React 18+ SSR, the initialiser runs on the server
(returns `undefined` because `window` is missing), the SSR'd state is
sent to the client, and React reuses it on hydration without re-running
the initialiser. As a result `cachedValue` was always `undefined` and
nothing ever rehydrated from `localStorage`.

The home page's `prevCachedRequirement` derived-state pattern then
masked the symptom: it initialised `prev` to the same (always
undefined) `cachedRequirement`, so the comparison never fired and the
restore branch was unreachable.

Switch to an effect-based read so consumers actually receive a state
update after mount, and replace the home page's derived-state restore
with a `useEffect` + `useRef` guard that only fills the input when it
is empty. Side benefit: PBL chat draft and quiz answer caches start
working too — they used the same broken pattern.

* feat(outline-review): clickable streaming card morphs into editor + UX overhaul

Major refresh of the outline review surface introduced in #198, applying
the placement design from docs/superpowers/specs. Key shifts:

Streaming card → editor morph
- The streaming preview card in the generation-preview page is now an
  interactive surface (tilt + hover-straighten + always-visible "点击审阅"
  affordance) that morphs into the full editor via shared `layoutId`.
- SSE keeps streaming uninterrupted into the expanded editor; the editor
  consumes either `session.sceneOutlines` or live `streamingOutlines` so
  scenes appear as they arrive and stay in sync after edits.
- A header collapse button shrinks back to the preview card. Mid-stream
  collapse keeps SSE running; post-stream collapse re-arms the same 2.5s
  auto-continue timer the no-review path uses, so the card doesn't strand.

Document-style editor
- Replaces the bordered card + accordion + numbered rail with a Notion-
  feeling stack: drag handle and number share a flex left rail aligned to
  the title baseline; title/description are inline-editable borderless
  textareas with auto-resize.
- ⋮ overflow menu and explicit move-up/move-down are removed; reordering
  is drag-only, with hover-revealed delete (popover-confirmed) next to the
  type pill.
- Hover-revealed `+` insert dividers between scenes; faint `+` at the
  list edges replaces the "Add scene" bar so insertion is uniform.
- Quiz config popover redesigned: stepper for question count, segmented
  control for difficulty, multi-select pills for question types so mixed
  types from the LLM round-trip correctly (the previous single-select
  silently truncated `questionTypes` to one element).
- Streaming placeholder row pulses below the latest scene during SSE.
- Scene types use a colour-coded pill that doubles as the type switcher.

State + flow plumbing
- Adds `previewPhase: 'review'` entry from the streaming visualizer via
  `outlineReviewIntentRef`; SSE-completion ORs in this intent when
  deciding whether to wait for confirmation.
- `localStorage.removeItem('requirementDraft')` moves to after the review
  promise resolves so "Back to requirements" actually restores the draft.
- Auto-start condition broadened so refreshes during early-review
  reattach to a fresh SSE rather than stalling on an empty editor.
- Six new locales (en-US, zh-CN, zh-TW, ja-JP, ru-RU, ar-SA) for the
  expand hint, streaming progress, collapse, delete confirmation,
  insert hint, and quiz summary; locale coverage test asserts the new
  keys plus the `{{count}}` interpolation contracts.

Removed: the redundant "Review outline" button + auto-continue caption
under the preview card, since the card itself is now the entry point.
Removed: the home toolbar "Outline" tab from #198 — placement design
explicitly rejects adding another always-visible toolbar control.

* fix(outline-review): address code review feedback (PR #558)

Single follow-up commit batching the issues raised in code review:

Critical
- E2E page object's reviewOutlineButton was hunting for the removed
  "Review outline" button. Re-target it to the streaming card's
  outlineExpandHint aria-label across all six locales.

Important
- waitForOutlineReviewChoice now accepts an AbortSignal and rejects on
  abort, so goBackToHome / unmount settle the parked promise instead of
  leaking the awaiting startGeneration closure. The existing AbortError
  catch swallows the rejection cleanly.
- Add CLDR plural variants for the count-bearing strings: en gets _one;
  ru gets _one and _few for quizConfigSummary; ar gets _one and _two
  for the three count-bearing strings. Bare key remains as _other
  fallback. (zh / zh-TW / ja have a single plural form.)
- Document the mid-stream collapse intent: dropping outlineReviewIntentRef
  is deliberate so SSE-completion takes the no-review path.
- Add keyboard reorder on the drag handle (Ctrl/⌘ + ArrowUp/ArrowDown)
  with aria-keyshortcuts; replace dragScene copy with dragSceneHint that
  surfaces the shortcut. Restores WCAG 2.1.1 reachability for reorder.
- KeyPointInput no longer commits on blur — only Enter / comma. Avoids
  surprise chips when users click away mid-typing.

Minor
- Drop unused i18n keys: reviewOutlineAction, moveSceneUp/Down, dragScene,
  sceneDescriptionLabel, keyPointsLabel/Placeholder, quizConfigLabel,
  addScene. Locale coverage test pruned to match actual usage.
- requestAnimationFrame-batch useAutoResize so a burst of edits doesn't
  thrash layout (forced reflow per keystroke).
- Reset isConfirmingOutlines in the no-parked-promise fallback path of
  handleConfirmOutlines so state doesn't linger.

* chore(outline-review): prettier format + drop redundant session check

- Run prettier on outlines-editor.tsx (CI Lint job was red).
- Remove `&& session` from the StepVisualizer onExpandOutline conditional;
  `session` is guaranteed non-null at that point by the early-return guard
  above (flagged by github-code-quality bot).

* fix(home): silence react-hooks/set-state-in-effect on draft restore

Match the existing eslint-disable convention already used in
app/page.tsx for the other localStorage-hydration effects. The setState
calls are deliberate: client-side state hydration from localStorage
must happen in an effect to remain SSR-safe (the lazy useState
initialiser runs on the server with `window` undefined).

* revert(i18n): drop CLDR plural variants until key-alignment check supports them

scripts/check-i18n-keys.mjs enforces strict key equality across all
locales, which is incompatible with i18next's per-locale plural-suffix
keys (a Russian locale needs `_one`/`_few`/`_many`/`_other`, an
Arabic one adds `_two`/`_zero`, while zh / ja need none). The check
script doesn't strip plural suffixes before comparing, so any partial
pluralization breaks alignment.

Roll back the partial fix from PR review #2 and revert to the bare
keys. The original "ungrammatical for n=1" wording stays, to be
addressed in a follow-up that also teaches check-i18n-keys.mjs to
ignore CLDR plural suffixes when comparing key sets.

* fix(outline-review): make streaming card expand-hint pill actually visible

The "Tap to review" pill was rendering but invisible in practice because:
- Both the bottom white gradient (z-auto) and the pill (z-10) sit inside the
  same parent stacking context, but motion.div applies a transform that
  creates per-element stacking contexts; the implicit ordering put the
  gradient above the pill in some browsers.
- text-[9px] + bg-blue-500/95 was too thin/translucent to read against the
  white gradient even when on top.

Make stacking explicit (gradient z-0, pill z-20), bump the pill to text-[10px]
font-semibold with solid bg-blue-500, larger Maximize icon, and lift it
slightly to bottom-2 so it sits above the gradient haze.
2026-05-11 19:44:31 +08:00
Helckandxuruiray 46b61dedfd feat: add HappyHorse video adapter (#509)
Add Alibaba Cloud DashScope HappyHorse text-to-video support as an OpenMAIC video generation provider.

Co-authored-by: xuruiray <15962843+xuruiray@users.noreply.github.com>
2026-05-09 10:07:31 +08:00
be759a8252 feat: add lemonade to provider (#508)
* feat: add lemonade to provider

* fix(lemonade): correct TTS/ASR model IDs and expand Kokoro voices

- TTS model: kokoro → kokoro-v1
- ASR model: single 'whisper' → 6 Whisper variants (Base/Large-v3/Large-v3-Turbo/Medium/Small/Tiny), default Whisper-Base
- Expand lemonade-tts voices to full Kokoro v1 set (54 voices across en-US/en-GB/zh-CN/ja-JP/es/fr-FR/hi/it-IT/pt-BR)

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

* fix(lemonade): zh-TW i18n parity, real Kokoro default voice, language code consistency

- zh-TW.json: add missing providerLemonadeTTS/ASR/Image keys
- TTS default voice: 'default' → 'af_heart' (Kokoro expects real voice ID, not placeholder)
- Voice language codes: 'es'/'hi' → 'es-ES'/'hi-IN' for consistency

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

* test(lemonade): add unit tests for image/TTS/ASR adapters and wav-utils

Covers:
- lib/media/adapters/lemonade-image-adapter: request shape, base URL fallback, custom model, optional Bearer auth, error paths, connectivity probe
- lib/audio/tts-providers (lemonade-tts case): request body (model/voice/format), af_heart fallback, optional auth, error path
- lib/audio/asr-providers (lemonade-asr case): WAV-only validation, model/language form fields, "audio is empty" graceful empty result, error propagation, default model fallback
- lib/audio/wav-utils: isWavBlob detection by MIME and filename, normalizeASRUploadAudio pass-through and wav handling

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

* fix(lemonade): remove text path fork and harden fallbacks

* style: format lemonade tts files

* i18n: add lemonade voice language labels

* fix(lemonade): align image default model and harden wav detection

* test(lemonade): fix File BlobPart typing

* fix(lemonade): simplify tts voice selection and clear asr test state

* docs: highlight Lemonade support

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
2026-05-08 13:53:37 +08:00
wyuc 092762f665 fix(i18n): align zh-TW provider names 2026-05-04 08:53:52 +00:00