trending/OpenMAIC
1
0
Fork 0
mirror of https://github.com/THU-MAIC/OpenMAIC.git synced 2026-10-18 05:40:25 +08:00
Code Issues Packages Projects Releases Wiki Activity
371 Commits 294 Branches 128 Tags
@openmaic/dsl@0.5.0
Commit Graph
23 Commits
Author SHA1 Message Date
wyucandClaude Opus 5 cc95851dc5 chore(packages): publish storage and enforce version bumps (#998) 
* chore(packages): publish storage and enforce version bumps

* fix(packages): cover all publish inputs and tarballs

* fix(packages): scope version guard to release inputs

* fix(packages): fail closed on new package inputs

* docs(packages): clarify version guard boundaries

* fix(packages): harden release guard edge cases

* fix(packages): align smoke peers and git inputs

* docs(packages): make release smoke policy explicit

* fix(packages): anchor version guard at repository root

* fix(packages): report version guard setup errors

* fix(packages): harden release validation

* fix(ci): validate complete main pushes

* test(storage): pin the exported PostgreSQL schemas

DOCUMENT_PG_SCHEMA and RUNTIME_PG_SCHEMA are public API. A deployment that
provisions these tables with its own migration tooling has to reproduce the
DDL exactly for ensureDocumentSchema() / ensureSchema() to stay the intended
no-op against an already-provisioned database.

Nothing guarded that today: every statement is CREATE ... IF NOT EXISTS, so
PostgreSQL silently accepts whatever table already exists under the name. A
column type, a nullability, an index or a FK action can drift apart from a
downstream migration without an error, and the first symptom is a store query
failing in production or succeeding against the wrong types.

Pin both constants verbatim, and assert every statement stays IF NOT EXISTS
guarded so the ensure functions remain idempotent. The pin does not judge the
DDL; it makes changing it impossible to do by accident.

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

* fix(packages): gate publishing on the version check

The version check ran only in ci.yml. publish-packages.yml is a separate
workflow, so it could reach `pnpm publish` on a main push, a matching tag, or
a manual run with dry_run=false even when CI was red, skipped, or never ran.

Run the validation inside the publish job, before publishing, in a new release
mode that works for every trigger. A push range only exists for branch pushes,
so release mode judges each package against the registry instead: a version
that is not published yet is a release, and a version that is already
published is accepted only when the package source has not moved since that
release. `pnpm publish` skips an already-published version, so without that
second half a drifted package releases as a silent no-op.

The anchor for "since that release" is the @openmaic/<name>@<version> tag the
job now writes after every successful publish, falling back to the push range
for packages released before those tags existed. With neither anchor the
release stops instead of guessing.

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

* fix(packages): make the release gate prove only what it can

Three independent reviews of the previous revision converged on one root
cause: it used git tags and a push range as the record of which tree produced
a published version. Neither is trustworthy. Tags are mutable and can be
created or moved by hand, so "the tag resolves" was being read as "the tag is
authentic"; pnpm records no gitHead; and a push range describes one push, not
the origin of a release. Packages released before the scheme existed had no
anchor at all, which made the tag and manual triggers fail closed from the
first run with no way to self-heal, dry runs included.

Drop the anchor machinery. Drift is prevented where it is provable, in diff
mode at merge time, which sees every commit before it can be released. The
pre-publish gate is now limited to claims a release can establish: every
version it publishes is new and moves forward, an already-published version is
reported and left alone, and any registry answer that is not a definitive
404 stops the release.

Around it, close what the reviews found in the workflow:

- real publishes only from a commit contained in main, so a tag or manual run
  cannot ship an unreviewed ref while holding NPM_TOKEN
- one repository-wide concurrency group, so a main push and a tag push cannot
  each decide the same version is unpublished
- publish and mark each package individually, so a partial failure stays
  retryable instead of leaving published packages unrecorded
- fail if the build rewrites tracked package files, which would otherwise
  publish content that is not in the released commit
- compare against every published version when ordering, and refuse to guess
  when the registry holds versions this check cannot order

The schema pin also asserted the constants without asserting what the ensure
functions execute, so those could diverge. Both are now run against a
recording queryable and their exact statement sequence is asserted.

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

* fix(packages): refuse to release from a tree behind the registry

Simplifying the gate introduced a hole that a mutation check caught: a package
whose local version is already published took the "already published, skip"
path before any ordering check, so a tree rolled back to an older published
version passed silently. That is not a harmless no-op, because pnpm publish
rewrites each workspace dependency to the version in the tree, and a sibling
released alongside it would be published declaring a dependency on the older
package.

Order every package against the registry first, then decide: at the highest
published version it is a legitimate skip, below it the release stops.

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

* fix(packages): couple publishing to a green CI run for the same commit

Second review round, on the reworked design. The headline defect was a hard
blocker: `git fetch --depth=0` is not valid git (that is an actions/checkout
convention), so under `set -e` every real publish aborted before the gate ever
ran. Remove the depth argument; the checkout already has full history.

The rest closes the gap both reviewers reached independently, that being on
main is not the same as having passed the gate:

- wait for this exact commit's CI conclusion and require success. ci.yml runs
  concurrently with this workflow on a push to main and blocks nothing, so an
  unpublished version whose source drifted could be released while its own
  version check was still running or already red.
- require the commit on main's FIRST-PARENT history. Plain reachability also
  accepts every intermediate commit of every branch merged with a merge commit.
  A pull request that adds a bad tree and reverts it in the next commit leaves
  that tree an ancestor of main forever, and a tag pointing at it published it.
- do not cancel CI runs on main. Each run validates only its own push range, so
  cancelling one drops the range that contained the change, and its replacement
  compares against the cancelled tip and sees nothing.
- run the version check on every main push. A branch creation or force push
  reports an unusable `before`, which used to skip the gate entirely; fall back
  to the first parent instead.
- publish with --ignore-scripts. Every package's prepublishOnly reruns the
  build, deleting and regenerating the dist that was just verified and
  smoke-tested, so npm could receive bytes nothing had checked.
- run storage's PostgreSQL contract suites before publishing it. They skip
  themselves without a database, so the one backend that needs a real
  PostgreSQL was shipping unexercised.
- order registry versions with real semver, prereleases included. Rejecting
  every non-x.y.z version meant one historical prerelease anywhere in one
  package's history would refuse every future release of every package.
- warn when a release marker exists but points at another commit.

Note what is NOT enforceable here: a workflow_dispatch or tag run executes the
workflow definition from the selected ref, so a branch that edits this file can
delete these checks. The boundary has to be a GitHub Environment holding
NPM_TOKEN behind a main-only deployment branch rule. The job now declares that
environment and the header states the required setup; the in-file checks are
defence in depth.

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

* fix(packages): stop the first-parent check failing on SIGPIPE

Third review round. The blocker this time: `git rev-list --first-parent | grep
-qx` under `set -o pipefail`. grep exits at the first match, rev-list then dies
of SIGPIPE, and the pipeline returns 141, so a commit that IS on main is read
as "not on main" and every real publish is refused. It does not reproduce in a
shallow clone, where main's history fits in the pipe buffer; with the full
history this job checks out it always will. Count matches instead, which reads
the whole stream.

Also from this round:

- identify the CI run by workflow file and triggering event rather than by a
  check-run display name. Names are not unique, so any other workflow or app
  publishing a check called "Lint, Typecheck & Unit Tests" could stand in for a
  red version gate.
- fail the main-push version check when the push range is unusable instead of
  substituting HEAD^. A force push can replace many commits at once, so the
  previous commit is not the range that needs checking, and a green run here is
  what publishing depends on.
- correct the stated limitation. It claimed the package-directory input model
  was exact for dsl and storage; it is not. Their dist is whatever the
  lockfile's TypeScript emits, and dsl's shipped JSON schema comes from the
  lockfile's ts-json-schema-generator, so a toolchain bump can change any of the
  four tarballs with no diff under the package directory.

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

* refactor(packages): make a merged version bump the only release input

The tag trigger was incoherent. Its own documentation admitted that any
@openmaic/* tag republishes the whole family and that which packages actually
go out is decided by the manifests, so the tag name never participated in the
decision. It was a second entry point to one decision function, it bypassed
review entirely because a tag is not a diff and can be created by anyone with
write access on any commit, and it cannot be guarded: environment deployment
rules match GITHUB_REF, so refs/tags/* and a main-only rule are mutually
exclusive.

Drop it. A version bump that landed on main is now the only release input, and
`@openmaic/<name>@<version>` tags are an output written after a package
reaches the registry. Nothing is lost: a manual dispatch from main still
republishes without a new commit, and that path is inside the protected
environment.

Split the workflow so the token has a boundary. `validate` holds everything
that does not need NPM_TOKEN and runs from any ref, which keeps dry runs
useful to contributors. `publish` is the only job declaring the `release`
environment, so the token is never attached to a run that is merely
validating. It rebuilds rather than sharing state, which is the right trade
for a release.

Also add the `actions: read` permission the CI-conclusion query needs; it was
switched from the checks API to the Actions API without updating the scope,
which would have failed with 403 on every real publish.

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

* docs(contributing): explain when a package version must be bumped

CONTRIBUTING said nothing about versioning or releases, while this branch adds
a CI check that fails a contributor's PR with "publishable package inputs
changed but version did not increase". A gate that rejects work without
telling anyone the rule is the kind that ends up disabled.

State the rule, the exact failure message, which files are exempt, and how to
choose the number, with a specific warning for @openmaic/dsl: it is the
contract the other packages validate against, so narrowing what an existing
document may contain is breaking even when the diff is small.

Also state what contributors do NOT do: publishing is automatic once a bump
lands on main, and the release tag is a marker written afterwards rather than
something to push.

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

* fix(packages): run renderer's tests before publishing renderer

The pre-publish gate ran renderer's typecheck but never its test suite, so the
one package whose behaviour is hardest to typecheck was the one shipping
unexercised. It has 25 test files and 242 tests; they just were not in the
filter list.

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

* fix(packages): keep the git credential away from package code

Review finding: the publish job held `contents: write` while
actions/checkout had persisted that credential, and it then ran
`pnpm install` and the package builds. Any dependency or build script
executed with a credentialed git remote in reach and a write scope to use
it, which is a wider blast radius than publishing needs.

Separate the two capabilities so no job holds both:

- `validate` and `publish` run package code. Both now check out with
  `persist-credentials: false`, `validate` is pinned to `contents: read`,
  and `publish` drops write scope entirely, keeping only the `actions: read`
  it needs for the CI conclusion and `id-token: write` for provenance.
- a new `mark` job is the only holder of `contents: write` and a git
  credential, and it installs nothing and builds nothing.

`mark` also reconciles instead of only recording this run. A marker whose
push failed previously could never be repaired before, because the release
plan excludes versions already on the registry and the marker logic sat
behind that plan. It now marks any registry version whose tag is missing,
and leaves an existing tag alone rather than moving it.

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

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-07-29 23:54:23 -04:00
wyuc c923e50e4a ci: retire the completed document-server-backend trunk from the PR whitelists (#981) 2026-07-25 00:35:49 -04:00
wyucandCodex 5cef056d17 feat(storage): server-backed documents — HTTP contract, Postgres backend, one reference server for both stores (#979) 
* ci: whitelist the document-server-backend integration trunk

* feat(storage): DocumentStore HTTP contract + client + reference-server routes (1B PR1) (#975)

Mirrors the runtime line's server-backed delivery for the document store:
a documented /documents HTTP contract (validation/not-found/FUTURE_VERSION
taxonomy; authorization stays a deployment concern via injected hooks with
an any-authenticated default), an HttpDocumentStore that runs the same
validators and migrate-on-read semantics as the browser backend before and
after the wire, and document routes on the shared reference server — one
server, both stores. The backend-agnostic document contract suite now runs
against HTTP → reference server → browser store.

Co-authored-by: Codex <codex@openai.com>

* ci: whitelist the trunk in the storage PG contract workflow too

* feat(storage): PgDocumentStore — Postgres document backend (1B PR2) (#976)

Implements the full DocumentStore contract over document_stages /
document_scenes / document_outlines, reusing the pure adapter split so
every backend shares one aggregate semantics: saveDocument replaces the
aggregate in one transaction under the stage row's FOR UPDATE lock
(vanished scenes deleted, outline row added/removed — omission means
deletion), incremental putStage/putScene/deleteScene take the same
current-version gate as the browser backend, loads read FOR SHARE and
migrate without writing back, listings never touch content, and deletes
cascade by FK. The document contract suite is PG-gated the same way the
runtime one is; local coverage comes from stubbed-queryable unit tests.

Co-authored-by: Codex <codex@openai.com>

* feat(document-store): sealed bootstrap injection seam for the document backend (1B PR3) (#977)

configureDocumentStorage mirrors the runtime seam: module-level bootstrap
injection sealed after first resolution, a factory that receives the app
validators so a server-backed store cannot silently skip them, and
reset-for-tests wiring. A deployment swaps the browser document backend
for HttpDocumentStore without touching app code. Storage README roadmap
updated — the document HTTP/PG backend items are done.

Co-authored-by: Codex <codex@openai.com>

* fix(storage): 1B final-review hardening — error classification, JSON-safety, body limits, parity coverage (#978)

Unversioned legacy incremental writes classify as 400 instead of leaking a
500; document/scene reads assert JSON safety before serialization so a
structured-clone value fails loud (500 NOT_JSON_SAFE naming the path)
instead of silently converting; a shared streaming body reader bounds
request bodies (default 32 MiB, 413 PAYLOAD_TOO_LARGE, option exposed
through every handler factory); the putStage stale/future guards and
corrupt-stamp listing tolerance move into the shared contract suite so all
four backends prove them; both HTTP store errors retain structured details.

Co-authored-by: Codex <codex@openai.com>

* refactor(storage): typed document version/not-found errors replace prose classification (#980)

DocumentVersionError (future | not-current, storedVersion) and
DocumentNotFoundError now carry the classification the server previously
regex-derived from message prose — instanceof matching mirrors the runtime
sibling's RuntimeAppendConflictError pattern, so a wording change can no
longer silently break status mapping. The prose fallback remains, after
the typed checks, solely for third-party DocumentStore implementations.
The HTTP client rematerializes 409s as DocumentVersionError for symmetry,
and http.ts's private validator fields are renamed to match the public
option names all three backends already share.

Co-authored-by: Codex <codex@openai.com>

---------

Co-authored-by: Codex <codex@openai.com>
 2026-07-23 12:56:26 +08:00
wyucCodexClaude Fable 5
 		d0d227424b feat(document): complete the document-persistence cutover — stage/scene/outline onto DocumentStore (#965) 
* feat(runtime): persist quiz attempts in RuntimeStore

* fix(runtime): coalesce quiz draft snapshots

* fix(runtime): recover concurrent quiz attempts

* fix(runtime): handle quiz completion races

* fix(runtime): commit quiz review atomically

* fix(runtime): dedupe concurrent quiz writes

* fix(runtime): drop stale quiz drafts

* fix: harden quiz runtime review recovery

* fix: serialize quiz attempt identity

* feat: read quiz state from runtime store

* fix: persist quiz retries before resetting

* fix: preserve authoritative quiz outcomes

* fix: preserve legacy quiz retries during cutover

* fix: reconcile legacy quiz snapshots safely

* fix: drain rollover quiz write queues

* fix: drain completed quiz retry queues

* fix: reuse concurrent quiz retries

* fix(quiz): preserve drafts across abrupt reloads

* fix(quiz): recover empty retry sessions

* fix(chat): abort stalled runtime state reads

* fix(quiz): expose queued phases to readers

* fix(quiz): retain concurrent writer tails

* fix(quiz): canonicalize retry branches

* fix(quiz): keep retry rollovers monotonic

* fix(quiz): validate skipped retry siblings

* fix(quiz): close read cutover races

* test(classroom): cover legacy quiz summaries

* fix(quiz): reset async consumers on scene changes

* fix(quiz): close scene transition windows

* test(pbl): cover launch freshness guards

* fix(quiz): close cutover concurrency gaps

* fix(quiz): harden retry and context freshness

* fix(quiz): reject malformed legacy answers

* fix(quiz): validate legacy answer values

* test(quiz): cover legacy multi-answer migration

* fix(merge): retire dead ChatRequestTemplate.storeState after quiz read cutover

Main's three call sites built static storeState blocks that runAgentLoopFn
never consumed (it always rebuilds fresh state via getStoreState); the quiz
read cutover replaced that callback with the async two-phase RuntimeStore
read, leaving the template field with zero consumers. Drop it.

* feat(storage): conform HTTP/PG backends and reference server to RuntimeAppendOptions

The quiz write path's expectedLastSeq / sessionTransition / RuntimeAppendConflictError
semantics existed only in the browser backend; server-backed deployments would
silently accept conflicting appends and leave completed sessions active. Forward
the options over the wire, detect conflicts atomically under the PG transaction,
map them to HTTP 409 RUNTIME_APPEND_CONFLICT, and rematerialize the typed error
client-side so quiz retry logic works across every backend.

Co-authored-by: Codex <codex@openai.com>

* fix(chat): Pi single requests build storeState via the async runtime quiz read

Pi bypasses runAgentLoop's per-iteration getStoreState and serializes the
request template straight to /api/chat/pi, which rejects bodies without
storeState. Extract the fresh-snapshot builder (async RuntimeStore quiz read
with the scene-transition guard) and call it on the Pi path too.

* ci: whitelist the runtime-data-cutover integration trunk for PR checks

* feat(runtime): playback cutover — cursor in KV, discussion facts in RuntimeStore (#956)

* feat(runtime): cut playback over to the runtime layer — cursor in KV, facts in RuntimeStore (#869)

The fourth and last runtime family. Consumed-discussion facts become
append-only 'playback' records folded into a set at read (at-least-once
appends, no conflict machinery); the resume cursor is device-scoped
last-write-wins KV per the amended #779/#869 split. sessionStorage keeps
same-tab priority; KV takes over on fresh tabs/reloads. The dead Dexie
playbackState machinery is retired, with a one-time lazy migration of any
legacy row (cursor half + facts half) before deletion, and stage deletion
now clears both the KV cursor and any unmigrated legacy row.

Co-authored-by: Codex <codex@openai.com>

* test(runtime): include playbackState in the stage-delete db mock

---------

Co-authored-by: Codex <codex@openai.com>

* fix(playback): persist discussion facts on every consumption path (#957)

* fix(playback): persist discussion facts on every consumption path (final-review P0+P1s)

- The engine now publishes a progress snapshot the moment a discussion is
  consumed (join / skip / unselected-agent auto-skip). onProgress otherwise
  fires before the discussion action executes and a discussion is the scene's
  last action, so the fact never reached persistence.
- Reads fold records across ALL playback sessions in the learner partition
  (mergeLearner deliberately preserves same-kind sessions from both keys).
- Legacy migration appends only not-yet-durable facts, so an interrupted
  migration resumes instead of dropping the tail.
- recordConsumedDiscussion reports durability; the component drops failed ids
  from its observed set so a later progress tick retries (at-least-once).

* test(e2e): live verification of the playback persistence chain

Seeds a deterministic stage straight into the Dexie DB, starts the lecture
via the canvas overlay, and asserts the full chain: discussion auto-skip
appends a discussionConsumed record to maic-runtime, the device cursor lands
in KV, and both survive a fresh browsing context (empty sessionStorage).

* refactor(playback): consumed-discussion state is volatile by decision — cursor-only persistence (#959)

Product ruling on #869's fourth family: playback learner state is front-end
ephemeral UX, not learner data. A re-shown proactive card auto-skips, joined
discussions' content already lives in chat runtime records, and no replay
export / analytics consumer exists — so durable facts bought nothing over
in-memory + same-tab sessionStorage. Drop lib/playback/runtime.ts and the
RuntimeStore facts wiring; keep the device-scoped KV resume cursor (the half
with real UX value), the engine's consumption-time progress snapshot (cursor
freshness), and the legacy Dexie retirement (cursor half migrates, row
deletes, consumed ids are dropped).

* ci: whitelist the document-cutover integration trunk for PR checks

* feat(document): widened-stage contracts + app document seam (#860 follow-up, PR1) (#961)

Package: MaicDocument/DocumentStore/StageRow gain a TStage parameter
(defaults keep existing users unchanged), BrowserDocumentStore accepts an
injectable validateStage, and a version-guarded putStage closes the rename
read-modify-write race — same current-version gate as putScene.

App: lib/document/ seam — AppDocument types (currentSceneId is device
state, not document data, and the app stage validator rejects it), a
four-kind scene validator (slide/quiz delegate to the DSL; interactive/pbl
validate envelope + discriminant binding only), and pure legacy
canonicalizers (type rebound from content.type, singular whiteboard →
whiteboards, outline envelope). No consumer switches off Dexie yet.

Co-authored-by: Codex <codex@openai.com>

* feat(document): stage-storage cutover + locked lazy migration (PR2) (#962)

* feat(document): cut stage/scene persistence over to DocumentStore with locked lazy migration (PR2)

stage-storage now persists through the lib/document seam: aggregate
saveDocument with a mandatory outline envelope (omission means deletion in
the contract; ordinary saves fall back to the stored envelope), lazy
per-stage migration under a Web Lock (destination authoritative, one
coherent legacy snapshot, save-verify-marker, legacy rows retained
read-only; no-lock environments read legacy without migrating),
currentSceneId in device KV, rename via version-guarded putStage, and a
list that merges legacy-only stages until they migrate. stageOutlines'
second write authority folds into the document service, making the final
scene set and generationComplete one atomic commit.

Co-authored-by: Codex <codex@openai.com>

* fix(document-store): relocate the persistence seam out of lib/document

lib/document/ is the server-side content-extraction domain (sharp, cloud
SDKs); exporting the persistence seam from its barrel dragged node-only
modules into the client bundle and broke the Turbopack build. The seam now
lives in lib/document-store/ with its own barrel, and the extraction barrel
is restored. Client-only guards become capability probes (indexedDB /
localStorage presence) so injected node test environments keep working
while a true server render still fails loud.

* fix(document-store): no-lock write classification + lock-order inversion (PR2 fix round)

Lock order is now per-stage document lock → global runtime epoch (a save
never waits on a document lock while occupying the shared epoch, which
deadlocked against fair-queued maintenance). Without Web Locks, mutation
classifies instead of refusing wholesale: destination-backed and genuinely
new documents accept the product's established lock-free/LWW risk, while a
legacy-only document stays read-only so two authorities cannot fork —
matching the chat-cutover-era acceptance suite, whose save assertions now
verify through the public API instead of legacy Dexie rows.

Co-authored-by: Codex <codex@openai.com>

* style: prettier on document-store seam files

---------

Co-authored-by: Codex <codex@openai.com>

* feat(document): cut secondary consumers over to the document seam (PR3) (#963)

ZIP classroom/video exports read stage metadata through the seam; classroom
import builds one canonical aggregate under the per-stage lock and writes
canonical 'whiteboards' (fixing the import-side singular-alias defect the
manifest never had); backups become versioned document aggregates that
finally include outline envelopes, while old {stages, scenes} backups are
accepted through the legacy canonicalizers; clearDatabase now clears
maic-documents and the seam's KV keys so clear-cache cannot strand
documents; deleteStageWithRelatedData is deprecated in favor of
deleteStageData. Four e2e seeders target maic-documents directly;
classroom-interaction stays legacy-seeded to exercise real-UI lazy
migration.

Co-authored-by: Codex <codex@openai.com>

* fix(document): final-review hardening — restore pre-images, honest markers, clear-race exclusion (3 P1 + 2 P2) (#964)

- Backup rollback restores pre-existing destination documents (and imported
  current-scene KV values) from captured pre-images instead of deleting them
- The skip-migration path only writes its marker after reconciling the
  legacy snapshot against the authoritative destination; a divergent
  snapshot logs and stays discoverable instead of being falsely certified
- Migration's destination write enrolls in the global shared storage epoch
  (per-stage -> global order), so clearDatabase's exclusive epoch can no
  longer race a lazy migration into resurrecting a document
- listStages drops legacy entries whose snapshot vanished mid-merge

Co-authored-by: Codex <codex@openai.com>

* fix(review): P3 pair from cross-review — scene-id boundary + sessionTransition 400 (#966)

* fix(review): scene-id boundary for quiz context + 4xx for malformed sessionTransition (P3 pair)

Review findings on #955: didActiveSceneRemainUnchanged compared the active
scene by object identity, so a store update reallocating the scene during
the async quiz read dropped the learner's graded answers from that turn's
request — the scene id is the real boundary. The records route now
classifies a malformed sessionTransition as a validation failure instead of
letting the store's throw surface as a 500.

* fix(playback): superseded-engine cursor guard + migration write-window recheck

Second-vendor review of the #959 shrink (requested after the cross-review
noted it had single-vendor coverage) found: an engine orphaned by a scene
switch during async lecture resume could pass the idle-only recheck, be
resurrected, and publish its old scene's progress over the new scene's
debounced cursor — the resume continuation now requires identity with the
installed engine, and onProgress drops snapshots from superseded engines.
The legacy cursor migration also rechecks KV immediately before its write
so a concurrent tab's newer cursor cannot be overwritten and orphaned by
the legacy-row delete.

Co-authored-by: Codex <codex@openai.com>

---------

Co-authored-by: Codex <codex@openai.com>

* fix(review): approval follow-up P3 nits (#967)

* release: v0.3.1

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

* fix(review): approval P3 nits — ISO gate on sessionTransition, dead mocks, corrupt-timestamp guard

- The records route's sessionTransition guard now requires an ISO
  updatedAt (isIsoTimestamp), matching the sibling PATCH /status route
- Dead vi.mock factories for the deleted playback-storage module dropped
- A corrupt legacy playback timestamp falls back to 'now' instead of
  wedging migration into a permanent re-throw that disabled resume

---------

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

* fix(document): backup covers no-lock legacy courses; clears fence stale saves (review P1s) (#968)

Backup assembly appends read-only canonicalized aggregates for legacy-only
stages the lazy migration could not persist (no-Web-Locks environments) —
courses visible in the app can no longer vanish from an export. A
device-scoped storage generation now fences document mutations: clears bump
it inside their exclusive section, and any save or migration commit that
entered before the clear re-reads it inside the shared epoch and fails loud
instead of repopulating a wiped store.

Co-authored-by: Codex <codex@openai.com>

* fix(document): review round 2 — legacy-only chat backup coverage + full-width generation fence (#972)

Backups now enumerate runtime chat sessions for every exported document,
not just store-backed ones — a legacy-only course's chat history (the chat
and document cutovers are independent seams) no longer drops out of the
export; the runtime read injects an empty legacy chat store since legacy
rows are collected by direct table reads, which also keeps the export
working without Web Locks. The storage-generation fence now guards every
mutating store method, with the exclusive-epoch delete cascades passing
storageSharedLockHeld so the guard cannot self-deadlock against their own
hold.

---------

Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
 2026-07-22 23:18:24 +08:00
wyucClaude Fable 5Codex
 		3eea9dc542 feat(runtime): complete the #869 learner-data cutover — quiz + playback onto RuntimeStore (#955) 
* feat(runtime): persist quiz attempts in RuntimeStore

* fix(runtime): coalesce quiz draft snapshots

* fix(runtime): recover concurrent quiz attempts

* fix(runtime): handle quiz completion races

* fix(runtime): commit quiz review atomically

* fix(runtime): dedupe concurrent quiz writes

* fix(runtime): drop stale quiz drafts

* fix: harden quiz runtime review recovery

* fix: serialize quiz attempt identity

* feat: read quiz state from runtime store

* fix: persist quiz retries before resetting

* fix: preserve authoritative quiz outcomes

* fix: preserve legacy quiz retries during cutover

* fix: reconcile legacy quiz snapshots safely

* fix: drain rollover quiz write queues

* fix: drain completed quiz retry queues

* fix: reuse concurrent quiz retries

* fix(quiz): preserve drafts across abrupt reloads

* fix(quiz): recover empty retry sessions

* fix(chat): abort stalled runtime state reads

* fix(quiz): expose queued phases to readers

* fix(quiz): retain concurrent writer tails

* fix(quiz): canonicalize retry branches

* fix(quiz): keep retry rollovers monotonic

* fix(quiz): validate skipped retry siblings

* fix(quiz): close read cutover races

* test(classroom): cover legacy quiz summaries

* fix(quiz): reset async consumers on scene changes

* fix(quiz): close scene transition windows

* test(pbl): cover launch freshness guards

* fix(quiz): close cutover concurrency gaps

* fix(quiz): harden retry and context freshness

* fix(quiz): reject malformed legacy answers

* fix(quiz): validate legacy answer values

* test(quiz): cover legacy multi-answer migration

* fix(merge): retire dead ChatRequestTemplate.storeState after quiz read cutover

Main's three call sites built static storeState blocks that runAgentLoopFn
never consumed (it always rebuilds fresh state via getStoreState); the quiz
read cutover replaced that callback with the async two-phase RuntimeStore
read, leaving the template field with zero consumers. Drop it.

* feat(storage): conform HTTP/PG backends and reference server to RuntimeAppendOptions

The quiz write path's expectedLastSeq / sessionTransition / RuntimeAppendConflictError
semantics existed only in the browser backend; server-backed deployments would
silently accept conflicting appends and leave completed sessions active. Forward
the options over the wire, detect conflicts atomically under the PG transaction,
map them to HTTP 409 RUNTIME_APPEND_CONFLICT, and rematerialize the typed error
client-side so quiz retry logic works across every backend.

Co-authored-by: Codex <codex@openai.com>

* fix(chat): Pi single requests build storeState via the async runtime quiz read

Pi bypasses runAgentLoop's per-iteration getStoreState and serializes the
request template straight to /api/chat/pi, which rejects bodies without
storeState. Extract the fresh-snapshot builder (async RuntimeStore quiz read
with the scene-transition guard) and call it on the Pi path too.

* ci: whitelist the runtime-data-cutover integration trunk for PR checks

* feat(runtime): playback cutover — cursor in KV, discussion facts in RuntimeStore (#956)

* feat(runtime): cut playback over to the runtime layer — cursor in KV, facts in RuntimeStore (#869)

The fourth and last runtime family. Consumed-discussion facts become
append-only 'playback' records folded into a set at read (at-least-once
appends, no conflict machinery); the resume cursor is device-scoped
last-write-wins KV per the amended #779/#869 split. sessionStorage keeps
same-tab priority; KV takes over on fresh tabs/reloads. The dead Dexie
playbackState machinery is retired, with a one-time lazy migration of any
legacy row (cursor half + facts half) before deletion, and stage deletion
now clears both the KV cursor and any unmigrated legacy row.

Co-authored-by: Codex <codex@openai.com>

* test(runtime): include playbackState in the stage-delete db mock

---------

Co-authored-by: Codex <codex@openai.com>

* fix(playback): persist discussion facts on every consumption path (#957)

* fix(playback): persist discussion facts on every consumption path (final-review P0+P1s)

- The engine now publishes a progress snapshot the moment a discussion is
  consumed (join / skip / unselected-agent auto-skip). onProgress otherwise
  fires before the discussion action executes and a discussion is the scene's
  last action, so the fact never reached persistence.
- Reads fold records across ALL playback sessions in the learner partition
  (mergeLearner deliberately preserves same-kind sessions from both keys).
- Legacy migration appends only not-yet-durable facts, so an interrupted
  migration resumes instead of dropping the tail.
- recordConsumedDiscussion reports durability; the component drops failed ids
  from its observed set so a later progress tick retries (at-least-once).

* test(e2e): live verification of the playback persistence chain

Seeds a deterministic stage straight into the Dexie DB, starts the lecture
via the canvas overlay, and asserts the full chain: discussion auto-skip
appends a discussionConsumed record to maic-runtime, the device cursor lands
in KV, and both survive a fresh browsing context (empty sessionStorage).

* refactor(playback): consumed-discussion state is volatile by decision — cursor-only persistence (#959)

Product ruling on #869's fourth family: playback learner state is front-end
ephemeral UX, not learner data. A re-shown proactive card auto-skips, joined
discussions' content already lives in chat runtime records, and no replay
export / analytics consumer exists — so durable facts bought nothing over
in-memory + same-tab sessionStorage. Drop lib/playback/runtime.ts and the
RuntimeStore facts wiring; keep the device-scoped KV resume cursor (the half
with real UX value), the engine's consumption-time progress snapshot (cursor
freshness), and the legacy Dexie retirement (cursor half migrates, row
deletes, consumed ids are dropped).

* fix(review): P3 pair from cross-review — scene-id boundary + sessionTransition 400 (#966)

* fix(review): scene-id boundary for quiz context + 4xx for malformed sessionTransition (P3 pair)

Review findings on #955: didActiveSceneRemainUnchanged compared the active
scene by object identity, so a store update reallocating the scene during
the async quiz read dropped the learner's graded answers from that turn's
request — the scene id is the real boundary. The records route now
classifies a malformed sessionTransition as a validation failure instead of
letting the store's throw surface as a 500.

* fix(playback): superseded-engine cursor guard + migration write-window recheck

Second-vendor review of the #959 shrink (requested after the cross-review
noted it had single-vendor coverage) found: an engine orphaned by a scene
switch during async lecture resume could pass the idle-only recheck, be
resurrected, and publish its old scene's progress over the new scene's
debounced cursor — the resume continuation now requires identity with the
installed engine, and onProgress drops snapshots from superseded engines.
The legacy cursor migration also rechecks KV immediately before its write
so a concurrent tab's newer cursor cannot be overwritten and orphaned by
the legacy-row delete.

Co-authored-by: Codex <codex@openai.com>

---------

Co-authored-by: Codex <codex@openai.com>

* fix(review): approval follow-up P3 nits (#967)

* release: v0.3.1

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

* fix(review): approval P3 nits — ISO gate on sessionTransition, dead mocks, corrupt-timestamp guard

- The records route's sessionTransition guard now requires an ISO
  updatedAt (isIsoTimestamp), matching the sibling PATCH /status route
- Dead vi.mock factories for the deleted playback-storage module dropped
- A corrupt legacy playback timestamp falls back to 'now' instead of
  wedging migration into a permanent re-throw that disabled resume

---------

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

---------

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Address the two remaining round-3 P1 boundary blockers.

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

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

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

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

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-07-20 11:28:34 +08:00
wyuc 34448beb6c feat(storage): server-backed runtime — pluggable backend seam, HTTP contract, Postgres backend, reference server (#939) (#946) 
* ci: run PR checks against the runtime-server-backend integration branch (#939)

* feat(storage): RuntimeStore HTTP contract + HttpRuntimeStore client (#939 Part B) (#940)

* feat(storage): RuntimeStore HTTP contract + HttpRuntimeStore client (#939 Part B)

- documented JSON HTTP contract for every RuntimeStore operation
  (server-assigned seq, learnerKey derived from auth — never trusted
  from the request, machine-readable error codes, idempotency notes)
- HttpRuntimeStore client with injected fetch + auth headers hook;
  session reads (including createSession responses) migrate forward
  on the runtime line so an older server cannot leak stale envelopes
- conformance test server bridging the contract onto the browser
  backend; full runRuntimeStoreContract green over HTTP plus error
  mapping cases

* fix(storage): harden HTTP runtime backend after cross-review (#939 Part B)

Cross-review fixes:
- appendRecord gates payloads through assertJsonValue: fail loud on
  values JSON cannot represent (Map, Date, NaN, nested undefined, NUL
  strings) instead of silently mangling them in transit; payload
  domain documented in the contract
- appendRecord/listRecords responses validate via validateRuntimeRecord
  (server-assigned seq is no longer trusted verbatim) and listRecords
  sorts by seq like listSessions already sorted defensively
- request headers no longer require an ambient Headers constructor
  when fetch is injected
- conformance server classifies errors structurally (existence checks,
  DSL validators, version stamps) instead of regex-sniffing messages
  that interpolate caller-controlled ids
- router preserves empty path segments so empty-key calls keep browser
  no-op semantics instead of shifting onto other routes
- stray runtimeDslVersion/seq in request bodies are ignored (store-
  assigned wins), matching the browser reference; docs updated
- loopback integration test exercises the real listening server
- docs state the conformance server is test-only; auth-derived
  learnerKey is Part D's reference server

* fix(storage): round-2 cross-review hardening for the HTTP backend (#939 Part B)

- json-value guard rewritten: additionally rejects -0, symbol-keyed and
  non-enumerable own properties, and non-index own properties on arrays;
  U+2028/U+2029 are accepted again (they round-trip through JSON per
  RFC 8259 — rejecting them lost legitimate pasted text)
- conformance server classifies racing duplicate creates as 409 via a
  structural post-check, gates payloads and merge learner keys as 400
- segment() rejects '.'/'..' ids the URL layer would fold away
- list responses must be arrays and mergeLearner's moved must be a
  finite number, else a typed MALFORMED_RESPONSE error

* fix(storage): round-3 cross-review hardening for the HTTP backend (#939 Part B)

- json-value guard: NUL is rejected in object keys too, and unpaired
  UTF-16 surrogates are rejected in string values and keys (jsonb
  refuses both; other JSON stacks corrupt lone surrogates to U+FFFD)
- typed storage errors survive non-object 200 responses instead of
  degrading into TypeErrors on .id access
- mergeLearner's moved must be a non-negative integer
- conformance server classifies missing/non-object request bodies as
  400 VALIDATION_FAILED
- createSession/appendRecord gate the full init envelope, not only the
  payload (stray Date/undefined properties, NUL in ids)

* fix(storage): round-4 convergence fixes for the HTTP backend (#939 Part B)

- envelope JSON gate tolerates explicitly-undefined optional anchors
  (sceneId: undefined behaves like omission, matching the browser)
- body-carried identifiers reject '.'/'..' so nothing persists that
  the URL layer cannot later address; conformance server mirrors it
- mergeLearner keys pass the JSON-domain gate on client and server
- json-value guard v4: rejects enumerable accessors (validation/serialize
  TOCTOU), Array subclasses and null-proto arrays, prototype-supplied
  array indices; sparse-array test now constructs a genuine hole

* fix(storage): round-5 convergence fixes for the HTTP backend (#939 Part B)

- undefined-stripping is limited to the DSL-declared optional anchors
  (sceneId/actionIndex/subAnchor); any other undefined member fails the
  JSON gate loud instead of being dropped silently
- json-value guard: array and object prototype checks are realm-agnostic
  (chain-shape instead of identity), so ordinary values from another
  realm are accepted while subclasses stay rejected; shared
  isLosslessJsonString predicate exported for SQL key guards
- conformance server merge route validates target-key addressability

* fix(storage): close the toJSON prototype channel in the JSON guard (#939)

toJSON is the single channel through which a prototype can alter JSON
output — prototype properties never serialize and own accessors are
already rejected — so refusing any value with a callable toJSON closes
prototype influence on serialization entirely, including prototypes
crafted to pass the realm-agnostic chain-shape check.

* fix(storage): probe toJSON via descriptor walk, not property read (#939)

Reading value.toJSON would execute an inherited accessor, letting a
stateful getter hide from validation and reappear at stringify time.
The probe now walks own descriptors up the prototype chain without
invoking any user code. Post-validation mutation of the caller's object
graph is documented as out of scope — it is equally unpreventable for
every other validated property.

* fix(storage): toJSON probe mirrors JSON.stringify semantics exactly (#939)

The own-most descriptor decides: absent is safe, a non-callable data
value is an ordinary shadowing member and is safe, a callable data
value is rejected, and an accessor is rejected because it cannot be
inspected without invoking it. No daylight remains between the guard
and the serializer on this property.

* feat(storage): PgRuntimeStore — Postgres runtime backend (#939 Part C) (#941)

* feat(storage): PgRuntimeStore — Postgres runtime backend over an injected queryable (#939 Part C)

- PgRuntimeStore implements RuntimeStore over a minimal injected
  Queryable (node-postgres and PGlite both satisfy it) — the package
  keeps zero runtime dependencies beyond @openmaic/dsl
- runtime_sessions / runtime_records schema exported as
  RUNTIME_PG_SCHEMA with idempotent ensureSchema()
- appends serialize per session via a session-row lock; MAX(seq)+1
  and the insert share one transaction, UNIQUE(session_id, seq) plus
  bounded retry backstop non-cooperating writers
- envelope semantics mirror the browser backend: version stamping,
  validation gates, migrate-on-read, fail-loud on future-stamped rows
- full runRuntimeStoreContract green on PGlite plus PG-specific cases
  (concurrent-append seq atomicity, ensureSchema and mergeLearner
  idempotence)

* fix(storage): require pinned transactions + JSON payload gate in PG backend (#939 Part C)

Cross-review fixes:
- withTransaction is now required; the BEGIN/COMMIT fallback is removed
  (on a pg Pool it spread BEGIN/body/COMMIT across different connections
  — no real transaction, leaked idle-in-transaction clients, broken
  mergeLearner atomicity; on a shared pinned client concurrent calls
  interleaved transactions)
- single-statement deletes no longer wrap in a transaction hook call
- appendRecord gates payloads through assertJsonValue: fail loud on
  values JSON cannot represent (Map, Date, NaN, nested undefined, NUL
  strings) instead of silently persisting something different
- append retry also covers 40001/40P01; READ COMMITTED assumption
  documented at the retry loop
- ensureSchema documented as create-only; redundant stage index dropped
- deterministic interleaving test proves the 23505 retry path; real
  PostgreSQL contract lane added (postgres:16 service workflow, pg
  driver suite skipped locally without PG_CONTRACT_URL)

* fix(storage): round-2 cross-review hardening for the PG backend (#939 Part C)

- json-value guard rewritten (shared with the HTTP backend): additionally
  rejects -0, symbol-keyed and non-enumerable own properties, and
  non-index own properties on arrays; accepts U+2028/U+2029
- storage-pg-contract workflow now triggers for the runtime-server-backend
  integration branch and fails loud (STORAGE_PG_CONTRACT_REQUIRED=1)
  when PG_CONTRACT_URL is missing instead of silently skipping
- loadSession distinguishes corrupt non-object rows from absent rows so
  getSession fails loud instead of reporting the session missing

* fix(storage): round-3 cross-review hardening for the PG backend (#939 Part C)

- json-value guard (shared): NUL rejected in object keys, unpaired
  UTF-16 surrogates rejected in values and keys
- createSession/appendRecord gate the full persisted envelope through
  assertJsonValue, not only the payload — stray Date/undefined
  properties and NUL in ids fail loud instead of silently diverging
  from the returned record or leaking raw 22P05
- real-PG lane covers a genuine 23505 conflict from a second
  connection and recovery after an aborted transaction
- retry-set asymmetry and mergeLearner's unbounded lock set documented

* fix(storage): round-4 convergence fixes for the PG backend (#939 Part C)

- NUL/lone-surrogate lookup and delete keys resolve to absent/no-op
  instead of leaking 22021 driver errors; setSessionStatus reports the
  session missing; mergeLearner from-key moves 0
- mergeLearner destination key passes the JSON-domain gate fail-loud
- envelope JSON gate tolerates explicitly-undefined optional anchors,
  matching the browser backend
- json-value guard v4 (shared) + tests for accessors, Array subclasses,
  prototype-supplied indices

* fix(storage): round-5 convergence fixes for the PG backend (#939 Part C)

- appendRecord pre-checks the session key like every other lookup path,
  so a NUL/lone-surrogate sessionId reports 'no session' instead of
  leaking a 22021 driver error
- the queryable-key predicate now structurally reuses the shared
  isLosslessJsonString export instead of restating the string rule
- undefined-stripping limited to the DSL-declared optional anchors
- json-value guard: realm-agnostic prototype checks (shared)

* fix(storage): close the toJSON prototype channel in the JSON guard (#939)

Shared guard change with the HTTP backend branch; adds the crafted
null-proto-prototype regression test. Both final-gate reviewers
independently converged on this same channel.

* fix(storage): probe toJSON via descriptor walk, not property read (#939)

Reading value.toJSON would execute an inherited accessor, letting a
stateful getter hide from validation and reappear at stringify time.
The probe now walks own descriptors up the prototype chain without
invoking any user code. Post-validation mutation of the caller's object
graph is documented as out of scope — it is equally unpreventable for
every other validated property.

* fix(storage): toJSON probe mirrors JSON.stringify semantics exactly (#939)

The own-most descriptor decides: absent is safe, a non-callable data
value is an ordinary shadowing member and is safe, a callable data
value is rejected, and an accessor is rejected because it cannot be
inspected without invoking it. No daylight remains between the guard
and the serializer on this property.

* fix(storage): conform HTTP/PG backends to the post-#926 RuntimeStore interface (#943)

The chat cutover (#926) added deleteAllRuntime() to the RuntimeStore
contract while the HTTP and Postgres backends were developed in
parallel against the pre-#926 interface. Implements the method on both
backends (single-statement wipe on PG via the FK cascade; DELETE
/runtime on the HTTP contract, documented as an operator-gated
administrative endpoint), restoring a green typecheck and contract
suite on the integration branch.

* feat(runtime): injectable RuntimeStore backend + learner-key provider (#939 Part A) (#944)

* wip(runtime): backend injection seam — pending gate verification

* fix(runtime): cross-review hardening for the storage injection seam

- stage-deletion IndexedDB probe applies only to the default browser
  backend; an injected store always receives deleteStageRuntime
- explicit kv argument takes precedence over the configured learner-key
  provider, matching the store seam's explicit-beats-global rule
- configured learner-key resolution is latched with in-flight dedup,
  mirroring the store singleton; identity changes require app-level
  handling
- factory retry semantics documented; seal errors explain the
  module-level bootstrap requirement; isRuntimeStorageConfigured()
  probe and a test-only reset added
- client-bootstrap-only contract documented (SSR/HMR caveats)

* fix(runtime): snapshot configuration and make the test reset complete

- configureRuntimeStorage copies the option fields so mutating the
  caller's object after configuring cannot swap the sealed backend or
  identity provider
- resetRuntimeStorageForTests now clears every latched consumer cache
  (store singleton, learner-key in-flight promise) via a reset-hook
  registry, so a reset-then-reconfigure test actually gets the new
  backend

* fix(runtime): reset also clears the default learner-key caches

resetRuntimeStorageForTests left defaultInFlight/defaultKv latched, so
a default-path test could leak its anonymous key or KV store into the
next test despite the documented full-reset promise.

* feat(storage): runtime reference server — auth-derived learnerKey (#939 Part D) (#945)

* wip(storage): reference server — pending deleteAllRuntime route + gates

* feat(storage): runtime reference server — auth-derived learnerKey enforcement (#939 Part D)

- createRuntimeHttpHandler(store, options) wires the documented HTTP
  contract onto any injected RuntimeStore over node http
- authenticate is required; every learner-scoped operation verifies the
  path/body learnerKey against the authenticated principal (403
  FORBIDDEN_LEARNER) — the client-supplied value is never trusted
- mergeLearner requires an explicit authorizeMerge grant and admin
  surfaces (stage cascade, DELETE /runtime) require authorizeAdmin;
  both default-deny
- runnable reference entry demonstrates a pg Pool withTransaction and
  bearer-token authentication, marked as demo-only
- contract suite green through HttpRuntimeStore -> listening reference
  handler -> PgRuntimeStore(pglite); security matrix tested (401/403
  paths, admin default-deny); threat model documented

* fix(storage): cross-review hardening for the reference server (#939 Part D)

- principal learnerKey is optional: admin/merge-only credentials no
  longer fabricate learner identity; learner-scoped routes 403 without
  ownership
- full session/record envelopes pass the JSON-domain gate at the
  handler, so NUL/lone-surrogate identifiers map to 400 instead of 500
- payload validation follows the injected store's validator map
  (options.payloadValidators) instead of imposing DSL defaults
- reference factory accepts authenticate/authorizeMerge/authorizeAdmin/
  payloadValidators overrides; docs no longer claim the factory binds
  to localhost; demo-impersonation warning hardened
- 500 responses carry a generic message; details go to the server log
- ownership checks precede version checks and unowned sessions read as
  404, closing existence/version oracles; cross-learner denial matrix
  tested per route
- merge/delete concurrency documented as linearizable-equivalent with
  the ownership re-check narrowed to the delete call

* fix(storage): align reference-server semantics with the store contract

- future-stamped sessions read and delete through unchanged; 409
  FUTURE_VERSION applies only to guarded writes (status, append, merge)
- check-then-write races reclassify structurally via a post-failure
  re-fetch: missing session 404, non-active session 400, never a
  message-sniffed or generic 500

* fix(storage): close the reference CLI's pg pool on startup failure

ensureSchema opens connections inside createReferenceRuntimeServer, so
a failed schema init or occupied port left the pool holding database
resources until its idle timeout.

* fix(storage): close the records-route existence oracle

cosarah's review point on #946: the records list answered 200 [] for an
absent session but 404 for another learner's, so the 404 leaked that an
id exists. Absent and foreign sessions now answer identically (404
SESSION_NOT_FOUND) and the HTTP client maps that code back to an empty
list, preserving the store contract's absent-lists-as-empty semantics.
Contract doc records the server MAY/SHOULD and the client MUST.
 2026-07-17 16:15:57 +08:00
wyucand杨慎 6f7ffa8302 chore: tighten GitHub issue intake (#921) 
* chore: tighten issue intake

* fix: address issue intake review feedback

* test: preserve scene selectors in pro mode

---------

Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
 2026-07-14 15:44:57 +08:00
wyuc 1c5078842a feat(storage): RuntimeStore — sessions + append-only records, browser backend (#869 Part B) (#880) 
* feat(storage): RuntimeStore contract — interface + backend-agnostic suite (#869)

* feat(storage): BrowserRuntimeStore — IndexedDB backend for the runtime layer (#869)

* test(storage): runtime version-skew coverage; run the storage suite in CI (#869)

Backend-specific tests seed raw session rows (mirroring the document
backend's reStampStage) to cover the version-skew surface the public API
cannot express: a stale stamp fails loud while the runtime ladder is empty,
a future stamp reads through unchanged but rejects appendRecord and
setSessionStatus, and a stamp-stripped row hits the no-unversioned-epoch
guard. Also covers the injected payloadValidators override (the contract
case deferred to the backend test, as document-contract does for scene
validators).

The @openmaic/storage suite — including the pre-existing DocumentStore /
KV / asset contracts — never ran in CI at all; add the missing step after
the dsl one. README gains the RuntimeStore section.

* fix(storage): harden RuntimeStore writes and listings per cross-review (#869)

- mergeLearner now takes the same gates as every other write: rejects
  empty learner keys, self-merges return 0 without a transaction,
  future-stamped rows throw (mutating a newer client's data), and every
  re-keyed envelope is validated before put — any throw aborts the whole
  merge atomically instead of contaminating the target partition.
- listSessions sorts by the instant a timestamp denotes (Date.parse),
  not by string order, which mis-ranks numeric zone offsets; and it
  tolerates corrupt rows by omission (the listDocuments precedent) so
  one poison row cannot make a partition unenumerable — direct reads
  stay fail-loud.
- appendRecord validates the ACTUAL completed record (with the assigned
  seq) inside the transaction, on top of the pre-flight, and derives seq
  from a key cursor's primaryKey instead of deserializing the previous
  record's payload.
- Docstrings now enumerate the corrupt-stamp throw paths and no longer
  claim every query is partition-scoped (mergeLearner is the one
  deliberate cross-stage sweep).
- The stale-row test comment no longer promises an impossible one-line
  flip; the IDBKeyRange shim moves to test/setup.ts alongside the other
  guarded shims.

* fix(storage): mergeLearner migrates stale sessions before re-keying (#869)

The re-key previously spread the RAW stored row, unlike setSessionStatus
and appendRecord which migrate a stale session in place before mutating
it. Once the runtime ladder gains a real step, that would either write an
old runtimeDslVersion into the target partition or fail validation when a
migration adds required fields. Build the updated row from
migrateSession(row) instead (order: future-guard, migrate, re-key,
validate, put).

Observable today (empty ladder): a below-epoch stale row makes the merge
abort with the ladder's no-migration-path error — pinned by a new backend
test with nothing moved.

* fix(storage): reads gate stored sessions through envelope validation (#869)

Reads previously ran only version resolution, so a row with a valid
runtimeDslVersion but corrupt other fields (a non-ISO createdAt, a bogus
status) came back as-is — contradicting the documented corrupt-row
semantics, which covered only version corruption. Extend the same policy
to the whole envelope: getSession validates the migrated row and fails
loud as a stored-row integrity error; listSessions omits rows whose
envelope validation fails, exactly like version-resolution failures.

setSessionStatus and appendRecord need no change: the status update
validates the full post-update envelope before writing (catching corrupt
non-status fields), and appendRecord's own writes are already validated.
 2026-07-09 00:03:51 +08:00
wyucClaude Fable 5杨慎
 		83fdecf399 feat(dsl): runtime envelope — RuntimeSession + RuntimeRecord + core-kind skeletons (#869 Part A) (#870) 
* feat(dsl): runtime envelope — RuntimeSession + RuntimeRecord + core-kind skeletons (#869)

* feat(dsl): runtime envelope validators (#869)

* test(dsl): runtime envelope rides the version ladder; document the runtime contract (#869)

* fix(dsl): harden runtime envelope validators and tighten contract linkage (#869)

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

* fix(dsl): isQuizAttemptSkeleton requires a plain-record answers map (#869)

* fix(dsl): review round — ISO 8601 timestamps, dedicated runtime migration ladder, payload excludes undefined (#869)

* fix(dsl): mechanical version-line separation + ISO day-overflow check (#869)

- Runtime sessions now stamp their own envelope field (runtimeDslVersion,
  RuntimeVersioned) instead of sharing dslVersion: the document and runtime
  ladders read disjoint fields, so misrouted data is inert rather than
  silently reinterpreted once the two lines diverge. Adds
  runtimeDslVersionOf + needsRuntimeMigration as the runtime-line
  counterparts of dslVersionOf + needsMigration.
- isIsoTimestamp: Date.parse normalizes day-of-month overflow on V8
  (2026-02-30 parses, rolls to Mar 2) instead of rejecting it; add a pure
  calendar round-trip so the verdict is correct and engine-independent.
- Report an empty-string timestamp once (required-field table), not twice.
- Scope migrateRuntime's contract to RuntimeSession; records are not
  independently versioned units.
- Run the @openmaic/dsl test suite in PR CI (it previously ran only in the
  publish workflow).

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

* fix(dsl): isIsoTimestamp validates calendar components without Date.parse (#869)

* test(dsl): cover month-00 / day-00 in isIsoTimestamp negatives (#869)

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

* fix(dsl): cross-line guard makes misrouted data inert across migration ladders (#869)

* fix(dsl): mirror the cross-line guard in the migration predicates (#869)

runLadder's cross-line guard returns a misrouted aggregate untouched, but
needsLadder still reported it as needing migration (its own stamp absent
reads as 0.0.0), so a correctly paired
`while (needsMigration(x)) x = migrate(x)` loop on a runtime-line object
would never terminate. Give the predicates the same guard, restoring the
predicate/runner agreement invariant the docs promise.

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

* fix(dsl): fail loud on ambiguous cross-line envelopes (#869)

The guard treated raw sibling-key presence as proof of misrouting, but the
same byte state also arises as this line's data carrying a stray foreign
stamp — e.g. a valid session that once passed through the document runner.
Silently returning it unchanged permanently orphaned that data from its own
line (predicate reports current forever, runner never lifts it).

The state is undecidable from the envelope, so stop guessing: both runners
and both predicates now throw the same cross-line error on
own-stamp-absent + sibling-stamp-present, mirroring the malformed-stamp
rule. validateRuntimeSession additionally rejects any present dslVersion
on a session at the door, so the ambiguous state cannot enter storage
through a validated write path.

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

* fix(dsl): enforce the cross-line rule in the shared envelope reader (#869)

dslVersionOf / runtimeDslVersionOf still read a sibling-stamp-only
envelope as unversioned while the runners and predicates threw on it, so
an authoritative version read (e.g. storage's putScene guard messages)
could report 0.0.0 with a load-and-save remediation for a row the load
path refuses to migrate. Move the cross-line throw into versionOf itself:
the plain readers, the needs*Migration predicates, and the migration
runners now give one answer for one envelope, and the duplicated guard
sites in runLadder/needsLadder collapse into the shared reader.

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

* fix(dsl): the runtime line has no unversioned epoch — sessions are born stamped (#869)

An unstamped object read as 0.0.0 let the runtime ladder lift arbitrary
document-shaped data; once a real session transform lands that walk
corrupts or throws. The runtime envelope is brand new — nothing
legitimately predates it and stores stamp runtimeDslVersion at write —
so an unstamped object on the runtime line is always a bug (a misrouted
legacy document or an unstamped producer write), not legacy data:

- RUNTIME_DSL_MIGRATIONS drops its legacy-lift entry (empty until the
  first real shape change appends a step from the pinned initial version).
- migrateRuntime / needsRuntimeMigration / runtimeDslVersionOf throw on
  an unstamped object (versionOf gains a per-line legacy version, null
  meaning no epoch). The document line keeps its legacy lift — real
  pre-versioning documents exist.
- RuntimeSession requires runtimeDslVersion (type and validator), so an
  unstamped session cannot pass a validated write path and the
  type/validator contract stays aligned.

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

* test(dsl): pin the future runtime ladder's first step to the initial version (#869)

A non-empty RUNTIME_DSL_MIGRATIONS must start at
INITIAL_RUNTIME_DSL_VERSION — the runtime line has no unversioned epoch,
so a ladder starting earlier (a copy-pasted 0.0.0 legacy lift) would
reintroduce the lift-arbitrary-unstamped-data hole. The contiguity test
now asserts the pinned origin as well.

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

* fix(dsl): restore the empty runtime ladder — drop swept-in local fault injection (#869)

e9d480e1 accidentally swept a local-only fault-injection edit (a mistaken
0.0.0 legacy origin used to exercise the new ladder-origin invariant test)
into the commit alongside the test change. The injected fault is exactly
what the new test guards against — the suite failed on it as intended.
Restore the empty ladder; 189 tests green again.

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

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
 2026-07-08 17:47:30 +08:00
xuyuanwei678 261fddb062 fix(packages): add openmaic repository metadata (#813) 
* fix(packages): add openmaic repository metadata

* ci(packages): publish on openmaic manifest changes
 2026-06-29 16:52:03 +08:00
wyuc 7cb129183d chore(packages): publish the @openmaic/* SDK family to npm (#778) (#780) 
* chore(packages): publish the @openmaic/* SDK family to npm (#778)

Prepares the @openmaic/{dsl,renderer,importer} family for its first npm
publish, and moves the SDK packages onto the @openmaic scope.

Why the scope move: the @maic org name is unavailable on npm (an unscoped
`maic` package already holds the name), so @maic/* is not claimable. @openmaic
matches the project name, the scope is free, and the repo already ships an
@openmaic/docs package — so the SDK family now lines up with that convention.

- rename @maic/{dsl,renderer,importer} -> @openmaic/* across packages, the
  workspace glob, the package dir, and all import sites; lockfile regenerated
- renderer: add publishConfig (public, registry.npmjs.org) — was missing, so
  a scoped publish would default to the wrong registry / restricted access
- importer: add a files allowlist (dist, README, LICENSE) and drop the
  fragile .npmignore blacklist that shipped src; add an exports map so ESM
  consumers resolve dist/index.js instead of falling back to the .cjs main
- all three: add a prepublishOnly build (+ test/typecheck) guard so a publish
  can never ship a stale or empty dist
- add a tag-triggered publish workflow with npm provenance, pinned by name to
  the three @openmaic packages so the vendored forks (mathml2omml, pptxgenjs)
  are never published

Refs #778, #720 (Phase 1).

* fix(packages): address cross-review on the @openmaic publish prep

Cross-review (Claude /code-review + codex) on this PR surfaced:

- renderer's advertised CJS entry was broken: it keeps @openmaic/dsl external
  and imports a runtime enum from it, but dsl is ESM-only (no `require`
  condition), so `require('@openmaic/renderer')` would throw
  ERR_PACKAGE_PATH_NOT_EXPORTED. Make renderer ESM-only: drop the `.cjs`
  rollup output, `main` now points at the ESM build, and the `require`
  conditions are removed from `exports`. (importer is unaffected — it bundles
  dsl, so its CJS build still works.)
- prepublishOnly re-ran the test suite during `pnpm -r publish`, so a flaky
  test after dsl had already published gave a non-atomic partial release.
  Reduce prepublishOnly to a build-only guard (never ship stale/empty dist)
  and move the real test/typecheck gate into the workflow, before any publish.
- document that an @openmaic/* tag publishes the whole family via `pnpm -r`
  (pnpm skips already-published versions); the tag is a release marker, not a
  per-package gate.

Verified: dsl + renderer + importer build; renderer emits ESM only (0 .cjs),
all exports entries resolve; `npm pack` ships dist + README + LICENSE with no
src leak; frozen-lockfile passes.

Refs #778.

* style: reflow @openmaic/dsl type imports past print-width after rename

The @maic -> @openmaic rename lengthened two single-line type imports past
prettier's 100-col width; prettier --check flagged them. Pure formatting.

Refs #778.

* docs(importer): mark @openmaic/importer browser-only (cr-loop accepted limitation)

codex cross-review flagged that the published @openmaic/importer throws
`XMLHttpRequest is not a constructor` when loaded in a pure Node process —
its rollup build is browser-targeted (`nodeResolve({browser:true})` + a
browser pdf.js build). The app only consumes it client-side ('use client'),
so this is by design. Document it as an accepted limitation: prominent
browser-only note in the README and a `browser` field in the manifest.

Refs #778.
 2026-06-24 15:12:23 +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
xuyuanwei678Cursorwyuc
 		d403014918 fix(importer): correct hanging-indent bullet slot rendering (#727) 
* fix(importer): correct hanging-indent bullet slot rendering

Size the bullet slot to the hanging-indent amount (|indent|) instead of
marL so wide marL paragraphs no longer push body text past the bullet.
Reset text-indent on the inline-block slot to stop symbol bullets from
drifting left onto adjacent shapes, and only pad synthesized-marL symbol
bullets. Add vitest setup and serializer tests.

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

* style(importer): apply prettier formatting to serializer tests

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

* test(importer): wire up package-local vitest config and CI

Add packages/@maic/importer/vitest.config.ts so the package tests in
test/ are discovered (the root config only globs tests/), and add a CI
step that runs them. Align vitest to a single 4.1.8 in the lockfile and
move the tableSerializer setup into beforeAll so parse failures surface
as test failures instead of collection errors.

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

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>
 2026-06-15 12:16:09 +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
wyucClaude Opus 4.8杨慎
 		77bcd589e0 docs: add Fumadocs documentation site (#622) 
* docs: add Fumadocs documentation site (packages/docs)

Static-exportable Fumadocs site for the OpenMAIC docs, served under /docs.
- 6 locales (en default + zh-CN/zh-TW/ja/ru/ar) with Arabic RTL
- English unprefixed (/docs/getting-started) to preserve legacy URLs;
  other locales at /docs/<lang>/<slug>
- Orama static search compatible with `output: 'export'`
- Brand theming via CSS variables; "Live Demo" link back to open.maic.chat

Kept fully isolated from the main app so it does not affect its build or CI:
- excluded from the pnpm workspace (own lockfile, build and deploy)
- ignored in .prettierignore (own toolchain, like the other packages)
- excluded from the root tsconfig so the main app build does not type-check it
ESLint already ignores packages/**.

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

* ci: add standalone docs build check

Validate that packages/docs still builds (next build + static export) on
PRs that touch it. Runs only on packages/docs changes; no secrets, no deploy.

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

* docs: address CR — CJK search, single-source locale config

- Fix Chinese/Japanese search: zh-CN/zh-TW use the mandarin tokenizer and ja
  the japanese tokenizer (@orama/tokenizers) on both the build-time index and
  the client query; the english whitespace tokenizer indexed CJK as one token.
- Add lib/locales.mjs as the single source for the locale list, default locale,
  per-locale search tokenizer, RTL set, labels, and the /docs basePath; consume
  it from i18n, the search index/dialog, next.config, and the postexport script
  (was duplicated and drift-prone).
- Drop dead gitConfig.branch; fix the stale README route table; document the
  English-nested-page limitation.

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 00:11:17 +08:00
Madoka a47b2d2fb1 Feat/439 i18n key alignment check (#447) 
* feat(ci): add i18n key alignment check

* fix(ci): harden i18n key alignment script
 2026-04-18 13:31:55 +08:00
wyucandClaude Opus 4.6 ae08cf47d1 chore: update Discord invite links 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-04-15 12:02:13 +08:00
wyucClaude Opus 4.6杨慎
 		37e04558b6 test: add Playwright e2e testing framework with core scenario coverage (#229) 
* chore: add Playwright e2e testing infrastructure

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

* test: add e2e mock fixture data

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

* test: add MockApi route interception helper

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

* test: add base fixture and page object models

Also exclude e2e/ from ESLint to avoid react-hooks false positives
on Playwright's fixture `use` callback.

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

* test: add home-to-generation e2e spec

Adds the first Playwright spec covering the home page UI and navigation
to generation-preview. Also updates playwright config to use port 3002
to avoid conflicts with other running services.

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

* test: add generation-flow e2e spec

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

* test: add classroom-interaction e2e spec

Seeds IndexedDB with a 3-scene stage by navigating to / first (so
Dexie initializes the DB at v8), then writing data without re-triggering
onupgradeneeded. Verifies the sidebar renders 3 scenes and that clicking
a scene switches the active scene heading.

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

* ci: add Playwright e2e test job

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

* test(e2e): fix review issues — data-testid selectors, shared helpers, type annotations

- Add data-testid="scene-list", "scene-item", "scene-title" to scene-sidebar.tsx
- Update classroom.page.ts selectors to use data-testid instead of CSS class chains
- Extract createSettingsStorage() helper into e2e/fixtures/test-data/settings.ts
- Update all 3 spec files to use createSettingsStorage() and import defaultTheme from scene-content
- Add SceneOutline[] type annotation to mockOutlines via relative import
- Add SlideTheme type annotation to defaultTheme in scene-content.ts
- Remove redundant mockServerProviders() call from setupGenerationMocks()

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

* chore: exclude e2e/ from tsconfig, rename CI job

- Add "e2e" to tsconfig.json exclude array to prevent Next.js
  compilation from pulling in Playwright/Node APIs
- Rename CI job from "Lint & Typecheck" to "Lint, Typecheck & Unit Tests"
  to reflect that it now also runs unit tests (added in PR #144)

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
 2026-03-24 12:19:59 +08:00
wyucandClaude Opus 4.6 95cdc38902 test: add Vitest infrastructure with provider-config and settings-sync tests (#144) 
* chore: set up Vitest testing infrastructure

- Add vitest as devDependency
- Create vitest.config.ts with @/ path alias and tests/ directory
- Add "test" script to package.json
- Add Unit Tests step to CI pipeline

Ref: #79

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

* test: add action-parser tests covering parsing, fault tolerance, and post-processing

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

* test: fix describe block names and add nanoid ID assertion

- Rename misleading "all layers/strategies fail" to "edge cases"
- Add assertion for generated action ID from nanoid mock

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

* test: add provider config and model string parsing tests

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

* test: replace low-value tests with server-sync store tests

Remove parse-model-string, action-parser, and json-repair tests.
Add settings-server-sync tests verifying fetchServerProviders()
correctly updates provider availability and model filtering.

Include 3 it.fails() cases documenting stale selection bug:
when server removes a model/provider, the store's modelId/providerId
should be cleared but currently persists as a stale value.

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

* test: add ASR_PROVIDERS to audio constants mock

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

* style: format settings-server-sync test with Prettier

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

* fix: address PR #144 review feedback

- Remove unrelated `release` script from package.json
- Narrow `vi.mock('fs')` to only intercept server-providers.yml reads
- Add positive test for `resolveProxy` with YAML config
- Add error-path tests for `fetchServerProviders()` (HTTP error, network error)
- Track stale-selection bugs as GitHub issue #226

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
 2026-03-23 16:40:26 +08:00
1/2极客andhumingfeng 0a9b5abe34 fix(build):Next.js 16 要求 Node.js >= 20.9.0 (#21) 
* fix(build):
1、README.md / README-zh.md — Node.js 版本要求 >= 18 → >= 20
2、package.json — 新增 engines: { node: ">=20.9.0" }
3、ci.yml — node-version: 20 → 22（与 Dockerfile 一致）
4、.nvmrc — 新建，内容 22

Co-authored-by: humingfeng <humfsss@gmail.com>
 2026-03-17 09:01:04 +08:00
yangshenandClaude Opus 4.6 b985f23d60 docs: add GitHub issue and PR templates 
Add structured issue templates (bug report, feature request) and a PR
template with verification checklist to standardize contributions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 2026-03-16 17:08:07 +08:00
wyucandClaude Opus 4.6 6466c649da ci: add GitHub Actions workflow for lint, typecheck, and format check 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
 2026-03-13 16:14:01 +08:00