@rackbops/ac-plugin-contract 2.0.0-alpha.38 → 2.0.0-alpha.39

package/AUTHORING.md

@@ -376,12 +376,21 @@ it.
 until the operator navigates away: it never remounts one to refresh it. (It used to, on any return to the
 window more than a minute after the panel was opened, which reset every filter, selection and half-typed field
 the panel held, every time.) So a panel whose data goes stale while it is open refreshes it itself, in place,
-into the state already on screen: the Board polls every 15 minutes (with a Refresh now button for a click-
-driven read past the poll, #546), and Issues (`issues-classic`) reads its list
-again when the tab comes back (`focus` on `window`, or `visibilitychange` to visible) more than a minute after
-it opened or last refreshed. A panel that does neither -- Agents, the Admin board's cards -- reads when it is
-opened and after its own actions. Only Home is still refreshed by the shell, which remounts it for Refresh, the
-heartbeat and a return after a minute.
+into the state already on screen: the Board polls every 15 minutes, and Issues (`issues-classic`) reads its
+list again when the tab comes back (`focus` on `window`, or `visibilitychange` to visible) 15 minutes or more
+after its last load or refresh; each also has a Refresh now button for a read on demand (#546, #550).
+Navigating to another console tab does unmount a panel, so a panel that should not reload on every tab change
+keeps its data at module scope: a plugin frontend is one ES module loaded once per page, so module-level state
+outlives the unmount, until a full page reload. The Board, Issues and Home's open-issues card all do this
+(#550). Coming back within 15 minutes of the last load shows the data it already had without reading it
+again, and coming back later reads at once. After a read fails, the Board retries the list or the broken
+card on its next remount; Issues re-reads on a remount only what has had no successful read in the last 15
+minutes, and a return or Refresh now click on Issues restarts its 15 minutes whether or not that read
+succeeds. For Issues, "the last load" is the oldest of its repo list's load and each listed repo's issues
+load, so it is only as fresh as its stalest part. A panel that does neither -- Agents, the Admin board's
+cards -- reads when it is opened and after its own actions. Only Home is still refreshed by the shell,
+which remounts it for Refresh, the heartbeat and a return after a minute; Home's open-issues card keeps
+its count across those remounts, so within 15 minutes of its last load none of them re-reads it (#550).
 
 ### The `@ac/host` browser module
 
@@ -516,7 +525,11 @@ still gets its own `Response` (`.clone()`), so two independent reads of a cache
 already-consumed body. Only `GET` may be cached (`cached` throws on any other method); a rejected fetch is
 never cached — the very next call retries. **A card reads through `cached`, never bare `fetch`, so Refresh
 and the Overview heartbeat (both call `invalidate`) actually reach it** — a card that bypasses `cached` keeps
-serving its own stale response until its own next poll, deaf to both:
+serving its own stale response until its own next poll, deaf to both. A card that deliberately keeps its own
+data across a remount (Home's open-issues card, #550) is a further exception on the other side: both Refresh
+and the heartbeat arrive at it as a remount, and it ignores a remount within 15 minutes of its last load —
+`invalidate()` clears `cached`'s own TTL cache, but the card's own freshness check skips calling `cached` at
+all before it ever gets there.
 
 ```ts
 import { cached, invalidate } from "@ac/host"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.38",
+  "version": "2.0.0-alpha.39",
   "private": false,
   "type": "module",
   "description": "The artifact-console plugin ABI for out-of-repo plugin authors: HostApi, the acPlugin manifest contribution points, the generated manifest JSON Schema, and the @ac/host ambient browser declaration.",