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

package/README.md

@@ -69,6 +69,190 @@ 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
+
+### 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

@@ -75,7 +75,7 @@ declare type DoenetEditorProps = Omit<React.ComponentProps<typeof DoenetEditor_2
  * DoenetML component. Instead you must use the message passing interface of `DoenetViewer` to communicate
  * with the underlying DoenetML component.
  */
-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, ...doenetViewerProps }: DoenetViewerIframeProps): default_2.JSX.Element | null;
 
 export declare type DoenetViewerIframeProps = DoenetViewerProps & {
     doenetML: string;
@@ -100,6 +100,17 @@ 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;
 };
 
 declare type DoenetViewerProps = Omit<React.ComponentProps<typeof DoenetViewer_2>, "doenetML" | "externalVirtualKeyboardProvided">;

package/index.js

@@ -25618,7 +25618,7 @@ function requireCssesc$1() {
   return cssesc_1$1;
 }
 requireCssesc$1();
-const viewerIframeJsSource = '(function() {\n  "use strict";\n  async function waitForStandaloneBundle(timeoutMs) {\n    if (typeof window.renderDoenetViewerToContainer === "function") {\n      return true;\n    }\n    const deadline = Date.now() + timeoutMs;\n    while (Date.now() < deadline) {\n      await new Promise((resolve) => setTimeout(resolve, 50));\n      if (typeof window.renderDoenetViewerToContainer === "function") {\n        return true;\n      }\n    }\n    return false;\n  }\n  ComlinkViewer.expose(\n    { renderViewerWithFunctionProps },\n    ComlinkViewer.windowEndpoint(globalThis.parent)\n  );\n  function renderViewerWithFunctionProps(...args) {\n    const augmentedDoenetViewerProps = { ...doenetViewerProps };\n    augmentedDoenetViewerProps.externalVirtualKeyboardProvided = true;\n    for (const propName of doenetViewerPropsSpecified) {\n      if (!(propName in doenetViewerProps)) {\n        const idx = args.indexOf(propName);\n        if (idx !== -1) {\n          augmentedDoenetViewerProps[propName] = args[idx + 1];\n        }\n      }\n    }\n    if (!doenetViewerPropsSpecified.includes("requestScrollTo")) {\n      augmentedDoenetViewerProps.requestScrollTo = (offset) => {\n        messageParentFromViewer({ type: "scrollTo", offset });\n      };\n    }\n    window.renderDoenetViewerToContainer(\n      document.getElementById("root"),\n      void 0,\n      augmentedDoenetViewerProps\n    );\n  }\n  (async () => {\n    if (await waitForStandaloneBundle(6e4)) {\n      messageParentFromViewer({ iframeReady: true });\n    } else {\n      messageParentFromViewer({\n        error: "Invalid DoenetML version or DoenetML package not found"\n      });\n    }\n  })().catch((err) => {\n    console.error(\n      "iframe DoenetViewer: unexpected failure while signalling iframeReady",\n      err\n    );\n    try {\n      messageParentFromViewer({\n        error: "iframe viewer failed to initialize"\n      });\n    } catch {\n    }\n  });\n  function messageParentFromViewer(data) {\n    window.parent.postMessage(\n      {\n        origin: viewerId,\n        data\n      },\n      window.parent.origin\n    );\n  }\n})();\n';
+const viewerIframeJsSource = '(function() {\n  "use strict";\n  async function waitForStandaloneBundle(timeoutMs) {\n    if (typeof window.renderDoenetViewerToContainer === "function") {\n      return true;\n    }\n    const deadline = Date.now() + timeoutMs;\n    while (Date.now() < deadline) {\n      await new Promise((resolve) => setTimeout(resolve, 50));\n      if (typeof window.renderDoenetViewerToContainer === "function") {\n        return true;\n      }\n    }\n    return false;\n  }\n  ComlinkViewer.expose(\n    { renderViewerWithFunctionProps },\n    ComlinkViewer.windowEndpoint(globalThis.parent)\n  );\n  function renderViewerWithFunctionProps(...args) {\n    const augmentedDoenetViewerProps = { ...doenetViewerProps };\n    augmentedDoenetViewerProps.externalVirtualKeyboardProvided = true;\n    for (const propName of doenetViewerPropsSpecified) {\n      if (!(propName in doenetViewerProps)) {\n        const idx = args.indexOf(propName);\n        if (idx !== -1) {\n          augmentedDoenetViewerProps[propName] = args[idx + 1];\n        }\n      }\n    }\n    if (!doenetViewerPropsSpecified.includes("requestScrollTo")) {\n      augmentedDoenetViewerProps.requestScrollTo = (offset) => {\n        messageParentFromViewer({ type: "scrollTo", offset });\n      };\n    }\n    window.renderDoenetViewerToContainer(\n      document.getElementById("root"),\n      void 0,\n      augmentedDoenetViewerProps\n    );\n  }\n  function installSharedCorePortProvider() {\n    let coreCounter = 0;\n    window.doenetGlobalConfig.createExternalCoreWorkerPort = () => {\n      const coreId = `${viewerId}-core-${++coreCounter}`;\n      const channel = new MessageChannel();\n      window.parent.postMessage(\n        { origin: viewerId, data: { type: "createSharedCore", coreId } },\n        window.parent.origin,\n        [channel.port2]\n      );\n      return {\n        port: channel.port1,\n        destroy: (suspectWedge) => {\n          messageParentFromViewer({\n            type: "destroySharedCore",\n            coreId,\n            suspectWedge: Boolean(suspectWedge)\n          });\n        }\n      };\n    };\n  }\n  (async () => {\n    if (await waitForStandaloneBundle(6e4)) {\n      if (typeof doenetSharedCoreWorker !== "undefined" && doenetSharedCoreWorker) {\n        installSharedCorePortProvider();\n      }\n      messageParentFromViewer({ iframeReady: true });\n    } else {\n      messageParentFromViewer({\n        error: "Invalid DoenetML version or DoenetML package not found"\n      });\n    }\n  })().catch((err) => {\n    console.error(\n      "iframe DoenetViewer: unexpected failure while signalling iframeReady",\n      err\n    );\n    try {\n      messageParentFromViewer({\n        error: "iframe viewer failed to initialize"\n      });\n    } catch {\n    }\n  });\n  function messageParentFromViewer(data) {\n    window.parent.postMessage(\n      {\n        origin: viewerId,\n        data\n      },\n      window.parent.origin\n    );\n  }\n})();\n';
 const editorIframeJsSource = `(function() {
   "use strict";
   let editorControlHandle = null;
@@ -25856,7 +25856,7 @@ function createIframeHead(standaloneUrl, cssUrl) {
 function createIframeBodyOpenTag(darkMode) {
   return `<body style="margin:0" ${BODY_BACKGROUND_ATTRIBUTE}="${bodyBackgroundMode(darkMode)}">`;
 }
-function createHtmlForDoenetViewer(id2, doenetML, doenetViewerProps, standaloneUrl, cssUrl) {
+function createHtmlForDoenetViewer(id2, doenetML, doenetViewerProps, standaloneUrl, cssUrl, useSharedCoreWorker = false) {
   const doenetViewerPropsSpecified = Object.keys(doenetViewerProps);
   return `
     <html style="overflow:hidden">
@@ -25866,6 +25866,7 @@ function createHtmlForDoenetViewer(id2, doenetML, doenetViewerProps, standaloneU
             const viewerId = "${id2}";
             const doenetViewerProps = ${JSON.stringify(doenetViewerProps)};
             const doenetViewerPropsSpecified = ${JSON.stringify(doenetViewerPropsSpecified)};
+            const doenetSharedCoreWorker = ${JSON.stringify(!!useSharedCoreWorker)};
             import * as ComlinkViewer from "https://unpkg.com/comlink/dist/esm/comlink.mjs";
 
             // This source code has been compiled by vite and should be directly included.
@@ -25907,6 +25908,124 @@ function createHtmlForDoenetEditor(id2, doenetML, width, doenetEditorProps, stan
     </html>
     `;
 }
+const MAX_CORES_PER_WORKER = 12;
+const hostsByWorkerUrl = /* @__PURE__ */ new Map();
+const coreRecords = /* @__PURE__ */ new Map();
+function resolveWorkerUrl(standaloneUrl) {
+  try {
+    return new URL("./doenetml-worker/index.js", standaloneUrl).href;
+  } catch {
+  }
+  try {
+    return new URL("/doenetml-worker/index.js", document.baseURI).href;
+  } catch {
+    return null;
+  }
+}
+function workerCreationUrl(workerUrl) {
+  try {
+    if (new URL(workerUrl).origin === window.location.origin) {
+      return workerUrl;
+    }
+  } catch {
+  }
+  const bootstrap = `importScripts(${JSON.stringify(workerUrl)});`;
+  return URL.createObjectURL(
+    new Blob([bootstrap], { type: "text/javascript" })
+  );
+}
+function quarantineHost(workerUrl, host) {
+  host.quarantined = true;
+  if (host.liveCores <= 0) {
+    try {
+      host.worker.terminate();
+    } catch {
+    }
+    const pool = hostsByWorkerUrl.get(workerUrl);
+    const index2 = pool?.indexOf(host) ?? -1;
+    if (pool && index2 !== -1) {
+      pool.splice(index2, 1);
+    }
+  }
+}
+function getHost(workerUrl) {
+  let pool = hostsByWorkerUrl.get(workerUrl);
+  if (!pool) {
+    pool = [];
+    hostsByWorkerUrl.set(workerUrl, pool);
+  }
+  let host = pool.find(
+    (h2) => !h2.quarantined && h2.liveCores < MAX_CORES_PER_WORKER
+  );
+  if (!host) {
+    const worker = new Worker(workerCreationUrl(workerUrl), {
+      type: "classic"
+    });
+    const newHost = {
+      worker,
+      remote: wrap$3(worker),
+      liveCores: 0,
+      quarantined: false
+    };
+    worker.addEventListener("error", () => {
+      quarantineHost(workerUrl, newHost);
+    });
+    pool.push(newHost);
+    host = newHost;
+  }
+  return host;
+}
+function handleCreateSharedCore({
+  viewerId,
+  coreId,
+  standaloneUrl,
+  port
+}) {
+  const workerUrl = resolveWorkerUrl(standaloneUrl);
+  if (workerUrl === null) {
+    console.warn(
+      "doenetml-iframe: could not resolve a shared core worker URL for",
+      standaloneUrl
+    );
+    return;
+  }
+  const host = getHost(workerUrl);
+  host.liveCores++;
+  const idPromise = host.remote.createCore(transfer(port, [port]));
+  idPromise.catch(() => {
+  });
+  coreRecords.set(coreId, {
+    viewerId,
+    host,
+    workerUrl,
+    idPromise,
+    destroyed: false
+  });
+}
+function handleDestroySharedCore({
+  coreId,
+  suspectWedge
+}) {
+  const record = coreRecords.get(coreId);
+  if (!record || record.destroyed) {
+    return;
+  }
+  record.destroyed = true;
+  coreRecords.delete(coreId);
+  record.host.liveCores--;
+  record.idPromise.then((id2) => record.host.remote.destroyCore(id2)).catch(() => {
+  });
+  if (suspectWedge || record.host.quarantined) {
+    quarantineHost(record.workerUrl, record.host);
+  }
+}
+function destroySharedCoresForViewer(viewerId) {
+  for (const [coreId, record] of [...coreRecords]) {
+    if (record.viewerId === viewerId) {
+      handleDestroySharedCore({ coreId, suspectWedge: false });
+    }
+  }
+}
 function findNodesWithPositionInfo(nodes) {
   if (typeof nodes !== "object" || nodes === null) {
     return [];
@@ -63053,7 +63172,7 @@ function ExternalVirtualKeyboard({
     }
   );
 }
-const version = "0.7.20-dev.321";
+const version = "0.7.20-dev.324";
 const latestDoenetmlVersion = version;
 function subscribeToPinnedTheme() {
   return () => {
@@ -63074,6 +63193,7 @@ function DoenetViewer({
   cssUrl: specifiedCssUrl,
   doenetmlVersion: specifiedDoenetmlVersion,
   autodetectVersion = true,
+  useSharedCoreWorker = false,
   ...doenetViewerProps
 }) {
   const [id2, _2] = React__default__default.useState(() => Math.random().toString(36).slice(2));
@@ -63106,12 +63226,22 @@ function DoenetViewer({
   } else {
     cssUrl = `https://cdn.jsdelivr.net/npm/@doenet/standalone@${selectedDoenetmlVersion}/style.css`;
   }
+  const standaloneUrlRef = React__default__default.useRef(standaloneUrl);
+  standaloneUrlRef.current = standaloneUrl;
+  React__default__default.useEffect(() => {
+    if (!useSharedCoreWorker) {
+      return;
+    }
+    return () => {
+      destroySharedCoresForViewer(id2);
+    };
+  }, []);
   React__default__default.useEffect(() => {
     const listener = (event) => {
       if (event.origin !== window.location.origin) {
         return;
       }
-      if (event.data.subject === "SPLICE.getState.response" || event.data.subject === "SPLICE.requestSolutionView.response" || event.data.subject == "SPLICE.submitAllAnswers") {
+      if (event.data.subject === "SPLICE.getState.response" || event.data.subject === "SPLICE.requestSolutionView.response" || event.data.subject == "SPLICE.submitAllAnswers" || event.data.subject === "SPLICE.flushState") {
         ref.current?.contentWindow?.postMessage(event.data);
         return;
       }
@@ -63127,6 +63257,22 @@ function DoenetViewer({
         return;
       }
       const data = event.data.data;
+      if (data.type === "createSharedCore" && event.ports[0]) {
+        handleCreateSharedCore({
+          viewerId: id2,
+          coreId: String(data.coreId),
+          standaloneUrl: standaloneUrlRef.current,
+          port: event.ports[0]
+        });
+        return;
+      }
+      if (data.type === "destroySharedCore") {
+        handleDestroySharedCore({
+          coreId: String(data.coreId),
+          suspectWedge: Boolean(data.suspectWedge)
+        });
+        return;
+      }
       if (ref.current && data.type === "scrollTo" && typeof data.offset === "number") {
         const iframeTop = ref.current.getBoundingClientRect().top + window.scrollY;
         const targetAbsoluteTop = iframeTop + data.offset;
@@ -63208,7 +63354,8 @@ function DoenetViewer({
         doenetML,
         doenetViewerProps,
         standaloneUrl,
-        cssUrl
+        cssUrl,
+        useSharedCoreWorker
       ),
       style: {
         width: "100%",