@doenet/doenetml-iframe 0.7.20 → 0.7.21

package/README.md

@@ -69,6 +69,306 @@ 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: 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 — once per page — points this out). Hosts that consume
+reports through the `reportScoreAndStateCallback` prop are fully supported:
+the wrapper captures the flushed report for its park snapshot before
+forwarding it to the callback.
+
+Parking also requires a standalone bundle new enough to acknowledge the
+flush (v0.7.21+). A viewer pinned to an older `doenetmlVersion` mounts
+lazily and obeys the boot cap, but is never parked. A host-specified
+`standaloneUrl` is assumed modern (hosts shipping a custom URL control both
+sides — note a `-dev.N` prerelease *version string* compares as its base
+release, so dev-channel hosts should pin `standaloneUrl` rather than
+`doenetmlVersion`).
+
+#### `keepLive`: prefetching hosts
+
+A windowed viewer inside a hidden (`display:none`) or far-off-screen
+container never intersects the viewport, so it would stay parked forever.
+A host that knows the viewer is about to be shown — e.g. a paginator
+prefetching the pages adjacent to the current one — sets the dynamic
+`keepLive` prop to treat it as visible: it boots eagerly (still subject to
+`maxConcurrentBoots`, visible-first) and is never parked while the hint is
+set. Clear the hint and the viewer becomes an ordinary windowed citizen
+again (parked when off-screen and over budget).
+
+```tsx
+<DoenetViewer
+    doenetML={doenetML}
+    flags={{ allowSaveState: true }}
+    mountPolicy={{ mode: "windowed", maxLiveViewers: 3 }}
+    keepLive={Math.abs(itemIndex - currentIndex) <= 1}
+/>
+```
+
+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

@@ -1,13 +1,28 @@
+import { CreativeCommonsVersion } from '../packages/utils/dist';
+import { creativeCommonsVersions } from '../packages/utils/dist';
 import { default as default_2 } from 'react';
+import { defaultCreativeCommonsVersion } from '../packages/utils/dist';
 import { DiagnosticRecord } from '../packages/utils/dist';
 import { DiagnosticsTabId } from '../packages/doenetml/dist';
 import { DoenetEditor as DoenetEditor_2 } from '../packages/doenetml/dist';
 import { DoenetEditorHandle } from '../packages/doenetml/dist';
 import { DoenetViewer as DoenetViewer_2 } from '../packages/doenetml/dist';
 import { ErrorRecord } from '../packages/utils/dist';
+import { getMediaLicenseDisplay } from '../packages/utils/dist';
+import { getMediaLicenseInfo } from '../packages/utils/dist';
 import { mathjaxConfig } from '../packages/utils/dist';
+import { MediaLicenseDisplay } from '../packages/utils/dist';
+import { MediaLicenseInfo } from '../packages/utils/dist';
+import { MediaLicenseKind } from '../packages/utils/dist';
+import { mediaLicenses } from '../packages/utils/dist';
 import { WarningRecord } from '../packages/utils/dist';
 
+export { CreativeCommonsVersion }
+
+export { creativeCommonsVersions }
+
+export { defaultCreativeCommonsVersion }
+
 export { DiagnosticRecord }
 
 export { DiagnosticsTabId }
@@ -55,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, ...doenetViewerProps }: DoenetViewerIframeProps): default_2.JSX.Element | null;
+export declare function DoenetViewer({ doenetML, standaloneUrl: specifiedStandaloneUrl, cssUrl: specifiedCssUrl, doenetmlVersion: specifiedDoenetmlVersion, autodetectVersion, useSharedCoreWorker, mountPolicy, keepLive, ...doenetViewerProps }: DoenetViewerIframeProps): default_2.JSX.Element | null;
 
 export declare type DoenetViewerIframeProps = DoenetViewerProps & {
     doenetML: string;
@@ -85,14 +111,145 @@ export declare type DoenetViewerIframeProps = DoenetViewerProps & {
      * overwriting any doenetmlVersion or urls provided
      */
     autodetectVersion?: boolean;
+    /**
+     * Opt-in (#1466): multiplex this viewer's core onto a shared core worker
+     * owned by this (parent) page, instead of the iframe booting its own
+     * ~100 MB dedicated worker. Viewers on the same page with the same
+     * standalone version share workers (up to a pool cap per worker), which
+     * is the dominant memory saving on pages embedding many documents.
+     * Trade-off: a worker-level hang or crash affects every document on that
+     * worker (per-core teardown stays individual; suspect workers are
+     * 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), and only when
+     * the selected bundle is new enough to acknowledge the flush (v0.7.21+,
+     * or a host-specified `standaloneUrl`); 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;
+    /**
+     * Windowed-mounting hint: treat this viewer as visible regardless of
+     * viewport intersection — boot it eagerly (still subject to the
+     * page-wide `maxConcurrentBoots` slot queue) and never park it while
+     * set. For hosts that know an off-screen or `display:none` viewer is
+     * about to be shown, e.g. a paginator prefetching the pages adjacent to
+     * the current one. Dynamic, unlike `mountPolicy`; no effect without a
+     * windowed `mountPolicy`. The hint counts as visibility for boot
+     * ordering and the least-recently-visible eviction order, so keep it on
+     * a few viewers at a time (a page-wide `keepLive` would defeat the
+     * budget).
+     */
+    keepLive?: boolean;
 };
 
 declare type DoenetViewerProps = Omit<React.ComponentProps<typeof DoenetViewer_2>, "doenetML" | "externalVirtualKeyboardProvided">;
 
 export { ErrorRecord }
 
+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 }
+
+export { MediaLicenseInfo }
+
+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 }