@doenet/doenetml-iframe 0.7.20-dev.324 → 0.7.20-dev.326

package/README.md

@@ -71,6 +71,83 @@ latest editor buffer:
 
 ## DoenetViewer
 
+### Prop changes and iframe reloads
+
+Changing props on a mounted `<DoenetViewer>` does **not** reload the iframe:
+the wrapper pushes changes into the already-loaded iframe as messages, and
+the inner viewer applies them with the same semantics as the in-process
+`<DoenetViewer>` from `@doenet/doenetml`. In particular:
+
+| Prop change                                                                | Effect                                                                                                      |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `render`, `darkMode`, `flags`, `answerResponseCounts`, callbacks, …         | applied live, no reload (flipping `render` false→true starts the document in the already-loaded realm)       |
+| `doenetML`, `activityId`, `docId`, `attemptNumber`, `requestedVariantIndex` | the document's core re-initializes **inside the same iframe realm** — the multi-MB bundle is not re-parsed   |
+| `initialState`, `forceDisable` and the other `force*` props, `userId`       | read at (re-)initialization only, exactly like the in-process viewer — change `docId`/`attemptNumber` or remount via `key=` to apply |
+| `standaloneUrl`, `cssUrl`, `doenetmlVersion` (or a version change detected in `doenetML`), `useSharedCoreWorker` | a different bundle/realm is required, so the iframe reloads                                                   |
+
+To force a full remount (fresh realm and worker), change the component's
+React `key`.
+
+Function props (callbacks) are forwarded across the iframe boundary via
+Comlink proxies and always follow the latest identity passed — parents may
+pass inline arrow functions freely; identity churn does not re-render the
+inner viewer.
+
+> **Note:** in-place updates require a standalone bundle ≥ 0.7.18. When an
+> older version is pinned (via `doenetmlVersion` or detected from the
+> document's `xmlns`), the wrapper falls back to its historical behavior of
+> reloading the iframe on any prop change.
+
+### Windowed mounting (`mountPolicy`)
+
+Pages that embed many viewers (assignment pages, textbook chapters) pay
+memory for every mounted iframe, whether or not the student can see it. The
+opt-in `mountPolicy` prop bounds this: at most `maxLiveViewers` viewers stay
+live page-wide, and off-screen viewers beyond the budget are **parked** —
+their state is flushed (via the `SPLICE.flushState` machinery) and their
+iframe is replaced by a placeholder of the same height, so the page layout
+doesn't shift. Scrolling a parked viewer back near the viewport restores it,
+seeded with the flushed state: typed work survives the round trip with no
+user interaction.
+
+```tsx
+<DoenetViewer
+    doenetML={doenetML}
+    flags={{ allowSaveState: true }}
+    mountPolicy={{ mode: "windowed", maxLiveViewers: 3 }}
+/>
+```
+
+- `maxLiveViewers` (default 3) — page-wide budget, shared by every windowed
+  viewer (the smallest value wins when viewers disagree). The budget is
+  soft: currently-visible viewers are never parked, even over budget.
+- `visibleMargin` (default `"1000px"`) — how far outside the viewport a
+  viewer still counts as visible (the `IntersectionObserver` rootMargin).
+- `parkDelayMs` (default 2000) — how long a viewer must stay off-screen
+  before it may be parked (debounce against scroll flicker).
+- `flushTimeoutMs` (default 5000) — how long to wait for the pre-park state
+  flush to be acknowledged before parking anyway.
+
+**Parking requires a persistence path** so no student work can be lost:
+either `flags.allowSaveState` (the wrapper snapshots the flushed
+`reportScoreAndState` and seeds `initialState` on restore) or
+`flags.allowLocalState` (IndexedDB restores on reboot). Windowed viewers
+with neither flag always stay live (a console warning points this out).
+
+Notes:
+
+- Eviction is least-recently-visible first.
+- While parked, a viewer emits no reports (its state was flushed at park
+  time). A host `SPLICE.flushState` broadcast is answered by the wrapper on
+  the parked viewer's behalf, so pre-navigation flush round-trips don't
+  hang.
+- When `requestedVariantIndex` is not specified, windowed viewers pin a
+  random variant once per mount so a restore cannot reroll the document.
+- Restoring pays a fresh iframe boot (bundle evaluation + core boot, ~1–2 s
+  warm). Pair with `useSharedCoreWorker` to make both live and restored
+  viewers cheaper.
+- `mountPolicy` is read at mount; changing it afterwards is not supported.
+
 ### Host message protocol (SPLICE)
 
 The viewer exchanges JSON messages with the host page via `postMessage`.

package/index.d.ts

@@ -70,12 +70,23 @@ declare type DoenetEditorProps = Omit<React.ComponentProps<typeof DoenetEditor_2
  * Render Doenet viewer constrained to an iframe. A URL pointing to a version of DoenetML
  * standalone must be provided (along with a URL to the corresponding CSS file).
  *
- * Parameters being passed to the underlying DoenetML component are passed via the `DoenetViewerProps` prop.
- * However, only serializable parameters may be passed. E.g., callbacks **cannot** be passed to the underlying
- * DoenetML component. Instead you must use the message passing interface of `DoenetViewer` to communicate
- * with the underlying DoenetML component.
+ * Parameters for the underlying `DoenetViewer` component are passed via props.
+ * Serializable prop changes after mount are pushed into the iframe as
+ * messages and applied in place with the same semantics as the in-process
+ * `<DoenetViewer>`: e.g. flipping `render` starts the document without a
+ * reload, and changing `doenetML` (or `activityId`/`docId`/`attemptNumber`/
+ * `requestedVariantIndex`) re-initializes the document's core inside the
+ * same iframe realm — the multi-MB standalone bundle is not re-parsed. Only
+ * a change of the bundle itself (`standaloneUrl`/`cssUrl`/`doenetmlVersion`,
+ * a version change detected in `doenetML`, or `useSharedCoreWorker`) reloads
+ * the iframe. To force a full remount instead, change the component's `key`.
+ *
+ * Function props are forwarded across the iframe boundary via Comlink
+ * proxies and follow the latest identity passed. (Bundles older than
+ * v0.7.18 cannot re-render in place; for those the wrapper falls back to
+ * reloading the iframe on any prop change, its historical behavior.)
  */
-export declare function DoenetViewer({ doenetML, standaloneUrl: specifiedStandaloneUrl, cssUrl: specifiedCssUrl, doenetmlVersion: specifiedDoenetmlVersion, autodetectVersion, useSharedCoreWorker, ...doenetViewerProps }: DoenetViewerIframeProps): default_2.JSX.Element | null;
+export declare function DoenetViewer({ doenetML, standaloneUrl: specifiedStandaloneUrl, cssUrl: specifiedCssUrl, doenetmlVersion: specifiedDoenetmlVersion, autodetectVersion, useSharedCoreWorker, mountPolicy, ...doenetViewerProps }: DoenetViewerIframeProps): default_2.JSX.Element | null;
 
 export declare type DoenetViewerIframeProps = DoenetViewerProps & {
     doenetML: string;
@@ -111,6 +122,20 @@ export declare type DoenetViewerIframeProps = DoenetViewerProps & {
      * quarantined so retries boot fresh ones). Default off.
      */
     useSharedCoreWorker?: boolean;
+    /**
+     * Opt-in windowed mounting (#1441, stream B): keep at most
+     * `maxLiveViewers` viewers live on the page. Off-screen viewers beyond
+     * the budget are *parked* — their state is flushed (`SPLICE.flushState`)
+     * and their iframe is replaced by a fixed-height placeholder — and
+     * restored when scrolled back near the viewport. Parking requires a
+     * persistence path: it only activates for viewers with
+     * `flags.allowSaveState` (the wrapper snapshots the flushed
+     * `reportScoreAndState` and seeds `initialState` on restore) or
+     * `flags.allowLocalState` (IndexedDB restores on reboot); otherwise the
+     * viewer always stays live. The policy is read at mount; changing it
+     * afterwards is not supported. Default off (no prop = today's behavior).
+     */
+    mountPolicy?: MountPolicy;
 };
 
 declare type DoenetViewerProps = Omit<React.ComponentProps<typeof DoenetViewer_2>, "doenetML" | "externalVirtualKeyboardProvided">;
@@ -121,6 +146,14 @@ export { getMediaLicenseDisplay }
 
 export { getMediaLicenseInfo }
 
+/** Snapshot for tests and diagnostics. */
+export declare function getViewerLifecycleStats(): {
+    registered: number;
+    live: number;
+    parking: number;
+    parked: number;
+};
+
 export { mathjaxConfig }
 
 export { MediaLicenseDisplay }
@@ -131,6 +164,58 @@ export { MediaLicenseKind }
 
 export { mediaLicenses }
 
+/**
+ * Page-wide lifecycle manager for windowed `<DoenetViewer>` mounting
+ * (#1441, stream B).
+ *
+ * Viewers that opt in via the `mountPolicy` prop register here. The manager
+ * enforces a page-wide budget of live viewers: when more than
+ * `maxLiveViewers` are live at once, the least-recently-visible off-screen
+ * viewers are asked to park (flush their state and replace their iframe with
+ * a placeholder), so idle memory tracks what the user can see rather than
+ * how many documents the page embeds.
+ *
+ * This module is pure policy: *when* to park. The mechanics of parking
+ * (flushing state, swapping the iframe for a placeholder, restoring) live in
+ * the `DoenetViewer` wrapper, which registers callbacks here. Module-level
+ * state is intentional — the budget is shared by every windowed viewer on
+ * the page (same pattern as `shared-core-pool.ts`).
+ *
+ * Rules:
+ * - A currently-visible viewer is never parked (the budget is soft: if more
+ *   than `maxLiveViewers` are visible at once, all of them stay live).
+ * - A viewer only becomes eligible to park after it has been off-screen for
+ *   its `parkDelayMs` (debounce against scroll flicker).
+ * - Viewers whose `canPark` returns false (no persistence path — parking
+ *   would lose student work) are never parked.
+ * - Eviction order is least-recently-visible first.
+ */
+export declare type MountPolicy = {
+    /** The only mode currently defined. */
+    mode: "windowed";
+    /**
+     * Page-wide budget of simultaneously live (iframe-mounted) viewers.
+     * When viewers on the same page specify different values, the smallest
+     * wins. Default 3.
+     */
+    maxLiveViewers?: number;
+    /**
+     * `rootMargin` for the visibility observer — how far outside the
+     * viewport a viewer still counts as "visible". Default "1000px".
+     */
+    visibleMargin?: string;
+    /**
+     * How long to wait for the viewer to acknowledge the pre-park state
+     * flush before parking anyway. Default 5000.
+     */
+    flushTimeoutMs?: number;
+    /**
+     * How long a viewer must be continuously off-screen before it may be
+     * parked. Default 2000.
+     */
+    parkDelayMs?: number;
+};
+
 export declare const version: string;
 
 export { WarningRecord }