@ai-matrx/agents 0.59.277 → 0.59.279

package/CHANGELOG.md

@@ -1,10 +1,24 @@
 # Changelog
 
-## 0.59.277
+## 0.59.279
 
 UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
 Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
 
+## 0.59.278
+
+- `./models`: `followModelCatalogVisibility` never swallows a return. Every show / focus after the tab was
+  hidden or blurred reads the stamp; only repeated shows with no time away share a read for `minIntervalMs`.
+  The baseline is read at bind (one row) and on hide / blur after a change made it unknown; a tab's own
+  catch-up keeps the stamp it read. Live 2026-10-24: the admin audit page took focus for a search, the admin
+  renamed in another tab and came back inside 20 s, and the throttle read nothing. Test:
+  `models/react/hidden-tab-catches-up-on-visible.test.tsx`. Consumer action: none.
+
+## 0.59.277
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff a13dc14bcc 9798073998 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.276
 
 - `./models`: one catalog edit costs a page at most two requests, however many model labels are mounted.

package/dist/models/index.cjs

@@ -1687,6 +1687,7 @@ function followModelCatalogVisibility(options) {
   let baseline;
   let inFlight = null;
   let lastShownRead = -Infinity;
+  let awaySinceRead = true;
   const stamp = () => inFlight ??= readModelCatalogStamp(options.client).finally(() => {
     inFlight = null;
   });
@@ -1697,34 +1698,45 @@ function followModelCatalogVisibility(options) {
       if (baseline === void 0) baseline = s4;
     }, fail);
   };
-  const onHidden = () => {
-    if (page.document.visibilityState === "hidden") learnBaseline();
+  const onAway = () => {
+    awaySinceRead = true;
+    learnBaseline();
   };
   const onShown = () => {
     if (page.document.visibilityState === "hidden") return;
     const t = now();
-    if (t - lastShownRead < minIntervalMs) return;
+    if (!awaySinceRead && t - lastShownRead < minIntervalMs) return;
+    awaySinceRead = false;
     lastShownRead = t;
     const known = baseline;
     if (known === void 0) return learnBaseline();
     void stamp().then((s4) => {
-      if (s4 === known) return;
+      if (s4 === baseline || baseline === void 0) return;
+      ownAnnounce = true;
+      try {
+        announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
+      } finally {
+        ownAnnounce = false;
+      }
       baseline = s4;
-      announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
     }, fail);
   };
+  let ownAnnounce = false;
   const offChanges = onModelCatalogChanged(() => {
+    if (ownAnnounce) return;
     baseline = void 0;
     if (page.document.visibilityState === "hidden") learnBaseline();
   });
-  const onVisibility = () => page.document.visibilityState === "hidden" ? onHidden() : onShown();
+  const onVisibility = () => page.document.visibilityState === "hidden" ? onAway() : onShown();
   page.document.addEventListener("visibilitychange", onVisibility);
   page.window.addEventListener("focus", onShown);
-  if (page.document.visibilityState === "hidden") learnBaseline();
+  page.window.addEventListener("blur", onAway);
+  learnBaseline();
   return () => {
     offChanges();
     page.document.removeEventListener("visibilitychange", onVisibility);
     page.window.removeEventListener("focus", onShown);
+    page.window.removeEventListener("blur", onAway);
   };
 }
 

package/dist/models/index.d.cts

@@ -2141,10 +2141,13 @@ interface ModelCatalogVisibilityOptions {
 /**
  * When the tab shows or takes focus, read the catalog stamp (one row) and, when it moved since the tab
  * last knew it, announce a model catalog change through the SAME door as the bus (every catalog re-reads
- * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is taken when the
- * tab hides (or at bind when it starts hidden), and refreshed by every announced change. Reads already in
- * flight are joined; shows/focuses within `minIntervalMs` share the last read. Returns the unbind. No-op
- * where there is no document (a server render, a worker).
+ * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is read at bind,
+ * and again when the tab hides or loses focus after an announced change made it unknown. Every return
+ * from away (hidden or blurred) reads the stamp; only repeated shows / focuses with no time away in
+ * between share the last read for `minIntervalMs` (a tab that took focus to type a search, went to
+ * another tab for a rename and came back inside 20 s used to read nothing — live 2026-10-24, the admin
+ * audit page). Reads already in flight are joined. Returns the unbind. No-op where there is no document
+ * (a server render, a worker).
  */
 declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 

package/dist/models/index.d.ts

@@ -2141,10 +2141,13 @@ interface ModelCatalogVisibilityOptions {
 /**
  * When the tab shows or takes focus, read the catalog stamp (one row) and, when it moved since the tab
  * last knew it, announce a model catalog change through the SAME door as the bus (every catalog re-reads
- * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is taken when the
- * tab hides (or at bind when it starts hidden), and refreshed by every announced change. Reads already in
- * flight are joined; shows/focuses within `minIntervalMs` share the last read. Returns the unbind. No-op
- * where there is no document (a server render, a worker).
+ * what it read; every reader following `onModelCatalogChanged` re-reads). The baseline is read at bind,
+ * and again when the tab hides or loses focus after an announced change made it unknown. Every return
+ * from away (hidden or blurred) reads the stamp; only repeated shows / focuses with no time away in
+ * between share the last read for `minIntervalMs` (a tab that took focus to type a search, went to
+ * another tab for a rename and came back inside 20 s used to read nothing — live 2026-10-24, the admin
+ * audit page). Reads already in flight are joined. Returns the unbind. No-op where there is no document
+ * (a server render, a worker).
  */
 declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 

package/dist/models/index.js

@@ -1503,6 +1503,7 @@ function followModelCatalogVisibility(options) {
   let baseline;
   let inFlight = null;
   let lastShownRead = -Infinity;
+  let awaySinceRead = true;
   const stamp = () => inFlight ??= readModelCatalogStamp(options.client).finally(() => {
     inFlight = null;
   });
@@ -1513,34 +1514,45 @@ function followModelCatalogVisibility(options) {
       if (baseline === void 0) baseline = s4;
     }, fail);
   };
-  const onHidden = () => {
-    if (page.document.visibilityState === "hidden") learnBaseline();
+  const onAway = () => {
+    awaySinceRead = true;
+    learnBaseline();
   };
   const onShown = () => {
     if (page.document.visibilityState === "hidden") return;
     const t = now();
-    if (t - lastShownRead < minIntervalMs) return;
+    if (!awaySinceRead && t - lastShownRead < minIntervalMs) return;
+    awaySinceRead = false;
     lastShownRead = t;
     const known = baseline;
     if (known === void 0) return learnBaseline();
     void stamp().then((s4) => {
-      if (s4 === known) return;
+      if (s4 === baseline || baseline === void 0) return;
+      ownAnnounce = true;
+      try {
+        announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
+      } finally {
+        ownAnnounce = false;
+      }
       baseline = s4;
-      announceModelCatalogChanged({ catalog: "models", change: "catch_up_visible" });
     }, fail);
   };
+  let ownAnnounce = false;
   const offChanges = onModelCatalogChanged(() => {
+    if (ownAnnounce) return;
     baseline = void 0;
     if (page.document.visibilityState === "hidden") learnBaseline();
   });
-  const onVisibility = () => page.document.visibilityState === "hidden" ? onHidden() : onShown();
+  const onVisibility = () => page.document.visibilityState === "hidden" ? onAway() : onShown();
   page.document.addEventListener("visibilitychange", onVisibility);
   page.window.addEventListener("focus", onShown);
-  if (page.document.visibilityState === "hidden") learnBaseline();
+  page.window.addEventListener("blur", onAway);
+  learnBaseline();
   return () => {
     offChanges();
     page.document.removeEventListener("visibilitychange", onVisibility);
     page.window.removeEventListener("focus", onShown);
+    page.window.removeEventListener("blur", onAway);
   };
 }
 

package/dist/versions/react/index.cjs

@@ -1280,9 +1280,9 @@ function ContractBreak({ version, ports }) {
       return;
     }
     {
-      ports.notify.success(
-        kind ? `v${version.version_number} marked as a ${kind} contract break.` : `Contract-break declaration cleared for v${version.version_number}.`
-      );
+      ports.notify.success(kind ? "Contract break marked" : "Contract break cleared", {
+        description: kind ? `v${version.version_number}, ${kind}` : `v${version.version_number}`
+      });
     }
   }
   const autoChange = version.contract_change || null;

package/dist/versions/react/index.d.cts

@@ -96,7 +96,10 @@ interface VersionHistoryLoad {
 
 /** Where the timeline says a result: the host's toasts (sonner on the web). */
 interface VersionTimelineNotify {
-    success: (message: string) => void;
+    /** A card: a short title and an optional line (design-system NOTICE_TEXT_BUDGET). */
+    success: (message: string, options?: {
+        description?: string;
+    }) => void;
     /** A card: a short title and an optional line (design-system NOTICE_TEXT_BUDGET). */
     error: (message: string, options?: {
         description?: string;

package/dist/versions/react/index.d.ts

@@ -96,7 +96,10 @@ interface VersionHistoryLoad {
 
 /** Where the timeline says a result: the host's toasts (sonner on the web). */
 interface VersionTimelineNotify {
-    success: (message: string) => void;
+    /** A card: a short title and an optional line (design-system NOTICE_TEXT_BUDGET). */
+    success: (message: string, options?: {
+        description?: string;
+    }) => void;
     /** A card: a short title and an optional line (design-system NOTICE_TEXT_BUDGET). */
     error: (message: string, options?: {
         description?: string;

package/dist/versions/react/index.js

@@ -1284,9 +1284,9 @@ function ContractBreak({ version, ports }) {
       return;
     }
     {
-      ports.notify.success(
-        kind ? `v${version.version_number} marked as a ${kind} contract break.` : `Contract-break declaration cleared for v${version.version_number}.`
-      );
+      ports.notify.success(kind ? "Contract break marked" : "Contract break cleared", {
+        description: kind ? `v${version.version_number}, ${kind}` : `v${version.version_number}`
+      });
     }
   }
   const autoChange = version.contract_change || null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.277",
+  "version": "0.59.279",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -522,5 +522,5 @@
       "optional": true
     }
   },
-  "gitHead": "9798073998e5fa0c03b673a38fda129a2bc7d19d"
+  "gitHead": "129b26d86cca439c51d2ec6bd4d421182b33922c"
 }