@stigmer/react 0.3.4 → 0.4.1

package/internal/store/structural-share.d.ts

@@ -0,0 +1,13 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+/**
+ * Compares two `AgentExecution` snapshots and returns a hybrid object
+ * that reuses old references for unchanged subtrees.
+ *
+ * The runner appends new messages and mutates the streaming tail.
+ * Messages at stable indices with unchanged content keep the previous
+ * reference so downstream `React.memo` can skip re-renders.
+ *
+ * When `prev` is `null` (first snapshot), returns `next` unchanged.
+ */
+export declare function structuralShare(prev: AgentExecution | null, next: AgentExecution): AgentExecution;
+//# sourceMappingURL=structural-share.d.ts.map

package/internal/store/structural-share.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-share.d.ts","sourceRoot":"","sources":["../../../src/internal/store/structural-share.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AAMlG;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,cAAc,GAAG,IAAI,EAC3B,IAAI,EAAE,cAAc,GACnB,cAAc,CA2DhB"}

package/internal/store/structural-share.js

@@ -0,0 +1,240 @@
+/**
+ * Compares two `AgentExecution` snapshots and returns a hybrid object
+ * that reuses old references for unchanged subtrees.
+ *
+ * The runner appends new messages and mutates the streaming tail.
+ * Messages at stable indices with unchanged content keep the previous
+ * reference so downstream `React.memo` can skip re-renders.
+ *
+ * When `prev` is `null` (first snapshot), returns `next` unchanged.
+ */
+export function structuralShare(prev, next) {
+    if (prev === null)
+        return next;
+    const prevStatus = prev.status;
+    const nextStatus = next.status;
+    if (!prevStatus || !nextStatus)
+        return next;
+    const sharedMessages = shareMessages(prevStatus.messages, nextStatus.messages);
+    const sharedSubAgents = shareSubAgents(prevStatus.subAgentExecutions, nextStatus.subAgentExecutions);
+    const sharedApprovals = shareApprovals(prevStatus.pendingApprovals, nextStatus.pendingApprovals);
+    const sharedTodos = shareTodos(prevStatus.todos, nextStatus.todos);
+    const messagesUnchanged = sharedMessages === prevStatus.messages;
+    const subAgentsUnchanged = sharedSubAgents === prevStatus.subAgentExecutions;
+    const approvalsUnchanged = sharedApprovals === prevStatus.pendingApprovals;
+    const todosUnchanged = sharedTodos === prevStatus.todos;
+    const statusFieldsUnchanged = prevStatus.phase === nextStatus.phase &&
+        prevStatus.error === nextStatus.error &&
+        prevStatus.startedAt === nextStatus.startedAt &&
+        prevStatus.completedAt === nextStatus.completedAt &&
+        prevStatus.runnerId === nextStatus.runnerId;
+    if (messagesUnchanged &&
+        subAgentsUnchanged &&
+        approvalsUnchanged &&
+        todosUnchanged &&
+        statusFieldsUnchanged &&
+        prevStatus.artifacts.length === nextStatus.artifacts.length &&
+        prevStatus.workspaceWriteBacks.length ===
+            nextStatus.workspaceWriteBacks.length) {
+        return prev;
+    }
+    const sharedStatus = Object.create(Object.getPrototypeOf(nextStatus));
+    Object.assign(sharedStatus, nextStatus);
+    sharedStatus.messages = sharedMessages;
+    sharedStatus.subAgentExecutions = sharedSubAgents;
+    sharedStatus.pendingApprovals = sharedApprovals;
+    sharedStatus.todos = sharedTodos;
+    const sharedExec = Object.create(Object.getPrototypeOf(next));
+    Object.assign(sharedExec, next);
+    sharedExec.status = sharedStatus;
+    return sharedExec;
+}
+// ---------------------------------------------------------------------------
+// Messages — compare by index (append-only slots)
+// ---------------------------------------------------------------------------
+function shareMessages(prev, next) {
+    if (prev.length === 0 && next.length === 0)
+        return prev;
+    if (prev.length === 0)
+        return next;
+    let allSame = prev.length === next.length;
+    const result = new Array(next.length);
+    for (let i = 0; i < next.length; i++) {
+        if (i < prev.length && messageEqual(prev[i], next[i])) {
+            result[i] = prev[i];
+        }
+        else {
+            result[i] = shareToolCalls(i < prev.length ? prev[i] : null, next[i]);
+            allSame = false;
+        }
+    }
+    return allSame ? prev : result;
+}
+function messageEqual(a, b) {
+    return (a.type === b.type &&
+        a.content === b.content &&
+        a.isStreaming === b.isStreaming &&
+        a.timestamp === b.timestamp &&
+        a.toolCalls.length === b.toolCalls.length &&
+        toolCallsEqual(a.toolCalls, b.toolCalls));
+}
+function toolCallsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!toolCallEqual(a[i], b[i]))
+            return false;
+    }
+    return true;
+}
+/**
+ * When the message itself has changed, try to preserve unchanged
+ * tool call references within it. Returns a new message with the
+ * tool calls array potentially reusing old references.
+ */
+function shareToolCalls(prev, next) {
+    if (!prev || prev.toolCalls.length === 0 || next.toolCalls.length === 0) {
+        return next;
+    }
+    const prevById = new Map();
+    for (const tc of prev.toolCalls) {
+        if (tc.id)
+            prevById.set(tc.id, tc);
+    }
+    if (prevById.size === 0)
+        return next;
+    let allSame = prev.toolCalls.length === next.toolCalls.length;
+    const shared = new Array(next.toolCalls.length);
+    for (let i = 0; i < next.toolCalls.length; i++) {
+        const ntc = next.toolCalls[i];
+        const ptc = ntc.id ? prevById.get(ntc.id) : undefined;
+        if (ptc && toolCallEqual(ptc, ntc)) {
+            shared[i] = ptc;
+        }
+        else {
+            shared[i] = ntc;
+            allSame = false;
+        }
+    }
+    if (allSame)
+        return next;
+    const sharedMsg = Object.create(Object.getPrototypeOf(next));
+    Object.assign(sharedMsg, next);
+    sharedMsg.toolCalls = shared;
+    return sharedMsg;
+}
+function toolCallEqual(a, b) {
+    return (a.id === b.id &&
+        a.status === b.status &&
+        a.isStreaming === b.isStreaming &&
+        a.result === b.result &&
+        a.completedAt === b.completedAt &&
+        a.error === b.error &&
+        a.name === b.name &&
+        a.argsPreview === b.argsPreview);
+}
+// ---------------------------------------------------------------------------
+// Sub-agent executions — compare by `id`
+// ---------------------------------------------------------------------------
+function shareSubAgents(prev, next) {
+    if (prev.length === 0 && next.length === 0)
+        return prev;
+    if (prev.length === 0)
+        return next;
+    const prevById = new Map();
+    for (const sa of prev) {
+        if (sa.id)
+            prevById.set(sa.id, sa);
+    }
+    let allSame = prev.length === next.length;
+    const result = new Array(next.length);
+    for (let i = 0; i < next.length; i++) {
+        const nsa = next[i];
+        const psa = nsa.id ? prevById.get(nsa.id) : undefined;
+        if (psa && subAgentEqual(psa, nsa)) {
+            result[i] = psa;
+        }
+        else if (psa) {
+            result[i] = shareSubAgentMessages(psa, nsa);
+            allSame = false;
+        }
+        else {
+            result[i] = nsa;
+            allSame = false;
+        }
+    }
+    return allSame ? prev : result;
+}
+function subAgentEqual(a, b) {
+    return (a.id === b.id &&
+        a.status === b.status &&
+        a.output === b.output &&
+        a.error === b.error &&
+        a.completedAt === b.completedAt &&
+        a.messages.length === b.messages.length &&
+        a.subject === b.subject &&
+        subAgentMessagesEqual(a.messages, b.messages));
+}
+function subAgentMessagesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!messageEqual(a[i], b[i]))
+            return false;
+    }
+    return true;
+}
+function shareSubAgentMessages(prev, next) {
+    const sharedMsgs = shareMessages(prev.messages, next.messages);
+    if (sharedMsgs === prev.messages && subAgentEqual(prev, next)) {
+        return prev;
+    }
+    const shared = Object.create(Object.getPrototypeOf(next));
+    Object.assign(shared, next);
+    shared.messages = sharedMsgs;
+    return shared;
+}
+// ---------------------------------------------------------------------------
+// Pending approvals — compare by `toolCallId`
+// ---------------------------------------------------------------------------
+function shareApprovals(prev, next) {
+    if (prev.length === 0 && next.length === 0)
+        return prev;
+    if (prev.length !== next.length)
+        return next;
+    const prevById = new Map();
+    for (const a of prev) {
+        prevById.set(a.toolCallId, a);
+    }
+    for (const na of next) {
+        const pa = prevById.get(na.toolCallId);
+        if (!pa || !approvalEqual(pa, na))
+            return next;
+    }
+    return prev;
+}
+function approvalEqual(a, b) {
+    return (a.toolCallId === b.toolCallId &&
+        a.toolName === b.toolName &&
+        a.message === b.message &&
+        a.argsPreview === b.argsPreview &&
+        a.requestedAt === b.requestedAt &&
+        a.fromSubAgent === b.fromSubAgent);
+}
+// ---------------------------------------------------------------------------
+// Todos — compare by map key
+// ---------------------------------------------------------------------------
+function shareTodos(prev, next) {
+    const prevKeys = Object.keys(prev);
+    const nextKeys = Object.keys(next);
+    if (prevKeys.length === 0 && nextKeys.length === 0)
+        return prev;
+    if (prevKeys.length !== nextKeys.length)
+        return next;
+    for (const key of nextKeys) {
+        if (!(key in prev) || prev[key] !== next[key])
+            return next;
+    }
+    return prev;
+}
+//# sourceMappingURL=structural-share.js.map

package/internal/store/structural-share.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-share.js","sourceRoot":"","sources":["../../../src/internal/store/structural-share.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,IAA2B,EAC3B,IAAoB;IAEpB,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE/B,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IAC/B,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;IAE/B,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,cAAc,GAAG,aAAa,CAClC,UAAU,CAAC,QAAQ,EACnB,UAAU,CAAC,QAAQ,CACpB,CAAC;IACF,MAAM,eAAe,GAAG,cAAc,CACpC,UAAU,CAAC,kBAAkB,EAC7B,UAAU,CAAC,kBAAkB,CAC9B,CAAC;IACF,MAAM,eAAe,GAAG,cAAc,CACpC,UAAU,CAAC,gBAAgB,EAC3B,UAAU,CAAC,gBAAgB,CAC5B,CAAC;IACF,MAAM,WAAW,GAAG,UAAU,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAEnE,MAAM,iBAAiB,GAAG,cAAc,KAAK,UAAU,CAAC,QAAQ,CAAC;IACjE,MAAM,kBAAkB,GAAG,eAAe,KAAK,UAAU,CAAC,kBAAkB,CAAC;IAC7E,MAAM,kBAAkB,GAAG,eAAe,KAAK,UAAU,CAAC,gBAAgB,CAAC;IAC3E,MAAM,cAAc,GAAG,WAAW,KAAK,UAAU,CAAC,KAAK,CAAC;IAExD,MAAM,qBAAqB,GACzB,UAAU,CAAC,KAAK,KAAK,UAAU,CAAC,KAAK;QACrC,UAAU,CAAC,KAAK,KAAK,UAAU,CAAC,KAAK;QACrC,UAAU,CAAC,SAAS,KAAK,UAAU,CAAC,SAAS;QAC7C,UAAU,CAAC,WAAW,KAAK,UAAU,CAAC,WAAW;QACjD,UAAU,CAAC,QAAQ,KAAK,UAAU,CAAC,QAAQ,CAAC;IAE9C,IACE,iBAAiB;QACjB,kBAAkB;QAClB,kBAAkB;QAClB,cAAc;QACd,qBAAqB;QACrB,UAAU,CAAC,SAAS,CAAC,MAAM,KAAK,UAAU,CAAC,SAAS,CAAC,MAAM;QAC3D,UAAU,CAAC,mBAAmB,CAAC,MAAM;YACnC,UAAU,CAAC,mBAAmB,CAAC,MAAM,EACvC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IACtE,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IACxC,YAAY,CAAC,QAAQ,GAAG,cAAc,CAAC;IACvC,YAAY,CAAC,kBAAkB,GAAG,eAAe,CAAC;IAClD,YAAY,CAAC,gBAAgB,GAAG,eAAe,CAAC;IAChD,YAAY,CAAC,KAAK,GAAG,WAAW,CAAC;IAEjC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9D,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAChC,UAAU,CAAC,MAAM,GAAG,YAAY,CAAC;IAEjC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,kDAAkD;AAClD,8EAA8E;AAE9E,SAAS,aAAa,CACpB,IAA6B,EAC7B,IAA6B;IAE7B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,IAAI,OAAO,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;IAC1C,MAAM,MAAM,GAAmB,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAEtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,CAAC,CAAC,GAAG,cAAc,CACxB,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAChC,IAAI,CAAC,CAAC,CAAC,CACR,CAAC;YACF,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AACjC,CAAC;AAED,SAAS,YAAY,CAAC,CAAe,EAAE,CAAe;IACpD,OAAO,CACL,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;QACvB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS;QAC3B,CAAC,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM;QACzC,cAAc,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CACzC,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,CAAsB,EACtB,CAAsB;IAEtB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CACrB,IAAyB,EACzB,IAAkB;IAElB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAoB,CAAC;IAC7C,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,IAAI,EAAE,CAAC,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAErC,IAAI,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;IAC9D,MAAM,MAAM,GAAe,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAE5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEtD,IAAI,GAAG,IAAI,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;YAChB,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC;IAED,IAAI,OAAO;QAAE,OAAO,IAAI,CAAC;IAEzB,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/B,SAAS,CAAC,SAAS,GAAG,MAAM,CAAC;IAC7B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,aAAa,CAAC,CAAW,EAAE,CAAW;IAC7C,OAAO,CACL,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE;QACb,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QACrB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QACrB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;QACnB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QACjB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW,CAChC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,yCAAyC;AACzC,8EAA8E;AAE9E,SAAS,cAAc,CACrB,IAAkC,EAClC,IAAkC;IAElC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA6B,CAAC;IACtD,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,EAAE,CAAC,EAAE;YAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,OAAO,GAAG,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;IAC1C,MAAM,MAAM,GAAwB,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAE3D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEtD,IAAI,GAAG,IAAI,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;QAClB,CAAC;aAAM,IAAI,GAAG,EAAE,CAAC;YACf,MAAM,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC5C,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;YAChB,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AACjC,CAAC;AAED,SAAS,aAAa,CAAC,CAAoB,EAAE,CAAoB;IAC/D,OAAO,CACL,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE;QACb,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QACrB,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QACrB,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;QACnB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM;QACvC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;QACvB,qBAAqB,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAC5B,CAA0B,EAC1B,CAA0B;IAE1B,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IAC9C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,qBAAqB,CAC5B,IAAuB,EACvB,IAAuB;IAEvB,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/D,IAAI,UAAU,KAAK,IAAI,CAAC,QAAQ,IAAI,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC5B,MAAM,CAAC,QAAQ,GAAG,UAAU,CAAC;IAC7B,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,8CAA8C;AAC9C,8EAA8E;AAE9E,SAAS,cAAc,CACrB,IAAgC,EAChC,IAAgC;IAEhC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAE7C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IACpD,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,CAAC,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;IACjD,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,aAAa,CAAC,CAAkB,EAAE,CAAkB;IAC3D,OAAO,CACL,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;QAC7B,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QACzB,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;QACvB,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;QAC/B,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,YAAY,CAClC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E,SAAS,UAAU,CACjB,IAA6B,EAC7B,IAA6B;IAE7B,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEnC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAErD,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IAC7D,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/internal/stream-controller.d.ts

@@ -0,0 +1,85 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+export type ControllerStage = "idle" | "connecting" | "streaming" | "complete" | "error";
+export type ControllerState = {
+    readonly stage: "idle";
+} | {
+    readonly stage: "connecting";
+    readonly executionId: string;
+} | {
+    readonly stage: "streaming";
+    readonly executionId: string;
+} | {
+    readonly stage: "complete";
+    readonly executionId: string;
+} | {
+    readonly stage: "error";
+    readonly executionId: string;
+    readonly error: Error;
+};
+/**
+ * Callback interface for the stream controller to communicate with
+ * its host (the React hook). All mutations to external state go
+ * through these callbacks.
+ */
+export interface StreamControllerSink {
+    /** Ingest a snapshot into the store (applies structural sharing). */
+    ingestSnapshot(snapshot: AgentExecution): void;
+    /** Transition the store's stream lifecycle state. */
+    setStreamState(state: ControllerState): void;
+}
+/**
+ * Framework-agnostic finite state machine that manages the lifecycle
+ * of a single execution stream subscription.
+ *
+ * Responsibilities:
+ * - Track FSM state transitions (idle → connecting → streaming → complete/error)
+ * - Buffer incoming snapshots and coalesce via `requestAnimationFrame`
+ * - Flush terminal snapshots immediately (no rAF delay)
+ * - Provide abort/reconnect semantics
+ *
+ * This class has no React dependency. It communicates outward through
+ * a {@link StreamControllerSink} and a `scheduleFlush` function
+ * (typically `requestAnimationFrame`).
+ */
+export declare class StreamController {
+    private _state;
+    private _bufferedSnapshot;
+    private _rafId;
+    private _sink;
+    private _scheduleFlush;
+    private _cancelFlush;
+    constructor(sink: StreamControllerSink, scheduleFlush?: (cb: () => void) => number, cancelFlush?: (id: number) => void);
+    /** Current FSM state (read-only). */
+    get state(): ControllerState;
+    /**
+     * Transition to `connecting` for the given execution ID.
+     * If already active for a different ID, resets first.
+     */
+    start(executionId: string): void;
+    /**
+     * Handle an incoming snapshot from the gRPC stream.
+     * Non-terminal snapshots are buffered for rAF coalescing.
+     * Terminal snapshots flush immediately.
+     */
+    handleSnapshot(snapshot: AgentExecution): void;
+    /**
+     * Handle stream completion (iterator exhausted without error).
+     * If we still have a buffered snapshot, flush it first.
+     */
+    handleStreamEnd(): void;
+    /**
+     * Handle a stream error. Flushes any buffered snapshot first
+     * so the UI shows the last known good state alongside the error.
+     */
+    handleError(error: Error): void;
+    /** Reset to idle. Cancels any pending flush. */
+    reset(): void;
+    /** Whether the controller has a buffered snapshot awaiting flush. */
+    get hasPendingFlush(): boolean;
+    private _activeExecutionId;
+    private _transition;
+    private _scheduleFlushOnce;
+    private _flushBuffer;
+    private _cancelPendingFlush;
+}
+//# sourceMappingURL=stream-controller.d.ts.map

package/internal/stream-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-controller.d.ts","sourceRoot":"","sources":["../../src/internal/stream-controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AASlG,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,YAAY,GACZ,WAAW,GACX,UAAU,GACV,OAAO,CAAC;AAEZ,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC5D;IACE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB,CAAC;AAIN;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/C,qDAAqD;IACrD,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC9C;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,iBAAiB,CAA+B;IACxD,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,cAAc,CAA6B;IACnD,OAAO,CAAC,YAAY,CAAuB;gBAGzC,IAAI,EAAE,oBAAoB,EAC1B,aAAa,GAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAEgB,EACnD,WAAW,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAEb;IAOlB,qCAAqC;IACrC,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED;;;OAGG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMhC;;;;OAIG;IACH,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAsB9C;;;OAGG;IACH,eAAe,IAAI,IAAI;IAUvB;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAS/B,gDAAgD;IAChD,KAAK,IAAI,IAAI;IAQb,qEAAqE;IACrE,IAAI,eAAe,IAAI,OAAO,CAE7B;IAMD,OAAO,CAAC,kBAAkB;IAK1B,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,kBAAkB;IAQ1B,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,mBAAmB;CAM5B"}

package/internal/stream-controller.js

@@ -0,0 +1,146 @@
+import { isTerminalPhase } from "../execution/execution-phases";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+const IDLE = { stage: "idle" };
+// ---------------------------------------------------------------------------
+// StreamController
+// ---------------------------------------------------------------------------
+/**
+ * Framework-agnostic finite state machine that manages the lifecycle
+ * of a single execution stream subscription.
+ *
+ * Responsibilities:
+ * - Track FSM state transitions (idle → connecting → streaming → complete/error)
+ * - Buffer incoming snapshots and coalesce via `requestAnimationFrame`
+ * - Flush terminal snapshots immediately (no rAF delay)
+ * - Provide abort/reconnect semantics
+ *
+ * This class has no React dependency. It communicates outward through
+ * a {@link StreamControllerSink} and a `scheduleFlush` function
+ * (typically `requestAnimationFrame`).
+ */
+export class StreamController {
+    _state = IDLE;
+    _bufferedSnapshot = null;
+    _rafId = null;
+    _sink;
+    _scheduleFlush;
+    _cancelFlush;
+    constructor(sink, scheduleFlush = typeof requestAnimationFrame !== "undefined"
+        ? requestAnimationFrame
+        : (cb) => setTimeout(cb, 16), cancelFlush = typeof cancelAnimationFrame !== "undefined"
+        ? cancelAnimationFrame
+        : clearTimeout) {
+        this._sink = sink;
+        this._scheduleFlush = scheduleFlush;
+        this._cancelFlush = cancelFlush;
+    }
+    /** Current FSM state (read-only). */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Transition to `connecting` for the given execution ID.
+     * If already active for a different ID, resets first.
+     */
+    start(executionId) {
+        this._cancelPendingFlush();
+        this._bufferedSnapshot = null;
+        this._transition({ stage: "connecting", executionId });
+    }
+    /**
+     * Handle an incoming snapshot from the gRPC stream.
+     * Non-terminal snapshots are buffered for rAF coalescing.
+     * Terminal snapshots flush immediately.
+     */
+    handleSnapshot(snapshot) {
+        const executionId = this._activeExecutionId();
+        if (!executionId)
+            return;
+        const phase = snapshot.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+        const terminal = isTerminalPhase(phase);
+        if (terminal) {
+            this._cancelPendingFlush();
+            this._bufferedSnapshot = null;
+            this._sink.ingestSnapshot(snapshot);
+            this._transition({ stage: "complete", executionId });
+        }
+        else {
+            if (this._state.stage === "connecting") {
+                this._transition({ stage: "streaming", executionId });
+            }
+            this._bufferedSnapshot = snapshot;
+            this._scheduleFlushOnce();
+        }
+    }
+    /**
+     * Handle stream completion (iterator exhausted without error).
+     * If we still have a buffered snapshot, flush it first.
+     */
+    handleStreamEnd() {
+        const executionId = this._activeExecutionId();
+        if (!executionId)
+            return;
+        this._flushBuffer();
+        if (this._state.stage !== "complete") {
+            this._transition({ stage: "complete", executionId });
+        }
+    }
+    /**
+     * Handle a stream error. Flushes any buffered snapshot first
+     * so the UI shows the last known good state alongside the error.
+     */
+    handleError(error) {
+        const executionId = this._activeExecutionId();
+        if (!executionId)
+            return;
+        this._cancelPendingFlush();
+        this._flushBuffer();
+        this._transition({ stage: "error", executionId, error });
+    }
+    /** Reset to idle. Cancels any pending flush. */
+    reset() {
+        this._cancelPendingFlush();
+        this._bufferedSnapshot = null;
+        if (this._state.stage !== "idle") {
+            this._transition(IDLE);
+        }
+    }
+    /** Whether the controller has a buffered snapshot awaiting flush. */
+    get hasPendingFlush() {
+        return this._rafId !== null;
+    }
+    // -------------------------------------------------------------------------
+    // Private
+    // -------------------------------------------------------------------------
+    _activeExecutionId() {
+        if (this._state.stage === "idle")
+            return null;
+        return this._state.executionId;
+    }
+    _transition(next) {
+        this._state = next;
+        this._sink.setStreamState(next);
+    }
+    _scheduleFlushOnce() {
+        if (this._rafId !== null)
+            return;
+        this._rafId = this._scheduleFlush(() => {
+            this._rafId = null;
+            this._flushBuffer();
+        });
+    }
+    _flushBuffer() {
+        if (this._bufferedSnapshot) {
+            const snap = this._bufferedSnapshot;
+            this._bufferedSnapshot = null;
+            this._sink.ingestSnapshot(snap);
+        }
+    }
+    _cancelPendingFlush() {
+        if (this._rafId !== null) {
+            this._cancelFlush(this._rafId);
+            this._rafId = null;
+        }
+    }
+}
+//# sourceMappingURL=stream-controller.js.map

package/internal/stream-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-controller.js","sourceRoot":"","sources":["../../src/internal/stream-controller.ts"],"names":[],"mappings":"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"}

package/internal/useAutoScroll.d.ts

@@ -0,0 +1,32 @@
+export interface UseAutoScrollReturn {
+    /** Attach to the scrollable container. */
+    readonly scrollRef: React.RefObject<HTMLDivElement | null>;
+    /** Attach to a zero-height div as the last child of the scroll container. */
+    readonly sentinelRef: React.RefObject<HTMLDivElement | null>;
+    /** Attach to a wrapper div around the thread content (ResizeObserver target). */
+    readonly contentRef: React.RefObject<HTMLDivElement | null>;
+    /** True when the thread auto-scrolls to follow new content. */
+    readonly isFollowing: boolean;
+    /** Scroll to the latest content and re-engage follow mode. */
+    readonly jumpToLatest: () => void;
+}
+/**
+ * Two-state auto-scroll state machine for chat threads.
+ *
+ * **Following** — content is pinned to the bottom; new content
+ * (streaming tokens, new messages, tool panel expansion) triggers a
+ * `requestAnimationFrame`-batched scroll-to-bottom.
+ *
+ * **Disengaged** — the user scrolled away from the bottom; no
+ * automatic scrolling occurs. Call {@link UseAutoScrollReturn.jumpToLatest}
+ * to re-engage.
+ *
+ * State transitions are driven by an `IntersectionObserver` on a
+ * bottom sentinel element. A `ResizeObserver` on the content wrapper
+ * detects height growth and triggers rAF-batched scroll writes when
+ * in the Following state.
+ *
+ * @internal Not part of the public API.
+ */
+export declare function useAutoScroll(): UseAutoScrollReturn;
+//# sourceMappingURL=useAutoScroll.d.ts.map

package/internal/useAutoScroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAutoScroll.d.ts","sourceRoot":"","sources":["../../src/internal/useAutoScroll.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC3D,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC7D,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC5D,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,IAAI,mBAAmB,CA6EnD"}

package/internal/useAutoScroll.js

@@ -0,0 +1,97 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+/**
+ * Near-bottom tolerance in pixels. The sentinel is considered visible
+ * (and follow mode stays engaged) when the user is within this distance
+ * of the bottom. Matches the threshold used by the previous scroll
+ * implementation.
+ */
+const NEAR_BOTTOM_MARGIN_PX = 80;
+/**
+ * Two-state auto-scroll state machine for chat threads.
+ *
+ * **Following** — content is pinned to the bottom; new content
+ * (streaming tokens, new messages, tool panel expansion) triggers a
+ * `requestAnimationFrame`-batched scroll-to-bottom.
+ *
+ * **Disengaged** — the user scrolled away from the bottom; no
+ * automatic scrolling occurs. Call {@link UseAutoScrollReturn.jumpToLatest}
+ * to re-engage.
+ *
+ * State transitions are driven by an `IntersectionObserver` on a
+ * bottom sentinel element. A `ResizeObserver` on the content wrapper
+ * detects height growth and triggers rAF-batched scroll writes when
+ * in the Following state.
+ *
+ * @internal Not part of the public API.
+ */
+export function useAutoScroll() {
+    const scrollRef = useRef(null);
+    const sentinelRef = useRef(null);
+    const contentRef = useRef(null);
+    const [isFollowing, setIsFollowing] = useState(true);
+    const isFollowingRef = useRef(true);
+    const rafIdRef = useRef(0);
+    // Keep ref in sync with state so observer callbacks read the latest
+    // value without re-subscribing on every state change.
+    useEffect(() => {
+        isFollowingRef.current = isFollowing;
+    }, [isFollowing]);
+    // --- IntersectionObserver: sentinel visibility drives state ---
+    useEffect(() => {
+        const sentinel = sentinelRef.current;
+        const scroller = scrollRef.current;
+        if (!sentinel || !scroller)
+            return;
+        // Establish initial position at the bottom so the first IO
+        // callback sees the sentinel as intersecting.
+        scroller.scrollTop = scroller.scrollHeight;
+        const io = new IntersectionObserver((entries) => {
+            const entry = entries[0];
+            if (!entry)
+                return;
+            const visible = entry.isIntersecting;
+            isFollowingRef.current = visible;
+            setIsFollowing(visible);
+        }, {
+            root: scroller,
+            rootMargin: `0px 0px ${NEAR_BOTTOM_MARGIN_PX}px 0px`,
+            threshold: 0,
+        });
+        io.observe(sentinel);
+        return () => io.disconnect();
+    }, []);
+    // --- ResizeObserver: scroll on content height growth while following ---
+    useEffect(() => {
+        const content = contentRef.current;
+        if (!content || !scrollRef.current)
+            return;
+        const ro = new ResizeObserver(() => {
+            if (!isFollowingRef.current)
+                return;
+            cancelAnimationFrame(rafIdRef.current);
+            rafIdRef.current = requestAnimationFrame(() => {
+                const el = scrollRef.current;
+                if (el)
+                    el.scrollTop = el.scrollHeight;
+            });
+        });
+        ro.observe(content);
+        return () => {
+            ro.disconnect();
+            cancelAnimationFrame(rafIdRef.current);
+        };
+    }, []);
+    const jumpToLatest = useCallback(() => {
+        const el = scrollRef.current;
+        if (!el)
+            return;
+        el.scrollTop = el.scrollHeight;
+        // Eagerly set following — IO callback will confirm when the
+        // sentinel becomes visible after the scroll.
+        isFollowingRef.current = true;
+        setIsFollowing(true);
+    }, []);
+    return { scrollRef, sentinelRef, contentRef, isFollowing, jumpToLatest };
+}
+//# sourceMappingURL=useAutoScroll.js.map

package/internal/useAutoScroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAutoScroll.js","sourceRoot":"","sources":["../../src/internal/useAutoScroll.ts"],"names":[],"mappings":"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"}