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

package/README.md

@@ -102,13 +102,15 @@ inner viewer.
 
 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.
+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
@@ -127,12 +129,18 @@ user interaction.
   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 always stay live (a console warning points this out).
+with neither flag still mount lazily but, once booted, always stay live
+(a console warning points this out).
 
 Notes:
 

package/index.d.ts

@@ -124,16 +124,20 @@ export declare type DoenetViewerIframeProps = DoenetViewerProps & {
     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
+     * `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 always stays live. The policy is read at mount; changing it
-     * afterwards is not supported. Default off (no prop = today's behavior).
+     * 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;
 };
@@ -152,6 +156,8 @@ export declare function getViewerLifecycleStats(): {
     live: number;
     parking: number;
     parked: number;
+    booting: number;
+    bootQueue: number;
 };
 
 export { mathjaxConfig }
@@ -175,8 +181,13 @@ export { mediaLicenses }
  * 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
+ * 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`).
@@ -214,6 +225,14 @@ export declare type MountPolicy = {
      * 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;

package/index.js

@@ -25858,6 +25858,9 @@ function createIframeBodyOpenTag(darkMode) {
 }
 function createHtmlForDoenetViewer(id2, doenetML, doenetViewerProps, standaloneUrl, cssUrl, useSharedCoreWorker = false) {
   const doenetViewerPropsSpecified = Object.keys(doenetViewerProps);
+  if (!doenetViewerPropsSpecified.includes("initializedCallback")) {
+    doenetViewerPropsSpecified.push("initializedCallback");
+  }
   return `
     <html style="overflow:hidden">
     ${createIframeHead(standaloneUrl, cssUrl)}
@@ -26030,19 +26033,27 @@ const DEFAULT_MAX_LIVE_VIEWERS = 3;
 const DEFAULT_VISIBLE_MARGIN = "1000px";
 const DEFAULT_FLUSH_TIMEOUT_MS = 5e3;
 const DEFAULT_PARK_DELAY_MS = 2e3;
+const DEFAULT_MAX_CONCURRENT_BOOTS = 2;
+const BOOT_SLOT_WATCHDOG_MS = 9e4;
 const records = /* @__PURE__ */ new Map();
 let visibleOrderCounter = 0;
 let effectiveMaxLive = null;
 let warnedMixedBudgets = false;
 let evaluateTimerId = null;
 let evaluateTimerAt = Infinity;
+let effectiveMaxBoots = null;
+const bootSlotHolders = /* @__PURE__ */ new Set();
+let bootRequestCounter = 0;
+const bootQueue = [];
 function registerWindowedViewer({
   id: id2,
   maxLiveViewers,
+  maxConcurrentBoots,
   parkDelayMs,
   canPark,
   requestPark
 }) {
+  effectiveMaxBoots = effectiveMaxBoots === null ? maxConcurrentBoots : Math.min(effectiveMaxBoots, maxConcurrentBoots);
   if (effectiveMaxLive !== null && effectiveMaxLive !== maxLiveViewers && !warnedMixedBudgets) {
     warnedMixedBudgets = true;
     console.warn(
@@ -26063,9 +26074,47 @@ function registerWindowedViewer({
   scheduleEvaluate(parkDelayMs);
   return () => {
     records.delete(id2);
+    cancelBootRequest(id2);
+    releaseBootSlot(id2);
     scheduleEvaluate(0);
   };
 }
+function requestBootSlot(id2, grant) {
+  if (bootSlotHolders.has(id2) || bootQueue.some((r2) => r2.id === id2)) {
+    return;
+  }
+  bootQueue.push({ id: id2, requestOrder: ++bootRequestCounter, grant });
+  pumpBootQueue();
+}
+function cancelBootRequest(id2) {
+  const idx = bootQueue.findIndex((r2) => r2.id === id2);
+  if (idx !== -1) {
+    bootQueue.splice(idx, 1);
+  }
+}
+function releaseBootSlot(id2) {
+  if (bootSlotHolders.delete(id2)) {
+    pumpBootQueue();
+  }
+}
+function pumpBootQueue() {
+  const max2 = effectiveMaxBoots ?? Infinity;
+  while (bootQueue.length > 0 && bootSlotHolders.size < max2) {
+    let best = 0;
+    for (let i2 = 1; i2 < bootQueue.length; i2++) {
+      const bestVisible = Boolean(
+        records.get(bootQueue[best].id)?.visible
+      );
+      const thisVisible = Boolean(records.get(bootQueue[i2].id)?.visible);
+      if (thisVisible && !bestVisible || thisVisible === bestVisible && bootQueue[i2].requestOrder < bootQueue[best].requestOrder) {
+        best = i2;
+      }
+    }
+    const [request] = bootQueue.splice(best, 1);
+    bootSlotHolders.add(request.id);
+    request.grant();
+  }
+}
 function setViewerVisibility(id2, visible) {
   const record = records.get(id2);
   if (!record || record.visible === visible) {
@@ -26099,7 +26148,14 @@ function getViewerLifecycleStats() {
       parked++;
     }
   }
-  return { registered: records.size, live, parking, parked };
+  return {
+    registered: records.size,
+    live,
+    parking,
+    parked,
+    booting: bootSlotHolders.size,
+    bootQueue: bootQueue.length
+  };
 }
 function scheduleEvaluate(delayMs) {
   const at = Date.now() + delayMs;
@@ -63306,7 +63362,7 @@ function ExternalVirtualKeyboard({
     }
   );
 }
-const version = "0.7.20-dev.326";
+const version = "0.7.20-dev.327";
 const latestDoenetmlVersion = version;
 function subscribeToPinnedTheme() {
   return () => {
@@ -63361,9 +63417,9 @@ function DoenetViewer({
   const doenetMLRef = React__default.useRef(doenetML);
   doenetMLRef.current = doenetML;
   const windowed = mountPolicy?.mode === "windowed";
-  const [parked, setParked] = React__default.useState(false);
+  const [parked, setParked] = React__default.useState(windowed);
   const [parkGeneration, setParkGeneration] = React__default.useState(0);
-  const parkedRef = React__default.useRef(false);
+  const parkedRef = React__default.useRef(windowed);
   const parkingRef = React__default.useRef(false);
   const visibleRef = React__default.useRef(false);
   const containerRef = React__default.useRef(null);
@@ -63379,6 +63435,40 @@ function DoenetViewer({
   if (windowed && pinnedVariantIndexRef.current === null) {
     pinnedVariantIndexRef.current = doenetViewerProps.requestedVariantIndex ?? Math.floor(Math.random() * 1e6) + 1;
   }
+  const bootWatchdogRef = React__default.useRef(
+    null
+  );
+  function clearBootWatchdog() {
+    if (bootWatchdogRef.current !== null) {
+      clearTimeout(bootWatchdogRef.current);
+      bootWatchdogRef.current = null;
+    }
+  }
+  function relinquishBootSlot() {
+    clearBootWatchdog();
+    releaseBootSlot(id2);
+  }
+  const composedInitializedCallbackRef = React__default.useRef(null);
+  if (composedInitializedCallbackRef.current === null) {
+    composedInitializedCallbackRef.current = (arg) => {
+      relinquishBootSlot();
+      doenetViewerPropsRef.current.initializedCallback?.(arg);
+    };
+  }
+  function functionPropToProxy(key, prop) {
+    if (windowed && key === "initializedCallback") {
+      return composedInitializedCallbackRef.current;
+    }
+    return prop;
+  }
+  function appendComposedInitializedCallback(proxiedFunctions, hostFunctions) {
+    if (windowed && !("initializedCallback" in hostFunctions)) {
+      proxiedFunctions.push("initializedCallback");
+      proxiedFunctions.push(
+        proxy(composedInitializedCallbackRef.current)
+      );
+    }
+  }
   const [height, setHeight] = React__default.useState("500px");
   const [inErrorState, setInErrorState] = React__default.useState(null);
   const [ignoreDetectedVersion, setIgnoreDetectedVersion] = React__default.useState(false);
@@ -63540,6 +63630,9 @@ function DoenetViewer({
         });
       }
       if (data.error) {
+        if (windowed) {
+          relinquishBootSlot();
+        }
         return setInErrorState(data.error);
       } else if (data.iframeReady) {
         if (ref.current) {
@@ -63553,9 +63646,15 @@ function DoenetViewer({
             if (typeof prop === "function") {
               registeredFunctions[key] = prop;
               proxiedFunctions.push(key);
-              proxiedFunctions.push(proxy(prop));
+              proxiedFunctions.push(
+                proxy(functionPropToProxy(key, prop))
+              );
             }
           }
+          appendComposedInitializedCallback(
+            proxiedFunctions,
+            registeredFunctions
+          );
           viewerIframe.renderViewerWithFunctionProps(...proxiedFunctions).catch(
             logComlinkError(
               "DoenetViewer",
@@ -63572,9 +63671,7 @@ function DoenetViewer({
         }
       }
     };
-    if (ref.current) {
-      window.addEventListener("message", listener);
-    }
+    window.addEventListener("message", listener);
     return () => {
       window.removeEventListener("message", listener);
     };
@@ -63632,8 +63729,9 @@ function DoenetViewer({
     const proxiedFunctions = [];
     for (const [key, val] of Object.entries(current)) {
       proxiedFunctions.push(key);
-      proxiedFunctions.push(proxy(val));
+      proxiedFunctions.push(proxy(functionPropToProxy(key, val)));
     }
+    appendComposedInitializedCallback(proxiedFunctions, current);
     const action = (remote) => {
       remote.updateViewerFunctionProps(...proxiedFunctions).catch(
         logComlinkError(
@@ -63717,6 +63815,7 @@ function DoenetViewer({
   function finishPark() {
     viewerIframeRef.current = null;
     destroySharedCoresForViewer(id2);
+    relinquishBootSlot();
     parkedRef.current = true;
     setParked(true);
     notifyViewerState(id2, "parked");
@@ -63725,10 +63824,21 @@ function DoenetViewer({
     if (!parkedRef.current) {
       return;
     }
-    parkedRef.current = false;
-    setParked(false);
-    setParkGeneration((generation) => generation + 1);
-    notifyViewerState(id2, "live");
+    requestBootSlot(id2, () => {
+      if (!parkedRef.current || !visibleRef.current) {
+        releaseBootSlot(id2);
+        return;
+      }
+      parkedRef.current = false;
+      setParked(false);
+      setParkGeneration((generation) => generation + 1);
+      notifyViewerState(id2, "live");
+      clearBootWatchdog();
+      bootWatchdogRef.current = setTimeout(() => {
+        bootWatchdogRef.current = null;
+        releaseBootSlot(id2);
+      }, BOOT_SLOT_WATCHDOG_MS);
+    });
   }
   React__default.useEffect(() => {
     if (!windowed || !containerRef.current) {
@@ -63741,6 +63851,8 @@ function DoenetViewer({
           setViewerVisibility(id2, entry.isIntersecting);
           if (entry.isIntersecting && parkedRef.current) {
             unpark();
+          } else if (!entry.isIntersecting) {
+            cancelBootRequest(id2);
           }
         }
       },
@@ -63765,12 +63877,17 @@ function DoenetViewer({
     const unregister = registerWindowedViewer({
       id: id2,
       maxLiveViewers: mountPolicy?.maxLiveViewers ?? DEFAULT_MAX_LIVE_VIEWERS,
+      maxConcurrentBoots: mountPolicy?.maxConcurrentBoots ?? DEFAULT_MAX_CONCURRENT_BOOTS,
       parkDelayMs: mountPolicy?.parkDelayMs ?? DEFAULT_PARK_DELAY_MS,
       canPark,
       requestPark: beginPark
     });
+    if (parkedRef.current) {
+      notifyViewerState(id2, "parked");
+    }
     return () => {
       parkFlushCleanupRef.current?.();
+      clearBootWatchdog();
       unregister();
     };
   }, [windowed]);