52 Commits

Include renames

Author	SHA1	Message	Date
wyuc	ee1bd6bbee	feat(storage): asset registry — allocated ids over the content-addressed blob layer (#1007 part 1) (#1024) ... * refactor(dsl): restate the asset seam as allocated, non-disclosing refs The asset seam's docstrings described a ref as a handle whose scheme was the backend's business, and recommended content-addressed hashing so identical bytes de-duplicate. Both are now wrong in the same place: a content-addressed ref *is* a statement about the bytes, so returning one from `put` tells the caller whether those bytes were already stored — an existence oracle over data the caller never wrote. State the contract the global asset pool needs instead: `put` allocates, every call returns a new ref, and nothing the caller receives reveals whether the bytes pre-existed. A provider may still de-duplicate internally; that is a property of its storage layer, not of the ref. Also spell out that the ref domain is unconstrained, so an unrecognized ref is a miss rather than an error. Comments only — no interface signature changes. * feat(storage): add the asset registry — allocated ids over the blob layer Part 1 of the global asset pool (#1007): the browser registry core. `BrowserAssetStore` is now the package's asset backend. It maps an allocated `AssetId` to a registry entry (`contentHash`, `mime`, `meta`), and the registry maps that hash to bytes, giving three properties at once: - an id survives the bytes behind it being regenerated or replaced, and one set of bytes can back several ids with different metadata; - identical bytes occupy one row however many ids name them; - the content hash never leaves the package, so "whoever knows the hash can reach the bytes" — the threat pure content-addressing has to defend against — structurally does not arise, and the blob layer beneath can stay global and metadata-free without being an isolation hole. `put` always allocates a new id and always writes the blob unconditionally, so the first-store and de-duplication-hit paths run the same statements, issue the same requests, and return the same shape. The caller cannot infer that someone else's bytes are already present. Both stores live in one IndexedDB database, so reference counting on `remove` happens inside the transaction that deletes the entry, over an index on `contentHash`. IndexedDB serializes readwrite transactions over the same stores, so a last-reference removal can never reclaim bytes a concurrent `put` has just adopted. Images, audio and video share one id space; the medium is a `mime` column, not a partition. There is no `principal` column: a principal is derived server-side from an authenticated session, and a value the client supplies about itself authorizes nothing — the column arrives with the server backend. The id domain is opaque and unvalidated, taking the KV key domain's conclusion as its starting point. `toAssetId` brands without checking; an id this store never issued is a miss, never an error. `BrowserAssetProvider` is demoted to an internal blob backend and dropped from the public exports (0.x, and it had no consumers): its content-addressed ref is precisely the de-duplication signal an outward API must not emit. Tests split along the same seam. `runAssetStoreContract` pins the outward semantics — allocation, an existence-disclosure matrix compared facet by facet rather than asserted in prose, reference-counted release, and a table of foreign ids that must all miss without throwing — while `runBlobStoreContract` keeps the content-addressed semantics for the layer underneath. Facts the outward API must not disclose (one blob row per byte string, reclamation at the last reference, the put/remove race) are asserted against the rows. * chore(packages): bump @openmaic/dsl to 0.5.1 and @openmaic/storage to 0.2.0 `storage` takes a minor bump rather than a patch: `BrowserAssetProvider` is no longer exported from the package entry point, which is breaking under 0.x convention even though nothing consumed it. * fix(storage): address asset registry review findings * fix(storage): complete asset registry lifecycle * fix(storage): harden asset cache coherence and lifecycle * fix(storage): close pending asset mint edges * refactor(storage): adopt immutable asset URL snapshots * fix(storage): close asset snapshot lifecycle gaps * test(storage): pin asset lifecycle contracts * docs(storage): document 0.1.x asset upgrade * fix(storage): reject incompatible asset database schemas * fix(storage): enforce asset allocation independence * fix(storage): instrument production asset allocation * test(storage): cover allocation ordinals across histories * refactor(storage): remove standalone blob backend seam	2026-08-01 22:21:23 -04:00
wyuc	091989c48b	feat(storage): promote KV HTTP contract + clients to main (Part A of #1000) (#1020) ... * feat(storage): KV HTTP contract and clients (#1000 Part A) (#1002) * feat(storage): KV + Asset HTTP contracts and clients Adds the client half of the server backends for the two components in the storage RFC that still had a browser backend only. Asset contract: the ref is `sha256-<hex>` over the bytes, computed by one shared rule both backends call, and it *is* the address bytes are written to (`PUT /assets/{ref}`). The server re-hashes what it received and refuses a mismatch, so content addressing is enforced end to end rather than assumed, and uploads become idempotent. `resolve` returns a URL per call, either an absolute signed URL passed through untouched or a root-relative proxied path joined to the base origin — the document never stores a raw URL either way. KV contract: account scope only, with no scope path segment, query parameter or body field anywhere on the wire. `HttpAccountKV` is the only object that can reach it and none of its methods takes a scope, so a device value is not a request the transport can express; `HttpKVStore` routes `device` to a local backend it requires at construction. Tests assert the invariant both ways — `@ts-expect-error` on every scope-passing call (unused directives fail the build if a scope is ever added) and a fetch spy proving device traffic does not exist. Both clients pass the existing `runKVStoreContract` and `runStorageProviderContract` suites against an in-memory conformance server, the asset one in both the proxied and signed URL shapes. * fix(storage): close the review findings on the KV + asset HTTP clients Cross-review found the device-scope guarantee resting on its weakest layer, and several places where the contract promised more than the code or the conformance server could deliver. deviceStore: the two type-level layers only documented intent — the barrier that actually kept device values off the wire was the injected store, typed as `KVStore`, which `HttpAccountKV` satisfies structurally (its methods are the same methods minus an optional parameter). Injecting the transport as the device backend type-checked and put device values on the network. The device scope now requires a branded `LocalKVStore`, the transport declares itself not to be one, and a runtime check refuses what a cast smuggles past. resolve URLs: a media `src` carries cookies, never the client's headers hook, so the proxied shape is only sound for cookie-authenticated deployments — the contract now says so instead of claiming the content route sits behind "the same authentication", and the conformance reader uses a cookie rather than a header no browser could send. The client also validates what it resolves: http(s) schemes only, and no `//host` or `/\host` slipping through the relative branch to another origin. Identifiers: refs and keys arrive percent-decoded, so `..%2F..%2F` was a traversal waiting for the first backend to join it to a path. Both are now constrained on both sides, and the contract states the MUST that keeps a storage layer from being the first to look. Also: the JSON gate runs before anything reads the value (a `JSON.stringify` pre-flight ran caller code first and reclassified `{ toJSON: () => undefined }` as a delete); scope routing fails closed; an upload's Content-Type can no longer be relabelled by the headers hook; a mutation invalidates in-flight resolution; unparseable 2xx bodies become typed errors rather than native SyntaxErrors; signed tokens are validated rather than merely present; and the contracts settle the per-principal claim model, the media-type allowlist, the literal prefix rule, and the identifier charset that Part B would otherwise have had to guess at. * fix(storage): close the second review round on the KV + asset HTTP clients The device-scope guard was in one place and needed to be in three. The transport is exported and structurally a `KVStore`, so `kvPersistStorage(new HttpAccountKV(...), 'device')` and a plain `KVStore`-typed reference both compiled without a cast, dropped the scope argument on the floor, and put a device value on the wire. The transport now takes the scope it was pretending not to have — typed as `'account'`, refused at runtime for anything else, since bivariant method parameters mean the type alone cannot hold — and the persist adapter requires a `LocalKVStore` when paired with `'device'`. The resolved-URL checks were text tests where only parsing works. The URL parser strips ASCII tab, LF and CR before parsing, so `/<tab>/evil/x` walked past the `//` prefix check and loaded cross-origin — in the app-mounted shape, where a path-only base URL leaves that check as the only guard. The absolute branch let through `https://` with no host and `https:host/x`, which names one place standalone and another when a browser resolves it against a same-scheme page. Both branches are now decided by the parser: control characters refused outright, relative references validated against a probe origin, absolute ones required to parse as `scheme://host` with an http(s) scheme — and still returned byte-for-byte, so signatures survive. The media-type MUST had no implementation and contradicted itself: the conformance server stored and served `text/html` verbatim, and a metadata-less upload became `application/octet-stream`, which cannot be on a renderable allowlist. The server now implements the allowlist, serves everything else as an opaque attachment, and the contract scopes its "usable as an img src" promise to allowlisted types. The KV key domain was HTTP-only, which made "the same suite proves the backends equivalent" untrue: `a/b`, an empty key and a 600-byte key all passed in the browser and would have become unreachable on a server. An audit of the app's keys (learner key, storage generation, current-scene and migration markers, persist names) found none in violation, so the rules are lifted to the primitive and both backends enforce them, with the shared suite asserting it. Also: the claim model the last round wrote into the contract is now implemented and covered case by case; malformed percent-escapes are a 400 rather than a 500; the in-flight identity guard has a test that can fail; and the Content-Type conflict raises a typed error. * fix(storage): final review round — backend parity, URL probe, credentials Four small things the final pass found, plus the contract patches Part B would otherwise inherit. The `toJSON` delete semantics were documented backwards. `BrowserKVStore.set` was the trial-serialize the KV contract said no backend does, so `{ toJSON: () => undefined }` was a silent delete there and a rejection over HTTP — opposite answers to the same call. The browser backend now validates scope and key before anything can run caller code, recognizes the delete case by type, and refuses a value that still fails to serialize. Both cases are in the shared suite, so the two backends cannot drift apart again. The probe-origin check could not vouch for a URL naming the probe host itself: `//asset-url-probe.invalid/x` resolves onto the probe origin and passed, then resolves somewhere else entirely against a real base. Any authority-bearing form is refused outright, so the check no longer depends on the probe host being unguessable. Cross-origin cookie deployments had no way to send a cookie: `fetch` omits them cross-origin by default and the headers hook cannot help, since `Cookie` is a forbidden header name. Both clients accept `credentials` and pass it to `fetch`; the contract records the CORS obligations that come with it. Rather than restricting cookie deployments to same-origin, which the asset contract explicitly does not require. The conformance server's dot-segment check was reading a path the URL parser had already normalized, so `/assets/%2e%2e/x` arrived as `/x` and the documented 400 was really post-routing behaviour. It now validates the raw request target, and the injected transport preserves it instead of handing over a normalized one. Contract: the prefix rule names backslash (PostgreSQL's default LIKE escape, and the one an implementer skips because a legal key cannot contain it, though a prefix can), and acquiring a claim MUST leave the bytes present — a de-duplicating server that inserts only the claim can race reclamation of the last previous claim and leave a document resolving to a 404. Also: base URLs are checked for an http(s) scheme at construction, the ref domain moved next to the KV key domain and is enforced by both asset backends with shared suite coverage, the KV client refuses a hook-supplied Content-Type like the asset one, and CI runs the package typecheck that makes the `@ts-expect-error` guards mean something. * fix(storage): probe guard spelling, prefix validator, base url shape Three one-line-level holes from the closing review. The probe-host guard was spelled `startsWith('//')`, so the backslash forms `/\host/x` and `/\/host/x` reached the origin comparison, passed it by naming the probe host, and were stopped only by that host failing to resolve. It now refuses any second character that can open an authority — which is also what makes the comment true rather than aspirational: a path-absolute reference always inherits the base's origin, so with no authority expressible the comparison cannot be satisfied cross-origin, whatever the probe host is. The conformance server validated `?prefix` with the path-segment validator, rejecting `keys('.')` and `keys('..')` — legitimate prefixes of keys like `.hidden`, which the client rightly allows. A prefix travels in the query string and is never a path segment, so it now has its own validator: the key rules minus the non-empty and dot-segment requirements. The contract says the same, and the shared suite pins both backends to it. Base URL validation moved into one shared helper both clients call, since two copies of a security rule is how they drift. It now also refuses `https:host/path` — which parses standalone to that host but is resolved against the current document by `fetch`, sending requests and their credentials somewhere the operator never wrote — and a base carrying a query or fragment, which silently swallows the path concatenated onto it. * fix(storage): close two holes in the shared base-url check The path-only branch returned its input unexamined, so `//evil.example` and `/\evil.example` were accepted as paths. A browser reads both as an authority, which means every request built on such a base — and every credential the headers hook attaches — leaves the origin. A base is now required to be a single `/` followed by something that is not `/` or `\`, the same refusal the resolved-URL check already makes, for the same reason. Control characters are refused first: the parser strips or re-encodes them, and `/<tab>/evil.example` becomes `//evil.example` after it does. The query/fragment check read the parsed `search` and `hash`, which are empty strings for a base ending in a bare `?` or `#` — so exactly the inputs that swallow the concatenated path into a query or fragment were the ones that got through. It reads the raw string now, which also makes the post-parse check redundant rather than merely unreachable. * fix(storage): bypass HTTP caches on reads, and require a 404 for not-found Two mechanisms the clients were missing, on both sides. Reads are marked `cache: 'no-store'`. The asset resolve request answers two mutable questions — does this principal hold a claim, and which URL is valid now — so a cached answer returns an expired signed URL or replays a negatively cached 404 for an asset written since; the in-flight coalescing that would otherwise cover this lives in the client and cannot reach the HTTP cache layer. KV reads have the same problem for a different reason: `account` is by definition the scope another device may have just written, and nothing here can invalidate a cached copy when it does. The contracts now require `no-store` on those responses. Asset content is left cacheable — bytes at a content-addressed ref never change — and writes are unmarked, having nothing to read from a cache. The not-found mappings now require the status as well as the code. A proxy or gateway answering 401, 403 or 500 while echoing the body's error code was being read as "this does not exist", and `null` is indistinguishable from a real miss — so an outage reached the caller as data loss. * fix(storage): reject unusable base urls, and make the harness meet the contract Two configuration checks and two harness gaps. A base URL carrying userinfo built a client that threw a native TypeError on every operation, because Fetch refuses to construct a request from a URL with embedded credentials — one legible error where the deployment is configured beats a per-call failure with no explanation. A base with surrounding whitespace was worse than useless: `new URL` strips it, so validation passed, and then concatenation moved the space inside the URL where it is no longer trailing and no longer stripped, breaking every request. The conformance server now sends `Cache-Control: no-store` on the three reads the contracts require it on. The requirement landed last round with nothing asserting it, so the suite would have passed against exactly the implementation it exists to catch. And `DELETE /kv/entries/{key}` refuses a request body outright: the query and the header were already checked for a smuggled scope, leaving the body as the one channel through which a delete could still describe one. * fix(storage): allow a device-routing composite to persist device-scoped state cosarah found kvPersistStorage(httpKVStore, "device") wrongly rejected. An HttpKVStore is a full dual-scope composite: it routes device operations to the LocalKVStore it requires at construction and only reaches the network for account, so device values never leave the machine. The guard tested isLocalKVStore — "is the whole store local" — and so turned away a store that is safe for device precisely because it is not fully local. The guard now turns on the capability that actually matters: does the device scope stay local. A new DeviceSafeKVStore brand (servesDeviceScopeLocally: true) marks a store whose device writes never leave the device — held by a fully-local LocalKVStore (which extends it) and by HttpKVStore, and declared false by HttpAccountKV, the pure account transport with no local device backend. The persist device overload requires DeviceSafeKVStore; the account overload is unchanged. The security boundary the red team opened this whole line on is untouched: HttpAccountKV used for device is still doubly refused — its false brand is not assignable to the true DeviceSafeKVStore requires (type), and the runtime check rejects the cast that would erase it. The brand is structurally unforgeable, not a flag the transport could set; and the injected device backend of a composite still demands the stronger, fully-local LocalKVStore, so composites cannot nest into a router loop with no local floor. Regression test (cosarah's ask): kvPersistStorage(httpKVStore, "device") set/get/remove reach the injected device backend, land device-scoped there, and make zero HTTP requests. Mutation-checked: widening the brand so HttpAccountKV is accepted, or neutering the guard, turns the device-out reject test red. * refactor(storage): scope #1002 down to KV — remove the asset HTTP backend Per the maintainer decision, the AssetProvider server design moves to the global-resource-pool RFC (#1007), where AssetRef changes from content-addressed to an allocated global id and the contract model itself changes. Continuing to harden the content-addressed asset client here would be work on code that is being replaced, so the asset half of #1002 is withdrawn and the PR is pure KV. Removed (all introduced by #1002): - docs/asset-http-contract.md - src/asset/http.ts (HttpAssetProvider) and its index / package.json exports - src/asset/content-ref.ts (assertAssetRef / computeAssetRef / the ref shape) - test/http-asset-provider.test.ts and the asset half of the conformance server Reverted to the #858 baseline, untouched: - src/asset/browser.ts — back to opaque resolve/remove, no assertAssetRef guard. This directly removes cosarah's latest asset finding: an opaque ref such as `bucket/path` no longer throws, restoring the DSL AssetRef-opaque contract. - test/asset-contract.ts, test/asset-browser.test.ts — 0-diff from origin/main. Kept (all KV): kv-http-contract.md, src/kv/* (HttpKVStore / HttpAccountKV / the DeviceSafeKVStore brand), the KV tests, and the KV conformance server — renamed kv-conformance-server.ts and reduced to KV routing over the shared harness framework (body caps, no-store, scope-channel and dot-segment guards, auth hooks). base-url.ts stays; KV still uses it. * fix(storage): treat KV keys as opaque; document account-sync prerequisites cosarah found the key validation we added for traversal defense breaks legitimate callers: DSL identifiers (stageId/sceneId/learnerKey) are unconstrained strings — verified, the DSL only requires typeof === 'string' — and app callers compose keys like `editor-current-scene:<stageId>`, so a valid stage id `stage/one` now throws in BrowserKVStore before localStorage. Fix, matching the asset-opaque precedent: a KV key is an opaque string again. The `/` and `\` rejection is removed from assertKVKey / assertKVKeyPrefix and from the conformance server. Traversal is defended by encoding, not rejection — the HTTP client already percent-encodes the whole key into one path segment, so a separator never opens a new segment on the wire, and the server stores the decoded key as a plain map key (bound value), never a path. `a%2F..%2F..%2Fb` decodes to the single opaque key `a/../../b`, which addresses one entry and traverses nothing; a raw unencoded `..` path produces extra segments that match no route (404). The rules that remain are only what encoding cannot cover and the transport cannot carry (empty, whole-key `.`/`..`, NUL, lone surrogate, length) — none producible by `prefix + id`. Tests: the shared suite now round-trips keys with `/`, `\`, `%`, `:`, spaces across both backends; a `stage/one` key round-trips through the real conformance server; the traversal input is proven to store as one opaque key and the raw path to 404. Mutation-checked: re-adding the `/` rejection reddens exactly the round-trip cases. Docs (kv-http-contract.md): - "A key is an opaque string" replaces the identifier-shape section — keys may contain separators; traversal is an encoding + server-bound-value duty. - Account settings sync now documents its security prerequisite next to the account scope: a deployment MUST provide real per-user isolation of stored rows and encryption at rest before enabling sync; the reference server is not that posture. - kvPersistStorage(device) doc corrected from LocalKVStore to DeviceSafeKVStore (the device-safe brand accepts the HttpKVStore composite; HttpAccountKV stays double-rejected). * fix(storage): close the scope/key/prefix contract gaps with a coverage matrix Three completeness gaps, nailed by an executable matrix so an untested channel/shape can't slip through the next pass rather than patched one by one. 1. Scope via a GET body was not rejected. `assertNoScopeChannel` covered the query and header, but the bodyless GET routes never read their body, so `GET /kv/keys` with `{"scope":"device"}` returned 200 []. Bodyless methods (GET, DELETE) now reject any request body up front — that is the channel a scope would hide in — and only `set` reads a body, checking it for a scope field. The DELETE route's own body check folds into the shared one. 2. The 512-byte key bound wrongly rejected legitimate keys. A DSL id is an unconstrained string (verified: the DSL requires only typeof === 'string'), and `editor-current-scene:` + a 500-char stage id is 521 bytes, which BrowserKVStore rejected before localStorage. Keys are length-unconstrained; the bound is raised to a generous 8 KiB DoS ceiling and documented as a resource guard, not part of the key domain — not a derived/hashed key, which would break the literal-prefix semantics of keys(prefix). Both backends and the conformance server move in lockstep. 3. The prefix contract text contradicted itself: it claimed a legal key can never contain a backslash, while the key section (correctly) makes keys opaque, backslash included. Reworded — a prefix is opaque like a key — and the shared literal-prefix matrix now covers `\` (PostgreSQL's LIKE escape), which it had skipped, alongside `%`, `_`, and combinations. Coverage matrix (CI-executable): - scope-rejection: {get,set,remove,keys} × {query,header,body}. query/header run in-process; the body cells use a raw HTTP client (fetch cannot put a body on a GET — exactly the non-conforming client the finding described) against a loopback listener, skipped where the sandbox forbids binding. - key-validity: `/ \ % _ : .` space, BMP + astral Unicode, `%2F`, a 500-char composed key, and all-at-once — each round-trips (set/get, keys(prefix) match, remove) on both browser and HTTP backends via the shared suite. - prefix-charset: `%`, `_`, `\`, and combinations match literally, both backends. - Boundaries still rejected: whole-key `.`/`..`, NUL, lone surrogate, empty, and the DoS ceiling. Mutation-checked: removing the bodyless-body rejection reddens the three GET/ DELETE body cells; lowering the ceiling back to 512 reddens the long-key round-trip on both backends. Bumps @openmaic/storage to 0.1.2 (src/kv/* changed). * fix(storage): bound the KV key DoS ceiling by encoded size, not UTF-8 bytes Follow-up to the 8 KiB ceiling: measuring it in UTF-8 bytes ignored percent-encoding expansion and reopened a backend-parity break. A non-ASCII key is small in bytes but large on the wire — `€` is 3 UTF-8 bytes and `%E2%82%AC`, 9, encoded — so `'€'.repeat(2730)` (8190 bytes, under the old cap) encoded to ~24.6 KB, which the Node HTTP server rejects with 431 before routing while `BrowserKVStore`, which never builds a URL, accepted it. The ceiling is now measured on `encodeURIComponent(key).length` — the size the key occupies as a request target — at 4096, far above any real id (a 500-char id under `editor-current-scene:` encodes to ~523) and well below Node's default 16 KiB `maxHeaderSize` (empirically the 431 trigger on Node 22), so no key that passes validation can reach a 431. Both backends and the conformance server use the same encoded-size limit, so a key is accepted iff its encoded form fits, whichever backend it reaches — parity restored. `MAX_KV_KEY_BYTES` becomes `MAX_KV_KEY_ENCODED_LENGTH`. Tests, against a real node:http server for the 431 boundary: - the max-legal non-ASCII key (455×€, encoded 4095) round-trips over real HTTP with no 431, and the browser accepts the same key — parity on accept; - one code point over (456×€, encoded 4104) is rejected by both backends at validation, before any request — the exact parity case a byte bound missed (1368 bytes, would have passed, then 431'd over HTTP); - a raw client bypassing client validation with an over-ceiling (under 16 KiB) encoded key gets a clean 400, not a 431. Shared suite's key-domain matrix now bounds by encoded size on both backends. Mutation-checked: reverting the ceiling to UTF-8 bytes reddens the three encoded-length parity tests. Bumps @openmaic/storage to 0.1.3 (src/kv/* changed). * fix(storage): make the KV key domain truly opaque; keep transport limits out The recurring key-limit findings (512 → 8 KiB → 4096, each patch exposing the next) shared one root cause: transport-driven rules kept being added to the key domain — the browser primitive included — breaking the "opaque unconstrained string key" contract. This is the structural fix, per cosarah: "keep HTTP transport limits out of the browser primitive and preserve the existing string key domain." Approach (a), the minimal one: a KV key is any string, validated nowhere. The browser primitive is a Map/Storage that stores any key; the HTTP backend carries the key as a URL path segment and inherits that transport's limits, documented as HTTP-deployment concerns that never constrain the key domain. Every real key (a `prefix:id` from an unconstrained DSL string) round-trips on both backends; only pathological keys hit a transport limit, and none of those are keys a caller produces. (b) — keys in the request body for accept-parity — was unnecessary: verified that no real key needs it. Removed from the key domain (browser + HTTP + conformance server): - the encoded-size / length ceiling entirely — there is no key-length limit; - the NUL exclusion — NUL percent-encodes to %00, is preserved end to end, and is a legitimate Map/Storage key (a false "cannot represent" premise); - the `.`/`..`/empty/`/`/`\` rejections — all opaque, all round-trip. `assertKVKey` / `assertKVKeyPrefix` / `MAX_KV_KEY_*` are gone. Kept, at the transport layer only (HttpAccountKV), never reaching the primitive: - an unpaired UTF-16 surrogate genuinely has no percent-encoding, so the HTTP client surfaces a clear transport error (KEY_NOT_ENCODABLE) while the browser stores the same key — verified: encodeURIComponent throws on it. Scope completeness (P2): the "reject scope in every channel" guarantee had two holes — a scope path segment (`/kv/device/keys`) 404'd instead of 400, and only `x-scope` was checked among header spellings. The server now rejects a scope path segment and the whole prohibited header set (scope, x-scope, kv-scope, x-kv-scope). The coverage matrix is {get,set,remove,keys} × {path, query, each header spelling, body}. Coverage matrix reworked to verify arbitrary opaque keys (empty, NUL, control chars, separators, long, Unicode) round-trip on both backends — not to verify a limit. A real node:http test proves NUL and long keys round-trip end to end, and that a lone surrogate is a transport limit (browser accepts, HTTP client errors). Mutation-checked: re-adding a NUL rejection, removing the path-segment check, or dropping a header spelling each reddens the matching cells. Cleanup: package.json description updated (KV HTTP delivered, not "later"); network-server bind/skip/close lifecycle deduped into one helper. Bumps @openmaic/storage to 0.1.4 (src/kv/* changed). * fix(storage): reject whole-key "."/".." in the HTTP client — they alias entries Follow-up to making the key domain opaque: removing the `.`/`..` key-domain rejection was right (the browser stores them fine), but the HTTP client then let them reach `fetch`, where URL path normalization silently rewrites the target before it is sent. `encodeURIComponent('.')` is `.`, so `/kv/entries/.` collapses to `/kv/entries/` (the empty key) and `/kv/entries/..` walks up a level — so `get`/`set`/`remove` on a whole-key `.` or `..` silently read, overwrite, or delete a *different* entry, with no error. A data-correctness bug. Fix, same pattern as the unpaired-surrogate limit already handled: a whole-key `.`/`..` is something the URL-path transport structurally cannot carry, so the client's path-segment encoder refuses it with `KEY_NOT_ENCODABLE` before a request is built. Split the encoder in two: `encodeKeyPathSegment` (key → path segment, rejects whole-key `.`/`..`) and `encodeComponent` (the `keys()` prefix → query value, where `.`/`..` are legitimate and untouched). A key that merely *contains* a dot (`a.b`, `prefix:id`) is unaffected and round-trips. The browser primitive still stores `.`/`..` opaquely. The HTTP transport's limits are now complete — three cases, all fail-loud at the transport layer, all storable on the browser: (1) an unpaired surrogate (no percent-encoding), (2) a whole-key `.`/`..` (URL normalization aliases it), and (3) an over-long key (deployment request-target ceiling). The contract lists all three as HTTP-deployment limits, not key-domain constraints. Tests: whole-key `.`/`..` — browser stores and round-trips (distinct from the empty key); HTTP client throws `KEY_NOT_ENCODABLE` and builds no request; and a real-server test asserts the empty-key entry is never read, overwritten, or deleted by a `.`/`..` operation. A dot-containing key (`a.b`) round-trips. Mutation-checked: dropping the whole-key check reddens the alias tests. Bumps @openmaic/storage to 0.1.5 (src/kv/* changed). * fix(storage): reconcile the settings/profile persist consumer with the KV API The integration merge (#1002 KV into main) surfaced two things the merge itself could not resolve mechanically: - `lib/store/kv-persist.ts` (added on main by #1001) called `kvPersistStorage(kv, scope)` with a *variable* scope, which #1002's overloads deliberately reject — `'device'` must be paired with a device-safe store, so the overloads take the scope as a literal. Branch on the scope: `'account'` takes any `KVStore`; `'device'` narrows the backend to `DeviceSafeKVStore` via its brand (the adapter re-checks at runtime) and otherwise fails loud. The app wires only `'account'` today; the `'device'` arm keeps the generic helper honest. `ControllableKV` in the persist test wraps a local `BrowserKVStore`, so it is genuinely device-safe and now declares the brand. - `packages/@openmaic/storage` version bumped 0.1.5 → 0.1.6: the merge changed storage inputs (README + a pg-schema test carried from main) relative to the previous integration tip, so the version-bump guard requires an increase above #1002's 0.1.5. Still ahead of main's 0.1.1. Verified: root `tsc --noEmit` clean, the persist test green (40 passed), and the storage package suite green on Node 22.	2026-07-30 22:31:17 -04:00
4 people	f378c25a53	feat(storage): route settings/user-profile persist through KVStore (no legacy migration) (#1001) ... * feat(storage): route zustand persist through KVStore The settings and user-profile stores persisted through zustand's default `localStorage` storage, while the rest of the app's small keyed values had already moved to `@openmaic/storage`'s `KVStore` — two unrelated mechanisms over the same browser API, which is the split-brain the storage RFC set out to remove. `kvPersistStorage` shipped with the package but had no importer. Add `lib/store/kv-persist.ts`, the app seam that adapts a `KVStore` into a zustand `PersistStorage`, and wire both stores to it under an explicit `account` scope. Store logic is unchanged: `version` / `migrate` / `merge` still belong to the stores, only the bytes' destination moves. Existing installs are adopted rather than orphaned. On first read the seam moves the raw `localStorage` entry into the KV scope — write first, then drop the raw key, so an interrupted migration leaves the value readable from one side or the other but never from neither. Once KV holds the entry it is authoritative, so a stale raw entry reappearing cannot roll back newer state, and re-running can neither duplicate nor resurrect anything. An entry that is not a readable persist envelope is left exactly where it is. Hydration is now asynchronous, because a `KVStore` may be remote. The browser backend resolves within a few microtasks of the store module being evaluated, so nothing user-visible changes, but tests that assert on persisted state now await `persist.rehydrate()` instead of relying on a synchronous read. The four pre-persist keys (`llmModel` / `providersConfig` / `ttsModel` / `selectedAgentIds`) are deliberately untouched: they are read-only inputs to a migration that never owned them, and `providersConfig` is still read independently by `lib/ai/providers.ts`. Part of #857. * fix(storage): close the async-storage failure modes in the KV persist seam Cross-review found that routing `persist` through an asynchronous store opens failure modes a synchronous `localStorage` never had. Each one below is now covered by a test that fails without its fix. Data loss on a failed or empty hydration. A KV read that threw was indistinguishable from an empty scope, so the store stayed on defaults while an always-on initializer's `set()` persisted those defaults; the next load then read them as a completed migration and deleted the raw original, leaving nothing. Reads now separate "nothing there" from "the backend could not answer": a failed read serves the raw entry read-only, adopts nothing and deletes nothing, and leaves the key unwritable for the session so no un-hydrated state can be persisted over an original. Raw entries are additionally only dropped against a recorded completion marker, so a KV entry of unknown provenance can never authorize deleting the only copy of the user's data. Lost adoption across tabs. A reader whose KV read answered before another tab's adoption write, and whose localStorage read landed after that tab's delete, saw nothing in either place and hydrated defaults. Against a remote backend that interleaving is ordinary rather than rare, so an apparent "nothing anywhere" is now re-checked before it is believed. Out-of-order writes. Two rapid `setItem`s could complete in either order and let the older value win. Reads and writes are serialized per key. Pre-persist migration resurrecting on every load. `migrateFromOldStorage` was guarded by the existence of the raw `settings-storage` key — the very key the migration removes — so once the blob moved into the KVStore it ran on every load and republished whatever the pre-persist keys still held, including API keys the user had since deleted, into first-frame state. It is now the persist layer's last-resort source instead of a synchronous read in the store initializer: its result is adopted like any other migration, so the adopted entry is the marker that stops it. Initial state is plain defaults, and nothing stored reaches observable state before the storage layer has vouched for it. The source keys are still only read, never deleted, since `lib/ai/providers.ts` remains a reader. Also: KV reads and writes are guarded so a corrupt entry surfaces instead of throwing through zustand's silent catch; clearing the cache now clears the migrated stores through their own storage, which a server-backed scope would need and a blanket `localStorage.clear()` would only appear to do; `removeItem` drops the KV copy before the raw one; and the e2e suite gains post-migration steady-state coverage, which every existing spec missed by seeding the pre-cutover key. Part of #857. * fix(storage): scope migration bookkeeping to the device, gate writes on call Second review round. The findings shared one root cause: two of the three sentinels recorded a fact about *this machine's* files but were stored beside the data, in the store's own scope. Under a syncing `account` backend that is a category error with teeth — one device's history would travel to another and authorize deleting files it says nothing about. Sentinels are now always `device`-scoped and carry a reserved `__` prefix, whatever scope the store uses. The worst combination this closes: device A migrates, its marker syncs, device B — which has never run this build — loads and deletes the raw entry that is still the only copy of its own settings. A test drives exactly that sequence against two devices sharing one account scope and nothing else. The pre-persist fallback gains a device sentinel of its own. Its source keys are device-local and deliberately left in place, so "KV and raw are both empty" was not a safe trigger: clearing the account entry, from the cache button or a server-side wipe, let any device re-read those keys and republish credentials the user had rotated. It is now consulted at most once per device, and `removeItem` deliberately does not clear that sentinel — clearing the entry is precisely the case it exists for. The fallback also no longer writes the adoption marker: that marker is a licence to delete a raw persist entry, and the fallback has adopted no such thing. Were it written, a raw entry later restored by an older bundle would be deleted unread. The write gate is now read when `setItem` is called rather than when its queued turn arrives. Evaluated inside the queue, a write issued during hydration waited behind `getItem`, found the gate opened by the very read it raced, and persisted its pre-hydration snapshot on top of the stored value. Refused writes are no longer a dead end: the first one asks the store to rehydrate, since the backend may have recovered, and if that does not work the user is told through a durable notice rather than losing every change on reload. Each refusal is logged, not just the first — a once-per-session warning hides how long a session has been silently unsaved. `removeItem` now propagates backend failures, so clearing the cache cannot report success for a clear that did not happen, and that flow reloads immediately instead of leaving a window in which a background `set()` re-persists the credentials just deleted. Also: the recovery hook is bound after each store is constructed, because naming the store inside its own definition made its type circular and silently widened every selector to `any`; the `serial` comment no longer claims an unreachable rejection handler; and the pre-persist version stamp documents that it skips `migrate`'s unversioned normalization too, which `merge` redoes anyway. Part of #857. * refactor(storage): make the KV persist seam a per-key state machine Three review rounds kept turning up the same defect class in new places: a backend failure read as "there is nothing there", and the result of an operation that nobody looked at. Patching instances of it was not working, because both are possible whenever a call site is free to decide for itself what a failed operation meant. This makes that decision unavailable to call sites. Every backend call now returns an `Outcome` whose payload is a private field and whose only reader demands a `KeyState`. Feeding the machine is not a convention to remember; it is the only way to get the value out. What comes back is the value or `UNAVAILABLE` — deliberately not `null`, so "the backend could not answer" is not spellable as "nothing is there". The machine then decides, in one place, what failure means: any read failure is unavailability, any write failure closes the key, and either raises the health signal and asks for recovery. The scattered closure flags (a settled set, a warned set, a recovery latch) become one explicit phase per key — unhydrated, settled, unavailable, clearing — with the transition table written out in the docstring and a test per row. What that consumes: - A write failing after the key settled used to be ignored; its outcome now closes the key, signals, and the value is remembered for replay. - `removeItem` enters `clearing` synchronously at call time, so a `set()` racing a clear cannot be admitted, queue behind the delete, and write the just-deleted value back. Nothing is replayed across a clear. - The pre-persist sentinel is recorded by *every* settling path, not only the one that consults the old keys. A device that had only ever loaded an already-populated account entry recorded nothing, and so stayed eligible to republish its own stale credentials the moment that entry was cleared — which the docstring already claimed it would not. - Two places treated a failed read as an answer: the sentinel read that decides whether the fallback runs, and the confirming re-read before adopting. Both now stop. - An adoption whose marker did not land no longer settles, and never deletes the raw entry: no proof, no licence. - Refused and failed writes are remembered and replayed once storage recovers, but only when the store was holding real data at the time — replaying a snapshot taken over defaults would overwrite the stored value, which is the failure this seam exists to prevent. When a snapshot cannot be replayed the user is told, because rehydration is about to discard those edits. - Health notices publish on a later task, so a recovery that lands moments later cancels a warning nobody should have seen, and a subscriber mounting after the failure is caught up once its toast host exists. `StorageHealthNotice` now sits after the `Toaster` for the same reason. Also: adoption re-reads before committing so a concurrent write is not rolled back; a shadowed raw entry is only deleted if it parses, matching the promise never to delete bytes we could not read; the unavailable copy points at the control that resolves it rather than suggesting a reload that cannot; and the version pin, the pre-persist retention rationale, and the cache-clear comment say what is actually true. Part of #857. * fix(storage): separate the contexts settle() was conflating Convergence round on the state machine. The findings share a root: settle() treated every read that concluded as licence to open the key, without asking what else was true at the time. - A read finishing while a clear is outstanding no longer settles. Under a remote backend a recovery rehydrate in flight during a clear is ordinary, and opening the gate there admits a write that queues behind the pending delete and restores the credentials just removed. Only finishClear opens a cleared key. - The raw entry served read-only after a failed read no longer counts as the authoritative value. A shadowed raw entry is by construction the older copy — long-term coexistence with a newer KV value is a designed state — so an edit taken against it must never be replayed, or one transient read failure on one device rolls the whole account back. - A write that lands supersedes an earlier failed one. Both were admitted before the key closed, so the queue ordered them; replaying the older snapshot on recovery would undo the newer value. - Unreachable browser storage is a failure, not an empty store. Privacy modes make localStorage throw; treating that as "nothing stored" hydrated defaults, refused every write and said nothing until the user reloaded and found the work gone. SSR stays a silent no-op. - The recovery latch re-arms when storage answers, so the three recovery transitions are not empty promises from the second failure onward. - A refusal carries the phase it happened in. Cold-start timing — an always-on initializer writing before the first read resolves, on a backend that never failed — is a log line, not a sticky red toast; only a refusal under `unavailable` reports lost changes. The health channel stops delivering stale catch-ups: its timers are cancellable and re-read the current state when they fire, so a recovery cannot be overtaken by a warning with nothing left to dismiss it. And `changes-lost` is now a fait accompli rather than a condition — a later recovery has nothing to retract and leaves it standing. Also: a throwing `localStorage` is unavailability rather than absence wherever the raw entry is read; clearing records the pre-persist sentinel like every other settling path, making that docstring true; the raw entry is dropped before the marker so a failed marker clear leaves something inert; and the pre-persist fallback and its four source reads can no longer throw into zustand's silent catch. Part of #857. * fix(storage): hold a replay until it lands, and prove a raw copy before deleting it Three failure-path corners. A replay was retired the moment its write was attempted. Readable but not writable is a real state — a quota-exhausted backend answers reads perfectly — so a recovering read could succeed, the replay write fail, and the snapshot be gone with nothing owed: the next rehydrate served the older stored value over the user's edit and said nothing. The snapshot is now held until the write is durable; a failed replay goes back to being a refused write, so the next recovery tries again and a permanent failure is eventually reported. The adoption marker was treated as proof that a raw entry is the migration's leftover. It proves only that a migration happened on this device once. A rolled-back deployment, or a tab still running the old bundle, writes the raw key again with settings the migration never saw, and the next load on the new bundle deleted them unread. A raw entry is now dropped only when its content equals the value shadowing it — anything else is data, and keeping a copy beats deleting an original here as everywhere else in this file. `changes-lost` was being cancelled by a later recovery. The two statuses answer different questions: "storage is down" describes the world now and stops being true when storage works, while "your edits were lost" describes something that already happened and no amount of recovery undoes. They are now tracked on independent lines per key and rendered as two toasts with distinct ids, so retracting the fault cannot take the acknowledgement with it; the loss notice goes away only when the user closes it. Part of #857. * fix(storage): bound recovery, keep a live store from walking backwards Three interactions the state machine did not have an answer for. Recovery had no budget. A backend that reads but cannot write — a quota-exhausted one does exactly that — turned it into a treadmill: the recovering read succeeds, the key settles, the replay write fails, and that failure asks for recovery again, forever. Attempts now follow a backoff schedule whose length is the cap, and the budget is re-armed only on real progress: a settle that left nothing owed. A settle reached *by* a recovery with a replay still queued is not progress, and counting it as such is precisely what made every lap look like a fresh start. When the budget runs out the key is left read-only and the loss is reported, rather than retrying where nobody can see it failing. A failed read could walk a live store backwards. Once a session has loaded the authoritative value, a transient read failure was still falling back to the shadowed raw copy — which is legitimately older, and legitimately long-lived now that a differing raw entry is kept rather than deleted — and handing it to zustand overwrote a live store with stale data. Worse, the store had already latched "holding real data", so edits made on top of that stale value counted as replayable. A failed read after an authoritative one now returns nothing, which is exactly "keep what you have", and the raw fallback stays where it belongs: the case where nothing authoritative has been seen at all. Dismissing a lost-changes toast only closed the UI. The key stayed in the lost set, so the same store losing changes a second time was swallowed as a duplicate and any later subscriber resurrected a notice the user had already dealt with. The close button now clears the latch, so a second loss is reported and an acknowledged one stays gone. Part of #857. * fix(storage): close the last two provisional and clear-ordering gaps An abandoned migration was handing back an authoritative value. When the confirming re-read fails, or the adoption write does, `adopt` returns the raw envelope unadopted — the same footing as the raw copy served after any other failed read — but it was returned bare, so the store latched "holding real data" and an edit taken on top of it counted as replayable. Another device publishing to the account scope in that window would have been rolled back. `adopt` now reports provisionality like every other read path, and the shape is a named `LoadedValue` so the next path cannot forget. Clearing swallowed a failed raw-entry deletion. The account entry was already gone by then and the marker was cleared afterwards, so the operation reported success while leaving an empty scope beside a live raw entry — precisely the shape the next hydration re-adopts, handing back the settings the user had just deleted. The raw entry now goes first and its failure propagates, which also fixes the ordering: failing before anything is removed leaves the KV value authoritative and the clear simply unperformed, which the caller can retry. Adoption keeps the tolerant variant, where a leftover raw entry is a duplicate rather than a loss. Part of #857. * fix(storage): make the shadowed-raw delete atomic against a concurrent tab cosarah reproduced a data loss: both raw-entry deletes verified the value, then awaited (reading or writing the adoption marker), then removed the key by name. A tab running an old bundle — which takes no Web Lock, so a lock could not have helped — overwrites the raw key with newer settings during that await, and the unconditional `removeItem` then deletes the newer value. The raw side is synchronous `localStorage`, so the fix needs no lock. Both deletes now finish every await first, then run a single synchronous compare-and-delete: re-read the raw bytes, and remove only if they still equal the exact string that was verified. A competing tab is a separate context whose writes surface here only at event-loop boundaries, so its write lands wholly before the re-read (seen — bytes differ — kept) or after the remove, never in between. A changed value is newer data, not a migration leftover, and is kept. Both sites cosarah named are covered: the shadowed-cleanup path (`dropShadowedLegacy`) and the adoption cleanup in `adopt`. `readLegacyEntry` now carries the exact bytes alongside the parse so the re-check is byte-exact rather than comparing a re-serialized value. The clear path's delete is unchanged: it is a deliberate full delete, not a conditional leftover cleanup. Part of #857. * fix(storage): stop deleting the raw entry — adopt by copy (Plan B) Maintainer decision after cross-vendor + red-team review: `localStorage` has no cross-process atomic compare-and-delete (the storage mutex was dropped from the spec), so a tab on an old bundle can insert a write between our re-read and our removeItem in a genuinely parallel process. The synchronous compare-and-delete narrowed that window but could not close it — as its own comment admitted. Since the raw-cleanup cannot be done safely on localStorage while an old bundle may be live, this stops doing it. Adoption is now a copy: the value is written to KV and the raw entry is left in place. The delete race is therefore impossible — there is no delete. KV stays authoritative (once it holds the value, reads take the KV path and never consume the raw one), so the shadow duplicate is inert, left for a wholesale raw-cleanup at migration exit. Removed with the two deletes: - `dropShadowedLegacy` (its only job was the gated delete) and its three call sites. - `deleteLegacyIfUnchanged` and the `{raw,value}` shape of the legacy read (`readLegacyEntry` → back to `readLegacy` returning the value). - The adoption marker (`__persist-adopted:`), whose only reader was that delete gate. It did not prevent re-adoption — the presence of the KV value does — so removing it breaks no invariant. `dropRaw` / `expectedRaw` on `adopt` and the marker-clear step in the clear path go with it. The clear path (user deletes all data) still deletes the raw entry strictly — that is a deliberate full delete, not a migration cleanup. Tests: the delete/marker cases become "the raw shadow always survives, KV is authoritative"; a two-device and an old-bundle-concurrent-write case guard it, and re-adding a delete on either adoption path turns them red. Part of #857. * fix(storage): add a monotonic migrated marker to stop shadow resurrection Cross-vendor + red-team review independently caught a P1 the previous "adopt-as-copy" revision introduced. Because the raw entry is now kept and writes only ever reach KV, the raw copy becomes a frozen pre-cutover value. If the account KV is later emptied by something other than a local clear — a server-side wipe, an account switch, KV eviction — the next load saw `stored === null` beside a live raw entry and re-adopted that stale copy, refilling the wiped account with ancient settings/credentials and syncing them to every device. Deterministic, not a race; it would fire once a server-backed account backend exists. Root cause: "keep the raw entry" inherently requires a record that it has already been migrated, so an empty-KV load can tell "first migration" from "external wipe". Removing the old delete-authorization marker in the copy revision dropped that record — Plan B was only half done. Adds a monotonic, device-scoped `__migrated:<name>` marker: - Read on every load. `stored === null` + raw present + marker set ⇒ respect the wipe, do not adopt (fall through to the confirm re-read, so a concurrent repopulation is still served). Only a genuine first migration (no marker, raw present) adopts. - Written best-effort after a successful KV write. A failed write degrades to the KV value's own presence check, so resurrection needs both a failed marker write and a later external wipe. - Read failure fails closed (do not adopt), never "assume not migrated". - Monotonic: only ever set true, cleared only by a deliberate full clear — no compare-and-delete race, which is why it is safe where deleting the raw entry was not. Live state with a real reader, not the delete-authorization marker removed earlier. The clear path clears the marker too (back to a genuine first-load state); best-effort, since with the raw entry already gone a leftover marker is inert. Tests: resurrection guard (external wipe does not re-adopt; concurrent post-wipe write is served; first migration records the marker; marker read fails closed) + the clear-path marker clearing. Mutation-checked: removing the gate resurrects the shadow, dropping the record leaves it unguarded. P3: the inert `__persist-adopted:` test rot is retargeted to the real `__migrated:` path. Part of #857. * refactor(storage): remove automatic legacy migration — pure KV wiring Maintainer decision (terminal): after repeated review rounds kept finding new P1s in the legacy-adoption path — its state space is too large to keep correct — the PR is narrowed from "migrate + wire" to "wire only". Settings and user-profile persist through the KVStore; pre-cutover data is not migrated; an upgrading user reconfigures once (the data is reconstructable and the cost is one-time). Removed the entire legacy-adoption subsystem from the adapter: - `adopt()`, `readLegacy()`, the `legacyStorage` dep, and the raw-fallback read on a failed KV read. - The `__migrated:` marker and its resurrection guard, the confirm-re-read, and the `provisional`/`LoadedValue` machinery. - The `prePersistFallback` dep, `recordPrePersistHandled`, the `__pre-persist-consulted:` sentinel, and `readSentinel`/`writeSentinel`. - In settings.ts, `readPrePersistSettings` (the llmModel/providersConfig reader wired as that fallback) — reading legacy keys is migration, which this PR no longer does. `lib/ai/providers.ts` still reads `providersConfig` independently, so those source keys are left in place. The adapter now reads and writes the KV scope and touches no legacy key: an empty scope hydrates the store to defaults (ordinary zustand). `load()` is a single KV read; a failed read stays unsettled so defaults are never persisted over an unread value; the clear path removes only the KV entry. Kept, because they are async-storage *steady state* a remote KV backend needs, not migration scaffolding: the KeyState machine (hydration gate, write gate, recovery, replay), the Outcome discipline, per-key serialization, and the persist-health channel. Added `purgeLegacyPersistKey`: a best-effort, fire-and-forget removal of the old raw persist blob, called once by each store. Never read, so a leftover is pure garbage — and the old settings blob held plaintext provider API keys, so clearing it is a small security win. Net: the adapter drops ~460 lines. Tests are rewritten to steady-state KV coverage plus an explicit "old raw key is ignored, not migrated" proof at the store level; the e2e seed fixtures move from the raw key to the KV scope key. Part of #857. * docs(storage): align README and comments with the no-migration behavior Follow-up requested on the approved PR: the migration/adoption logic was removed, but a few comments and one README roadmap line still referred to those deleted concepts. Documentation only — no behaviour change. - README roadmap: the settings/user-profile line said "adopting their pre-cutover raw keys"; it now states there is no automatic migration (legacy keys ignored and best-effort purged, users reconfigure once). - kv-persist.ts: the per-key serial chain comment no longer claims to keep "adoption" from interleaving; it serializes a key's read/write/clear. - settings.ts: `SETTINGS_PERSIST_VERSION` no longer documents a "pre-persist fallback" that no longer exists. - Test/fixture headers that described seeding "the pre-cutover raw key" for "one-time adoption" now describe seeding the KV `account` scope, with no legacy-key migration. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(storage): bump version to 0.1.1 for README doc alignment The README is a publishable input, and the no-migration doc alignment changed it, so the package version must increase. Patch bump: documentation only, no code or API change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com> Co-authored-by: wyuc <zdq1204@gmail.com>	2026-07-30 15:12:51 +08:00
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
xuyuanwei678	f4c1b46642	fix(importer): handle custom shapes without paths (#1015)	2026-07-30 10:53:45 +08:00
sophietao20-star	0cf2a33041	docs: refresh and synchronize documentation (#996) ... Refresh the Chinese documentation against current functionality, synchronize all localized guides, document deployment and configuration behavior, and align the PPTX import feature flag implementation.	2026-07-27 22:45:15 -04:00
xuyuanwei678andwyuc	ff95e6683d	feat(renderer): add optional playback canvas (#958) ... * feat(renderer): add optional playback canvas * style(renderer): format playback tests * fix(renderer): center text by default * fix(renderer): address playback review feedback * docs(renderer): align playback canvas API docs --------- Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>	2026-07-27 04:15:07 -04:00
杨慎andClaude Opus 4.8	6d29241bb0	feat(video-export): fidelity polish — spotlight geometry, video clips, formulas, subtitles (#952) ... * fix(video-export): bridge play_video element id → media ref Generated-media records are keyed by the element's media ref (gen_vid_…), but a play_video action targets the slide element by its .id. The app-side compiler deps looked media/durations up by the raw element id, so every generated video missed → present:false → no <video> emitted, no bytes collected → the clip vanished from the export (only its static first frame, baked into the base PNG, remained). Build an elementId → mediaRef bridge across all slide scenes in createVideoTimelineDeps (mirroring the live engine's resolveMediaPlaceholderId) and resolve both media() and videoDurationMs() through it. Refs #867. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): re-measure KaTeX fit-scale after fonts settle KaTeX sizes large delimiters (\left\{, \begin{cases}) from its KaTeX_Size faces, which load asynchronously. KatexContent measured its shrink-to-fit scale once on mount, against the fallback font, and never recomputed — so a cold slide snapshot baked a stale scale and the big brace desynced from the piecewise body ("大括号后面的分段函数与大括号错位"). - Re-run the fit-scale measurement on document.fonts.ready and on each `loadingdone`, keeping the shrink-only (cap-at-1) behavior. - slideToPng waits two extra frames before capture so the font-triggered React re-measure commits into the DOM html2canvas reads. Refs #867. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): place spotlight/laser/video on the rendered content box The pure geometry helper resolves an element's authored outer box against a fixed 1000×562.5 base, but the live overlays — and the exported frame PNG — measure the element's `.element-content` box, which for horizontal text is auto-height plus 10px content padding. So a spotlight/laser sat offset from where the text actually renders ("spotlight 与对应元素的位置有偏差", #867 item 5). Add an optional GeometryProbe to the compiler's DI boundary: when supplied, the geometry pass prefers each element's measured content-box geometry (video keeps its rotation from the authored element), degrading to the pure authored-box calc on a miss so the compiler stays deterministic in unit contexts. App side: measureSlideElementGeometry (new, in @openmaic/renderer/snapshot) mounts the slide off-screen and reads the same `.element-content`-against- container box the live SpotlightOverlay uses; createVideoTimelineDeps pre-measures every spotlight/laser/play_video target per scene and serves the probe as a synchronous table lookup. Tests: geometry.test.ts quantifies the outer-box vs content-box delta and proves probe-wins / fallback / rotation-preservation; timeline-deps.test.ts covers the pre-measure wiring. Refs #867. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): decode a first-frame poster for posterless videos A play_video clip only shows during its play window; the rest of the time the static base-frame PNG backs that spot. But html2canvas can't draw a <video>, so the snapshot swaps it for its poster <img> — and generated videos usually carry no poster, leaving the video area blank whenever the clip isn't playing. When a video record has no stored poster bytes, decode the video blob's first frame (seek slightly off 0, draw to a canvas) and set element.poster before the base snapshot, so that spot shows the first frame — the "paused on frame one" look — instead of blank. Falls back to no poster on decode failure / timeout / CORS taint, never failing the export. Refs #867. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(video-export): split subtitles, make burn-in optional, centered modal Burned-in captions used one cue per whole narration paragraph, so a long cue became a 4–6 line block covering the lower half of the slide, and there was no way to turn it off. - Split cues (pure, compiler layer): lib/video-export/split-cue.ts splits each cue on sentence → clause → hard-wrap to ≤~40 CJK-equiv units, distributing the parent window by character weight (last piece pinned to the parent end, sub-1.2s slivers merged). Wired into the timeline pass, so the burned-in overlay and the SRT/VTT sidecar share one split track and can't drift. - Burn-in optional (default off, #867 item 2): emitHyperframes gains burnInSubtitles; off → clean video + sidecar SRT/VTT only. Caption layout hard- clamped to 2 lines so an outlier can't grow tall again. - Download subtitles without rendering: compileSubtitles() runs only the compiler (no assets/zip/service); new useDownloadSubtitles saves an .srt. - Centered modal: video-export-dialog.tsx replaces the cramped dropdown section, grouping Output / Subtitles / Actions / Progress with a stable lifecycle for multi-minute renders. header-controls opens it from an "Export Video" entry; old video-export-menu.tsx removed. i18n keys added across all 8 locales. Refs #867. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style: prettier format video-export fidelity changes Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test: drop unused playVideo helper in timeline-deps test The media-bridge tests assert via deps.assets.media(...) directly, so the playVideo helper (and its PlayVideoAction import) were dead. Flagged by the code-quality bot on #952. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): resolve cross-review findings + lower subtitle band - emit-hyperframes: drop duplicate `display:-webkit-box` on subtitle cues so they start truly `display:none` (a second declaration overrode the `none`, showing every cue stacked at t=0 when burn-in was enabled). - geometry: don't feed the measured content-box AABB to a rotated video clip — it already encloses the rotation, so re-applying `rotate` doubled it. Rotated elements fall back to the authored box (one, un-doubled source of truth). - build-export-zip: extract shared `compileStageIr` so buildExportZip and compileSubtitles can't drift on the timing/assets/geometry wiring. - split-cue: join merged CJK cue pieces without a spurious ASCII space. - subtitles: lower the caption band (bottomRatio 0.055 → 0.01) and hoist the band's magic numbers into a named SUBTITLE constants block. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): stop the snapshot onclone override from reshaping KaTeX The export snapshot injects a neutral-kerning / geometricPrecision style over `.slide-renderer-prose *` to keep CJK prose+table glyphs from mis-advancing under html2canvas-pro. KaTeX formulas (output:'html') also live inside `.slide-renderer-prose`, so the override was reshaping their math glyph advances — a burned-in formula rendered subtly differently from the live canvas, which applies no such override. Empirical check (Playwright + system Chrome, cases+fraction formula, native paint vs html2canvas): the override raised the formula's mean per-pixel delta vs the live paint from 120.1 to 139.2 (~16%) and moved ~75% of inked pixels. Restoring native font-kerning/text-rendering for `.katex` subtrees brings the formula's delta back to 120.1 (bit-identical to the no-override capture) while prose and table text keep the override. The residual 120.1 is the deeper html2canvas rasterization gap (vlist/frac-line/delimiter), a separate track. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): render slides via native paint, bundle KaTeX font embed Root-fix the exported-vs-live formula distortion (and the filter/mask/video gaps) by rasterizing slides with native Chrome paint instead of html2canvas's reimplementation. - slideToPng now captures via html-to-image (foreignObject → the same Chrome engine that paints the live classroom rasterizes the same DOM). KaTeX formulas, CSS filter, soft-edge masks, and mixed CJK/Latin text come out as the classroom shows them. html2canvas-pro stays as a fallback (with the filter/mask bakes + KaTeX text-rendering reset) for when native paint can't run — e.g. a cross-origin image taints the canvas. - A foreignObject SVG can't reach the document font registry, so fonts must be inlined. KaTeX math faces are prepended from the bundled woff2 (KATEX_FONT_EMBED_CSS, generated by scripts/generate-katex-fonts.mjs), NOT left to runtime getFontEmbedCSS — which reads cssRules and silently drops a cross-origin KaTeX stylesheet, collapsing a large brace to a fallback glyph (the observed "formula render failure" on e.g. a \begin{cases} with \text{}). A per-face guard verifies every KaTeX face the formula references is embedded, falling back to html2canvas otherwise. Verified in a Playwright spike (native vs html2canvas vs html-to-image): formula inked-delta 143→53; filter/mask/video match native; and with getFontEmbedCSS forced empty, the bundled embed alone still renders the failing formula correctly. Renderer package tests: 226 passed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): prettier-format the generated KaTeX font-embed module The generator emitted an unformatted TS file (double quotes, long unwrapped CSS literal) that failed CI `prettier --check`. Run the generated output through the repo's Prettier config before writing, so every rebuild produces CI-clean, stable output. Regenerated the committed file to match. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(lint): rename reserved `module` var in katex-fonts generator; ignore .scratch - generate-katex-fonts.mjs assigned to a variable named `module`, tripping @next/next/no-assign-module-variable (the one hard eslint error). Renamed to `fileContents`; generated output is byte-identical (deterministic). - Add `.scratch/**` to the eslint globalIgnores (alongside .claude/.worktrees) so local throwaway verification scaffolding doesn't pollute `pnpm lint`. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): address PR #952 review — scene-scoped media bridge, safer cue splitting Resolves the two blocking correctness issues and three follow-ups from the cross-review on #952. - Scope the elementId→mediaRef bridge by scene (was deck-wide/last-writer-wins): slide-local ids like `video_001` now resolve within their own scene. `assets.media` uses its scene arg; `timing.videoDurationMs` resolves via action object identity. Adds a cross-scene collision test. - Stop treating every ASCII period as a sentence boundary: a lone `.` splits only when not between word chars (3.14, v1.2) and not an abbreviation dot (e.g.), collapsing repeated-punctuation runs. Adds decimal/version/abbrev/ellipsis tests. - Share the module-level in-flight guard across ZIP export and subtitle download (extracted to export-in-flight.ts); dialog `busy` folds in `downloading`. - Skip the off-screen geometry render for the subtitles-only path (skipGeometry); duration probes are kept so sidecar cue timing stays in sync with the video. - Align measure.ts font settling with slideToPng: force-load each used face before fonts.ready so measured content-boxes don't bake fallback advance widths. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(video-export): prettier-format split-cue test Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * perf(video-export): enable beginFrame capture via PRODUCER_BROWSER_GPU_MODE=hardware The producer defaults to `software` GPU mode, which silently force-enables the CPU-bound `Page.captureScreenshot` fallback: SwiftShader pins every core on rasterization and caps frame capture at ~10 fps. Selecting `hardware` keeps Chromium's `HeadlessExperimental.beginFrame` capture active instead. Measured on a 900-frame (30s) clip, no real GPU on the host: - capture ~10 -> ~19 fps, total 100s -> 62s (~38% faster) - CPU peak ~810% -> ~98%; peak mem 2.2 GiB -> 0.9 GiB - static frames pixel-identical; animation frames differ only in sub-pixel edge antialiasing (same-path re-render is deterministic/inf PSNR) No real GPU is required — the win is the faster capture API, not hardware rasterization; beginFrame falls back gracefully if the host lacks a GPU. Also eases the RENDER_JOB_DEADLINE_MS timeout risk on long videos. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(video-export): sentence splitting via Intl.Segmenter + abbreviation merge Addresses the PR #952 follow-up: separate sentence-boundary detection from cue shaping and stop growing a custom punctuation heuristic. - splitSentences now delegates boundary detection to Intl.Segmenter (locale- agnostic ICU), the multilingual/CJK baseline. It already preserves 3.14, v1.2, e.g., U.S., ellipses, and CJK 。！？… without any hand-rolled period scan. - ICU still ends a sentence after a titlecase abbreviation before a capitalized word (Dr. Smith, Fig. 3) — the edge case the reviewer flagged. A small abbreviation-aware post-merge re-joins those, driven by an ABBREVIATIONS set. - Semicolons are no longer sentence ends (they join clauses); moved ；; into the clause-level SECONDARY splitter so over-budget sentences still break there. - Cue shaping (budget / clause / hard-wrap / weighted timing) is unchanged, so detection and shaping are now distinct stages. Not using `sbd` as suggested: lib/video-export/*.ts sits behind the machine- enforced eslint purity boundary (imports limited to @openmaic/dsl, zod, ../choreography, siblings), so a new npm dep is rejected. Intl.Segmenter is a pure Node >=20.9 builtin, matching the reviewer's "small abbreviation-aware post-merge layer" alternative. Tests: add Dr. Smith / Fig. 3 / U.S. coverage; the rhetorical ellipsis now stays one under-budget cue (was split); add a semicolon over-budget case. 22/22 pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(video-export): prettier-format split-cue sentence refactor Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * i18n(es-MX): add 7 subtitle/video export keys to align with en-US main added the Spanish (Mexico) locale (#942) after this branch's subtitle keys landed, so es-MX was the only locale missing export.subtitles* and export.videoBurnSubtitles* — which failed the i18n key-alignment CI check. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(video-export): restrict title post-merge so it never deletes real boundaries Addresses the blocking re-review on the Intl.Segmenter change: the abbreviation post-merge unconditionally rejoined the next ICU segment whenever the previous one ended in a listed abbreviation, which erased genuine sentence boundaries — `It was made by Acme Inc. Next point.` collapsed into one cue, and even an explicit newline (`Acme Inc.\nNext topic`) was rejoined. The merge now fires only for the case ICU actually mis-splits — a title (Mr/Mrs/Ms/Dr/Prof/Sr/Jr) before a capitalized proper noun — and only when: - the previous segment does not end at a newline (hard boundary), and - the next segment starts with a capital letter. Sentence-trailing abbreviations (Inc./Ltd./etc./vs./No.) are dropped from the set entirely: they legitimately end sentences, and ICU already keeps a title before a number (No. 5, Fig. 3) or a lowercase continuation (etc. and…) whole without any merge, so nothing there needs rejoining. Regression tests: Inc./etc. boundary preserved, newline-after-title preserved, lowercase continuation kept whole, plus the retained Dr. Smith / Fig. 3 / U.S. cases. 26 split-cue tests pass; full video-export suite 123 pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-27 02:58:04 -04:00
3 people	b4e3145c90	feat(roster): single-source the generated agent roster on the stage document (#994) ... * feat(roster): single-source the generated agent roster on the stage document The generated agent roster used to live in two places at once: the stage document carried generatedAgentConfigs, while a per-stage IndexedDB mirror (db.generatedAgents) was the actual read authority — and the only home of each agent's voice binding. The split caused real losses: voices vanished on device switches, exports, and shares (the mirror never travels), the load path trusted a device-local table over the portable document, and roster edits persisted through a bespoke debounce with no beforeunload flush. Make the stage document the single source of truth: - Contract: add optional voiceConfig/voiceDesign to GeneratedAgentConfig in @openmaic/dsl (VoiceDesign moves into the contract; the app re-exports it). Additive optional fields — not a breaking serialized-shape change, so DSL_VERSION stays put per the version policy. - Writes: remove every mirror writer (registry saveGeneratedAgents, the stage store's debouncedSaveAgents bypass, classroom-load hydration, import direct writes). setStageAgents now only marks the stage dirty for the shared persistence scheduler plus synchronous in-memory registry/selection mirrors; generation and import embed the roster on the stage. - Reads: classroom load hydrates the registry from the loaded stage's generatedAgentConfigs; export reads the stage roster directly. - Lazy migration: the mirror is retained read-only. On load, a roster (or voice fields) missing from the document is backfilled from the mirror, committed onto the in-memory stage, and persisted by the next flush — idempotent, and gated on the current stage id after every await so a classroom switch cannot leak a stale roster into the registry. - Deletion: deleteStageData discards the deleted stage's pending persistence work so a queued flush cannot resurrect the document. - Round trip: classroom ZIP manifests now carry the voice fields, so export/import preserves agent voices. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(roster): harden deletion, migration, selection, and ingress paths Review hardening on top of the roster single-source change: - Deletion vs in-flight persistence: deleting a stage now registers a session-scoped tombstone (lib/utils/deleted-stages.ts) before the cascade starts. Every persistence landing point checks it — the scheduled flush and the departing-stage retry drop their snapshots, and the aggregate/incremental saves re-check under the document lock, including the incremental path's full-save fallback that would otherwise rebuild a deleted document from the in-memory snapshot. A deletion that fails before the document is removed lifts the tombstone so the still-existing stage keeps persisting. - Lazy migration termination: a fruitless legacy-mirror probe (nothing to merge — e.g. server-generated rosters, which are voiceless by design) is remembered per stage for the session instead of re-querying the mirror on every load forever. Successful merges are not memoized so a failed flush is retried on the next load. Docstrings now state the real lifecycle. - Selection provenance: setStageAgents no longer overwrites a user-set agent selection with the full roster. Stage-derived selections still track the roster; a user-set auto selection is only narrowed to surviving agents (newcomers are not auto-selected, the user-set flag is untouched), and a user-set preset selection is left alone — matching restoreAgentSelection. - Mirror hygiene: deleteStageData clears the deleted stage's rows from the legacy roster mirror (best-effort), and the mirror table's docs now describe its actual access pattern (migration reads + deletion hygiene). - Registry persistence: the agent registry's persist snapshot partializes generated agents out of localStorage, making the stage document the roster's only durable home; the rehydration merge filter remains as defense in depth. - Ingress validation: imported manifest voice fields are structurally validated (malformed bindings dropped per field, the agent survives), and applyGeneratedAgentsToRegistry validates providerId against the known TTS provider registry instead of casting, treating unknown providers as "no bound voice". - Contract: drop the speculative AgentVoiceConfig.modelId — an audit of every roster producer, current and historical, found none that ever emitted it. Contract fields are added once a producer exists, not before. New tests cover the deletion tombstone at both the store and storage layers (including the missing-destination full-save pin and the lock-race re-check), the fruitless-probe memo, the selection-provenance matrix, persistence exclusion of generated agents, and voice-field sanitization on import. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(roster): close tombstone lifecycle, probe-memo, and selection-intent gaps Second hardening pass over the deletion/migration/selection fixes: - Tombstone lifecycle: a deleted classroom id can legitimately come back (deletion is client-side only). Explicit (re)creation points now lift the tombstone — server-copy restore in applyClassroomStageAndScenes and backup restore in importDatabase — so edits after a same-session restore persist again, while in-flight flushes stay fenced. - Failed deletion now restores the dirt it discarded: deleteStageData snapshots the pending map plus the in-flight round before tombstoning, and re-marks it when the delete fails with the document still present. - Legacy-mirror probe memo now distinguishes a FAILED read (null, retried on the next load) from a confirmed-empty mirror (memoized), so a transient IndexedDB error cannot suppress migration for the whole session. - Incremental save tail (currentScene KV row + chat sessions) is tombstone- fenced like the aggregate path, and both paths re-check the tombstone immediately before every write, with comments scoped honestly for the lock-free (no Web Locks) best-effort LWW fallback. - Roster-edit selection mirror: an empty intersection now falls back to the full roster and clears the user-set flag (matching restoreAgentSelection's length > 0 gate), and a user-set selection that equals the pre-edit full roster keeps tracking the roster wholesale so newcomers are not excluded forever by the AgentBar auto-toggle snapshot. - TTS/ASR provider lookups use Object.hasOwn instead of `in`/bare indexing, so prototype-chain keys ('toString', 'constructor', ...) no longer pass the provider whitelist or resolve to Object.prototype members. - Documented the per-tab limit of the tombstone set. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(roster): replace the boolean deletion tombstone with a deletion-generation model A boolean tombstone cannot express the deletion lifecycle once a deleted id legitimately comes back (server-copy restore on revisit, backup import): after the restore lifts the flag, a pre-delete flush still in flight is indistinguishable from a post-restore edit and can overwrite the restored document with pre-delete content. Two rounds of point fixes kept leaking variants of this race, so this restructures the fence instead. deleted-stages.ts now keeps a per-stage monotonic deletion epoch plus a deleted flag. markStageDeleted bumps the epoch; unmarkStageDeleted clears only the flag and never rewinds the epoch. Every persistence path captures the epoch at the moment it captures the data it will write (flush-round snapshot, departing-stage snapshot, aggregate save entry) and re-checks "captured epoch is current AND not deleted" immediately before each individual write. Invariants: - A write captured before a deletion can never land after it, even when a same-id restore has lifted the deleted flag (the captured epoch is permanently stale). - A write capturing data after a restore observes the current epoch and persists normally. - A failed deletion lifts only the flag; the restored pending changes are re-queued as descriptors, so their flush re-captures current store state under the current epoch and is neither dropped nor a stale replay. Also fixed in the same restructuring: - Incremental tail writes (currentScene, chats) each re-check independently; a delete landing while the first tail write is awaiting now fences the chat write instead of riding the earlier check. - Deleting a classroom evicts it from the warm in-memory store, and loadFromStorage treats a warm-but-deleted stage as not loaded (discarding the ghost), so navigating Back to a deleted classroom reaches the server-restore path instead of rendering an editable ghost whose every edit is silently dropped. - importDatabase records each document's pre-import deletion state and reinstates it when a failed import rolls the document back, so an outstanding flush cannot recreate the rolled-back document. - Docstrings on the failed-deletion restore path now state that only dirt captured before the deletion is restored; edits refused during the deletion window are not part of the snapshot. New tests cover the epoch invariants at the storage layer (pre-delete rounds dropped across restores on the incremental, aggregate, and tail paths; post-restore captures landing; strictly increasing epochs), the scheduler layer (departing-retry delete+restore straddle; restored dirt flushing under the current epoch), the warm-ghost restore driven through the real loadFromStorage, and the import lift/rollback pair. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(deletion): report fenced drops, gate ghost eviction on cascade settlement Edge hardening around the deletion-epoch fence; the epoch model itself is unchanged. - An epoch-stale drop is now reported, not disguised: saveStageData / saveStageDataIncremental return a distinct 'stale-dropped' status (entry check, every in-mutation re-check, and both tail-write re-checks) instead of a shape identical to success. saveToStorage reacts by skipping all success bookkeeping - no chatSnapshot rebind to a snapshot that never landed, no pending-dirt clearing - and returns false, keeping its "true means verified write" contract honest. persistDirtySnapshot keeps its existing (correct) semantics explicitly: a drop has nothing to retry. - Warm-ghost eviction is settlement-gated: the deletion cascade records an in-flight bit (begun by deleteStageData, settled in its finally), and the deleted-warm branch of loadFromStorage keeps the warm state while the cascade is unsettled - a delete can still fail before removing the document, in which case the warm state plus the restored pending dirt is the only copy of the pre-delete edits. Once settled, the ghost discard and server-restore path behave as before. - Read-side landing re-check: loadFromStorage re-checks isStageDeleted after hydration, immediately before set(), mirroring the write-side "re-check immediately before landing" discipline - a lock-free mid-cascade read can no longer re-materialize a ghost classroom. - clearStoreForDeletedStage re-checks isStageDeleted at eviction time, so a same-id restore completing inside the cascade-tail window is never wiped. - capturedEpoch is now a required parameter on both storage entry points: the default (call-time capture) silently reopened the capture-point/ validation-point split for future callers; the type system now enforces the pairing. All production callers already passed it explicitly. New tests cover the dropped-status contract, the cascade in-flight lifecycle (including both failure shapes), keep-warm during an unsettled delete with end-to-end pending restore after a failed delete, settlement- then-eviction on success, the eviction guard against a tail-window restore, and the read-side hydration re-check. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(deletion): settle the deleted-warm load by awaiting the cascade outcome Hardening around the deletion settlement gate introduced previously; the epoch model is unchanged. - The deleted-warm branch of loadFromStorage no longer completes the load while the deletion cascade is undecided (which exposed a classroom whose edits were refused without being restorable, and left a successful deletion's eviction with no follow-up reload). It now parks on a per-stage settlement promise (stageDeletionSettled) and branches on the outcome: a failed delete keeps the warm, restored classroom; a successful delete falls through to a full cold load so the server-restore path recovers the route; a navigation that moved on during the park is stopped by the load token guard. The eviction (clearStoreForDeletedStage) deliberately stops claiming a new load token so the parked load stays current - ghost re-materialization is fenced by the read-side deleted re-checks instead. No deadlock: a parked load holds no document lock, and the cascade never waits on a load. - 'stale-dropped' now propagates through the debounced flush path: persistDirtySnapshot returns the sentinel instead of an empty failure set, and startFlushRound skips the chatSnapshot rebind on it (mirroring saveToStorage) - a falsely rebound baseline would let later chat saves no-op-skip chats that never landed and corrupt cross-tab conflict detection. Pending-map clearing keeps its empty-failure semantics (restored descriptors mint fresh revisions). - The cascade in-flight state is a counter (begin++/settle--) instead of a boolean, and deleteStageData is single-flight per stage (a concurrent second call joins the first cascade), so overlapping deletions can never expose an undecided cascade as settled. - The StaleDroppedSave docstring no longer overpromises: a tail saveCurrentScene can land after the cascade's clearCurrentScene; the orphaned cursor row is ignored by the load path rather than removed by the cascade. Net +8 tests: overlapping-cascade counting, settlement-promise resolution (success and failure), concurrent double-delete single-flight join, the parked mid-cascade Back in both outcomes plus the navigation-away guard, and the fenced flush round keeping an honest chat baseline end-to-end. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(deletion): re-verify store identity on keep-warm resume, re-run joined deletes after a mid-cascade restore Three hardening refinements on the deletion/persistence fencing: - loadFromStorage's parked keep-warm branch now mirrors the success path's store-identity guard: if a tokenless writer (e.g. a database import) replaced the stage during the park, a failed deletion falls through to the cold load instead of reporting another classroom as the kept warm state. The ghost-discard block is correspondingly gated on the deleted flag so the fall-through does not mislabel a surviving document as a ghost. - deleteStageData: a joined call carries its own deletion intent. When the first cascade fulfills but a same-id restore lifted the deleted flag in the meantime, the joined caller now runs one fresh cascade against the restored document instead of reporting the pre-restore outcome. Exactly one re-check per call (no recursion); a rejected first cascade still propagates unchanged to every joined caller. - Narrowed the failed-delete restore-ownership comments: the restore covers only the pending map plus an in-flight flush round's dirt; a departing-stage snapshot is outside that capture and is fenced and dropped by design. Comment-only, no behavior change. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(roster): gate deleted-warm handling on stage identity, keep an explicit empty roster authoritative Final-audit fixes, three items: - loadFromStorage keyed its deleted-warm settlement handling (park / keep-warm / ghost discard) behind the scenes.length > 0 shortcut, so a zero-scene warm ghost of a deleted classroom skipped it entirely: the cold load found no document, the ghost stayed in the store, and the classroom loader's server-fallback gate (!getCurrentStage()) never ran — the silently-uneditable trap this branch exists to close, in its scene-less form. Deletion handling now keys on stage identity alone, before any scene-count shortcut; the non-deleted warm skip still requires scenes. - rosterNeedsLegacyFallback collapsed "roster field absent" (document predates roster persistence) with "explicitly persisted empty roster". A future writer persisting [] on a device whose read-only mirror still held stale rows would have its emptied roster resurrected on every load. The full-lift branch now triggers only when the field is absent (undefined); an explicit [] is authoritative and never probes the mirror. No current writer produces [], but the read side no longer depends on that invariant. - The GeneratedAgentConfig docstring claimed the voice fields are not a breaking change; that only holds for this codebase's tolerant structural validators. The generated stage.schema.json sets additionalProperties: false, so consumers pinning an older published schema artifact reject documents carrying the new fields. The docstring now states both sides honestly. Tests: a zero-scene deleted warm ghost is restored through the real loadFromStorage (fails pre-fix), an explicit empty roster does not resurrect stale mirror rows (fails pre-fix), and the rosterNeedsLegacyFallback unit matrix covers undefined vs []. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(deletion): re-queue aggregate persistence when a failed deletion is recovered Direct aggregate saves (saveToStorage: generation completion, server-restore hydration) run outside the pending map and the flush round, so the deletion path's pre-delete dirt snapshot cannot describe them. When a deletion bumped the epoch while such a save was in flight, the save was correctly fenced ('stale-dropped') — but if the deletion then failed before removing the document, the recovery only re-queued the snapshotted scheduler descriptors. The fenced aggregate-only content stayed memory-only with no retry anywhere, and a later reload lost it. The failed-deletion restore now merges a full re-mark of the aggregate (structure / stage / outline / currentScene / chats plus a descriptor for every current scene) into the recovery set, still guarded on the store holding the stage. Because the flush recaptures the CURRENT store state under the CURRENT epoch, this necessarily carries whatever the fenced aggregate save held — and, for the same reason, edits refused by the scheduler during the deletion window, which previously stayed memory-only as well; the scope docstrings now say so instead of declaring them excluded. New integration coverage drives the real store scheduler and the real storage layer end to end: a genuinely fenced in-flight saveToStorage (generation completion) plus a pre-removal deletion failure ends with the completion flag durable on the next flush; a deletion-window scene edit survives the same way; and a successful deletion re-marks nothing (control). Both recovery tests fail against the previous restore logic. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-27 14:39:19 +08:00
wyucand杨慎	16dad613c9	fix(storage): bind default fetch to globalThis in both HTTP store clients (#984) ... * fix(storage): bind default fetch to globalThis in both HTTP store clients Browsers require fetch to be invoked with this === globalThis; storing the global as an instance field and calling this.fetchImpl(...) throws 'Illegal invocation' on the very first request — while node's undici does not enforce the receiver, which is exactly why every node-side contract suite stayed green. Found by a downstream end-to-end test: the persistence bootstrap configured the HTTP stores correctly, but the first page load crashed on fetch and nothing ever reached PostgreSQL. A strict-receiver regression test now guards the gap node cannot catch natively. * fix(storage): validate the fetch option before binding it (review P2) .bind on a non-function throws a native TypeError that preempted the documented 'requires a fetch implementation' error; both constructors now validate the selected implementation first. --------- Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-24 14:09:24 +08:00
wyucandCodex	e39c64cd9e	feat(persistence): one-command server-backed stack (compose profile + embedded API + docs) (#982) ... * feat(persistence): one-command server-backed stack — embedded API + compose postgres profile docker compose --profile server-persistence up --build runs exactly two containers: the app (persistence HTTP server embedded at /api/persistence, enabled only when DATABASE_URL is set — unset keeps today's browser-only behavior byte-for-byte) and PostgreSQL 16. Client bootstrap configures both storage seams against the same-origin route when NEXT_PUBLIC_PERSISTENCE=1, riding the existing lazy migrations so prior browser data reaches the server per-course on first open. Dev auth (bearer token + client-asserted learner header) lives in one overridable module and is loudly documented as development-grade. Verified end-to-end against the real stack: document PUT/GET and runtime session create land in Postgres; bad tokens 401. Co-authored-by: Codex <codex@openai.com> * fix(persistence): review round — structural bootstrap ordering, retryable init, honest failure surfaces The bootstrap side-effect import moves into the two storage seam entry modules, so any module graph that can resolve a store necessarily evaluates it first — no client-entry ordering luck, and the two configure calls are all-or-nothing. A failed server init clears its cached promise (next request retries instead of permanent 500s). listStages rethrows backend failures and the dashboard surfaces a persistence-unavailable error instead of rendering an empty list that reads as data loss. Docs state the build-time nature of NEXT_PUBLIC_PERSISTENCE, the real token boundary (any visitor can extract it and impersonate any learner — localhost/trusted-network only), and the correct postgres password rotation. Dev-token compare is timing-safe; the handler singleton lives on globalThis so HMR cannot leak pools. Co-authored-by: Codex <codex@openai.com> * fix(persistence): review response — no-confidentiality wording + adapter round-trip coverage The token docs now state plainly that the NEXT_PUBLIC token is compiled into the public bundle and provides no confidentiality or user isolation (its only role is keeping unrelated scanners off a trusted network). The Fetch/Node adapter — the route's most bug-prone code — gains a round-trip integration test: PUT body streaming, 201 with multi-value headers, 204 empty body, and encoded path segments reaching the handler un-decoded. --------- Co-authored-by: Codex <codex@openai.com>	2026-07-23 16:28:03 +08: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
3 people	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
3 people	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
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
wyuc	65bf20a84b	feat(runtime): cut chat sessions over to RuntimeStore (#926) ... * feat(runtime): persist chat sessions in RuntimeStore * fix(runtime): harden chat persistence ordering * fix(runtime): protect cross-tab chat snapshots * fix(runtime): compare structured chat values safely * fix(runtime): preserve chat backup and reset semantics * fix(runtime): restore imported chat snapshots * fix(runtime): isolate chat load failures * fix(runtime): make cache clearing lossless * fix(runtime): normalize empty chat saves * fix(runtime): serialize legacy chat migration * fix(chat): serialize backup restoration * test(chat): cover multi-stage restore locking * fix(chat): coordinate fallback migrations across tabs * fix(chat): harden cross-tab migration locking * fix(database): retire abandoned chat lease schema * fix(chat): preserve monotonic local edits * fix(chat): protect unseen runtime sessions * fix(chat): order lifecycle transitions monotonically * fix(chat): serialize runtime maintenance * fix(chat): order queued writes before maintenance * fix(chat): preserve cross-version lock compatibility * fix(chat): preserve streamed and backup data * fix(chat): isolate empty no-lock saves * fix(chat): isolate partial runtime snapshots * fix(runtime): close cross-store cutover races * fix(runtime): close remaining cutover races * fix(chat): retain caller-visible conflict baseline * fix(chat): preserve read-only legacy autosaves * fix(chat): avoid restore lock inversion * fix(runtime): enroll writes before maintenance * fix(runtime): retain maintenance ordering * fix(runtime): close restore and deletion races * fix(chat): order partition queues within lock epochs * fix(chat): preserve recovery and deletion intent * fix(runtime): recover interrupted chat restores * fix(backup): scope chat deduplication by stage * fix(backup): stage chats by runtime partition * fix(backup): clear staged chats with stages	2026-07-16 18:30:40 +08:00
wyucand杨慎	ebb12b5fc1	feat(agent): add validated JSON Patch element edits (#927) ... * feat(agent): add validated JSON Patch element edits * fix(agent): preserve JSON Patch replace semantics * fix(agent): close structured replace contract gaps * fix(agent): preserve structured add sequencing * fix(renderer): preserve existing image filter units --------- Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-15 14:20:00 +08:00
4 people	cc5a6ab152	feat(agent): edit_elements — NL → EditIntent vertical (#895) (#896) ... * feat(agent): add edit_elements NL → EditIntent vertical (#895) Give the editing surface its first real consumer: natural-language per-element style/geometry edits flow through the same EditIntent vocabulary as pointer gestures, with an all-or-nothing validation gate and one undo entry per instruction. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(agent): harden edit_elements against CR findings (#895) Re-validate intents at apply time (atomic refuse on missing/locked ids), type-check prop values, require an open edit session for undo, clamp line stroke width correctly, enforce group cohesion, nest shape text chrome, and surface refuseReason on the tool card. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(agent): close remaining edit_elements CR residuals (#895) Feed apply outcomes into next-turn history and post-run chat corrections, phrase tool success as proposed-not-applied, and tighten gradient/filters/ enums/per-type value validation plus label-less shape text refusal. Co-authored-by: Cursor <cursoragent@cursor.com> * refactor(agent): derive edit_elements prop validation from the DSL schema (#895) Three review rounds each found a hand-written validator disagreeing with the DSL contract (a gradient pos range pinned at [0,1] against the percent contract, a textType enum matching the DSL in neither direction, per-type ownership gaps like vertical-on-shape and color-on-everything). Replace the class instead of the instances: - The gate now loads the dsl-generated JSON schema (@openmaic/dsl/schema/scene.schema.json) and validates every proposed prop value against the target element type's subschema via a compact schema-subset checker — per-type ownership, enums, and structured shapes (outline/shadow/gradient/filters) come from the single source of truth and stay correct as the DSL evolves. - Explicit policy layers stay on top: the content/identity blocklist (schema would allow what policy forbids), geometry clamps (coords, min sizes, line stroke width), and a numeric-range overlay for what plain number types cannot express — gradient stop pos is a percent in [0,100] (the previous [0,1] check refused canonical gradients and the unit test pinned the wrong contract), fontSize/lineHeight/radius bounds, filter value length, stop-count cap. - Consequences: color is refused on types that do not render it, with prompt guidance steering text color to defaultColor and shape body to fill; fill on charts is now allowed (the schema has it; the inventory already advertised it); textType accepts the full DSL enum. - Apply-time revalidation also refuses element-type drift via a gate-time targetElementTypes map carried in the tool details. - Refusal reasons render as visible card text, not only a hover title. - Test pins added for all of the above plus selection scoping, coord bounds, non-finite rotate, and empty batch/props. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(agent): harden the schema-derived gate — fail closed, assert schema source, unify numeric clamping (#895) - A schema construct the subset checker cannot judge (unresolved $ref, malformed anyOf, unsupported keywords) now refuses instead of accepting — the gate fails closed on the unknown. - A module-load assertion verifies the loaded dsl schema carries every definition the gate maps and a sane TextType enum, so a stale or missing build artifact fails loudly with a rebuild hint instead of validating an outdated contract silently. - Numeric-overshoot convention unified and documented: structural, enum, or ownership mismatches refuse (teaching the model the contract); numeric overshoot on a valid prop clamps (matching gesture behavior) — opacity now clamps like geometry. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(agent): localize edit element refusals (#895) * fix(agent): preserve partial element edit semantics (#895) * fix(agent): prevent stale element edit application (#895) * fix(agent): preserve live canvas edit invariants (#895) * fix(agent): close element style contract gaps (#895) * fix(agent): reject non-persistent element styles (#895) * fix(agent): preserve rigid group geometry (#895) * fix(agent): tolerate decimal group translations (#895) * fix(agent): constrain line height edits (#895) * fix(agent): reject stale or shadowed element edits (#895) * fix(agent): close renderer contract gaps (#895) --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-14 18:24:35 +08:00
wyucand杨慎	40ff80ab63	feat(editor): add draggable insert toolbar (#912) ... * feat(editor): add draggable insert toolbar * fix(editor): improve toolbar accessibility * fix(quiz): update empty-state guidance * fix(settings): sanitize retired toolbar state * fix(editor): keep hints from blocking controls * fix(editor): refine toolbar and hint interactions * fix(editor): preserve toolbar position across scenes --------- Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-14 11:57:51 +08:00
wyucand杨慎	c8a638a101	feat: support GPT-5.6 model family (#907) ... * feat: support GPT-5.6 model family * test: cover GPT-5.6 SDK validation * fix: canonicalize GPT-5.6 Sol alias * fix: complete GPT-5.6 alias lookups --------- Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-13 18:19:40 +08:00
3 people	268ace5ad1	perf(renderer): diff code lines in O(n) via a prev-line map (#706) ... BaseCodeElement diffed each render against the previous one with a linear prevLinesRef.current.find() per line, on top of a separate Set pass — O(lines x prevLines). This effect runs on every streaming update while a code block types out, and code blocks routinely run dozens to hundreds of lines, so the quadratic cost lands on a render hot path. Build a single Map<id, prevLine> and fold the insert/replace checks into one O(n) pass. Behavior is identical: a line missing from the previous render is "inserted", a line present with changed content is "replaced" (the two were already mutually exclusive). Closes #705 Co-authored-by: ly-wang19 <ly-wang19@users.noreply.github.com> Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>	2026-07-11 19:53:44 +08:00
3 people	09f490cffe	feat(renderer/editing): marquee multi-select + multi-element drag (#851 Part A) (#888) ... * feat(renderer/editing): marquee multi-select + multi-element drag (#851 Part A) Completes the selection model half of the Part A scope: - core/marquee.ts: normalized min/max marquee rect (collapses the reference implementation's four quadrant branches into one contain/intersect predicate pair), rotation-aware AABB hit-testing, lock exclusion, all-or-nothing group cohesion. - Blank-canvas capture surface + MarqueeBox chrome + useMarqueeGesture: rubber-band selection with the 5-canvas-unit both-axes threshold — below it a blank click clears the selection (previously blank clicks did nothing at all). - Click modifiers on elements (ctrl/shift/meta): add when outside the selection, remove when inside (guarded against emptying); a plain pointer-down on an already-selected element keeps the selection, sets it primary, and arms a multi-element drag. - core/drag.ts computeMultiDragMove: rigid translation of the selected set — snap computed on the union bounding box, the corrected delta applied to every member; selected elements excluded from snap candidates. Commit emits ONE element.updateMany intent (the declared batch member, previously unused) = one host undo entry; single-element drags keep emitting element.update. Multi-selections still show no resize/rotate handles (group scaling is a later slice; the #881 gate is re-asserted in tests). Part of #851 (Part A) / #720 Phase 3. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(renderer/editing): review round — unified selection resolver, group cohesion on click, safer capture surface (#851) - Locked elements are never translated by a multi-drag (they may sit in a host-controlled selection for feedback; they stay put and remain snap candidates). - Marquee hit-testing of lines uses an AABB over start/end plus any present broken/curve/cubic control points — the visible path of a bent line can bow outside its chord, which the plain element range misses. Conservative by the Bezier convex-hull argument. - The click modifier table moved into a shared pure resolver (core/selection.ts) used by both box and line pointer-down paths, so a ctrl-click on a line now adds/removes it instead of replacing the selection; the resolver also expands clicks to whole groups (select/add/remove act on the group unit), keeps primaryId when it survives a subtraction, and drags carry the group. - Blank capture surface: only on editable mounts (select-only mounts keep native touch panning), and only for the main button — a right-click no longer clears the selection. - Shift held mid-drag now engages the dominant-axis lock (previously dead plumbing); shift at pointer-down remains a selection modifier. - Marquee release decisions read the live selection (ref refreshed per render) instead of the pointer-down closure; computeMultiDragMove guards the empty set. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(renderer/editing): review round — selection features decoupled from mutability, shared line bounds, group closure (#851) - The blank capture surface renders for any selection-capable mount (marquee and blank-click-clear are pure selection features); touchAction none applies only on editable mounts, so select-only hosts keep native touch panning and gain mouse/pen marquee. - The control-point-aware line bounds moved to the editing geometry layer (getEditingElementRange / getEditingElementListRange) and are now shared by marquee hit-testing, the multi-drag union snap box, and align-line candidates — a bowed line selects and snaps with one bbox. - resolveClickSelection group-closes the incoming controlled selection, so a host-supplied partial group can no longer produce a drag that splits the group; the resolver's no-op emit survives only when the incoming selection was already cohesive. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(renderer/editing): review round — visual snap bounds for lines, touch gating on all hit layers (#851) - Align-line candidates now come from getVisualElementRange: exact rendered bounds for lines (polyline elbows are vertices; quadratic and cubic curves contribute their Bezier axis extrema), so a guide line is never emitted for geometry the curve does not render. The conservative control-point hull remains for marquee hit-testing and the multi-drag union box — hull answers 'could this be here' (selection must never miss), visual answers 'what the user sees aligns'. - The editability-conditional touchAction now covers every editing hit layer (box hit targets, locked blockers, line stroke paths), not just the blank surface: a select-only mount preserves native touch panning wherever the swipe starts, while tap-to-select keeps working. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(renderer/editing): broken2 visual bounds mirror the rendered orthogonal elbows (#851) The renderer never draws through the raw broken2 point — the path builder derives orthogonal elbows from it by orientation. The visual range branch now mirrors getLineElementPath's elbow coordinates exactly (documented to stay in lockstep), so align-line candidates for broken2 lines match the rendered path; the raw point survives only in the conservative hull used by marquee/union. Regression pins the rendered AABB for the elbow case that previously reported an invisible bottom edge. 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-09 22:07:58 +08:00
3 people	ff300b077f	feat(renderer/editing): 8-point resize + rotate operate handles (#851 Part A) (#881) ... * feat(renderer/editing): 8-point resize + rotate operate handles (#851 Part A) Extends the gesture core from the selection/drag slice with the next two deferred capabilities: - core/resize.ts: computeResize — unrotated path with moving-edge snapping (before clamping, aspect re-lock after), rotated path via local-axis pointer delta + opposite-point correction so the diagonal handle stays visually fixed; per-type minimum sizes; aspect lock from a modifier or the element's fixedRatio (corners only); rotation-bucketed resize cursors; per-kind handle gates (text exposes two handles by orientation, code none, line excluded). - core/rotate.ts: computeRotate — signed (-180,180] angle from the pointer around the element center, snapped to 45-degree multiples; canRotate gate (chart/video/audio excluded). - useResizeGesture / useRotateGesture + ResizeHandles / RotateHandle, wired into EditableSlideCanvas behind the existing editable gates. Handle positions are computed analytically in screen space (not nested in a rotated CSS frame), sourced from the same rotated-points math as the resize correction. One element.update intent per completed gesture, as with move and line reshape. Content-space recomputation (shape pathFormula, table row heights, image clip) stays host-side; intents carry box props only. Part of #851 (Part A) / #720 Phase 3. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(renderer/editing): review round — skip no-op resize intents, gate handles to single selection (#851) - A snap that returns the box to its exact original geometry no longer emits an element.update (it would cost the host a redundant undo entry) — same guard the rotate gesture already had for an unchanged angle. - Operate handles render only for a single-element selection: the gestures transform one element, and per-element handles on a multi-selection would misread as group scaling (a later slice). 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-09 00:53:21 +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
3 people	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
3 people	191689f98d	feat(renderer/editing): selection + drag-to-move core (@openmaic/renderer v2, #851 Part A) (#859) ... * chore(renderer): enable component tests (jsdom + testing-library, tsx include) * feat(renderer/editing): pure geometry helpers for the editing core * feat(renderer/editing): alignment snapping math (element + viewport lines) * feat(renderer/editing): single-element drag math + move intent derivation * feat(renderer/editing): presentational selection overlay + border handle * feat(renderer/editing): controlled selection + drag-to-move on EditableSlideCanvas Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): align interaction overlay with SlideCanvas centering offset Finding 1: the hit layer and SelectionOverlay sat at el.left*scale from the overlay wrapper origin, ignoring the viewportStyles.left/top offset SlideCanvas applies when letterboxing/centering the slide, so pointer-down hit-tested the wrong element. EditableSlideCanvas now computes the same viewportStyles via the exported useViewportSize on the overlay wrapper and offsets the hit divs (and a positioning container wrapping the unchanged SelectionOverlay) to match. Finding 2: window pointermove/pointerup listeners armed in onElementPointerDown were removed only on pointer-up, leaking on mid-drag unmount. Track teardown in a ref and remove it from a useEffect unmount cleanup; single-pointer re-arm kept. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore(renderer/editing): typecheck/lint/build green for the editing core - Apply prettier formatting to editing source/test files flagged by `pnpm check`. - Replace `any`/`Partial<any>` test fixture helpers with `Partial<PPTElement>`/`Slide` typed builders cast via `as unknown as T`, clearing @typescript-eslint/no-explicit-any errors in the editing test suite. No behavior change; typecheck, full editing test suite (18/18) plus package suite (20/20), prettier, eslint (incl. #853 no-restricted-imports boundary rule), and the ./editing subpath build are all green. * fix(renderer/editing): reuse line-aware getElementRange from utils geometry.ts re-implemented getElementRange/getRectRotatedRange without line support (start/end), producing NaN alignment guides when a slide contained a PPTLineElement. Re-export the renderer's line- and rotation-aware getElementRange from utils/element so snapping.ts/drag.ts are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): auto-fit, gate hit layer, defer lines, padding-safe layout - Restore SlideCanvas auto-fit: when scale is omitted, read fitScale from the overlay's own useViewportSize and pass scale through so both measure the same box and stay aligned at auto-fit (was hard-forced to scale=1). - Gate the interactive hit layer on onElementsChange||onSelectionChange so a read-only mount does not swallow pointer events. - Defer line elements: skip type==='line' in the hit layer and SelectionOverlay (box-model update intent can't represent line moves); narrow via predicate so width/height/rotate are available without in/as fallbacks. - Move className/style to an outer wrapper with a padding-free inner relative wrapper so consumer padding can't diverge SlideCanvas vs overlay box models. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): Euclidean drag threshold + multi-pointer guard - Classify click-vs-drag by combined Math.hypot(dx,dy) so a diagonal move past the threshold on both axes isn't misread as a click. - Track the active gesture's pointerId: ignore further pointer-downs while a gesture is in flight and drop window move/up events from other pointerIds, so a second touch can't overwrite the teardown ref or drag the first element. - Doc: SnappingOptions.range is in canvas units (viewportSize space), not px. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(renderer/editing): prettier formatting for SelectionOverlay line filter Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): fill container on outer wrapper to restore auto-fit Round-1 split moved className/style to an outer wrapper that lost its dimensions, leaving it auto-height; the inner height:100% then resolved against a zero-height box so useViewportSize read clientHeight~0 -> fitScale~0 -> blank render when scale is omitted. Give the outer wrapper width/height:100% merged BEFORE ...style so consumers can still override. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): select-only fallback and pointercancel teardown C2: only emit a move intent when onElementsChange exists; a drag-classified gesture on a read-only (onSelectionChange-only) host now falls back to selection instead of doing nothing on >2px jitter. C3: listen for pointercancel (filtered by active pointerId) and tear down without emitting any intent or selection change, reverting the working copy so a cancelled gesture leaves the hook ready for a new one. removeListeners (and thus the unmount cleanup) now also drops the pointercancel listener. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(renderer/editing): narrow lines in computeDragMove without casts Replace the double as-unknown-as cast (used to read box fields off the PPTElement union) with a type === 'line' guard: a line reaching computeDragMove now early-returns its current position unchanged, and the remaining code is narrowed to the non-line box variants so left/top/width/ height/rotate are directly available. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): don't allow dragging locked elements PPTBaseElement.lock was not honored by the editing overlay: a locked element still rendered an active move hit target and useEditGesture would still emit element.update after a drag on it. Skip locked elements when mounting the interactive hit layer, and defense-in-depth early-return them in onElementPointerDown so no gesture can arm even if a hit target somehow reached one. SelectionOverlay is left untouched. * fix(renderer/editing): locked elements block pointer events instead of click-through A locked element previously had no hit target at all in the interactive overlay, so a pointer-down over a locked element that visually overlapped an unlocked element fell through to the unlocked element's hit target underneath, moving/selecting the wrong element. Render an inert blocker div for locked elements (same stacking position, no data-element-id, no gesture wiring) so it consumes the pointer instead. Line elements remain deliberately click-through (bbox != stroke hit area). * fix(renderer/editing): route line pointer-downs to an inert stroke blocker A line was skipped entirely from the hit layer, so a pointer-down on a rendered line fell through to a box element underneath and moved/selected the wrong thing. Render an inert stroke-shaped blocker per line instead: a thin rotated rectangle laid along the segment from the start endpoint (left+start) to the end endpoint (left+end), with a fixed zoom-independent grab thickness. It consumes pointer-downs on the stroke (no gesture armed) while leaving the rest of the line's bbox click-through, so it never over-blocks other visible elements around a thin diagonal line. Locked blocker and box move-target behavior are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): sync selection on interaction; no live-move on select-only hosts Keep the controlled selection in step with what the pointer acts on, and stop faking drags where nothing can commit: - Select-on-pointer-down: a gesture that starts on an element selects it (collapsing to that single element) unless it is already the sole/primary selection. Both a click and a drag then operate on — and end with — a selected element, so dragging a not-yet-selected element no longer leaves the selection stale. Selection is emitted once (on down); pointer-up emits only the move intent for a drag, and nothing extra for a click. - Select-only hosts: when there is no onElementsChange channel, the live working copy no longer follows the pointer during pointermove (it could never commit and would snap back on release). Such surfaces only select. Moving all members of a multi-selection together remains out of scope. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): mirror v1 line renderer with an SVG-path hit blocker Replace the straight start->end strip blocker with an inert SVG <path> that reuses getLineElementPath, so the hit region traces the same path the v1 renderer draws for every line shape (straight/broken/broken2/curve/cubic). pointer-events:stroke covers only the visible stroke, leaving the empty bbox click-through (P2). stroke-width is the grab band, max(10, el.width*canvasScale) in screen px (divided by canvasScale for the scaled svg), so a wide or zoomed stroke stays covered (P3). Blocker stays inert: onPointerDown only stops propagation, no gesture armed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(renderer/editing): note deferred line endpoint-marker hit coverage * fix(renderer): make line elements selectable but not draggable The line hit blocker in EditableSlideCanvas only called stopPropagation on pointer-down, which blocked fall-through to an overlapped box but also made lines unselectable (a regression from the pre-series behavior where the host delegated line selection via onElementClick). SelectionOverlay additionally filtered lines out, so even a host-controlled line selection showed no feedback. - EditableSlideCanvas: the line blocker's onPointerDown now also selects the line via onSelectionChange (on pointer-down, for parity with box elements) when a selection callback is present. No drag gesture is armed and no element.update is ever emitted (line editing stays deferred). It still consumes the pointer to block fall-through even when onSelectionChange is absent, and never selects/moves an overlapped box beneath. - SelectionOverlay: render a selection border for a selected line, computing its bounding box via getElementRange and reusing BorderLine (no rotation). Box-element rendering is unchanged. Adds regression tests (line selects on pointer-down with no update intent; blocker still consumes the pointer without a selection callback; SelectionOverlay draws a border at the line bbox) and adjusts the tests whose behavior intentionally changed. Editing suite: 41 passed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): correct line selection bounds and locked/idempotent line selection F1: line selection border now encloses the actual drawn path. Add a pure getLineBounds helper in editing/core/geometry.ts that spans every control point (start/end/broken/broken2/curve/cubic, each offset by left/top), and use it in SelectionOverlay instead of getElementRange, which only bounded the start/end chord (curve/broken/cubic lines got a wrong, sometimes zero-size box). F2: a locked line is now inert like a locked box — its blocker still stops propagation (blocks fall-through) but no longer selects. F3: the line blocker skips re-emitting onSelectionChange when the line is already the sole primary selection, mirroring the box alreadySolePrimary guard. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): derive line selection bounds from the rendered path getLineBounds min/maxed the raw line control points, but the renderer's getLineElementPath does not draw broken2 as a point — it uses only broken2[0] (horizontal) or broken2[1] (vertical). A horizontal broken2=[50,80] line renders flat at y=0, yet the bounds reported maxY=80, painting an oversized selection border. Reimplement getLineBounds to parse the coordinates out of getLineElementPath (the single source of truth for the drawn path) and min/max over them, offset by left/top. This is exact for straight, broken, broken2 (one-axis), curve (Q control point in the path) and cubic (C) lines. Guard an empty/odd match list by falling back to the element origin. Also document a deferred limitation in EditableSlideCanvas: line selection bypasses useEditGesture and thus the activePointerRef multi-pointer guard (comment only, no behavior change). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): compute tight Bézier bbox for line selection bounds getLineBounds took min/max over every number in the rendered path, which includes Bézier control points. A control point can lie outside the drawn curve, so the selection border was oversized (e.g. M0,0 Q50,80 100,0 reported maxY=80 though the quadratic only peaks at y=40). Replace it with an exact per-segment path bbox: parse the M/L/Q/C path (tracking the SVG current point and implicit command repeats) and, for Q/C, take the true Bézier extrema instead of the control points — quadratic extremum at t*=(P0-P1)/(P0-2P1+P2), cubic roots of B'(t)=0 (with the degenerate a≈0 linear case). Endpoints and offset by left/top are preserved; fall back to the element origin for empty paths. Exposed quadraticBounds/cubicBounds/getPathBounds as pure, unit-tested helpers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer/editing): parse exponent-form path coordinates in getPathBounds * fix(renderer/editing): inflate line selection bounds by half the stroke width * feat(renderer): add pure line-handle drag core for editing v2 Port the app's useDragLineElement math into a store-free, React-free core: computeLineDrag lifts endpoints/controls to absolute canvas coords, applies the pointer delta with axis snapping (endpoint straighten, ctrl midpoint snap), re-normalizes the bbox, and recomputes only the control field(s) the line actually carries (broken/broken2/curve/cubic). Add LineHandle type and 7 hand-computed tests. External-element adsorption is deferred. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(renderer): draggable line endpoint/control handles for v2 editor Replace a selected line's approximate bbox selection border with draggable endpoint/control handles that reshape it. Add a presentational LineHandles component and a useLineHandleGesture hook (mirroring useEditGesture: working-copy preview, one intent on pointer-up, pointerId guard, pointercancel revert) driven by the existing computeLineDrag core. Wire both into EditableSlideCanvas so the v1 canvas, the line stroke blocker, and the handles preview off the same working element. Remove the line branch from SelectionOverlay. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): line selection highlight, precedence, and dead-code cleanup F1: a selected line now always shows selection chrome. Its inert blocker path takes a visible accent stroke when selected, so a locked or read-only (no callback) selected line still gets feedback; the highlight renders even when no handles do, and stays pointer-inert in a read-only mount. F2: remove the now-dead getLineBounds and its transitive-only helpers (getPathBounds, quadraticBounds, cubicBounds, quadraticAt, cubicAt, EPS) plus their tests; they had no production consumer after the line-bbox removal. F3: align LineHandles control-field precedence with computeLineDrag (broken || broken2 || curve) so the handle renders where the drag math reads it. F4: add tests for the curve ctrl-handle drag and that a handle grab never re-selects, plus the F1 highlight states. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): split line hit blocker from highlight; gate handles on editability The line overlay used a single <path> as both the interaction blocker and the visual selection chrome. On select its stroke-width switched from the fat grab band to the thin highlight width, shrinking the pointer-events:stroke hit region so a thin selected line let clicks fall through to a box beneath. - FIX B: render two paths sharing the same d/position/scale — a stable transparent blocker (grab band, pointer-events:stroke, inert onPointerDown) whose hit region never changes with selection, plus a separate accent highlight (pointer-events:none) rendered only when selected. - FIX A: gate LineHandles on onElementsChange (editability) instead of generic interactive, so a select-only mount shows the highlight but no draggable handles that could never commit. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-08 13:03:17 +08:00
wyucandClaude Opus 4.8	6d6e1ac8f5	feat(storage): DocumentStore — normalized document aggregate (browser backend) (#860) ... * feat(storage): add DocumentStore — normalized document aggregate (browser) Persist the `document` aggregate (stage metadata + scenes + embedded agents / quiz / actions + an opaque outline snapshot) through a DSL-typed `DocumentStore` with a browser (IndexedDB) backend. Depends only on `@openmaic/dsl`; no Dexie dependency (raw injected `IDBFactory`, matching the Part 1 asset backend). - Aggregate <-> normalized adapter: the portable embedded document splits into per-entity rows on write (diffing so only changed scenes are written) and reassembles on read. Scenes key by [stageId, id] so documents stay isolated. - Migrate-on-read/write: each document is root-stamped with `dslVersion`. Reads migrate forward (a newer-versioned document passes through untouched, never downgraded); `saveDocument` normalizes stale input forward (or fails loud on a version with no ladder path) and refuses to overwrite a newer stored document; the incremental `putScene` / `deleteScene` require an already-current document so they can never strand unmigrated sibling scenes. The opaque outline rides alongside — persisted verbatim, never validated or migrated. - Validation gate: writes run `validateStage` / `validateScene` and fail loud before any row is written (atomic). The store additionally enforces its own key/sort invariants (scene belongs to its stage, id is a string, order is a number, no duplicate ids) independently of the content validator. - Generic over scene type: `DocumentStore<TScene>` defaults to the DSL `Scene` (slide / quiz); an app widens it with its own kinds (interactive / pbl) by injecting a matching `validateScene`, so those scenes persist and the gate stays fail-loud for them. - One backend-agnostic contract suite (`test/document-contract.ts`) plus backend-seeded migrate-on-read / forward-compat / app-widened cases, and pure adapter unit tests. Part of the @openmaic/storage rollout (#779, #857); follows the KV / asset primitives in #858. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(storage): safe scene diff for opaque content; document listDocuments version tolerance Review follow-up. - The write-diff in `saveDocument` compared scenes with `JSON.stringify`, which is unsafe now that the store is generic over opaque app scene content: IndexedDB persists structured-clone values (`Map` / `Set` / `Date`, `NaN`, `undefined` members) that JSON flattens or drops, so a real edit (e.g. a `Map` value change) could stringify identically and be silently skipped. Replace it with a structural deep-equal that recognizes those kinds and, crucially, declines to prove equality for anything it doesn't recognize (class instance, typed array, Blob) — biasing to a harmless spurious write, never a false positive that drops an edit. Recursion is depth-bounded so cyclic/pathological content can't overflow the stack. - Document that `listDocuments` intentionally tolerates a corrupt/unknown `dslVersion` stamp: it returns only version-independent summary fields and never migrates or reads content, so one bad row must not fail the whole listing (a broken document still fails loud when actually opened). Both covered by new tests (opaque `Map` content re-save; corrupt-stamp listing). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(storage): always write scene rows instead of diffing opaque content Second review follow-up. The scene write-diff relied on a structural equality over opaque app scene content, which cannot be done reliably: matching what IndexedDB actually persists means reproducing structured-clone equality — iteration order (Map/Set/object keys), sparse-array holes vs explicit undefined, array expando properties, null vs Object prototype, and shared-reference topology. Each is a false-positive risk where a wrong "equal" silently drops a user's edit. Rather than carry a fragile hand-rolled deep-equal, drop the per-scene skip: `saveDocument` now writes every incoming scene and deletes the ones no longer present. A redundant write is harmless; cheap per-scene incremental writes go through `putScene`. Tests that a real edit (value change, Map/Set/object-key reorder) is persisted are retained. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(storage): require a finite scene order `assertStorableScene` accepted `NaN` / `Infinity` because they are `typeof number`, but a non-finite `order` makes the read-time `a.order - b.order` comparator return `NaN` and silently scrambles scene order — the exact failure the guard exists to prevent. Require `Number.isFinite(order)`. 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-07 17:25:15 +08:00
wyucandClaude Opus 4.8	04b70f0359	feat(storage): scaffold @openmaic/storage — KV + asset primitives (browser) (#857) (#858) ... * feat(storage): scaffold @openmaic/storage — KV + asset primitives (browser) (#857) First executable slice of the @openmaic/storage RFC (#779, Part 1): a pure, app-agnostic persistence package depending only on @openmaic/dsl. - Add the DSL-owned `StorageProvider` asset seam to @openmaic/dsl (put(blob)->ref / resolve(ref)->url / remove), typed against a structural `BinaryBlob` so the pure DSL keeps `lib: ES2022` (no DOM). - `KVStore` (device/account scopes) + `BrowserKVStore` over localStorage. - `BrowserAssetProvider`: content-addressed (sha256) bytes in IndexedDB, resolved to object URLs; identical bytes de-duplicate. - `kvPersistStorage`: adapt a KVStore into a zustand `persist` storage (pure util; app store wiring is a follow-up). - Implementation-agnostic contract suites (KV + StorageProvider), run against the browser backends so future backends prove equivalence. - Machine-enforce the package import boundary in eslint (no `@/...`), mirroring the @openmaic/renderer boundary. Backends take their Storage/IDBFactory by injection, so the package is testable without a browser. Deferred to later Part-1 steps: wiring the app's zustand stores + ad-hoc localStorage through KVStore (needs a legacy-key compat migration), DocumentStore/RuntimeStore, and the HTTP backend. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(storage): address cross-review findings - BrowserAssetProvider: resolve writes on transaction.oncomplete (not request.onsuccess) so a commit-time abort (e.g. QuotaExceeded) can't be reported as durable success. - BrowserAssetProvider.openDb: don't memoize a rejected open — a transient IDB failure no longer bricks the provider; the next call retries. - BrowserAssetProvider.resolve: memoize the resolution per ref so concurrent resolves share one object URL instead of orphaning a second one. - BrowserKVStore.set: treat a value JSON can't represent (undefined / function / symbol) as a removal, instead of writing a literal "undefined" that throws on the next get (and would reject zustand rehydration). - Tests: build contract Blobs from strings (a Uint8Array BlobPart fails the root tsconfig typecheck under TS 5.7+ typed-array generics); reset the object-URL registry per test; add regression tests for set(undefined), concurrent-resolve, and actual de-dup (one stored row). - Drop @openmaic/storage from the root postinstall build chain: nothing imports it yet, so building it on every install added latency and coupled its build failures to importer/renderer/sync. It re-joins when the app consumes it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(storage): don't cache a rejected resolve promise Second cross-review pass caught that the per-ref resolve memoization reintroduced the same rejected-promise-caching bug just fixed in openDb: a transient IndexedDB failure inside resolve() left the rejected promise in the `urls` map, so every later resolve(ref) replayed the rejection and never retried. Evict the entry on rejection (mirroring the null-miss path), and add a regression test that fails a resolve's IDB open once and asserts the next resolve recovers. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(storage): review — coherent re-put contentType + restore bootstrap build Addresses @cosarah's review on #858: - BrowserAssetProvider.put: invalidate (revoke + drop) any cached object URL for the ref after a write, so a re-put of the same bytes with a corrected contentType is reflected by resolve() instead of a stale, cache-warmth- dependent MIME type. remove() reuses the same invalidateUrl helper. Adds a regression test (put type="" -> resolve -> put same bytes type="image/png" -> resolve now reports image/png). - Restore @openmaic/storage to the root postinstall build chain: the package publishes dist/*, so a clean install must build it or workspace consumers resolving it via exports would fail until a manual --filter build. 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-06 17:12:10 +08:00
wyucandClaude Opus 4.8	b53f202d9d	feat(renderer): scaffold @openmaic/renderer/editing subpath (v2 editing surface, Stage 0) (#855) ... * feat(renderer): scaffold the @openmaic/renderer/editing subpath (v2 Stage 0) Adds the packaging skeleton for the renderer v2 editing surface behind a dedicated `./editing` subpath export, so the read-only entry (@openmaic/renderer) never pulls the editing bundle — packaging decision A from the editing-surface RFC. Scaffold only, no interaction logic yet: - src/editing/types.ts: the L1 edit-intent contract (EditIntent, Selection, EditableSlideCanvasProps) — the bounded canvas gesture vocabulary. The agent tool surface (L2) and the canonical change (L0, @openmaic/dsl) are out of scope here. - src/editing/EditableSlideCanvas.tsx: a shell that renders through the v1 read-only SlideCanvas and supports click-to-select only. Operate handles, snapping, ProseMirror inline editing, and onElementsChange emission land in Part A / Part B. - package.json + rollup.config.js: wire the ./editing entry (mirrors ./snapshot). Refs #851 (renderer v2 editing surface, #720 Phase 3). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): address editing-scaffold cross-review - Add `'use client'` to EditableSlideCanvas so the editing subpath is a proper client boundary (every v1 client component leads with it). Without it, a Next App Router server component importing the subpath would reject the function props the shell passes to the client SlideCanvas. - Drop the wrapper `<div>`: it had `height: auto`, collapsing SlideCanvas's `height: 100%` auto-fit to 0 (the slide rendered invisibly). Forward `className`/`style` straight to SlideCanvas, preserving the v1 fill contract. - Freeze `EMPTY_SELECTION` and type `Selection.elementIds` as `readonly` so the shared sentinel cannot be mutated. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): add 'use client' to the public editing entry Review follow-up: put the client-boundary directive on the public `@openmaic/renderer/editing` entry (the barrel that consumers resolve), not only on EditableSlideCanvas.tsx. Note: this is necessary but not sufficient on its own — the rollup build currently drops module-level directives (the config's onwarn silences the MODULE_LEVEL_DIRECTIVE warning), so the published bundle strips `'use client'` today (the published v1 dist has none either). The effective fix is preserving directives in the build; tracked separately since it changes the whole package's published output. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(renderer): preserve 'use client' in the build output The rollup build stripped module-level directives (the MODULE_LEVEL_DIRECTIVE warning is silenced in onwarn), so the published dist dropped 'use client' from every file — including the editing entry and v1's client components — which breaks Next App Router server-component consumers. Enable `preserveModules` (the `preserveModulesRoot` option was already present but inert without it) and add `rollup-plugin-preserve-directives`, so each source module's `'use client'` survives per-file into dist. Verified against the built output: - dist/editing/index.js and dist/editing/EditableSlideCanvas.js keep 'use client' - dist/SlideCanvas.js (v1) keeps it too (it was dropped before) - dist/index.js (read-only barrel) stays clean — re-exports the client module, so the read-only path/design is unchanged and still doesn't pull the editing bundle - all export entries (., ./elements, ./types, ./snapshot, ./editing) resolve 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-06 13:20:58 +08:00
wyucandClaude Fable 5	b669f791db	feat(importer): normalize slides at the pipeline output boundary (#787 follow-up) (#845) ... * feat(importer): normalize slides at the pipeline output boundary (#787) Wire the DSL contract's element normalization at the importer's output boundary, the counterpart of the generator wiring that landed with normalize itself: parsedToSlides (and therefore importPptx) now runs every transformed element through normalizeElement. - normalizeImportedSlides: fills any required content field the transform left off and derives geometry-dependent fields; an element normalization cannot repair is dropped with a warning instead of failing the whole import or reaching consumers unguarded, matching the importer's existing degrade-not-fail upload policy. - exported from the package root for consumers that call transformParsedToSlides directly. - test/normalizeImportedSlides.test.ts covers default-filling, pass-through of well-formed elements, drop-and-warn on malformed input, input purity, and the parsedToSlides end-to-end boundary. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): preserve explicit empty shape fill; own the drop policy in normalizeSlide Cross-review round on the importer boundary wiring surfaced two issues, both fixed at the contract level: - normalizeShape no longer treats an explicit `fill: ''` as absent. The empty string is a meaningful fill — "no solid fill" (transparent, or gradient/pattern carried by sibling fields) — and the renderer maps it to `none`. Defaulting it painted every imported gradient / image-filled / unfilled shape with the canonical color. Font/color fields keep the empty-is-absent repair semantics; only `fill` uses the new strKeepEmpty. (This also means a generator-emitted `fill: ''` now renders as intended no-fill instead of the legacy default color.) - normalizeSlide gains an optional { onInvalid: 'throw' | 'drop', onDropped } policy, so producers normalizing wild-world input own a single shared repair-or-drop pass instead of each hand-rolling the try/normalizeElement/catch idiom (the importer was about to become the second copy alongside the generator's). Default stays 'throw'. normalizeScene/normalizeStage now call normalizeSlide via an explicit arrow so map's index can't land in the options parameter. The importer's normalizeImportedSlides composes normalizeSlide with the drop policy, keeps the console.warn reporting, and documents that direct transformParsedToSlides callers should apply it themselves. New tests: empty-fill preservation (dsl unit + importer unit + parsedToSlides end-to-end regression), drop-policy semantics, plus the existing suite. @openmaic/dsl 0.3.0 -> 0.4.0 (new normalizeSlide option). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(importer): document normalizeImportedSlides in the README API surface Round-2 review finding: the function is a public export whose docstring tells direct transformParsedToSlides callers to apply it, but it was missing from the API table and signature block. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(dsl): keep normalizeSlide unary via curried normalizeSlideWith; bump importer to 0.1.0 Addresses review: - normalizeSlide is unary again, so existing point-free `slides.map(normalizeSlide)` call sites keep type-checking. The element-invalidity policy moves to normalizeSlideWith(options), which returns a map-safe unary function (and returns normalizeSlide itself when no drop policy is requested). normalizeScene/normalizeStage go back to plain .map(normalizeSlide); the importer builds its dropper once and maps it. A test pins the point-free ergonomics. - @openmaic/importer 0.0.2 -> 0.1.0: the publish workflow is version-bump driven and 0.0.2 is already on npm; without the bump the new export + output-boundary behavior would never ship. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>	2026-07-05 13:14:23 +08:00
wyucandClaude Opus 4.8	fcdb6d62b3	feat(dsl): own element-level normalization & defaults; wire the generator (#787) (#832) ... * feat(dsl): own element defaults + normalize(); wire the generator (#787) Bring element-level normalization into the @openmaic/dsl contract, so producers stop carrying their own imperative "fix up the output" pass. Companion to the #817 validators: where validate* reports on a document, normalize* repairs one. - src/normalize.ts: pure, zero-dep normalizeElement / normalizeSlide / normalizeScene / normalizeStage + canonical ELEMENT_DEFAULTS. Fills missing required content fields, derives geometry (a line's start/end, a shape's viewBox/path from its box), and FAILS LOUD on a present-but-wrong-typed field instead of silently resetting it. Pure, non-mutating, idempotent. Scope is element content — base identity/geometry (id, left/top/width/height/rotate) is producer-supplied (the id is assigned downstream) and left to validate*/schema. - slides.ts: static defaults ride out on the generated JSON Schema as @default annotations (so non-TS consumers ship them too); ELEMENT_DEFAULTS is the single source of truth, pinned to the schema by a lockstep test. - generator: fixElementDefaults drops its per-type fixups for normalizeElement, wrapped in try/catch so a malformed element degrades gracefully (log + keep raw) rather than aborting a whole scene/course — generation runs on unreliable model output and on legacy slides the old pass itself produced. Image aspect-ratio reconciliation stays (it needs the resolved asset's real dimensions — a producer concern the DSL does not own). Two latent bugs fixed while canonicalizing into the contract: - shape viewBox: the old missing-viewBox fallback emitted a string "0 0 w h", which every consumer reads as viewBox[0]/[1]; normalize emits the contract's [w, h] pair. - line start/end: the old fallback derived ABSOLUTE [left, top] coordinates, but the renderer positions the line container at (left, top) and reads start/end as LOCAL offsets (getLineElementPath / getElementRange) — double-offsetting the line. normalize derives them in the local frame ([0,0] .. [w, h]). Minor bump @openmaic/dsl 0.2.0 -> 0.3.0. test/normalize.test.ts covers the defaults, derivation (incl. the local-frame line regression), fail-loud coercion, purity/idempotency, generic app-widened normalizeScene, schema conformance of normalized output, and the ELEMENT_DEFAULTS <-> schema lockstep. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style: format normalize.ts / normalize.test.ts with prettier Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsl): normalize nested ShapeText; repair-or-drop malformed elements in the generator Address review on #832: - normalizeShape now normalizes a present `text` overlay (ShapeText): fills content / defaultFontName / defaultColor / align with canonical defaults (align 'middle' per the renderers' convention), fails loud on a malformed overlay. Consumers read `text.content` unguarded (the PPTX exporter feeds it to formatHTML), so a present overlay gets the same repair semantics as the element's own required fields. Defaults ride the schema as @default and are pinned by the lockstep test. - The generator's fixElementDefaults no longer keeps a raw element when normalization fails — repair or drop: JSON nulls from the model are stripped first (null means absent; normalize then fills/derives the field), and an element that still fails is discarded with a warning. Keeping the raw payload handed malformed lines (start/end null) to consumers that index straight into start[0] (getElementRange / BaseLineElement / export), crashing playback or export over one bad element. 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-03 14:19:38 +08:00
3 people	cd5f997dd2	docs: document the dev-server OOM workaround for large generations (#808) ... Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com> Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>	2026-07-02 05:44:20 -04:00
3 people	9b4746efe9	feat(dsl): activate the migration registry + runner (#787 Part B-2) (#825) ... * feat(dsl): activate the migration registry + runner (#787 Part B-2) `version.ts` was a stub (`DSL_MIGRATIONS = []`, no runner). Fill in the document-level migration mechanism, keeping @openmaic/dsl zero-runtime-dep: - `migrate(doc)` — walks a document from its written `dslVersion` (absent => legacy) up the `DSL_MIGRATIONS` ladder to `DSL_VERSION`, stamping the result. Idempotent, forward-compatible (never downgrades a newer doc), fail-loud on a broken ladder. Mirrors the app's `migrateSlideContent` philosophy. - `dslVersionOf` / `needsMigration` readers; `DslVersioned` envelope type; `UNVERSIONED_DSL_VERSION` / `DSL_VERSION_KEY` constants. - First ladder entry: a no-op transform stamping legacy docs to the current `DSL_VERSION` (0.1.0) — no serialized shape changed in #811/#817, so this wires the pipeline end to end without faking a shape bump. - `DSL_VERSION` stays 0.1.0 (serialized-contract axis); package minor-bumps to 0.2.0 for the new API surface. README documents the two independent version axes (+ the orthogonal app-side `SlideContent.schemaVersion`). - test/version.test.ts: ladder invariants, stamp/idempotence/purity, forward-compat, fail-loud. Closes the migration-registry acceptance box of #787; the app-side wiring of a normalized store onto this pipeline remains future work (per the issue's open question). * fix(dsl): pin migration endpoints to literals, not the moving DSL_VERSION Cross-review (codex, P2): the first ladder entry used `to: DSL_VERSION`. Once a future shape change bumps DSL_VERSION and appends a real step, that entry's `to` would move too, so legacy docs would be stamped straight to the new version and skip the appended transform. Migration endpoints must be immutable. - add `INITIAL_DSL_VERSION` (pinned '0.1.0' literal); first entry targets it instead of the moving `DSL_VERSION` constant. - test asserts `DSL_MIGRATIONS[0].to === INITIAL_DSL_VERSION` to guard the intent. * fix(dsl): validate version stamps + align needsMigration/migrate on non-objects Addresses cosarah's review on #825: - Malformed version stamps no longer silently bypass migration. `dslVersionOf` now fails loud on a present-but-malformed stamp (e.g. "1", "0.1", "0.1.0-beta"), instead of letting `parseVersion` coerce it into a comparable value that reads as >= DSL_VERSION. Absent stamp / non-object still map to the unversioned baseline. Adds an `isValidVersion` (`x.y.z`) guard. - `needsMigration` and `migrate` now agree on non-objects: both treat a non-object as "nothing to migrate" (needsMigration -> false, migrate -> input unchanged), so `while (needsMigration(x)) x = migrate(x)` can't loop forever. Tests cover malformed-stamp fail-loud and the non-object agreement invariant. --------- Co-authored-by: wyuc <zdq1204@gmail.com> Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-07-01 18:53:12 +08:00
wyucandClaude Opus 4.8	7c19ab8f1e	feat(dsl): JSON Schema artifacts + pure validators (#787 Part B-1) (#817) ... * feat(dsl): add ACTION_TYPES set + isActionType guard A frozen set of every valid ActionType plus a pure membership guard, mirroring the PPT_ELEMENT_TYPES / isPPTElementType idiom in guards.ts. Used by the new validators; useful standalone for narrowing untrusted action.type values. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(dsl): build-time JSON Schema codegen for stage/scene/action TS types stay the single source of truth; ts-json-schema-generator (a devDependency, build-only) emits dist/schema/{stage,scene,action}.schema.json, shipped under the new ./schema/* export. Serves non-TS / bring-your-own-validator consumers without adding a runtime dependency. JSON Schema is not generic, so schema-roots.ts provides a concrete Scene<Action, SceneContent> entry point (kept internal, not re-exported). schema.test.ts compiles the generated schema with ajv (devDep) to prove the artifact is real and self-contained on a clean checkout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * feat(dsl): add pure structural validators (stage/scene/action) validateStage / validateScene / validateAction: hand-written, zero-dependency, fail-loud structural checks layered on the existing guards. They verify discriminants, required fields, and known nested discriminants — a gate for untrusted input (LLM/agent output) and persistence boundaries. Exhaustive per-field validation is delegated to the shipped JSON Schema. Error-collecting ValidationResult reports every issue with a JSON-pointer-ish path. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(dsl): document the runtime schema + validator layer Add a Runtime layer section covering the two complementary consumption modes (schema-as-data via @openmaic/dsl/schema/* and the zero-dep validate* gate), the validate.ts module row, the build:schema step, and tick the JSON Schema roadmap box. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsl): harden validators per cross-review (exhaustiveness, discriminant agreement) Addresses cross-review findings on the validator layer: - Add compile-time exhaustiveness assertions for ACTION_TYPES and SCENE_TYPES. `satisfies` only proved each entry is valid, not that the tuple covers the whole union — a newly-added Action/Scene variant could silently be rejected by the validators. The assertion now fails the build on drift. - validateScene cross-checks that scene.type agrees with content.type; a slide-typed scene carrying quiz content (or vice versa) is now rejected. - Move SCENE_TYPES + add an isSceneType guard to stage.ts, next to SceneType, matching the PPT_ELEMENT_TYPES / isPPTElementType idiom in guards.ts; validate.ts reuses them instead of re-encoding the union locally. - Make the validators' scope honest in the doc comment + README: they check the structural envelope, known discriminants, and scene/content agreement; they do NOT exhaustively check per-variant fields, and app-side interactive/pbl content is validated only at the envelope level (exhaustive checks → the JSON Schema). - Note the contract-owned content scope in schema-roots.ts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * perf(dsl): reuse one schema generator + harden direct-invocation guard Addresses cross-review findings on the codegen path: - gen-schema.mjs built a fresh ts-json-schema-generator (full TS program parse) per root type; build one generator over the tsconfig program and reuse it for every createSchema call — parses once, identical per-type output. - Harden the `invoked directly` check to compare realpaths, so a symlinked invocation (bin shim / pnpm link) still runs main() instead of silently emitting no schema. - schema.test.ts generates all roots once at module scope, then only compiles per case — no repeated heavy codegen. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsl): bind scene schema discriminants + pin node-20-compatible generator Addresses round-2 cross-review (codex) findings: - scene.schema.json now ties scene `type` to the matching `content.type`. SerializedScene became a discriminated union (SlideScene | QuizScene via `Omit<Scene<…>, 'type'> & { type }`), so the generator emits a const-narrowed discriminant per branch. Previously the schema accepted e.g. { type: 'quiz', content: { type: 'slide', … } } even though validateScene rejects it — the schema is now consistent with the validator. Locked with a test. - Pin ts-json-schema-generator to ~2.4.0. ^2.3.0 resolved to 2.9.0, which declares `node >=22`, conflicting with the repo's `engines.node >=20.9.0`; 2.4.x supports node >=18, keeping the build runnable on every supported Node. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * style(dsl): prettier formatting + drop unused ts-expect-error for green CI - Apply repo Prettier (`pnpm check`) formatting to the new/edited files. - Remove the `@ts-expect-error` on the gen-schema.mjs import: the root `tsc --noEmit` (which compiles test files; allowJs infers the .mjs exports) flagged it as an unused directive (TS2578). Plain comment retained. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(dsl): align validators + schema to the public Scene type (review) Addresses cosarah's review: the validator, the JSON Schema, and the public TS type had drifted into three different notions of a valid scene. Realign them so the TS types stay the single source of truth, and position the two runtime layers honestly. - schema-roots.ts: revert SerializedScene to the plain default Scene<Action, SceneContent>. The schema no longer encodes a stricter type/content binding that the public Scene type doesn't express (the constraint had effectively moved into a hidden internal type). - validate.ts: drop the scene.type<->content.type agreement check (the public Scene does not bind them, so neither does the validator); restrict content to the contract-owned kinds (slide/quiz), matching SceneContent and the schema, so validator and schema no longer disagree on interactive/pbl content. - Reposition docs (validate.ts header + README): the JSON Schema is the authoritative, exhaustive per-field validator (it checks variant fields like an action's elementId) for trust boundaries; validate* are a cheap, zero-dep structural pre-check and a strict subset of the schema — not a separate or stricter gate. - Tests updated to lock the realigned behavior. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * refactor(dsl): bind scene type<->content in the public Scene contract (review) cosarah's review showed the scene type<->content agreement is a real, load-bearing invariant: consumers branch on `scene.type` and then read `scene.content` as the matching shape (e.g. `stage-api-canvas` casts `content as SlideContent` after a `scene.type === 'slide'` check; `complete-summary` counts by `scene.type` and reads `content as QuizContent`). A validator/schema that blesses mismatched pairs is unsafe. So tighten the *exported* contract rather than loosening the runtime checks to match a hole — and make the pure validators the authoritative, relied-upon boundary. DSL contract: - `Scene` becomes a distributive discriminated type binding `type` to `content['type']` (`SceneCore<TAction> & { type: TContent['type']; content: TContent }` distributed over TContent). TS itself now rejects mismatched scenes; generic widening still works. Extract `SceneCore` for the kind-independent fields. - `validateScene` re-establishes the type<->content agreement check; scene `type` is the contract's slide/quiz; `scene.schema.json` (from the spelled-out discriminated `SerializedScene`) binds `type` to content per branch. Type, validator, and schema now describe the same thing. - `validateAction` checks each variant's required fields (e.g. spotlight.elementId, discussion.topic) — closes the false-positive gap. A test pins the hand map to the generated schema (the TS-derived source of truth) so it cannot drift. - Reposition docs: `validate*` is the zero-dep in-process boundary producers rely on; the JSON Schema is the cross-language mirror + exhaustive value checker. App consumers (the sites the discriminated Scene exposes): - Add `ScenePatch` (non-distributive partial) + `makeScene(core, content)` helper to lib/types/stage.ts — one isolated cast, type derived from content. Patch-typed signatures (`updateScene`, `applyScenePatchInSync`, regenerate plan) and scene rebuilds (`stage-api-scene`, store `updateScene`, `migrateScene`, stage-storage deserialize) route through these. Closes two latent desync foot-guns. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(dsl): validate action field types + migrate scene.update; bidirectional drift-guard (review) Round-2 review of the contract-tightening change (codex + Claude): - validateAction now checks each variant-required field's TYPE, not just presence (`{ type:'spotlight', elementId: 123 }` is rejected — elementId must be a string). ACTION_REQUIRED_FIELDS carries a runtime kind per field. - The schema lockstep test is now bidirectional and type-aware: it asserts a fully-typed action is accepted (catches the map OVER-listing an optional field), every required field flags when missing (under-listing), and flags when present but mis-typed — all keyed off the generated schema's field names + types. - Migrate the public `stageApi.scene.update()` to ScenePatch + makeScene (the create() path was done last commit; update() still did a raw spread that could desync type<->content — masked from tsc only because StageStore.setState is typed `any`). Now both public scene-construction paths rebind type to content. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * fix(api): keep scene.create's params.type authoritative over content.type (review) cosarah's review: `CreateSceneParams` exposes an independent `type` plus `content?: Partial<SceneContent>`, and after switching create() to makeScene() (which derives the scene kind from content.type), a call like `create({ type: 'slide', content: { type: 'interactive', ... } })` would silently become an interactive scene — params.type ignored — and mix slide defaults into it. Reject a `content.type` that disagrees with `params.type`, and pin the merged content's `type` to `params.type` so a partial content override can't flip the scene's discriminant. params.type stays authoritative. Adds a test both ways. 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-01 01:04:34 +08:00
4 people	a3f88d53e5	fix(mathml2omml): call includes() instead of indexing it (#681) ... parse.js used `textContainerNames.includes[arr[level].name]`, which reads a property of the includes function (always undefined) instead of calling it, so the "trailing text node" branch never ran and trailing text inside a MathML text container (mtext/mi/mn/mo/ms) was dropped from the OMML. Line 48 of the same file already uses the correct `includes(...)` form. dist/ is gitignored and rebuilt by postinstall, so the runtime bundle picks up the fix on install. Closes #680 Co-authored-by: ly-wang19 <ly-wang19@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>	2026-06-30 04:50:07 -04:00
wyuc	b122ca30d3	feat(dsl): bring the Action playback verbs into @openmaic/dsl (#787) ... Promote the Action contract (Action union + variants, ActionType, the action-category lists, PercentageGeometry) into @openmaic/dsl/src/action.ts, zero-runtime-dep. Widget interaction actions graduate into the contract; Scene<TAction> defaults to the standard Action union; lib/types/action.ts becomes a re-export shim. Part A of #787 (Phase 2 under #720).	2026-06-29 23:38:28 -04: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
xuyuanwei678andwyuc	72e3ef04d7	chore(packages): set openmaic package versions to 0.0.2 (#812) ... Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>	2026-06-29 16:22:13 +08:00
xuyuanwei678andwyuc	8e39e7e665	fix(importer): port PPTX shape restoration hotfixes (#789) ... * fix(importer): port pptx shape hotfixes * chore: format pptx importer hotfix * test(importer): satisfy strict typecheck * fix(renderer): constrain slide element hit target * test(renderer): keep hit target regression in package * fix(renderer): preserve thumbnail click-through * fix(importer): correct warp height and blank date labels --------- Co-authored-by: wyuc <wang-yc24@mails.tsinghua.edu.cn>	2026-06-25 23:35:28 -04: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
wyucandClaude Opus 4.8	beac93ab3d	chore: relicense from AGPL-3.0 to MIT ... Switch the OpenMAIC root and the in-house @maic/* SDK packages (@maic/dsl, @maic/importer, @maic/renderer) from AGPL-3.0 to the MIT License. Updates LICENSE files, package.json license fields, README badges and license sections (EN/ZH), CONTRIBUTING, and renderer FONTS note. Third-party vendored packages are left untouched: packages/mathml2omml remains LGPL-3.0, packages/pptxgenjs remains MIT. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-17 04:00:00 -04:00
wyucand杨慎	b1e5beee0f	feat(dsl): promote Stage/Scene lesson skeleton into @maic/dsl (#740) (#743) ... * feat(dsl): promote Stage/Scene lesson skeleton into @maic/dsl (#740) Phase 2 of the @maic SDK consumption epic (#720): move the universal lesson skeleton into the contract package, with Scene generic so app-side feature surfaces (Action, widgets, PBL) plug in via type parameters. DSL (packages/@maic/dsl): - New src/stage.ts: Stage, SceneType, StageMode, Whiteboard, VideoManifest, GeneratedAgentConfig, MultiAgentConfig, SlideContent, QuizContent, and a narrowed SceneContent (SlideContent | QuizContent). - Scene<TAction = never, TContent extends { type: SceneType } = SlideContent | QuizContent> — the contract owns only the structure + universal content kinds; TContent is constrained structurally so an app can pass a wider content union. Defaults give renderers/importers a feature-free skeleton. - Pure guards isSlideContent / isQuizContent. - Registered in index.ts barrel; README roadmap item checked off + 'Stage / Scene split' section added. - Added vitest config + test script + stage.test.ts (9 contract tests). App (lib/types/stage.ts): - Rewritten as a shim: re-exports the skeleton types from @maic/dsl, keeps InteractiveContent / PBLContent (app feature surfaces), and aliases Scene = Scene<Action, AppSceneContent> so all ~55 existing import sites keep their semantics. The generation re-export block is dropped (verified zero consumers import those five types via @/lib/types/stage). Scope B from #740 (lesson container in DSL, features plug in). Decision: generic Scene<TAction, TContent> over a registry/extension seam — explicit, isolatedModules-friendly, no declaration-merge pitfalls. * fix(dsl): address review — guard genericity, standalone tests, type pin 1. isSlideContent / isQuizContent: relax <T extends SceneContent> to <T extends { type: SceneType }> so the guards accept an app-widened content union (interactive / pbl) — the generic case Scene<TAction, TContent> is meant to support. Add a regression test exercising the widened union. 2. tests: resolve @maic/dsl to ./src/index.ts via resolve.alias in vitest.config.ts, so 'pnpm --filter @maic/dsl test' is standalone on a clean checkout (no dist build required). Verified by deleting dist and re-running. 3. Pin the TAction-defaults-to-never type test to .toEqualTypeOf<never[] | undefined> instead of the trivially-true .toMatchTypeOf<unknown[] | …>. * style: prettier-format lib/types/stage.ts (CI prettier --check) * fix(stage): value-export isSlideContent/isQuizContent from the compat shim The two discriminant guards are runtime functions but were sitting inside the shim's `export type { … }` block, which erases them: `import { isSlideContent } from '@/lib/types/stage'` would resolve to `undefined` at runtime and TS-error 'cannot be used as a value'. No call sites import the guards through the shim today (latent), but the shim's job is back-compat re-export, so move them to a plain `export { … }`. --------- Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-06-16 16:11:15 +08:00
3 people	254ec743db	chore(phase-1): drop dead ThumbnailSlide + fix @maic/dsl Node ESM resolution (#736) ... * refactor(slide-renderer): remove dead legacy ThumbnailSlide/ThumbnailElement These were the in-app read-only thumbnail renderers replaced by SlideThumbnail (→ @maic/renderer) in #707. They have zero importers now — the editor nav rail renders through SceneThumbnailContent → SlideThumbnail; the only remaining "ThumbnailSlide" mentions are an unrelated local type alias / util name and historical doc comments. Delete the dead code (~215 LOC). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(dsl): emit explicit .js extensions so @maic/dsl resolves under Node ESM The build used `moduleResolution: bundler` + extensionless re-exports, so the emitted `dist/index.js` did `export * from './slides'` — which fails bare-node ESM resolution (`ERR_MODULE_NOT_FOUND`), even though Next's bundler tolerated it. Switch the package tsconfig to `NodeNext` and add `.js` extensions to the relative specifiers so tsc emits resolvable ESM. `node -e import('@maic/dsl')` now loads; NodeNext also enforces extensions going forward. 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-06-15 14:05:03 +08:00
3 people	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
3 people	7bb9e864ae	feat(packages): introduce maic-import and maic-renderer workspace packages (#668) ... * feat(import): add pptxtojson-pro workspace package and stage-1 PPTX import Vendor the TypeScript pptxtojson-pro parser as a workspace package, sync its bundle to public/vendor at install time (avoids Turbopack dynamic require issues), and wire a home-page import hook that parses files for inspection. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(import): extend pptxtojson-pro with PPTX → Slide[] pipeline `importPptx` now turns a .pptx file directly into canvas `Slide[]`, optionally uploading every base64 image and blob-backed media via a caller-supplied OSS callback before resolving. - Vendor OpenMAIC slide types and shapes config into `src/openmaic/` so the bundled dist is self-contained and loadable via `/vendor/` URL under Turbopack; add stubs for `resolveFont`, `getSvgPathRange` and `parseVideoCodec` until the real PPTist helpers are ported. - Move `import-pipeline/` under `src/` and re-export `importPptx`, `parsedToSlides`, `OssUpload`, `ImportPptxOptions` and `CanvasSlide` from the package main entry. - Add `nanoid`, `katex` and `pptxtojson` as runtime deps of the package. - Update `useImportPptx` to accept `upload` / `onImported` and return the converted `Slide[]`. - Document the new API surface, error semantics and Turbopack workaround in the package README. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(slide-renderer): package skeleton (rollup + tsc + empty index) Workspace package scaffolding: package.json with peer deps (react/react-dom/motion/tailwindcss), rollup ESM+CJS config, tsconfig (strict, jsx react-jsx), and empty entrypoints under src/. Verified: pnpm --filter slide-renderer build produces dist/{index,elements/index,types/index}.{js,cjs,d.ts} (empty chunks are expected at this stage). * docs(slide-renderer): DESIGN.md + README.md * feat(slide-renderer): copy Slide/Element types + add effects types * feat(slide-renderer): add utils (geometry simplified to elements API, element ranges, cn) * feat(slide-renderer): shared element hooks (fill/outline/shadow/flip) + ElementOutline * feat(slide-renderer): BaseTextElement * feat(slide-renderer): BaseShapeElement + GradientDefs + PatternDefs * feat(slide-renderer): pure <img> BaseImageElement, decouple OpenMAIC media business The base component drops: - useMediaGenerationStore / isMediaPlaceholder (AI media generation polling) - useSettingsStore (imageGenerationEnabled toggle) - useMediaStageId / retryMediaTask (classroom-scoped retry orchestration) - useI18n (placeholder/error/disabled copy) - skeleton / error / disabled render branches Retains: clip / filter / outline / shadow / colorMask, output <img src={elementInfo.src}>. Adds a `renderImage` slot so consumers can re-inject business behavior (placeholders, retry buttons, custom src resolvers) without modifying the package. * feat(slide-renderer): Line / Table / Latex / Code base elements - Line + LinePointMarker: copied with stroke-draw animation intact - Table + StaticTable + tableUtils: copied with getTableSubThemeColor moved to package utils - Latex: katex HTML + legacy SVG fallback, no business deps - Code: shiki-based syntax highlighting (dynamic import); shiki added as optional peer dependency so consumers without code slides pay zero install cost * feat(slide-renderer): BaseChartElement + Chart + chartOption (echarts as optional peer) * feat(slide-renderer): pure <video> BaseVideoElement, decouple OpenMAIC media business Drops: - useCanvasStore (playingVideoElementId / pauseVideo) - useMediaGenerationStore / useMediaStageId / retryMediaTask / getVideoMediaRefForElement - useSettingsStore (videoGenerationEnabled) - useI18n, motion/react animate scope - skeleton / error / disabled / placeholder branches Retains <video src controls preload=metadata>. Adds a `renderVideo` slot so consumers can re-inject orchestrator-driven playback or placeholders. * feat(slide-renderer): canvas hooks (useSlideBackgroundStyle, useViewportSize simplified) - useSlideBackgroundStyle: copied as-is (no business deps) - useViewportSize: rewritten to take viewportSize/Ratio/canvasPercentage as args, drop useCanvasStore, drop editor-only canvasDragged/dragViewport, return fitScale instead of writing to a store * feat(slide-renderer): 4 effect overlays (Highlight/Spotlight/Laser/Zoom), props-driven All overlays now receive element/geometry/options through props instead of reading useCanvasStore. SpotlightOverlay uses a configurable element-id prefix (default 'slide-element-') to locate DOM nodes for measurement, matching the convention SlideElement will set in T14. HighlightEffectOptions extended with color/opacity/borderWidth/animated to surface the original visual knobs through the public API. * feat(slide-renderer): SlideElement dispatcher with renderImage/renderVideo slots * feat(slide-renderer): SlideCanvas v1 main entry (props-driven, auto-fit viewport) Mirrors ScreenCanvas structure but reads from props: slide.elements, slide.theme, props.background ?? slide.background, props.scale ?? autoFit, props.effects. Auto-fits viewport into container by default via useViewportSize+ResizeObserver; pass scale=1 to opt out and render at slide-native dimensions. * feat(slide-renderer): SlideRendererProvider + useSlideContext (props or context) SlideCanvas now reads from context as a fallback when props are omitted. Allows the wrap-then-compose pattern from spec §3.2: provider holds shared data, sibling overlays read via useSlideContext. * feat(slide-renderer): aggregate public exports Main entry exposes SlideCanvas, SlideElement, Provider/hooks, effects, hooks, utils. `slide-renderer/elements` re-exports all 9 Base*Element + shared ElementOutline/useElementXxx for granular composition. `slide-renderer/types` already lived in src/types/index.ts. * docs(slide-renderer): complete README (install / quickstart / API / effects / Tailwind setup) * feat(demo): /slide-renderer-demo route exercising the workspace package Hand-written single Slide with shapes + text demonstrates the v1 API end-to-end: - props-driven SlideCanvas - auto-fit viewport via parent container - gradient background, shape outline + text fill Wires slide-renderer as a workspace dep and registers its dist as a Tailwind @source so utility classes inside the package get picked up by the host PostCSS pipeline. * feat(pptxtojson-pro): align imported Slide JSON with renderer contract - Drive `viewportWidth` from the deck's actual pixel width (json.size.width × ratio) instead of the legacy 960 default, so 16:9 widescreen decks no longer get text element widths clamped to 4:3 dimensions (e.g. titles truncated to 842px and forced to wrap). Per-slide `viewportSize` now reports the same value, keeping transform-time and render-time aligned. - Replace the pass-through font STUB with real resolution: 22-font self-hosted whitelist + alias map (微软雅黑/等线/宋体/楷体/仿宋/Arial/etc.) → 5-category primary font mapping, so unknown PPT fonts fall back to a rendered open-source equivalent and the pipeline can surface the replacement via `replacedFonts.fallback`. - Translate cell `vAlign` from PPT-native (`up`/`mid`/`down`) to CSS-native (`top`/`middle`/`bottom`) at the importer boundary, so the renderer can transparently pass it through to `vertical-align` / `justify-content` without per-component conversion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(slide-renderer): drop Tailwind defaults, data-drive styles, ship fonts Three intertwined changes that together make the package self-contained and align it with the "slide JSON is the single source of visual truth" contract. 1. Remove Tailwind utility classes from every element renderer. - Replace `className="absolute ..."` / `className="rounded ..."` etc. with inline `style={{ position: 'absolute', borderRadius: ... }}`. - The few rules that can't be expressed inline (descendant selectors, keyframes, browser-default <p> margin reset) move to a new `src/styles.ts` injected once by `<SlideCanvas>` via `<style>`. Named animation classes (`slide-renderer-pulse` / `-ping`) replace `animate-pulse` / `animate-ping` so consumers don't need Tailwind. 2. Strip renderer-level positive defaults; surface them as data fields. - `BaseTextElement`: drop hardcoded `overflowWrap: 'break-word'` and the `paragraphSpace ?? 5` fallback. `--paragraphSpace` is only set when defined in data; CSS `var()` fallback is 0. - `StaticTable`: drop hardcoded `padding: '5px'`, `verticalAlign: 'middle'`, `wordBreak: 'break-word'`. Extend `TableCell` with `padding?: string` and `vAlign?: 'top' | 'middle' | 'bottom'` so PPT-extracted padding / vertical alignment flow through unchanged. - `PPTTableElement` gets `rowHeights?: number[]` (per-row min-height; content can still grow rows). - Reshape `<td>` to match the classroom Vue layout: outer `<td>` carries only border + textStyle; inner `slide-renderer-cell-text` <div> is a flex column with `min-height = rowHeight - 4`, `padding = cell.padding`, `line-height: 1`, `justify-content` from `cell.vAlign`. Add `.slide-renderer-cell-text p + p { margin-top: 0.4em }` to give adjacent paragraphs breathing room without breaking the reset. 3. Self-contained font shipping. - Move the 22 woff2 files into `packages/slide-renderer/fonts/`. - Ship a sibling `fonts.css` with @font-face declarations using relative `./fonts/<name>.woff2` URLs. - Expose both via `package.json` exports (`./fonts.css`, `./fonts/*`) and the `files` array. - Consumer adds one import (`import 'slide-renderer/fonts.css'`); the bundler resolves the relative URLs against the package and emits each woff2 as a static asset. Removes the dependency on consumer- owned `app/globals.css` @font-face blocks and `public/font/` copies. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(demo): wire slide-renderer fonts and swap demo to a table-heavy slide - Import `slide-renderer/fonts.css` in the root layout so consumer apps pull the package's self-hosted @font-face declarations and woff2 assets through Next.js' static-asset pipeline. - Replace the hardcoded `demoSlides` array (24 mixed-element slides) in `/slide-renderer-demo` with a single 5×7 table-heavy slide so the demo exercises the new `TableCell.padding` / `TableCell.vAlign` / `PPTTableElement.rowHeights` fields and the flex-based cell layout. Convert the legacy `vAlign: 'up' | 'mid' | 'down'` values to the CSS-native `'top' | 'middle' | 'bottom'` form the renderer now expects. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(slide-renderer): add slideToPng standalone snapshot util Exposes a new `slide-renderer/snapshot` sub-export with `slideToPng(slide, options)`, the foundation for the AI-driven visual diff loop (snapshot the rendered slide, compare against PowerPoint's own PNG export, decide whether a discrepancy belongs to the import algorithm or the renderer). Implementation notes - Mounts `<SlideCanvas>` into an off-screen container sized exactly to the slide's native pixels, so `useViewportSize` collapses to a 1:1 render (no scale offset). - `flushSync` for the initial commit so the snapshot doesn't fire on an empty container; `requestAnimationFrame` × 2 to let the ResizeObserver settle; then waits for `document.fonts.ready` and every `<img>` in the container (with a configurable `timeoutMs`, default 5s). - Snapshots the SlideCanvas root (`container.firstElementChild`) rather than the outer wrapper — html2canvas-pro's bounding-box math otherwise leaves white edges or drops absolutely-positioned children. - Uses `html2canvas-pro` instead of `html-to-image`: the latter's SVG `<foreignObject>` path loads embedded woff2 asynchronously, so the drawImage fires before fonts decode and text re-wraps in the fallback font. html2canvas-pro walks the DOM and inherits the parent document's font registry, keeping wrap positions identical to the on-screen render. - `onclone` hook injects a small CSS reset (`font-kerning: none`, `font-feature-settings: normal`, `font-variant-east-asian: normal`, `text-rendering: geometricPrecision`) scoped to the slide tree, to prevent html2canvas-pro's CJK text measurement from clipping full-width punctuation (e.g. `（` / `）`) past cell boundaries. - Default `pixelRatio` follows `window.devicePixelRatio` for retina-sharp output; consumers can override. - Optional `debugVisibleMs` briefly shows the off-screen container after snapshot so callers can compare what was captured vs the live render. Wiring - Sub-export added to `package.json` (`./snapshot`) and Rollup `entries` for tree-shaking — apps that don't use snapshot don't pay the `html2canvas-pro` bundle cost. - Demo route adds an "导出 PNG" button that calls `slideToPng` on the active slide and triggers a browser download. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: build slide-renderer in root postinstall Without this, fresh installs leave packages/slide-renderer/dist missing and Next.js fails to resolve the `slide-renderer` import. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(parser+renderer): iteration-0601-002 fidelity fixes Parser (pptxtojson-pro): - shapeSerializer: stop painting parent fill on grpFill children; honor explicit <a:ln><a:noFill/></a:ln> over theme lnRef (master logo dots were rendering as visible green rings). - imageSerializer: detect custGeom ellipses and 8-vertex chamfered-rect photo frames; resolve to 'ellipse'/'octagon' instead of falling back to 'rect'. - textSerializer: emit text-shadow from rPr effectLst > outerShdw, and compensate the half-leading PowerPoint puts above the first line for unitless lnSpc > 1 (cover-title gap regression). - border/tableSerializer: pass rgba()/hsla() colors through ensureHex untouched so '#rgba(...)' never reaches the DOM. - transformParsedToSlides: drop the 1.1 SAFE_PADDING wrap-fudge and thread bodyPr@anchor through as vAlign. - font config: add 思源黑体/思源宋体 + Source Han aliases and a trailing region/weight suffix stripper so 'SourceHanSerif CN Light' resolves. Renderer (slide-renderer): - SlideCanvas: new chrome prop (default true) to opt out of the preview-only card shadow + rounded corners; snapshot pipeline passes false so html2canvas output matches PPT edges. - BaseTextElement: flex-column + justifyContent driven by the new vAlign field; width/height stay 100% so the box anchors correctly. - BaseImageElement: maxWidth/maxHeight 'none' to prevent host CSS from shrinking absolutely-positioned <img>. - snapshot: render with chrome=false. Docs: SKILL.md expanded with the iteration workflow + OOXML traps. * fix(parser+renderer): iteration-0605-001 fidelity fixes slide-renderer: - PPTImageElement: add `softEdge` field (feather radius that fades image alpha to transparent at every edge, per a:softEdge@rad). - TableCell: add per-side `borders` so cells with partial dividers render each side independently instead of falling back to the table-level uniform outline. - BaseTextElement: hoist `fill`/`opacity` to the outer wrapper so the background covers the full shape rectangle, matching PowerPoint behavior for short text inside tall shapes. - Misc tweaks across image/latex/shape/video base elements, StaticTable and the standalone snapshot util. pptxtojson-pro: - Parser/serializer fidelity improvements for text, math, image, shape and table (notably ~500 lines in textSerializer and ~127 in mathSerializer). - Refinements in GroupNode, MathNode and ShapeNode models; richer Theme, StyleResolver and RenderContext plumbing. - Expanded shape presets and customGeometry utilities, plus adapter and import-pipeline updates to surface the new fields. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: stop tracking local slide-renderer-demo sandbox `app/slide-renderer-demo/page.tsx` is a personal scratchpad used for ad-hoc rendering tests; it shouldn't ship with the package. Remove it from the index (file stays on disk locally) and ignore the directory so future tweaks don't show up in `git status`. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: rename packages pptxtojson-pro→maic-import and slide-renderer→maic-renderer Align workspace package names with the MAIC product family: packages/pptxtojson-pro → packages/maic-import packages/slide-renderer → packages/maic-renderer Functional references updated end to end: - Root package.json: workspace deps + postinstall/sync scripts - next.config.ts: transpilePackages - app/globals.css: Tailwind `@source` for renderer dist - app/layout.tsx: `maic-renderer/fonts.css` import - lib/import/use-import-pptx.ts: imports + runtime URL (`/vendor/maic-import/index.js`) + script comment - scripts/sync-maic-import.mjs: renamed and pointed at the new dist - .gitignore: vendor path and sync-script comment - Package package.json `name` fields and cross-link in READMEs Also re-include the gitignored `app/slide-renderer-demo/` in Tailwind's source detection via an explicit `@source` so its classes (e.g. `bg-violet-600`) keep getting generated — Tailwind v4 skips gitignored paths by default, which was making the demo's import button render white-on-white after the demo was excluded from version control. CSS class names (`slide-renderer-prose` / `slide-renderer-cell-text` / `slide-renderer-pulse` / `slide-renderer-ping` / `slide-renderer-code- cursor-blink`) and internal source comments that still reference the old package names are intentionally left untouched to keep the rename diff minimal; they can be updated separately as the codebase evolves. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(dsl): extract @maic/dsl contract package and adopt @maic/* scope Establish the SDK family's contract keystone and align package naming with the planned @maic/* scope, per PR #668 review. 1. New @maic/dsl package (packages/maic-dsl) - Pure, zero-runtime-dependency spec: the canonical slide object model, pure type-guards, and DSL version/migration scaffolding. - Seeded from lib/types/slides.ts but reconciled into a *superset* of the three previously-drifted copies (app / renderer / importer); merged fields are annotated @since-merge. README documents the divergence and the acyclic dependency arrows (renderer/importer -> dsl -> nothing). - Enums are regular (not const) so consumers compiling with isolatedModules can import them across the package boundary (TS2748). 2. Wire @maic/importer to @maic/dsl - Import all slide types from @maic/dsl; delete the vendored openmaic/types/slides.ts copy. - Eliminate the Slide drift at the root: transformParsedToSlides now fills viewportSize/viewportRatio/theme at construction and emits a complete DSL Slide, removing the partial "draft slide" + post-fill step in parsedToSlides (no DraftSlide type needed). - Add @maic/dsl to the root postinstall build chain before the importer. 3. Adopt @maic/* scope (agent-noun names) - maic-import -> @maic/importer - maic-renderer -> @maic/renderer - Update all package-name references (deps, app imports, transpilePackages, fonts.css subpath import, Tailwind @source node_modules path, READMEs). - Directory names and /vendor paths are intentionally left unchanged. Note: @maic/renderer still vendors its own slide types; wiring it to @maic/dsl is the next step. Co-authored-by: Cursor <cursoragent@cursor.com> * refactor(renderer): consume slide types from @maic/dsl, drop vendored copy Wire @maic/renderer to the @maic/dsl contract keystone, completing the de-duplication of the slide object model across the SDK family. - Delete packages/maic-renderer/src/types/slides.ts (the vendored copy) and repoint all ~30 internal imports at @maic/dsl. SlideElement's runtime `ElementTypes` value import now resolves to the DSL enum. - Re-export the DSL types from src/types/index.ts so the public `@maic/renderer/types` entry keeps exporting the full slide contract (alongside the renderer-only effect types). - Add @maic/dsl as a regular dependency and mark it external in the rollup build so consumers share a single copy (enum not inlined); the emitted .d.ts references @maic/dsl directly. @maic/dsl is a superset of the renderer's former types, so this is non-breaking; the renderer additionally gains `script` and the importer-origin fields it didn't previously declare. Co-authored-by: Cursor <cursoragent@cursor.com> * refactor(renderer): serve fonts from OSS, drop the 43.6MB bundled woff2 Move the 22 CJK fonts off the repo and onto object storage to fix the PR #668 blocking repo-weight concern. - fonts.css now points every @font-face src at https://file.maic.chat/fonts/<name>.woff2 instead of bundled local files. - Extract the CDN origin + font whitelist into fonts.config.mjs (single source of truth) and generate fonts.css from it via scripts/generate-fonts-css.mjs. `genfonts` runs first in the build, so the CSS always reflects the config; changing the domain is now a one-liner. - Delete packages/maic-renderer/fonts/*.woff2 (22 files, ~43.6MB) and drop the now-unused "./fonts/*" export and "fonts" files entry from package.json (fonts.css is kept). Font names are unchanged, so consumers and the importer font whitelist are unaffected. Note: this removes the files going forward only; purging them from git history (LFS / filter-repo) is a separate follow-up. Co-authored-by: Cursor <cursoragent@cursor.com> * feat(home): gate the unwired PPTX import button behind a feature flag The PPTX import flow is still scaffolding — `useImportPptx` has no `onImported` consumer, so clicking it only logs the parsed slides. Hide both PPTX import entry points (and the hidden file input) behind NEXT_PUBLIC_ENABLE_PPTX_IMPORT (default off) so the UI doesn't expose a no-op. The classroom import button is unaffected. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(import): harden the runtime URL-loaded PPTX parser The PPTX parser is loaded at runtime from /vendor/maic-import/index.js — a gitignored artifact synced into public/vendor during postinstall. If a deploy skips that step the URL 404s and import() fails with an opaque SyntaxError (404 HTML parsed as JS). Add guards on both ends plus docs. - Build-time assertion: scripts/assert-vendor-maic-import.mjs verifies the bundle exists and is non-empty; wired into `build` so a misconfigured deploy fails early with an actionable message instead of shipping a broken runtime. - Runtime guard: use-import-pptx.ts HEAD-probes the URL before import() and, on a non-ok response, throws a clear error surfaced to the user via the new import.error.parserUnavailable string (added to all 6 locales). - Docs: document the postinstall deploy dependency and the pull-without-install type/runtime drift in @maic/importer's README. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: unify the @maic/* license policy to AGPL-3.0 Pick one license for the SDK family and apply it uniformly, matching the OpenMAIC root, per PR #668 review. - @maic/dsl and @maic/importer: relicense MIT -> AGPL-3.0 (package.json + full AGPL-3.0 LICENSE text). - @maic/renderer: already AGPL-3.0; add the LICENSE file its package.json `files` already referenced. @maic/importer is derived from pptxtojson (MIT); MIT permits relicensing a derivative under AGPL, and the upstream MIT attribution is retained in the package README/index.html, so this is compliant. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: rename packages/maic-import dir to maic-importer Align the importer's directory with its @maic/importer package name and the maic-* sibling dirs (maic-dsl, maic-renderer). Package name is unchanged, so imports/transpilePackages/node_modules resolution are unaffected. - git mv packages/maic-import -> packages/maic-importer (history preserved). - Rename the vendor sync/assert scripts and the runtime vendor path to match: scripts/{sync,assert-vendor}-maic-importer.mjs, public/vendor/maic-importer, URL /vendor/maic-importer/index.js. - Update all path references: root postinstall/build/sync scripts, .gitignore, use-import-pptx.ts, and doc links in the dsl/renderer/importer READMEs. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: nest the @maic packages under packages/@maic/ Mirror the @maic/* npm scope in the directory layout: move the three family packages into packages/@maic/{dsl,importer,renderer}. Package names are unchanged, so imports / transpilePackages / node_modules resolution are unaffected. - git mv packages/maic-{dsl,importer,renderer} -> packages/@maic/* (history preserved). - pnpm-workspace.yaml: add packages/@maic/* glob. - Recompute the root postinstall cd chain for the nested layout. - Update dir-path references: sync script srcDir, .gitignore comment, the dsl source comment, and the renderer/importer README/SKILL cross-links. Unchanged: the @maic/* package names, the runtime vendor path (public/vendor/maic-importer) and its sync/assert scripts. Co-authored-by: Cursor <cursoragent@cursor.com> * chore(renderer): clear font licenses, drop non-redistributable faces, remove importer font remapping Address the PR #668 blocking font-license-clearance review. Font licensing (renderer): - Reduce the self-hosted whitelist to 6 clearly-redistributable faces: SourceHanSans/SourceHanSerif/LXGWWenKai/ZhuQueFangSong (SIL OFL 1.1), ZcoolHappy (ZCOOL free-use), WenDingPLKaiTi = AR PL KaitiM GB (Arphic PL 1999). - Drop AlibabaPuHuiTi: free to *use* commercially but its license grants no explicit redistribution/re-host right, unlike OFL — dropped to keep public CDN serving unambiguous. - Add FONTS.md (per-face attribution/clearance record, separate from the package's AGPL LICENSE) and bundle the verbatim license texts under font-licenses/ (OFL.txt, ZcoolHappy-LICENSE.txt, ARPHIC-PL.txt); ship both via package.json `files`. Regenerate fonts.css from the trimmed config. Importer font remapping removed: - The importer no longer rewrites font-family names (alias -> category -> primary). It passes each slide's original font-family through unchanged, so it can never target a face the renderer doesn't ship. Delete configs/font.ts, the resolveFont/replaceFontFamilyInHtml helpers, and the now-unused FontReplacementBucket / ImportContext.replacedFonts plumbing. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(renderer): document the CDN font runtime dependency Add a "Fonts" section to the renderer README per PR #668: the optional `@maic/renderer/fonts.css` loads woff2 from an external host (https://file.maic.chat), which must be reachable + CORS-enabled or the browser silently falls back to system fonts. Note that the import is optional and that the origin is configurable via fonts.config.mjs + `pnpm run genfonts`. Co-authored-by: Cursor <cursoragent@cursor.com> * docs(renderer): verify WenDingPLKaiTi == AR PL KaitiM GB from the font name table Record the embedded-name-table evidence (Family/Copyright/Trademark/Designer = Arphic, nameID 13 = the full Arphic Public License) so the WenDingPLKaiTi ⇄ AR PL KaitiM GB correspondence is provable, and correct the copyright year to 1994–1999 to match the font metadata. Co-authored-by: Cursor <cursoragent@cursor.com> * chore: fix `pnpm check` (prettier) after merging main main added a `prettier . --check` CI step that flagged 180 files. Resolve it consistently with the existing convention (vendored/workspace packages are excluded from root Prettier): - .prettierignore: exclude `packages/@maic/` (own rollup/tsc/eslint toolchains; dist is generated, importer/src1 is a vendored oracle), matching how pptxgenjs / mathml2omml / docs are already handled. - Format the three root-level files we added/edited that root Prettier does cover: lib/import/use-import-pptx.ts and the two scripts/*-maic-importer.mjs. `pnpm check` now passes. Co-authored-by: Cursor <cursoragent@cursor.com> * style: align @maic/{dsl,renderer,importer} source to root Prettier Per review preference, the @maic packages are our own code and should follow the repo style rather than be ignored wholesale. Narrow .prettierignore to only the generated build output (packages/@maic/*/dist/) and the vendored legacy reference (packages/@maic/importer/src1/), then `prettier --write` the package sources. Formatting-only; all three packages still build. `pnpm check` passes. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(lint): scope ESLint to @maic source and clear all errors - eslint.config.mjs: replace blanket packages/** ignore with precise rules so @maic/{dsl,importer,renderer} source is linted, while skipping third-party packages, dist output, importer/src1 and public/vendor (the generated bundle was producing thousands of false errors in CI). - importer: replace `any` with concrete narrowings/types, fix prefer-const. - renderer: drop manual useMemo that React Compiler could not preserve. - remove leftover debug console.log + stale eslint-disable in use-import-pptx. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(i18n): add missing PPTX import keys to pt-BR pt-BR.json was missing import.{pptx,parsingPptx,pptxSuccess} and import.error.{invalidPptx,parserUnavailable}, failing the i18n key alignment check against en-US.json. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-06-09 03:25:05 -04:00
wyuc	2165e55bac	feat: add MiniMax web search provider (#634)	2026-06-02 11:47:13 +08:00
3 people	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
3 people	c0b7ea23a1	fix(pptxgenjs): use ESM import for typescript in rollup config (#616) ... rollup.config.mjs is ESM but handed the compiler to rollup-plugin-typescript2 via require("typescript"). When rollup loads the config as native ESM (e.g. workspace postinstall, without --bundleConfigAsCjs) this throws "require is not defined in ES module scope". Switch to a top-level `import ts from "typescript"` and add an explicit .ts/.tsx include. Supersedes #397 — keeps only the rollup fix and drops that PR's unrelated .env.example deletion and full lockfile rewrite. Co-authored-by: shunan-lu <49121953@qq.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>	2026-05-29 15:35:58 +08:00
wyucand杨慎	e613b7578f	[codex] add per-model thinking config (#494) ... * add per-model thinking config * Refine thinking model controls --------- Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>	2026-04-26 19:41:10 +08:00
tsinglua	1b5d2114c1	chore: fix some minor issues in the comments (#71) ... Signed-off-by: tsinglua <tsinglua@outlook.com>	2026-03-18 16:28:20 +08:00