openmaic-custom/lib/store/interactive-iframe-pool.ts
wyuc cdc04b7670
fix(interactive): keep-alive iframe pool — interactive scenes no longer reload on remount (#619) (#629)
* fix(interactive): keep-alive iframe pool so interactive scenes don't reload on remount (#619)

Interactive scene iframes reloaded on every remount — Pro mode toggle,
scene switch and back, any PlaybackChromeRoot remount — because the
<iframe srcDoc> was rendered inline in the scene subtree and React's
unmount (or a DOM re-parent) makes the browser drop and re-run the doc.

Persist the iframes in a stable host at the Stage root, outside the
mode-swap/scene subtree, keyed by sceneId:

- lib/store/interactive-iframe-pool: per-scene entries (srcDoc/src, content
  hash, tracked rect, visibility), LRU-bounded (CAP=3). Re-mounting with an
  unchanged hash keeps the existing content reference, so the iframe is
  never re-set; only a content-hash change rebuilds it.
- InteractiveIframeHost: mounted once in Stage, portals one persisted
  <iframe> per entry to document.body, positioned over each scene's rect.
  Hidden (visibility, never display:none) in edit mode and whenever the
  placeholder is gone. Owns the widget-iframe postMessage registration.
- InteractiveRenderer: now a placeholder that registers content, marks the
  scene active/visible, reports its rect via a rAF loop, and hides (not
  evicts) on unmount.

Mode toggle, back-and-forth scene switching, and re-renders now hit the
cache with zero reload and zero flash. widget-iframe messaging API is
unchanged; no change to the playback engine / SSE / edit-lock.

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

* test(e2e): interactive iframe keep-alive across Pro toggle + scene switch (#619)

Seeds an interactive scene whose widget holds click-counter state, then drives
the two remount triggers (Pro mode toggle, scene switch and back). A
MutationObserver scoped to the keep-alive iframe's title asserts the element is
never removed or recreated across either trigger, and the in-iframe counter
state is preserved — i.e. zero reload.

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

* fix(interactive): address review — widget callback timing, fullscreen, content compare, rect gate (#619)

Code-review round-1 fixes for the keep-alive iframe pool:

- PlaybackChromeRoot: resolve the widget postMessage callback lazily at send
  time instead of capturing it once at engine construction. The iframe (and its
  registration) now lives in the keep-alive host, which registers a commit after
  the engine is built — so eager capture got null on a scene's first visit and
  silently dropped every widget action.
- InteractiveIframeHost: portal target follows document.fullscreenElement so the
  iframe stays inside the presentation-fullscreen subtree (requestFullscreen runs
  on the stage, not body) instead of vanishing. Known tradeoff: entering/exiting
  fullscreen re-parents the iframe and reloads it once — accepted over an
  invisible widget during presentation.
- InteractiveIframeHost: reset the pool when the host unmounts (classroom switch)
  so a new classroom doesn't retain the previous one's resident iframes.
- InteractiveIframeHost: only show the iframe once its rect has a real measured
  size (width>0 && height>0), avoiding a 0x0 flash at the viewport origin before
  first layout.
- pool: drop the djb2 hash; compare srcDoc/src by value (string === is value
  equality, so an equal-but-new remount string still hits the keep-alive path).
  Removes the hash-collision-skips-rebuild hole and simplifies the store.

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

* fix(interactive): owner-token visibility so stale cross-fade cleanup can't blank the iframe (#619)

cosarah reproduced: after toggling Edit mode on an interactive scene and
returning to playback, the scene flashed its preserved state then went
permanently blank. Root cause is a visibility race, not a reload — the document
stayed alive. Visibility was keyed only by sceneId, so during Stage's
AnimatePresence mode cross-fade the outgoing PlaybackChromeRoot's placeholder
cleanup (hide) ran after the incoming placeholder had already shown the same
scene, hiding the live iframe.

Give each placeholder mount a visibility-ownership token (useId). The pool
records the owner on claim(); release() only clears visibility when the caller
still owns it, so a stale cleanup no-ops instead of blanking a newer instance.
The host now shows iff entry.owner !== null.

- store: replace visible boolean + show/hide with owner + claim/release.
- interactive-renderer: owner = useId(); claim on mount, release on unmount.
- e2e: after returning from Pro mode, wait out the cross-fade and re-assert the
  iframe stays visible with its state (guards the blank-on-return regression).

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-01 23:42:24 +08:00

173 lines
6.5 KiB
TypeScript

/**
* Keep-alive pool for interactive scene iframes (#619).
*
* Interactive scenes render their content in an `<iframe>`. When that element
* unmounts or is re-parented (Pro mode toggle, scene switch and back, any
* PlaybackChromeRoot remount) the browser drops the document and re-parses /
* re-runs from scratch, losing in-iframe state. To avoid that, the actual
* iframe elements live in a single stable host (`InteractiveIframeHost`)
* mounted at the `Stage` root, outside the reconciled scene subtree. This store
* is the coordination layer between the in-tree placeholder (`InteractiveRenderer`)
* and that host: it tracks, per scene, the content to render, the live on-screen
* rect to position the iframe over, and whether it should currently be visible.
*
* Entries are keyed by sceneId and persist across scene/mode changes — a scene's
* iframe is only rebuilt when its content actually changes. A small LRU cap
* bounds how many documents stay resident in memory.
*/
import { create } from 'zustand';
export const IFRAME_POOL_CAP = 3;
export interface IframeRect {
readonly left: number;
readonly top: number;
readonly width: number;
readonly height: number;
}
export interface IframePoolEntry {
/** Patched HTML for `srcDoc`, when the scene carries inline HTML. */
readonly srcDoc?: string;
/** URL for `src`, when the scene points at an external page. */
readonly src?: string;
/** Live screen rect the host positions the iframe over, or null until measured. */
readonly rect: IframeRect | null;
/**
* Id of the placeholder instance that currently owns visibility, or null when
* no placeholder is mounted. The iframe shows iff this is non-null. Ownership
* (rather than a bare boolean) is what makes `release` race-safe: during the
* Stage mode cross-fade an outgoing placeholder's unmount cleanup can run
* *after* a newer placeholder for the same scene has already mounted and
* claimed it — keying the release on the owner id lets the stale cleanup
* no-op instead of hiding the live iframe.
*/
readonly owner: string | null;
/** Monotonic recency marker for LRU eviction. */
readonly tick: number;
}
interface MountInput {
readonly srcDoc?: string;
readonly src?: string;
}
interface InteractiveIframePoolState {
entries: Record<string, IframePoolEntry>;
activeSceneId: string | null;
/** Monotonic counter; each mount/touch takes the next value. */
tick: number;
mount: (sceneId: string, input: MountInput) => void;
setRect: (sceneId: string, rect: IframeRect) => void;
/** A placeholder claims visibility for its scene, recording its owner id. */
claim: (sceneId: string, owner: string) => void;
/** Release visibility, but only if `owner` still owns it (stale = no-op). */
release: (sceneId: string, owner: string) => void;
setActive: (sceneId: string) => void;
evict: (sceneId: string) => void;
/** Drop everything (e.g. when the host unmounts on classroom switch). */
reset: () => void;
}
/**
* Drop the least-recently-touched entries until at most CAP remain. The active
* scene is never evicted (its iframe is on screen). Returns a new entries map.
*/
function evictLru(
entries: Record<string, IframePoolEntry>,
activeSceneId: string | null,
): Record<string, IframePoolEntry> {
const ids = Object.keys(entries);
if (ids.length <= IFRAME_POOL_CAP) return entries;
const evictable = ids
.filter((id) => id !== activeSceneId)
.sort((a, b) => entries[a].tick - entries[b].tick);
const next = { ...entries };
let overflow = ids.length - IFRAME_POOL_CAP;
for (const id of evictable) {
if (overflow <= 0) break;
delete next[id];
overflow--;
}
return next;
}
export const useInteractiveIframePool = create<InteractiveIframePoolState>((set) => ({
entries: {},
activeSceneId: null,
tick: 0,
mount: (sceneId, input) =>
set((state) => {
const tick = state.tick + 1;
const existing = state.entries[sceneId];
// Same content already loaded: just refresh recency. Crucially we keep the
// existing srcDoc/src reference so the host never re-sets it (which would
// reload the iframe). String `===` is by value, so a remount that produces
// an equal-but-new srcDoc string still hits this keep-alive fast path.
if (existing && existing.srcDoc === input.srcDoc && existing.src === input.src) {
const entries = { ...state.entries, [sceneId]: { ...existing, tick } };
return { entries, tick };
}
// New scene, or content changed: (re)build the entry. A content change here
// is the one intended reload path.
const entry: IframePoolEntry = {
srcDoc: input.srcDoc,
src: input.src,
rect: existing?.rect ?? null,
owner: existing?.owner ?? null,
tick,
};
const entries = evictLru({ ...state.entries, [sceneId]: entry }, state.activeSceneId);
return { entries, tick };
}),
setRect: (sceneId, rect) =>
set((state) => {
const existing = state.entries[sceneId];
if (!existing) return {};
const r = existing.rect;
if (
r &&
r.left === rect.left &&
r.top === rect.top &&
r.width === rect.width &&
r.height === rect.height
) {
return {};
}
return { entries: { ...state.entries, [sceneId]: { ...existing, rect } } };
}),
claim: (sceneId, owner) =>
set((state) => {
const existing = state.entries[sceneId];
if (!existing || existing.owner === owner) return {};
return { entries: { ...state.entries, [sceneId]: { ...existing, owner } } };
}),
release: (sceneId, owner) =>
set((state) => {
const existing = state.entries[sceneId];
// Only the current owner may release. A stale placeholder (whose unmount
// cleanup runs after a newer one already re-claimed during the mode
// cross-fade) finds owner !== its id and no-ops, so the live iframe stays.
if (!existing || existing.owner !== owner) return {};
return { entries: { ...state.entries, [sceneId]: { ...existing, owner: null } } };
}),
setActive: (sceneId) => set({ activeSceneId: sceneId }),
evict: (sceneId) =>
set((state) => {
if (!state.entries[sceneId]) return {};
const entries = { ...state.entries };
delete entries[sceneId];
const activeSceneId = state.activeSceneId === sceneId ? null : state.activeSceneId;
return { entries, activeSceneId };
}),
reset: () => set({ entries: {}, activeSceneId: null, tick: 0 }),
}));