@doenet/doenetml-iframe 0.7.24 → 0.7.25-dev.499

package/README.md

@@ -289,6 +289,9 @@ again (parked when off-screen and over budget).
 Notes:
 
 - Eviction is least-recently-visible first.
+- A boot slot is released when the viewer's document initializes *or* when
+  its core cannot be started at all, so a failed activity does not hold a
+  slot until the wrapper's 90 s boot watchdog expires.
 - 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
@@ -392,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
@@ -417,10 +447,31 @@ 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 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
+afterwards keeps the cache's answer.
 
 Passing `initialState` yourself (or `initialState: null` for "start
 fresh") skips this request entirely.