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

package/README.md

@@ -71,6 +71,91 @@ 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: windowed viewers **start as
+placeholders and only create their iframe when they come near the viewport**
+(an off-screen viewer never boots at all), simultaneous boots are capped
+page-wide, and at most `maxLiveViewers` viewers stay live. 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.
+- `maxConcurrentBoots` (default 2) — page-wide cap on how many windowed
+  viewers may be booting their iframe realm at once (each boot parses the
+  multi-MB standalone bundle and starts a core worker). Additional viewers
+  wait for a slot, visible-first — this removes the initialization stampede
+  when a page with many activities loads.
+
+**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 still mount lazily but, once booted, 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,24 @@ 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. Windowed viewers start as
+     * fixed-height placeholders and only create their iframe when they come
+     * near the viewport AND a boot slot is free (`maxConcurrentBoots` caps
+     * simultaneous realm boots page-wide — an off-screen viewer never boots
+     * at all). Off-screen viewers beyond the budget are *parked* — their
+     * state is flushed (`SPLICE.flushState`) and their iframe is replaced
+     * by the placeholder again — 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 boots on visibility but then 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 +150,16 @@ export { getMediaLicenseDisplay }
 
 export { getMediaLicenseInfo }
 
+/** Snapshot for tests and diagnostics. */
+export declare function getViewerLifecycleStats(): {
+    registered: number;
+    live: number;
+    parking: number;
+    parked: number;
+    booting: number;
+    bootQueue: number;
+};
+
 export { mathjaxConfig }
 
 export { MediaLicenseDisplay }
@@ -131,6 +170,71 @@ 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.
+ *
+ * It also gates *when* a lazily-mounted viewer may boot its iframe realm: a
+ * page-wide boot-slot semaphore (`maxConcurrentBoots`) caps how many viewers
+ * evaluate the multi-MB standalone bundle at once, serving visible viewers
+ * first (see `requestBootSlot`).
+ *
+ * This module is pure policy: *when* to park and *when* to boot. The
+ * mechanics (flushing state, creating/swapping the iframe, 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;
+    /**
+     * Page-wide cap on how many windowed viewers may be *booting* their
+     * iframe realm at once (each boot parses the multi-MB standalone bundle
+     * and starts a core worker — the initialization stampede #1439
+     * targets). Additional viewers wait for a slot, visible-first. As with
+     * `maxLiveViewers`, the smallest value across viewers wins. Default 2.
+     */
+    maxConcurrentBoots?: number;
+};
+
 export declare const version: string;
 
 export { WarningRecord }