@doenet/doenetml-iframe 0.7.24-dev.496 → 0.7.24-dev.498

package/README.md

@@ -395,6 +395,33 @@ booted yet) — equally safe to unmount.
 > safe. Every viewer on the page receives a broadcast request and responds
 > (correlate by `activity_id`/`doc_id`/`message_id`).
 
+#### The page going away flushes on its own
+
+A host need not send `flushState` for an ordinary departure. The viewer
+flushes whatever the throttle is holding back when the page hides — on
+`pagehide` and on a `visibilitychange` to `hidden` — so closing the tab,
+typing a new URL, following an external link, or backgrounding a tab on a
+phone no longer strands up to a minute of work. The flushed work arrives on
+your window as an ordinary `SPLICE.reportScoreAndState` message, so a host
+that already persists those saves it with no extra code. Nothing is torn
+down on the way, so a page that comes back — a re-foregrounded tab, a
+back/forward-cache restore — carries on with its state already saved.
+
+> **Important:** for this to survive a real unload, your listener has to
+> persist **synchronously**. The report is handed over by dispatching the
+> message event directly rather than posting it, because a document being
+> unloaded is destroyed before a posted message is ever delivered — but a
+> listener that defers its own write (a `fetch`, a `setTimeout`, an `await`)
+> is destroyed just the same. Write from the listener itself, with
+> `navigator.sendBeacon` or a synchronous store such as `localStorage`.
+>
+> The `reportScoreAndStateCallback` prop does not get this guarantee here:
+> the viewer runs inside the iframe, so calling your callback crosses the
+> frame boundary as a posted message, which an unloading page will not
+> deliver. Listen for `SPLICE.reportScoreAndState` on your window if
+> surviving an unload matters. (Everything else — routine reports, and
+> flushes you requested yourself — reaches the callback as before.)
+
 ### Loading saved state at boot (`SPLICE.getState`)
 
 With `flags: { allowLoadState: true }` and no `initialState` prop, the
@@ -420,14 +447,27 @@ respond:
 { subject: "SPLICE.getState.response", message_id, state }
 ```
 
+Quote the `message_id`: a response carrying state is only read by the viewer
+whose request it names. Replies reach every viewer in the window, and `cid`
+cannot tell two of them apart — it hashes the DoenetML text alone, so a
+second attempt at the same document, or that document opened twice on a
+page, carries the identical `cid`. An unaddressed answer would be restored
+by all of them.
+
 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`).
+`{ subject: "SPLICE.getState.response", error: { code, message } }`,
+either quoting the request's `message_id` or leaving it out — an error is
+the one reply the viewer will take unaddressed, since the worst it costs is
+a message the next usable answer clears. Prefer quoting it even so: an
+unaddressed error is taken by whichever request is open when it lands, on
+every viewer on the page, including one a rebuild opened after the error was
+sent. A reply quoting a *different* id is ignored, since that id belongs to
+some other request.
 
 A request has a single answer: the **first** response carrying state for
-this `cid` is the one the viewer reboots from, and later responses to the
-same `message_id` are ignored. A response with no state — or state for a
+this `cid` is the one the viewer reboots from, and every response after
+that — errors included — is ignored. A response with no state — or state for a
 different `cid` — does not count as that answer, so a listener with nothing
 saved cannot shut out one still in flight. Answer once, out of durable
 storage: a host that replies from an in-memory cache first and from storage

package/index.js

@@ -68534,7 +68534,7 @@ function ExternalVirtualKeyboard({
     }
   );
 }
-const version = "0.7.24-dev.496";
+const version = "0.7.24-dev.498";
 const latestDoenetmlVersion = version;
 function subscribeToPinnedTheme() {
   return () => {

package/package.json

@@ -2,7 +2,7 @@
     "name": "@doenet/doenetml-iframe",
     "type": "module",
     "description": "A renderer for DoenetML contained in an iframe",
-    "version": "0.7.24-dev.496",
+    "version": "0.7.24-dev.498",
     "license": "AGPL-3.0-or-later",
     "homepage": "https://github.com/Doenet/DoenetML#readme",
     "repository": {