@econ-v1/ports 7.0.45 → 7.0.47

package/dist/shell-cache-reset.d.ts

@@ -10,8 +10,44 @@ export type ShellCacheResetPort = {
  * healthy the node is. Told apart, the two cases need opposite advice: an offline node is
  * fixed by reconnecting and retrying, an uncontrolled page never is — retrying re-runs the
  * identical failure, and only re-establishing a worker recovers it.
+ *
+ * `activateWaitingUpdate` is the recovery for the OTHER stale-worker failure: a page that IS
+ * controlled, by a worker one build behind the node. Its precached shell chunk statically
+ * references a content-hashed chunk that is deliberately NOT precached
+ * (`LIVE_ONLY_STAGE_ASSET_RE`), so after the node is redeployed that reference 404s and the
+ * stage can never open — Retry re-runs the identical fetch. Re-checking the worker script and
+ * handing over to whatever a fresh `update()` finds is the only recovery.
+ *
+ * The worker does NOT wait for the user to accept an update — `service-worker-runtime.js`'s
+ * `install` handler calls `skipWaiting()` UNCONDITIONALLY at the end of every install. What
+ * actually leaves a page stale is that nothing on the long-lived tab ever calls
+ * `registration.update()` in reaction to a stage failing to import: the old shell simply sits on
+ * screen, still fully functional for everything it already has cached, until the next real
+ * navigation. Combined with `skipWaiting()`'s immediacy, a fresh `update()` call can land and
+ * self-activate a new worker (`installing` -> `activating` -> `activated` ->
+ * `clients.claim()`) between one microtask and the next — so by the time this function can look,
+ * `registration.waiting` may already be `null` again, consumed rather than never populated.
+ * Reporting `false` in that case would be treating "didn't catch it in `waiting`" as "nothing
+ * happened", so this also succeeds when `update()` demonstrably found something even though
+ * nothing was left sitting in `waiting`: the page's controller already changed, a new worker is
+ * still `installing`, or a new worker already reached `active` without (yet) being this page's
+ * controller. Resolves `true` in any of those cases; the reload itself is left to the existing
+ * `controllerchange` handler.
+ *
+ * That reload is a GUARANTEE only for the first two of the four `true`-resolving cases above (a
+ * worker was actually messaged, or the controller had already changed) — both are proof a
+ * handoff already happened or was just requested directly. The other two are PREDICTIONS that a
+ * `controllerchange` is coming, not proof of it: a worker `installing` can still have its install
+ * rejected (never reaching waiting/active), and a worker that reached `active` can still fail
+ * inside its own `activate` cleanup in a way that stops `clients.claim()` from ever running,
+ * per spec, without preventing the worker from being considered "activated". A caller that shows
+ * a blocking "reload is coming" panel on `true` cannot treat the reload as certain — it needs its
+ * own bounded fallback for the two predicted cases (`client/ui/src/shell/app-shell.js`'s
+ * `#armStaleShellHandoverFallback`, 2026-09-06 review) rather than trusting this method's
+ * `true` to always end in a page navigation.
  */
 export type ShellWorkerControlPort = {
     isControlled(): boolean;
+    activateWaitingUpdate(): Promise<boolean>;
 };
 //# sourceMappingURL=shell-cache-reset.d.ts.map

package/dist/shell-cache-reset.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell-cache-reset.d.ts","sourceRoot":"","sources":["../src/shell-cache-reset.js"],"names":[],"mappings":"kCACc;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE;;;;;;;;;;;qCAWlB;IAAE,YAAY,IAAI,OAAO,CAAA;CAAE"}
+{"version":3,"file":"shell-cache-reset.d.ts","sourceRoot":"","sources":["../src/shell-cache-reset.js"],"names":[],"mappings":"kCACc;IAAE,KAAK,IAAI,IAAI,CAAA;CAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA8ClB;IACR,YAAY,IAAI,OAAO,CAAC;IACxB,qBAAqB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@econ-v1/ports",
-  "version": "7.0.45",
+  "version": "7.0.47",
   "description": "Platform-neutral ports for Node client applications",
   "license": "MIT OR Apache-2.0",
   "author": "Node contributors",

package/src/shell-cache-reset.js

@@ -10,6 +10,44 @@
  * fixed by reconnecting and retrying, an uncontrolled page never is — retrying re-runs the
  * identical failure, and only re-establishing a worker recovers it.
  *
- * @typedef {{ isControlled(): boolean }} ShellWorkerControlPort
+ * `activateWaitingUpdate` is the recovery for the OTHER stale-worker failure: a page that IS
+ * controlled, by a worker one build behind the node. Its precached shell chunk statically
+ * references a content-hashed chunk that is deliberately NOT precached
+ * (`LIVE_ONLY_STAGE_ASSET_RE`), so after the node is redeployed that reference 404s and the
+ * stage can never open — Retry re-runs the identical fetch. Re-checking the worker script and
+ * handing over to whatever a fresh `update()` finds is the only recovery.
+ *
+ * The worker does NOT wait for the user to accept an update — `service-worker-runtime.js`'s
+ * `install` handler calls `skipWaiting()` UNCONDITIONALLY at the end of every install. What
+ * actually leaves a page stale is that nothing on the long-lived tab ever calls
+ * `registration.update()` in reaction to a stage failing to import: the old shell simply sits on
+ * screen, still fully functional for everything it already has cached, until the next real
+ * navigation. Combined with `skipWaiting()`'s immediacy, a fresh `update()` call can land and
+ * self-activate a new worker (`installing` -> `activating` -> `activated` ->
+ * `clients.claim()`) between one microtask and the next — so by the time this function can look,
+ * `registration.waiting` may already be `null` again, consumed rather than never populated.
+ * Reporting `false` in that case would be treating "didn't catch it in `waiting`" as "nothing
+ * happened", so this also succeeds when `update()` demonstrably found something even though
+ * nothing was left sitting in `waiting`: the page's controller already changed, a new worker is
+ * still `installing`, or a new worker already reached `active` without (yet) being this page's
+ * controller. Resolves `true` in any of those cases; the reload itself is left to the existing
+ * `controllerchange` handler.
+ *
+ * That reload is a GUARANTEE only for the first two of the four `true`-resolving cases above (a
+ * worker was actually messaged, or the controller had already changed) — both are proof a
+ * handoff already happened or was just requested directly. The other two are PREDICTIONS that a
+ * `controllerchange` is coming, not proof of it: a worker `installing` can still have its install
+ * rejected (never reaching waiting/active), and a worker that reached `active` can still fail
+ * inside its own `activate` cleanup in a way that stops `clients.claim()` from ever running,
+ * per spec, without preventing the worker from being considered "activated". A caller that shows
+ * a blocking "reload is coming" panel on `true` cannot treat the reload as certain — it needs its
+ * own bounded fallback for the two predicted cases (`client/ui/src/shell/app-shell.js`'s
+ * `#armStaleShellHandoverFallback`, 2026-09-06 review) rather than trusting this method's
+ * `true` to always end in a page navigation.
+ *
+ * @typedef {{
+ *   isControlled(): boolean,
+ *   activateWaitingUpdate(): Promise<boolean>,
+ * }} ShellWorkerControlPort
  */
 export {};