@entifix/react-integration 0.1.0-0

package/dist/reactive/reactive-channel.js

@@ -0,0 +1,55 @@
+import { Context } from 'effect';
+export class ReactiveChannelTag extends Context.Tag('ReactiveChannel')() {
+}
+/**
+ * A channel that never emits — the default until a transport is provided.
+ *
+ * It never connects either, so `onConnect` registers nothing: a consumer of this
+ * channel reconciles never, which is the honest behaviour for a transport that
+ * is not there.
+ */ export const NoopReactiveChannel = {
+    subscribe: ()=>()=>undefined,
+    onConnect: ()=>()=>undefined
+};
+/**
+ * A synchronous in-memory channel: `emit` fans out to every live subscriber.
+ *
+ * It backs specs. It is no longer what the workspace runs on — that is
+ * `makeEventSourceReactiveChannel`, and until ADR 0036 landed a transport this
+ * one was mounted in its place, emitting nothing, so a reader of the workspace
+ * could not tell "the transport is missing" from "nothing changed".
+ */ export function makeInMemoryReactiveChannel() {
+    const listeners = new Set();
+    const connectListeners = new Set();
+    let connected = false;
+    return {
+        subscribe (listener) {
+            listeners.add(listener);
+            return ()=>{
+                listeners.delete(listener);
+            };
+        },
+        onConnect (listener) {
+            connectListeners.add(listener);
+            // Mirrors the real transport: a listener arriving after the connection is
+            // already up must not wait for the next drop to hear about it.
+            if (connected) listener();
+            return ()=>{
+                connectListeners.delete(listener);
+            };
+        },
+        connect () {
+            connected = true;
+            for (const listener of connectListeners){
+                listener();
+            }
+        },
+        emit (event) {
+            for (const listener of listeners){
+                listener(event);
+            }
+        }
+    };
+}
+
+//# sourceMappingURL=reactive-channel.js.map

package/dist/reactive/reactive-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/reactive/reactive-channel.ts"],"sourcesContent":["import type { DomainEvent, EntityChangeEvent } from '@entifix/core';\nimport { Context } from 'effect';\n\nexport type { EntityChangeEvent };\n\n/**\n * A listener on the reactive stream.\n *\n * It receives the whole message, not just the payload: the transaction id, the\n * emission time and the sequence a consumer needs are `meta.event.correlationId`,\n * `.at` and `.id`, and duplicating them onto {@link EntityChangeEvent} is how\n * two sources of one fact drift (ADR 0036). `#137` settles an optimistic write\n * on the correlation id; `useReactiveInvalidation` reads only `data.entity`.\n */\nexport type EntityChangeListener = (\n  event: DomainEvent<EntityChangeEvent>,\n) => void;\n\n/**\n * The reactive-updates port. Framework-free on purpose (like the OTel tooling):\n * the transport is swappable, and the React side wires `subscribe` to the query\n * client. `subscribe` returns its own unsubscribe.\n */\nexport interface ReactiveChannel {\n  subscribe(listener: EntityChangeListener): () => void;\n  /**\n   * Runs whenever the stream is (re)connected — and **immediately if it is\n   * already connected when the listener registers**.\n   *\n   * The stream does not replay, by design (ADR 0036), so a consumer that missed\n   * an outcome while disconnected has to go and ask. This is the signal that\n   * tells it when to: `#137` re-queries every pending transaction id here.\n   *\n   * ⚠️ **The replay is the mechanism, not a convenience.** The channel is\n   * refcounted and opened by its *first* subscriber, and\n   * `useReactiveInvalidation` typically is that subscriber. A consumer mounting\n   * after it — which depends on nothing more than component-tree ordering —\n   * would otherwise register for an open that had already happened, and\n   * reconcile nothing until the next real network drop. On a page load with no\n   * disconnect, a pending set restored from the previous session would never be\n   * reconciled at all, which is the case this exists for.\n   *\n   * Required rather than optional: an optional member on a port is how one\n   * implementation quietly stops honouring it while every consumer compiles.\n   */\n  onConnect(listener: () => void): () => void;\n}\n\nexport class ReactiveChannelTag extends Context.Tag('ReactiveChannel')<\n  ReactiveChannelTag,\n  ReactiveChannel\n>() {}\n\n/**\n * A channel that never emits — the default until a transport is provided.\n *\n * It never connects either, so `onConnect` registers nothing: a consumer of this\n * channel reconciles never, which is the honest behaviour for a transport that\n * is not there.\n */\nexport const NoopReactiveChannel: ReactiveChannel = {\n  subscribe: () => () => undefined,\n  onConnect: () => () => undefined,\n};\n\nexport interface InMemoryReactiveChannel extends ReactiveChannel {\n  /** Push an event to every current subscriber (drives tests and the mock). */\n  emit(event: DomainEvent<EntityChangeEvent>): void;\n  /**\n   * Announce a (re)connection, so a spec can drive the reconciliation path.\n   *\n   * Also flips this channel to \"connected\", which is what makes a listener\n   * registered afterwards fire immediately — the behaviour the real transport\n   * has and the one most likely to be got wrong.\n   */\n  connect(): void;\n}\n\n/**\n * A synchronous in-memory channel: `emit` fans out to every live subscriber.\n *\n * It backs specs. It is no longer what the workspace runs on — that is\n * `makeEventSourceReactiveChannel`, and until ADR 0036 landed a transport this\n * one was mounted in its place, emitting nothing, so a reader of the workspace\n * could not tell \"the transport is missing\" from \"nothing changed\".\n */\nexport function makeInMemoryReactiveChannel(): InMemoryReactiveChannel {\n  const listeners = new Set<EntityChangeListener>();\n  const connectListeners = new Set<() => void>();\n  let connected = false;\n  return {\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    onConnect(listener) {\n      connectListeners.add(listener);\n      // Mirrors the real transport: a listener arriving after the connection is\n      // already up must not wait for the next drop to hear about it.\n      if (connected) listener();\n      return () => {\n        connectListeners.delete(listener);\n      };\n    },\n    connect() {\n      connected = true;\n      for (const listener of connectListeners) {\n        listener();\n      }\n    },\n    emit(event) {\n      for (const listener of listeners) {\n        listener(event);\n      }\n    },\n  };\n}\n"],"names":["Context","ReactiveChannelTag","Tag","NoopReactiveChannel","subscribe","undefined","onConnect","makeInMemoryReactiveChannel","listeners","Set","connectListeners","connected","listener","add","delete","connect","emit","event"],"mappings":"AACA,SAASA,OAAO,QAAQ,SAAS;AA+CjC,OAAO,MAAMC,2BAA2BD,QAAQE,GAAG,CAAC;AAG/C;AAEL;;;;;;CAMC,GACD,OAAO,MAAMC,sBAAuC;IAClDC,WAAW,IAAM,IAAMC;IACvBC,WAAW,IAAM,IAAMD;AACzB,EAAE;AAeF;;;;;;;CAOC,GACD,OAAO,SAASE;IACd,MAAMC,YAAY,IAAIC;IACtB,MAAMC,mBAAmB,IAAID;IAC7B,IAAIE,YAAY;IAChB,OAAO;QACLP,WAAUQ,QAAQ;YAChBJ,UAAUK,GAAG,CAACD;YACd,OAAO;gBACLJ,UAAUM,MAAM,CAACF;YACnB;QACF;QACAN,WAAUM,QAAQ;YAChBF,iBAAiBG,GAAG,CAACD;YACrB,0EAA0E;YAC1E,+DAA+D;YAC/D,IAAID,WAAWC;YACf,OAAO;gBACLF,iBAAiBI,MAAM,CAACF;YAC1B;QACF;QACAG;YACEJ,YAAY;YACZ,KAAK,MAAMC,YAAYF,iBAAkB;gBACvCE;YACF;QACF;QACAI,MAAKC,KAAK;YACR,KAAK,MAAML,YAAYJ,UAAW;gBAChCI,SAASK;YACX;QACF;IACF;AACF"}

package/dist/reactive/use-reactive-invalidation.d.ts

@@ -0,0 +1,10 @@
+import type { ReactiveChannel } from './reactive-channel.js';
+/**
+ * Subscribe the query cache to a {@link ReactiveChannel}: when the server
+ * reports an entity changed, invalidate every cached query for that entity so
+ * the visible lists refetch. The key prefix `['entity', <name>]` matches
+ * {@link entityQueryKey}, so one event refreshes all pages/filters of the entity
+ * without touching unrelated caches. Optimistic writes settle the same way.
+ */
+export declare function useReactiveInvalidation(channel: ReactiveChannel): void;
+//# sourceMappingURL=use-reactive-invalidation.d.ts.map

package/dist/reactive/use-reactive-invalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-reactive-invalidation.d.ts","sourceRoot":"","sources":["../../src/reactive/use-reactive-invalidation.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAYtE"}

package/dist/reactive/use-reactive-invalidation.js

@@ -0,0 +1,25 @@
+'use client';
+import { useQueryClient } from '@tanstack/react-query';
+import { useEffect } from 'react';
+/**
+ * Subscribe the query cache to a {@link ReactiveChannel}: when the server
+ * reports an entity changed, invalidate every cached query for that entity so
+ * the visible lists refetch. The key prefix `['entity', <name>]` matches
+ * {@link entityQueryKey}, so one event refreshes all pages/filters of the entity
+ * without touching unrelated caches. Optimistic writes settle the same way.
+ */ export function useReactiveInvalidation(channel) {
+    const queryClient = useQueryClient();
+    useEffect(()=>channel.subscribe((event)=>{
+            void queryClient.invalidateQueries({
+                queryKey: [
+                    'entity',
+                    event.data.entity
+                ]
+            });
+        }), [
+        channel,
+        queryClient
+    ]);
+}
+
+//# sourceMappingURL=use-reactive-invalidation.js.map

package/dist/reactive/use-reactive-invalidation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/reactive/use-reactive-invalidation.tsx"],"sourcesContent":["'use client';\n\nimport { useQueryClient } from '@tanstack/react-query';\nimport { useEffect } from 'react';\n\nimport type { ReactiveChannel } from './reactive-channel.js';\n\n/**\n * Subscribe the query cache to a {@link ReactiveChannel}: when the server\n * reports an entity changed, invalidate every cached query for that entity so\n * the visible lists refetch. The key prefix `['entity', <name>]` matches\n * {@link entityQueryKey}, so one event refreshes all pages/filters of the entity\n * without touching unrelated caches. Optimistic writes settle the same way.\n */\nexport function useReactiveInvalidation(channel: ReactiveChannel): void {\n  const queryClient = useQueryClient();\n\n  useEffect(\n    () =>\n      channel.subscribe(event => {\n        void queryClient.invalidateQueries({\n          queryKey: ['entity', event.data.entity],\n        });\n      }),\n    [channel, queryClient],\n  );\n}\n"],"names":["useQueryClient","useEffect","useReactiveInvalidation","channel","queryClient","subscribe","event","invalidateQueries","queryKey","data","entity"],"mappings":"AAAA;AAEA,SAASA,cAAc,QAAQ,wBAAwB;AACvD,SAASC,SAAS,QAAQ,QAAQ;AAIlC;;;;;;CAMC,GACD,OAAO,SAASC,wBAAwBC,OAAwB;IAC9D,MAAMC,cAAcJ;IAEpBC,UACE,IACEE,QAAQE,SAAS,CAACC,CAAAA;YAChB,KAAKF,YAAYG,iBAAiB,CAAC;gBACjCC,UAAU;oBAAC;oBAAUF,MAAMG,IAAI,CAACC,MAAM;iBAAC;YACzC;QACF,IACF;QAACP;QAASC;KAAY;AAE1B"}

package/dist/reactive/use-transaction-settlement.d.ts

@@ -0,0 +1,41 @@
+import type { PendingTransactionStore, TransactionRecord } from '@entifix/transactions';
+import type { ReactiveChannel } from './reactive-channel.js';
+export interface UseTransactionSettlementOptions {
+    /** The stream outcomes arrive on, and whose reconnects trigger a re-query. */
+    channel: ReactiveChannel;
+    /**
+     * The writes being watched.
+     *
+     * Passed in rather than imported: the store is a shell concern
+     * (`layer:shell`) and this hook is `layer:entifix`, which may not depend
+     * upward. Same seam, and the same reason, as `EntityDraftStore` for autosave.
+     */
+    pending: PendingTransactionStore;
+    /** Reads one record. `undefined` means *not tracked yet* — never *failed*. */
+    read: (transactionId: string) => Promise<TransactionRecord | undefined>;
+    pollIntervalMs?: number;
+}
+/**
+ * Settles the optimistic writes this browser started.
+ *
+ * Three things drive it, and they exist for three different failures:
+ *
+ * - **The stream**, the fast path: `transaction.completed` and
+ *   `transaction.failed` carry the correlation id, so an outcome lands in the
+ *   moment it happens.
+ * - **`onConnect`**, because the stream does not replay (ADR 0036). It fires on
+ *   every open *including for a listener registered while already connected*, so
+ *   a page load holding a restored pending set and an in-session reconnect take
+ *   one path rather than two.
+ * - **An interval**, because `STALE` is written by the recovery sweep and emits
+ *   no event at all — it is reachable only by asking. It runs only while
+ *   something is pending, so an idle workspace polls nothing.
+ *
+ * ⚠️ **A missing record keeps the entry pending.** `accepted` reaches the
+ * tracker over the bus, so with the broker down the entity write commits while
+ * no event is ever published and the tracker holds nothing. Rolling back there
+ * un-renders a healthy write at exactly the moment nobody can tell a UI bug from
+ * an outage. Only `FAILED` and `STALE` are terminal.
+ */
+export declare function useTransactionSettlement({ channel, pending, read, pollIntervalMs, }: UseTransactionSettlementOptions): void;
+//# sourceMappingURL=use-transaction-settlement.d.ts.map

package/dist/reactive/use-transaction-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-transaction-settlement.d.ts","sourceRoot":"","sources":["../../src/reactive/use-transaction-settlement.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAK/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAK7D,MAAM,WAAW,+BAA+B;IAC9C,8EAA8E;IAC9E,OAAO,EAAE,eAAe,CAAC;IACzB;;;;;;OAMG;IACH,OAAO,EAAE,uBAAuB,CAAC;IACjC,8EAA8E;IAC9E,IAAI,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,OAAO,EACP,OAAO,EACP,IAAI,EACJ,cAAgC,GACjC,EAAE,+BAA+B,GAAG,IAAI,CA2GxC"}

package/dist/reactive/use-transaction-settlement.js

@@ -0,0 +1,123 @@
+'use client';
+import { useQueryClient } from '@tanstack/react-query';
+import { useCallback, useEffect, useRef } from 'react';
+import { entityQueryScopeFor } from '../query/entity-query-key.js';
+/** How often to re-ask while anything is pending. */ const DEFAULT_POLL_MS = 30000;
+/**
+ * Settles the optimistic writes this browser started.
+ *
+ * Three things drive it, and they exist for three different failures:
+ *
+ * - **The stream**, the fast path: `transaction.completed` and
+ *   `transaction.failed` carry the correlation id, so an outcome lands in the
+ *   moment it happens.
+ * - **`onConnect`**, because the stream does not replay (ADR 0036). It fires on
+ *   every open *including for a listener registered while already connected*, so
+ *   a page load holding a restored pending set and an in-session reconnect take
+ *   one path rather than two.
+ * - **An interval**, because `STALE` is written by the recovery sweep and emits
+ *   no event at all — it is reachable only by asking. It runs only while
+ *   something is pending, so an idle workspace polls nothing.
+ *
+ * ⚠️ **A missing record keeps the entry pending.** `accepted` reaches the
+ * tracker over the bus, so with the broker down the entity write commits while
+ * no event is ever published and the tracker holds nothing. Rolling back there
+ * un-renders a healthy write at exactly the moment nobody can tell a UI bug from
+ * an outage. Only `FAILED` and `STALE` are terminal.
+ */ export function useTransactionSettlement({ channel, pending, read, pollIntervalMs = DEFAULT_POLL_MS }) {
+    const queryClient = useQueryClient();
+    // The store is rebuilt whenever an entry changes and `read` is typically
+    // inline, so both are held in refs: keying the subscription on their identity
+    // would tear down and re-open the stream every time a write settled.
+    const pendingRef = useRef(pending);
+    const readRef = useRef(read);
+    // Refs may not be written during render. This runs before the effects below,
+    // since effects fire in declaration order, so they always see the latest.
+    useEffect(()=>{
+        pendingRef.current = pending;
+        readRef.current = read;
+    });
+    const invalidate = useCallback((entity)=>void queryClient.invalidateQueries({
+            queryKey: entityQueryScopeFor(entity)
+        }), [
+        queryClient
+    ]);
+    /**
+   * Applies whatever the tracker currently says about one entry.
+   *
+   * The single place the terminal-state rule lives — the stream path, the
+   * reconnect path and the interval all come through here, so there is one
+   * answer to "what does this state mean" rather than three that can drift.
+   */ const reconcile = useCallback(async (entry)=>{
+        const record = await readRef.current(entry.transactionId).catch(// The tracker being unreachable says nothing about the write. Keeping
+        // the entry is what makes a service restart converge instead of dropping
+        // every optimistic row on the floor.
+        ()=>undefined);
+        // ⚠️ Not tracked yet, or still running. Either way it is not over, and
+        // this is the branch that must not be turned into a rollback.
+        if (record === undefined || record.state === 'PENDING') return;
+        if (record.state === 'COMPLETED') {
+            pendingRef.current.settle(entry.transactionId);
+        } else {
+            // `record.error` is free text from whatever threw — diagnostic detail
+            // beside a translated headline, never the message itself.
+            pendingRef.current.fail(entry.transactionId, record.error);
+        }
+        invalidate(entry.entity);
+    }, [
+        invalidate
+    ]);
+    const reconcileAll = useCallback(()=>{
+        for (const entry of pendingRef.current.entries){
+            if (entry.state === 'pending') void reconcile(entry);
+        }
+    }, [
+        reconcile
+    ]);
+    useEffect(()=>{
+        const stopListening = channel.subscribe((event)=>{
+            const transactionId = event.correlationId;
+            if (transactionId === undefined) return;
+            const entry = pendingRef.current.entries.find((candidate)=>candidate.transactionId === transactionId);
+            // An id this browser never started belongs to another tab or another
+            // session — the stream is organization-scoped, not connection-scoped.
+            if (entry === undefined) return;
+            if (event.name === 'transaction.completed') {
+                pendingRef.current.settle(transactionId);
+                invalidate(event.data.entity);
+                return;
+            }
+            if (event.name === 'transaction.failed') {
+                // The frame carries no reason: `EntityChangeEvent` collapses four states
+                // into created/deleted and holds no `error`. So the record is re-read
+                // rather than the payload widened (ADR 0036's hint-versus-record split).
+                void reconcile(entry);
+            }
+        });
+        const stopWatchingConnections = channel.onConnect(reconcileAll);
+        return ()=>{
+            stopListening();
+            stopWatchingConnections();
+        };
+    }, [
+        channel,
+        invalidate,
+        reconcile,
+        reconcileAll
+    ]);
+    // Keyed on whether anything is watched at all, not on the entries: that flips
+    // once per transition rather than on every settle, so the timer is not torn
+    // down and rebuilt each time a write lands.
+    const watching = pending.entries.length > 0;
+    useEffect(()=>{
+        if (!watching) return;
+        const timer = setInterval(reconcileAll, pollIntervalMs);
+        return ()=>clearInterval(timer);
+    }, [
+        watching,
+        pollIntervalMs,
+        reconcileAll
+    ]);
+}
+
+//# sourceMappingURL=use-transaction-settlement.js.map

package/dist/reactive/use-transaction-settlement.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/reactive/use-transaction-settlement.tsx"],"sourcesContent":["'use client';\n\nimport type {\n  PendingEntry,\n  PendingTransactionStore,\n  TransactionRecord,\n} from '@entifix/transactions';\nimport { useQueryClient } from '@tanstack/react-query';\nimport { useCallback, useEffect, useRef } from 'react';\n\nimport { entityQueryScopeFor } from '../query/entity-query-key.js';\nimport type { ReactiveChannel } from './reactive-channel.js';\n\n/** How often to re-ask while anything is pending. */\nconst DEFAULT_POLL_MS = 30_000;\n\nexport interface UseTransactionSettlementOptions {\n  /** The stream outcomes arrive on, and whose reconnects trigger a re-query. */\n  channel: ReactiveChannel;\n  /**\n   * The writes being watched.\n   *\n   * Passed in rather than imported: the store is a shell concern\n   * (`layer:shell`) and this hook is `layer:entifix`, which may not depend\n   * upward. Same seam, and the same reason, as `EntityDraftStore` for autosave.\n   */\n  pending: PendingTransactionStore;\n  /** Reads one record. `undefined` means *not tracked yet* — never *failed*. */\n  read: (transactionId: string) => Promise<TransactionRecord | undefined>;\n  pollIntervalMs?: number;\n}\n\n/**\n * Settles the optimistic writes this browser started.\n *\n * Three things drive it, and they exist for three different failures:\n *\n * - **The stream**, the fast path: `transaction.completed` and\n *   `transaction.failed` carry the correlation id, so an outcome lands in the\n *   moment it happens.\n * - **`onConnect`**, because the stream does not replay (ADR 0036). It fires on\n *   every open *including for a listener registered while already connected*, so\n *   a page load holding a restored pending set and an in-session reconnect take\n *   one path rather than two.\n * - **An interval**, because `STALE` is written by the recovery sweep and emits\n *   no event at all — it is reachable only by asking. It runs only while\n *   something is pending, so an idle workspace polls nothing.\n *\n * ⚠️ **A missing record keeps the entry pending.** `accepted` reaches the\n * tracker over the bus, so with the broker down the entity write commits while\n * no event is ever published and the tracker holds nothing. Rolling back there\n * un-renders a healthy write at exactly the moment nobody can tell a UI bug from\n * an outage. Only `FAILED` and `STALE` are terminal.\n */\nexport function useTransactionSettlement({\n  channel,\n  pending,\n  read,\n  pollIntervalMs = DEFAULT_POLL_MS,\n}: UseTransactionSettlementOptions): void {\n  const queryClient = useQueryClient();\n\n  // The store is rebuilt whenever an entry changes and `read` is typically\n  // inline, so both are held in refs: keying the subscription on their identity\n  // would tear down and re-open the stream every time a write settled.\n  const pendingRef = useRef(pending);\n  const readRef = useRef(read);\n\n  // Refs may not be written during render. This runs before the effects below,\n  // since effects fire in declaration order, so they always see the latest.\n  useEffect(() => {\n    pendingRef.current = pending;\n    readRef.current = read;\n  });\n\n  const invalidate = useCallback(\n    (entity: string) =>\n      void queryClient.invalidateQueries({\n        queryKey: entityQueryScopeFor(entity),\n      }),\n    [queryClient],\n  );\n\n  /**\n   * Applies whatever the tracker currently says about one entry.\n   *\n   * The single place the terminal-state rule lives — the stream path, the\n   * reconnect path and the interval all come through here, so there is one\n   * answer to \"what does this state mean\" rather than three that can drift.\n   */\n  const reconcile = useCallback(\n    async (entry: PendingEntry): Promise<void> => {\n      const record = await readRef.current(entry.transactionId).catch(\n        // The tracker being unreachable says nothing about the write. Keeping\n        // the entry is what makes a service restart converge instead of dropping\n        // every optimistic row on the floor.\n        () => undefined,\n      );\n\n      // ⚠️ Not tracked yet, or still running. Either way it is not over, and\n      // this is the branch that must not be turned into a rollback.\n      if (record === undefined || record.state === 'PENDING') return;\n\n      if (record.state === 'COMPLETED') {\n        pendingRef.current.settle(entry.transactionId);\n      } else {\n        // `record.error` is free text from whatever threw — diagnostic detail\n        // beside a translated headline, never the message itself.\n        pendingRef.current.fail(entry.transactionId, record.error);\n      }\n      invalidate(entry.entity);\n    },\n    [invalidate],\n  );\n\n  const reconcileAll = useCallback(() => {\n    for (const entry of pendingRef.current.entries) {\n      if (entry.state === 'pending') void reconcile(entry);\n    }\n  }, [reconcile]);\n\n  useEffect(() => {\n    const stopListening = channel.subscribe(event => {\n      const transactionId = event.correlationId;\n      if (transactionId === undefined) return;\n\n      const entry = pendingRef.current.entries.find(\n        candidate => candidate.transactionId === transactionId,\n      );\n      // An id this browser never started belongs to another tab or another\n      // session — the stream is organization-scoped, not connection-scoped.\n      if (entry === undefined) return;\n\n      if (event.name === 'transaction.completed') {\n        pendingRef.current.settle(transactionId);\n        invalidate(event.data.entity);\n        return;\n      }\n\n      if (event.name === 'transaction.failed') {\n        // The frame carries no reason: `EntityChangeEvent` collapses four states\n        // into created/deleted and holds no `error`. So the record is re-read\n        // rather than the payload widened (ADR 0036's hint-versus-record split).\n        void reconcile(entry);\n      }\n    });\n\n    const stopWatchingConnections = channel.onConnect(reconcileAll);\n\n    return () => {\n      stopListening();\n      stopWatchingConnections();\n    };\n  }, [channel, invalidate, reconcile, reconcileAll]);\n\n  // Keyed on whether anything is watched at all, not on the entries: that flips\n  // once per transition rather than on every settle, so the timer is not torn\n  // down and rebuilt each time a write lands.\n  const watching = pending.entries.length > 0;\n\n  useEffect(() => {\n    if (!watching) return;\n\n    const timer = setInterval(reconcileAll, pollIntervalMs);\n    return () => clearInterval(timer);\n  }, [watching, pollIntervalMs, reconcileAll]);\n}\n"],"names":["useQueryClient","useCallback","useEffect","useRef","entityQueryScopeFor","DEFAULT_POLL_MS","useTransactionSettlement","channel","pending","read","pollIntervalMs","queryClient","pendingRef","readRef","current","invalidate","entity","invalidateQueries","queryKey","reconcile","entry","record","transactionId","catch","undefined","state","settle","fail","error","reconcileAll","entries","stopListening","subscribe","event","correlationId","find","candidate","name","data","stopWatchingConnections","onConnect","watching","length","timer","setInterval","clearInterval"],"mappings":"AAAA;AAOA,SAASA,cAAc,QAAQ,wBAAwB;AACvD,SAASC,WAAW,EAAEC,SAAS,EAAEC,MAAM,QAAQ,QAAQ;AAEvD,SAASC,mBAAmB,QAAQ,+BAA+B;AAGnE,mDAAmD,GACnD,MAAMC,kBAAkB;AAkBxB;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,SAASC,yBAAyB,EACvCC,OAAO,EACPC,OAAO,EACPC,IAAI,EACJC,iBAAiBL,eAAe,EACA;IAChC,MAAMM,cAAcX;IAEpB,yEAAyE;IACzE,8EAA8E;IAC9E,qEAAqE;IACrE,MAAMY,aAAaT,OAAOK;IAC1B,MAAMK,UAAUV,OAAOM;IAEvB,6EAA6E;IAC7E,0EAA0E;IAC1EP,UAAU;QACRU,WAAWE,OAAO,GAAGN;QACrBK,QAAQC,OAAO,GAAGL;IACpB;IAEA,MAAMM,aAAad,YACjB,CAACe,SACC,KAAKL,YAAYM,iBAAiB,CAAC;YACjCC,UAAUd,oBAAoBY;QAChC,IACF;QAACL;KAAY;IAGf;;;;;;GAMC,GACD,MAAMQ,YAAYlB,YAChB,OAAOmB;QACL,MAAMC,SAAS,MAAMR,QAAQC,OAAO,CAACM,MAAME,aAAa,EAAEC,KAAK,CAC7D,sEAAsE;QACtE,yEAAyE;QACzE,qCAAqC;QACrC,IAAMC;QAGR,uEAAuE;QACvE,8DAA8D;QAC9D,IAAIH,WAAWG,aAAaH,OAAOI,KAAK,KAAK,WAAW;QAExD,IAAIJ,OAAOI,KAAK,KAAK,aAAa;YAChCb,WAAWE,OAAO,CAACY,MAAM,CAACN,MAAME,aAAa;QAC/C,OAAO;YACL,sEAAsE;YACtE,0DAA0D;YAC1DV,WAAWE,OAAO,CAACa,IAAI,CAACP,MAAME,aAAa,EAAED,OAAOO,KAAK;QAC3D;QACAb,WAAWK,MAAMJ,MAAM;IACzB,GACA;QAACD;KAAW;IAGd,MAAMc,eAAe5B,YAAY;QAC/B,KAAK,MAAMmB,SAASR,WAAWE,OAAO,CAACgB,OAAO,CAAE;YAC9C,IAAIV,MAAMK,KAAK,KAAK,WAAW,KAAKN,UAAUC;QAChD;IACF,GAAG;QAACD;KAAU;IAEdjB,UAAU;QACR,MAAM6B,gBAAgBxB,QAAQyB,SAAS,CAACC,CAAAA;YACtC,MAAMX,gBAAgBW,MAAMC,aAAa;YACzC,IAAIZ,kBAAkBE,WAAW;YAEjC,MAAMJ,QAAQR,WAAWE,OAAO,CAACgB,OAAO,CAACK,IAAI,CAC3CC,CAAAA,YAAaA,UAAUd,aAAa,KAAKA;YAE3C,qEAAqE;YACrE,sEAAsE;YACtE,IAAIF,UAAUI,WAAW;YAEzB,IAAIS,MAAMI,IAAI,KAAK,yBAAyB;gBAC1CzB,WAAWE,OAAO,CAACY,MAAM,CAACJ;gBAC1BP,WAAWkB,MAAMK,IAAI,CAACtB,MAAM;gBAC5B;YACF;YAEA,IAAIiB,MAAMI,IAAI,KAAK,sBAAsB;gBACvC,yEAAyE;gBACzE,sEAAsE;gBACtE,yEAAyE;gBACzE,KAAKlB,UAAUC;YACjB;QACF;QAEA,MAAMmB,0BAA0BhC,QAAQiC,SAAS,CAACX;QAElD,OAAO;YACLE;YACAQ;QACF;IACF,GAAG;QAAChC;QAASQ;QAAYI;QAAWU;KAAa;IAEjD,8EAA8E;IAC9E,4EAA4E;IAC5E,4CAA4C;IAC5C,MAAMY,WAAWjC,QAAQsB,OAAO,CAACY,MAAM,GAAG;IAE1CxC,UAAU;QACR,IAAI,CAACuC,UAAU;QAEf,MAAME,QAAQC,YAAYf,cAAcnB;QACxC,OAAO,IAAMmC,cAAcF;IAC7B,GAAG;QAACF;QAAU/B;QAAgBmB;KAAa;AAC7C"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@entifix/react-integration",
+  "nx": {
+    "tags": [
+      "layer:entifix",
+      "scope:shared",
+      "entifix:react",
+      "tier:3"
+    ],
+    "sourceRoot": "packages/react/integration/src",
+    "targets": {
+      "build": {
+        "executor": "@nx/js:swc",
+        "outputs": [
+          "{options.outputPath}"
+        ],
+        "options": {
+          "outputPath": "packages/react/integration/dist",
+          "main": "packages/react/integration/src/index.ts",
+          "tsConfig": "packages/react/integration/tsconfig.lib.json",
+          "skipTypeCheck": true,
+          "stripLeadingPaths": true
+        }
+      }
+    }
+  },
+  "version": "0.1.0-0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/r10c-technologies/entifix.git",
+    "directory": "packages/react/integration"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@entifix/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@entifix/transactions": "0.1.0-0",
+    "@entifix/business": "0.1.0-0",
+    "@entifix/core": "0.1.0-0"
+  },
+  "devDependencies": {
+    "@tanstack/react-form": "1.33.5",
+    "@tanstack/react-query": "^5.101.4",
+    "effect": "3.22.1",
+    "react": "19.2.8",
+    "@entifix/testing-unit": "0.1.0-0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-form": ">=1.33 <2",
+    "@tanstack/react-query": ">=5.101 <6",
+    "effect": ">=3.22 <4",
+    "react": ">=19 <20"
+  }
+}