State sync and persistence issues

package.json

@@ -1,6 +1,6 @@
 {
   "name": "lo_event",
-  "version": "0.0.5",
+  "version": "0.0.9-ack.0",
   "description": "Event logging library for the Learning Observer",
   "main": "dist/loEvent.js",
   "types": "dist/loEvent.d.ts",
@@ -61,10 +61,23 @@
     "./types": {
       "types": "./dist/types.d.ts",
       "import": "./dist/types.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
     }
   },
   "scripts": {
     "test": "vitest run",
+    "typecheck": "tsc --noEmit",
     "test:watch": "vitest",
     "build": "tsup",
     "prepublishOnly": "npm run build",
@@ -100,6 +113,7 @@
     "@types/ws": "^8.18.1",
     "@typescript-eslint/parser": "^8.55.0",
     "eslint": "^9.39.2",
+    "fake-indexeddb": "^6.2.5",
     "globals": "^17.3.0",
     "parcel": "^2.12.0",
     "react": "^19.2.4",

src/disabler.ts

@@ -100,6 +100,17 @@ export function streamEvents () {
   return action === EVENT_ACTION.TRANSMIT;
 }
 
+/** Explicit predicates for the two permanent cases. Callers must never infer a
+ * privacy deletion from retry()'s boolean: permanent MAINTAIN means retain the
+ * outbox forever, while permanent DROP is the one sanctioned destructive case. */
+export function isPermanent (): boolean {
+  return expiration === TIME_LIMIT.PERMANENT;
+}
+
+export function isPermanentOptOut (): boolean {
+  return isPermanent() && action === EVENT_ACTION.DROP;
+}
+
 /**
  * Determines if a client should retry based on the `expiration` status.
  * This function:
@@ -108,14 +119,15 @@ export function streamEvents () {
  *    initializations), and then returns `true` to allow a retry.
  */
 export async function retry () {
-  if (expiration === TIME_LIMIT.PERMANENT) {
-    return false;
-  }
-  const now = Date.now();
-  if (now < expiration!) {
-    debug.info(`waiting for expiration to happen ${new Date(expiration!).toString()}`);
-    await util.delay(expiration! - now);
-    debug.info('we are done waiting');
+  while (true) {
+    if (expiration === TIME_LIMIT.PERMANENT) return false;
+    const deadline = expiration;
+    const now = Date.now();
+    if (deadline === null || now >= deadline) break;
+    debug.info(`waiting for expiration to happen ${new Date(deadline).toString()}`);
+    await util.delay(deadline - now);
+    // A later block frame may have extended or made the block permanent while
+    // we slept. Re-read state instead of clearing that newer instruction.
   }
   action = DEFAULTS.action;
   expiration = DEFAULTS.expiration;

src/hooks.ts

@@ -0,0 +1,49 @@
+/**
+ * React hooks for lo_event persistence status.
+ *
+ * These use useSyncExternalStore against a plain module-level store
+ * in reduxLogger (NOT Redux state — see reduxLogger.ts for rationale).
+ *
+ * Import from 'lo_event/hooks' — this entry point depends on React.
+ */
+import { useSyncExternalStore } from 'react';
+import {
+  subscribeStatus,
+  getSaveStatus,
+  getConnected,
+  getLoaded,
+} from './reduxLogger.js';
+
+export type { SaveStatus } from './reduxLogger.js';
+
+/**
+ * Whether the current state has been persisted.
+ *
+ *   'saved'    — all changes have been sent to the server / localStorage
+ *   'modified' — changes exist, debounce timer running
+ */
+export function useSaved() {
+  return useSyncExternalStore(subscribeStatus, getSaveStatus, () => 'saved' as const);
+}
+
+/**
+ * WebSocket connection status.
+ *
+ *   true  — connected
+ *   false — disconnected (show offline indicator)
+ *   null  — no WebSocket configured (don't show indicator)
+ */
+export function useConnected() {
+  return useSyncExternalStore(subscribeStatus, getConnected, () => null);
+}
+
+/**
+ * Whether initialization is complete (a fetch_blob load cycle has resolved).
+ *
+ * Use this to gate the UI — show a loading screen until true. Note: a store
+ * with no fetch_blob server never resolves loaded (local-only mode is not yet
+ * supported — see reduxLogger).
+ */
+export function useLoaded() {
+  return useSyncExternalStore(subscribeStatus, getLoaded, () => false);
+}