@godspeedai/cognate-react 0.8.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +4 -4
  2. package/src/EGM.md +37 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@godspeedai/cognate-react",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
4
4
  "description": "React 19 bindings over the headless client: runs, projections, frontend capabilities, continuations, artifacts (spec §25.2). No Astryx.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -22,9 +22,9 @@
22
22
  ".": "./src/index.tsx"
23
23
  },
24
24
  "dependencies": {
25
- "@godspeedai/cognate-client": "^0.8.0",
26
- "@godspeedai/cognate-events": "^0.8.0",
27
- "@godspeedai/cognate-runtime-api": "^0.8.0"
25
+ "@godspeedai/cognate-client": "^0.9.1",
26
+ "@godspeedai/cognate-events": "^0.9.1",
27
+ "@godspeedai/cognate-runtime-api": "^0.9.1"
28
28
  },
29
29
  "devDependencies": {
30
30
  "@godspeedai/cognate-runtime-bun": "workspace:*",
package/src/EGM.md ADDED
@@ -0,0 +1,37 @@
1
+ # react / src — React 19 bindings over the headless client
2
+
3
+ ## Overview
4
+
5
+ React 19 hooks that adapt the headless client's framework-neutral `Readable` values with `useSyncExternalStore`, leaving the client as the single source of truth `[index.tsx:1]`. The module exports `CognateProvider`, `useCognate`, and the run/state/capability/artifact/connection hooks `[index.tsx:CognateProvider]`. A module-level `RemoteCapabilityRendererRegistry` keeps same-session renderer provenance for remote capability calls `[index.tsx:RemoteCapabilityRendererRegistry]`.
6
+
7
+ ## Interface
8
+
9
+ - `CognateProvider` — context provider carrying one `CognateClient` `[index.tsx:CognateProvider]`
10
+ - `useCognate` / `useConnectionStatus` — client access and `ConnectionStatus` subscription `[index.tsx:useConnectionStatus]`
11
+ - `useRun` / `useAgent` — derived run state and agent start helper `[index.tsx:useRun]`
12
+ - `useSharedState` / `useThreadSharedState` — mutable shared state with write functions `[index.tsx:useSharedState]`
13
+ - `useProjection` / `useArtifact` / `useContinuations` — projection rows, artifact fetch, open continuations plus resolver `[index.tsx:useContinuations]`
14
+ - `useCapability` / `useRemoteCapability` / `useRemoteCapabilityHistory` — frontend and remote capability registration `[index.tsx:useRemoteCapability]`
15
+ - `RemoteCapabilityRenderRecord` / `RemoteCapabilityRenderer` — renderer record and callback types `[index.tsx:RemoteCapabilityRenderRecord]`
16
+
17
+ ## Invariants
18
+
19
+ - `useCognate` requires a mounted `CognateProvider`; the context default is `undefined` `[index.tsx:CognateContext]`
20
+ - Without a `runId`, `useRun` and `useRemoteCapabilityHistory` return `undefined` / an empty frozen history rather than throwing `[index.tsx:useRemoteCapabilityHistory]`
21
+ - A renderer key is `${continuationId}@${contractVersion}`, so a remounted offer is never mistaken for an older call `[index.tsx:RemoteCapabilityRendererRegistry]`
22
+ - Renderer history is keyed per run and cached as a stable snapshot per run id `[index.tsx:RemoteCapabilityRendererRegistry]`
23
+ - Renderer provenance is derived from durable `run.waiting` metadata where the type starts with `remote:`, plus terminal run events for positions `[index.tsx:RemoteCapabilityRendererRegistry]`
24
+ - Renderer callbacks live in provider memory and cannot be restored after a full reload `[index.tsx:useRemoteCapabilityHistory]`
25
+ - `useRemoteCapability` status is exactly `publishing`, `available`, `error`, and an unmounted prior registration is stopped on cleanup `[index.tsx:useRemoteCapability]`
26
+ - `useArtifact` decodes the body only when `mediaType` starts with `text/` `[index.tsx:useArtifact]`
27
+ - Only continuations whose action is `resume` or `cancel` can be resolved through `useContinuations` `[index.tsx:useContinuations]`
28
+
29
+ ## Side Effects
30
+
31
+ - Client subscriptions (`client.subscribe`, `client.status.subscribe`) while hooks are mounted `[index.tsx:useRemoteCapabilityHistory]`
32
+ - Service calls: `offerCapability`, `artifact`, `resolveContinuation`, shared-state updates `[index.tsx:useRemoteCapability]`
33
+ - `crypto.randomUUID()` for the per-instance remote lease id `[index.tsx:useRemoteCapability]`
34
+
35
+ ## Verification
36
+
37
+ - Run: `cd packages/react && bun test`