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

package/README.md

@@ -69,6 +69,267 @@ latest editor buffer:
 > surface a completion signal or error to the caller — failures from the
 > underlying ComLink RPC are logged to the console rather than thrown.
 
+## 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`.
+Viewer → host messages arrive on **your window** (the iframe posts to
+`window.parent`, which is your page). Host → viewer requests are posted on
+**your own window** too — the wrapper forwards these subjects into the
+iframe: `SPLICE.getState.response`, `SPLICE.requestSolutionView.response`,
+`SPLICE.submitAllAnswers`, and `SPLICE.flushState`. On a page with several
+viewers, every viewer receives a forwarded request; correlate responses by
+`activity_id`/`doc_id`/`message_id`.
+
+The messages are documented in the subsections below:
+
+| Subject                                                    | Direction     | Purpose                                        |
+| ---------------------------------------------------------- | ------------- | ---------------------------------------------- |
+| `SPLICE.reportScoreAndState`                                | viewer → host | periodic score/state saves                     |
+| `SPLICE.getState` / `.response`                             | viewer ⇄ host | load saved state at boot                       |
+| `SPLICE.flushState` / `.response`                           | host ⇄ viewer | on-demand state flush (lossless unmount)       |
+| `SPLICE.submitAllAnswers` / `.response`                     | host ⇄ viewer | submit every answer in the document            |
+| `SPLICE.requestSolutionView` / `.response`                  | viewer ⇄ host | permission gate for viewing solutions          |
+| `SPLICE.sendEvent`                                          | viewer → host | analytics/event stream                         |
+
+### Saving and restoring state (lossless unmount)
+
+The viewer reports the student's serialized document state to the host as
+they work: it posts `SPLICE.reportScoreAndState` messages to the host
+window (the wrapper's iframe posts to `window.parent`, which is your page):
+
+```js
+window.addEventListener("message", (e) => {
+    if (e.data?.subject === "SPLICE.reportScoreAndState") {
+        // e.data.state — serialized document state (opaque; store as-is)
+        // e.data.score, e.data.activity_id, e.data.doc_id
+    }
+});
+```
+
+To restore, remount the viewer with the saved state:
+
+```tsx
+<DoenetViewer
+    doenetML={doenetML}
+    flags={{ allowLoadState: true }}
+    initialState={savedState}
+/>
+```
+
+**The gap — and `SPLICE.flushState`.** Reports are throttled (one per 60
+seconds per viewer), so at any moment the student may have committed work
+that no report has delivered yet. A host that unmounts a viewer based on
+save events alone silently loses that work. Before unmounting, request a
+flush — post on your own window; the wrapper forwards it into the iframe:
+
+```js
+window.postMessage(
+    { subject: "SPLICE.flushState", message_id: "my-id-123" },
+    "*",
+);
+```
+
+The flush settles in-flight updates and pushes any pending state out through
+the **normal `SPLICE.reportScoreAndState` message** (which reaches your page
+as shown above) — so a host that already persists those reports saves the
+just-flushed state with no extra code. (No report is emitted when nothing is
+pending, or when state saving is disabled — there is then nothing to lose.)
+The viewer then replies with a stateless acknowledgement (again on your
+window):
+
+```js
+{
+    subject: "SPLICE.flushState.response",
+    message_id: "my-id-123",   // echoed from the request
+    activity_id, doc_id,       // to correlate on multi-viewer pages
+    success: true,
+    hadState: true,            // false ⇒ nothing beyond initialization
+}
+```
+
+The acknowledgement is the completion signal: once it arrives, every saved
+`reportScoreAndState` is current, so unmounting loses nothing — remounting
+later with `initialState: <the last saved state>` (and
+`flags: { allowLoadState: true }`) restores the document exactly, including
+work an earlier report never delivered. `hadState: false` means the viewer
+held no state beyond what it was initialized with (e.g. its core has not
+booted yet) — equally safe to unmount.
+
+> **Note:** Wrap the round-trip in a retry/timeout — the viewer's listener
+> registers on mount, so a request posted moments after mounting can land
+> before anyone is listening, and flushing is idempotent so re-posting is
+> safe. Every viewer on the page receives a broadcast request and responds
+> (correlate by `activity_id`/`doc_id`/`message_id`).
+
+### Loading saved state at boot (`SPLICE.getState`)
+
+With `flags: { allowLoadState: true }` and no `initialState` prop, the
+viewer asks the host for saved state when it boots:
+
+```js
+{
+    subject: "SPLICE.getState",
+    message_id,
+    cid,                 // content id of the DoenetML source
+    domain_id: "Doenet",
+    activity_id, doc_id, attempt_number, user_id,
+}
+```
+
+The viewer does not block on a reply — it boots fresh immediately and
+**reboots seeded with the state** if a response arrives. If you have saved
+state for this document (an object previously received from
+`reportScoreAndState`, whose `cid` matches the request),
+respond:
+
+```js
+{ subject: "SPLICE.getState.response", message_id, state }
+```
+
+If there is no saved state, no response is needed. To surface a load
+failure to the student instead, respond with
+`{ subject: "SPLICE.getState.response", error: { code, message } }`
+(and no `message_id`).
+
+Passing `initialState` yourself (or `initialState: null` for "start
+fresh") skips this request entirely.
+
+### Submitting all answers (`SPLICE.submitAllAnswers`)
+
+Post `{ subject: "SPLICE.submitAllAnswers" }` and the viewer submits every
+answer in the document, then responds with
+`{ subject: "SPLICE.submitAllAnswers.response", success }`.
+
+> **Note:** this pair carries no correlation id — on a page with several
+> viewers, every viewer submits and responds, and the responses cannot be
+> told apart. Use it with a single viewer per page (its original use case)
+> or treat it as fire-and-forget.
+
+### Solution-view permission (`SPLICE.requestSolutionView`)
+
+With `flags: { solutionDisplayMode: "buttonRequirePermission" }`, a student
+opening a solution triggers a permission request to the host:
+
+```js
+{
+    subject: "SPLICE.requestSolutionView",
+    message_id,
+    activity_id, doc_id, attempt_number, user_id,
+    component_idx,       // the solution component being opened
+}
+```
+
+Decide and respond — note the response echoes the id as **`messageId`**
+(camelCase), unlike the snake_case request field:
+
+```js
+{ subject: "SPLICE.requestSolutionView.response", messageId, allowView: true }
+```
+
+The solution is revealed only when `allowView` is `true`.
+
+### Event stream (`SPLICE.sendEvent`)
+
+With `flags: { allowSaveEvents: true }`, the viewer emits an analytics
+event for student interactions (answers submitted, solutions viewed,
+content experienced, …). Fire-and-forget; no response is expected:
+
+```js
+{
+    subject: "SPLICE.sendEvent",
+    message_id,
+    name,                // mirrors data.verb
+    data: {
+        activityId, cid, docId, attemptNumber, variantIndex,
+        verb,            // e.g. "answered", "experienced"
+        object,          // JSON string: the component acted on
+        result,          // JSON string: the outcome
+        context,         // JSON string: additional context
+        timestamp,       // "YYYY-MM-DD HH:MM:SS"
+        version,
+    },
+}
+```
+
 ## Development
 
 Source code in `src/iframe-viewer-index.ts` and `src/iframe-editor-index.ts`

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 }