@holonograph/client 0.4.0 → 0.6.0

package/README.md

@@ -93,6 +93,37 @@ status, an error code, and any details the lens returned.
 
 Everything is fully typed; the package ships its own type declarations.
 
+## Watching for changes
+
+Pull-side alerting, transport-agnostic. Poll any windowed lens read on a cadence
+and act only on the delta — a steady state is silent (the same "no all-quiet
+pings" discipline the lens applies to its own output). You supply the fetch and
+where the change goes; the client supplies the cadence and change-detection.
+
+- **`watchByKey({ poll, intervalMs, keyOf, onChange })`** — poll a collection and
+  fire `onChange(diff)` only when items are `added` / `removed` / `changed`
+  (matched by `keyOf`). Returns a handle with `.stop()`. The first poll silently
+  seeds the baseline, so you only hear about change since the watch started (pass
+  `emitInitial: true` for a cold-start inventory).
+- **`diffByKey(prev, next, keyOf)`** / **`hasChanges(diff)`** — the underlying
+  keyed diff, if you want change-detection without the loop.
+- **`createPoller({ poll, intervalMs, onResult })`** — the bare cadence loop
+  (non-overlapping; errors isolated to `onError`, never kill the watcher).
+- **`watchReconciliation(...)` / `watchEmission(...)`** — typed sugar over
+  `watchByKey` for the lens's reconciliation + emission reads.
+
+```ts
+import { watchByKey } from '@holonograph/client';
+
+const handle = watchByKey({
+  poll: (signal) => fetchReconciliation({ signal }), // your windowed read
+  intervalMs: 30_000,
+  keyOf: (row) => row.emissionStreamId,
+  onChange: (diff) => notifyOnCall(diff), // added / removed / changed only
+});
+// later: handle.stop();
+```
+
 ## Requirements
 
 This client does nothing on its own — it needs a **running Holonograph lens** to