@jini-ai/chat 0.1.0

package/dist/react/hooks/context.js

@@ -0,0 +1,60 @@
+/**
+ * @module context
+ *
+ * The context objects `<JiniChatProvider>` (see
+ * `../components/JiniChatProvider.js`) wires up, plus the `use*` accessor
+ * hooks every presentational component in this package reads instead of
+ * taking these as prop-drilled arguments. Split out from the provider
+ * component itself so pure consumer hooks (`useT`, `useProjectContext`, ...)
+ * don't need to import the composition-root component.
+ *
+ * Every context defaults to a safe no-op/passthrough so a component can be
+ * unit-tested standalone (no `<JiniChatProvider>` mounted) — mirrors
+ * `@jini-ai/ui`'s `useI18n`/`useT` passthrough convention, reimplemented
+ * locally here since `@jini-ai/chat-react` cannot depend on `@jini-ai/ui` (not an
+ * allowed dependency per `ADS-memory/reports/jini-port/recon/r4b-webui-design.md` §1).
+ */
+import { createContext, useContext } from 'react';
+const PASSTHROUGH_I18N = {
+    t: (key, vars) => interpolate(key, vars),
+    locale: 'en',
+};
+function interpolate(template, vars) {
+    if (!vars)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (_match, name) => {
+        const value = vars[name];
+        return value === undefined ? `{${name}}` : String(value);
+    });
+}
+const NOOP_ANALYTICS = { track: () => { } };
+export const I18nContext = createContext(PASSTHROUGH_I18N);
+export const AnalyticsContext = createContext(NOOP_ANALYTICS);
+export const ProjectContext = createContext(undefined);
+export const ChatTransportContext = createContext(undefined);
+export const ArtifactRegistryContext = createContext(undefined);
+/** Convenience for call sites that only need the translator function. */
+export function useT() {
+    return useContext(I18nContext).t;
+}
+export function useI18n() {
+    return useContext(I18nContext);
+}
+export function useAnalytics() {
+    return useContext(AnalyticsContext);
+}
+/** `undefined` when no `<JiniChatProvider project={...}>` is mounted — components must treat project-dependent affordances (file links, uploads) as unavailable rather than throwing. */
+export function useProjectContext() {
+    return useContext(ProjectContext);
+}
+/** Throws when read outside `<JiniChatProvider>` — unlike the other contexts, hooks that need a transport (`useConversation`/`useRunStream`) have no sensible no-op fallback. */
+export function useChatTransport() {
+    const transport = useContext(ChatTransportContext);
+    if (!transport)
+        throw new Error('useChatTransport() must be called within <JiniChatProvider transport={...}>');
+    return transport;
+}
+export function useArtifactRegistry() {
+    return useContext(ArtifactRegistryContext);
+}
+//# sourceMappingURL=context.js.map

package/dist/react/hooks/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/react/hooks/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAKlD,MAAM,gBAAgB,GAAgB;IACpC,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC;IACxC,MAAM,EAAE,IAAI;CACb,CAAC;AAEF,SAAS,WAAW,CAAC,QAAgB,EAAE,IAAiD;IACtF,IAAI,CAAC,IAAI;QAAE,OAAO,QAAQ,CAAC;IAC3B,OAAO,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,cAAc,GAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;AAE7D,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAc,gBAAgB,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAmB,cAAc,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAkC,SAAS,CAAC,CAAC;AACxF,MAAM,CAAC,MAAM,oBAAoB,GAAG,aAAa,CAA4B,SAAS,CAAC,CAAC;AACxF,MAAM,CAAC,MAAM,uBAAuB,GAAG,aAAa,CAA+B,SAAS,CAAC,CAAC;AAE9F,yEAAyE;AACzE,MAAM,UAAU,IAAI;IAClB,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,OAAO;IACrB,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACtC,CAAC;AAED,yLAAyL;AACzL,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC,cAAc,CAAC,CAAC;AACpC,CAAC;AAED,iLAAiL;AACjL,MAAM,UAAU,gBAAgB;IAC9B,MAAM,SAAS,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACnD,IAAI,CAAC,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,6EAA6E,CAAC,CAAC;IAC/G,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO,UAAU,CAAC,uBAAuB,CAAC,CAAC;AAC7C,CAAC"}

package/dist/react/hooks/testing/fake-transport.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A hand-written `ChatTransport` fake for this package's own hook/component
+ * tests — no global mocking, per the DI-seam discipline the OD slices use
+ * (`dependencies.ts` binds a fake, never a jest/vitest module mock). Not
+ * exported from the package's public barrel; import via the relative test
+ * path (`../testing/fake-transport.js`).
+ */
+import type { AgentEvent } from '../../../core/index.js';
+import type { ChatTransport, RunHandlers, StartRunInput } from '../../../core/index.js';
+export interface FakeTransportCall {
+    input: StartRunInput;
+    handlers: RunHandlers;
+}
+export interface FakeChatTransport extends ChatTransport {
+    /** Every `startRun` call, in order — inspect to drive/assert scripted event emission. */
+    calls: FakeTransportCall[];
+    reattachCalls: {
+        runId: string;
+        handlers: RunHandlers;
+    }[];
+    stoppedRunIds: string[];
+    /** Emits `ev` to the most recent call's handlers. */
+    emit: (ev: AgentEvent) => void;
+    /** Emits a live tool-input delta to the most recent call's handlers. */
+    emitToolInputDelta: (id: string, name: string, delta: string) => void;
+    /** Finishes the most recent run successfully with `finalEvents` (defaults to whatever was emitted so far). */
+    finish: (finalEvents?: AgentEvent[]) => void;
+    fail: (err: Error) => void;
+    nextRunId: () => string;
+}
+export declare function createFakeChatTransport(options?: {
+    runIdPrefix?: string;
+}): FakeChatTransport;
+//# sourceMappingURL=fake-transport.d.ts.map

package/dist/react/hooks/testing/fake-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-transport.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks/testing/fake-transport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAExF,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,yFAAyF;IACzF,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,aAAa,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,EAAE,CAAC;IAC1D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,qDAAqD;IACrD,IAAI,EAAE,CAAC,EAAE,EAAE,UAAU,KAAK,IAAI,CAAC;IAC/B,wEAAwE;IACxE,kBAAkB,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtE,8GAA8G;IAC9G,MAAM,EAAE,CAAC,WAAW,CAAC,EAAE,UAAU,EAAE,KAAK,IAAI,CAAC;IAC7C,IAAI,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,iBAAiB,CA8CjG"}

package/dist/react/hooks/testing/fake-transport.js

@@ -0,0 +1,46 @@
+export function createFakeChatTransport(options = {}) {
+    const prefix = options.runIdPrefix ?? 'run';
+    let counter = 0;
+    const calls = [];
+    const reattachCalls = [];
+    const stoppedRunIds = [];
+    let accumulated = [];
+    function currentHandlers() {
+        return calls[calls.length - 1]?.handlers ?? reattachCalls[reattachCalls.length - 1]?.handlers;
+    }
+    return {
+        calls,
+        reattachCalls,
+        stoppedRunIds,
+        nextRunId: () => `${prefix}-${counter + 1}`,
+        async startRun(input, handlers) {
+            counter += 1;
+            accumulated = [];
+            calls.push({ input, handlers });
+            return { runId: `${prefix}-${counter}` };
+        },
+        async reattachRun(runId, handlers) {
+            reattachCalls.push({ runId, handlers });
+        },
+        async fetchRunStatus() {
+            return null;
+        },
+        async stopRun(runId) {
+            stoppedRunIds.push(runId);
+        },
+        emit(ev) {
+            accumulated = [...accumulated, ev];
+            currentHandlers()?.onEvent(ev);
+        },
+        emitToolInputDelta(id, name, delta) {
+            currentHandlers()?.onToolInputDelta?.(id, name, delta);
+        },
+        finish(finalEvents) {
+            currentHandlers()?.onDone(finalEvents ?? accumulated);
+        },
+        fail(err) {
+            currentHandlers()?.onError(err);
+        },
+    };
+}
+//# sourceMappingURL=fake-transport.js.map

package/dist/react/hooks/testing/fake-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-transport.js","sourceRoot":"","sources":["../../../../src/react/hooks/testing/fake-transport.ts"],"names":[],"mappings":"AA8BA,MAAM,UAAU,uBAAuB,CAAC,UAAoC,EAAE;IAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,IAAI,KAAK,CAAC;IAC5C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,KAAK,GAAwB,EAAE,CAAC;IACtC,MAAM,aAAa,GAA+C,EAAE,CAAC;IACrE,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,IAAI,WAAW,GAAiB,EAAE,CAAC;IAEnC,SAAS,eAAe;QACtB,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,QAAQ,IAAI,aAAa,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC;IAChG,CAAC;IAED,OAAO;QACL,KAAK;QACL,aAAa;QACb,aAAa;QACb,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,IAAI,OAAO,GAAG,CAAC,EAAE;QAC3C,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ;YAC5B,OAAO,IAAI,CAAC,CAAC;YACb,WAAW,GAAG,EAAE,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;YAChC,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,OAAO,EAAE,EAAE,CAAC;QAC3C,CAAC;QACD,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,QAAQ;YAC/B,aAAa,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,KAAK,CAAC,cAAc;YAClB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5B,CAAC;QACD,IAAI,CAAC,EAAE;YACL,WAAW,GAAG,CAAC,GAAG,WAAW,EAAE,EAAE,CAAC,CAAC;YACnC,eAAe,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACjC,CAAC;QACD,kBAAkB,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK;YAChC,eAAe,EAAE,EAAE,gBAAgB,EAAE,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,CAAC,WAAW;YAChB,eAAe,EAAE,EAAE,MAAM,CAAC,WAAW,IAAI,WAAW,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,GAAG;YACN,eAAe,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/react/hooks/useArtifactStream.d.ts

@@ -0,0 +1,18 @@
+import type { ArtifactFile, ArtifactRenderMatch, RendererRegistry } from '../artifact-types.js';
+export interface ArtifactStreamItem {
+    identifier: string;
+    artifactType: string;
+    title: string;
+    content: string;
+    status: 'streaming' | 'complete';
+    file: ArtifactFile;
+    match: ArtifactRenderMatch | null;
+}
+export interface UseArtifactStreamResult {
+    /** Every artifact found in `content`, oldest first. */
+    items: ArtifactStreamItem[];
+    /** The last item — the one most likely to be "the artifact this turn produced". */
+    current: ArtifactStreamItem | null;
+}
+export declare function useArtifactStream(content: string, registry?: RendererRegistry): UseArtifactStreamResult;
+//# sourceMappingURL=useArtifactStream.d.ts.map

package/dist/react/hooks/useArtifactStream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useArtifactStream.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useArtifactStream.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEhG,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,WAAW,GAAG,UAAU,CAAC;IACjC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,uDAAuD;IACvD,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,mFAAmF;IACnF,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACpC;AAMD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,uBAAuB,CAoCvG"}

package/dist/react/hooks/useArtifactStream.js

@@ -0,0 +1,55 @@
+/**
+ * @module useArtifactStream
+ *
+ * Streaming artifact buffer + resolved renderer + partial-vs-complete state,
+ * built purely over a message's text content via `@jini-ai/chat/core`'s
+ * `parseArtifacts` (completed `<artifact>` blocks) and `splitStreamingArtifact`
+ * (the currently in-flight one, if any) plus an injected `RendererRegistry`.
+ * Per `ADS-memory/reports/jini-port/recon/r4b-webui-design.md` §4.
+ *
+ * `ArtifactFile`/`ArtifactRenderer`/`RendererRegistry` are the local
+ * placeholder shapes from `../../artifact-types.js` — see that file's
+ * TODO(renderers-react) header for the follow-up to re-point this hook at
+ * `@jini-ai/renderers-react`'s real exports.
+ */
+import { useMemo } from 'react';
+import { parseArtifacts, splitStreamingArtifact } from '../../core/index.js';
+function toFile(item) {
+    return { name: item.identifier || item.title || 'artifact', kind: item.artifactType, content: item.content };
+}
+export function useArtifactStream(content, registry) {
+    return useMemo(() => {
+        const items = [];
+        // `splitStreamingArtifact` is the authority on "is there a trailing,
+        // still-open artifact": split first so `parseArtifacts` (a one-shot
+        // feed+flush that synthesizes an `artifact:end` for whatever is still
+        // open when it's called — correct for a genuinely complete message, but
+        // wrong here) only ever sees the CLOSED-artifact-only `head` portion.
+        // Running it on the raw `content` would double-count a live artifact:
+        // once (wrongly) as "complete" via the synthetic flush, and again (correctly)
+        // as "streaming" below.
+        const { head, live } = splitStreamingArtifact(content);
+        let current = null;
+        for (const ev of parseArtifacts(head)) {
+            if (ev.type === 'artifact:start') {
+                current = { identifier: ev.identifier, artifactType: ev.artifactType, title: ev.title, content: '' };
+            }
+            else if (ev.type === 'artifact:chunk' && current && current.identifier === ev.identifier) {
+                current.content += ev.delta;
+            }
+            else if (ev.type === 'artifact:end' && current && current.identifier === ev.identifier) {
+                const finished = { ...current, content: ev.fullContent, status: 'complete' };
+                items.push({ ...finished, file: toFile(finished), match: registry?.resolve({ file: toFile(finished) }) ?? null });
+                current = null;
+            }
+        }
+        // A trailing artifact whose close tag hasn't streamed in yet — surfaced
+        // separately so a live preview can render mid-generation.
+        if (live) {
+            const streaming = { identifier: live.identifier, artifactType: live.artifactType, title: live.title, content: live.content, status: 'streaming' };
+            items.push({ ...streaming, file: toFile(streaming), match: registry?.resolve({ file: toFile(streaming) }) ?? null });
+        }
+        return { items, current: items.length > 0 ? items[items.length - 1] : null };
+    }, [content, registry]);
+}
+//# sourceMappingURL=useArtifactStream.js.map

package/dist/react/hooks/useArtifactStream.js.map

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

package/dist/react/hooks/useChatFabDrag.d.ts

@@ -0,0 +1,25 @@
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+/** Movement below this is a click, not a drag. Roughly the slop of a deliberate tap. */
+export declare const CHAT_FAB_DRAG_THRESHOLD_PX = 4;
+/** Keeps the button fully on screen with a small margin. */
+export declare const CHAT_FAB_EDGE_MARGIN_PX = 8;
+export interface ChatFabPosition {
+    readonly x: number;
+    readonly y: number;
+}
+export interface UseChatFabDragResult {
+    buttonRef: RefObject<HTMLButtonElement | null>;
+    /** `null` until first drag: the button sits wherever CSS puts it, so it stays responsive. */
+    position: ChatFabPosition | null;
+    onPointerDown: (event: ReactPointerEvent<HTMLButtonElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<HTMLButtonElement>) => void;
+    onPointerUp: (event: ReactPointerEvent<HTMLButtonElement>) => void;
+    onPointerCancel: (event: ReactPointerEvent<HTMLButtonElement>) => void;
+}
+/** Keeps a dragged position fully on screen, re-clamped on drag and on viewport resize. */
+export declare function clampChatFabToViewport(position: ChatFabPosition, size: {
+    width: number;
+    height: number;
+}): ChatFabPosition;
+export declare function useChatFabDrag(onClick: () => void): UseChatFabDragResult;
+//# sourceMappingURL=useChatFabDrag.d.ts.map

package/dist/react/hooks/useChatFabDrag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatFabDrag.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useChatFabDrag.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,IAAI,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAE1E,wFAAwF;AACxF,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/C,6FAA6F;IAC7F,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IACrE,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IACrE,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IACnE,eAAe,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;CACxE;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC,eAAe,CAOjB;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,oBAAoB,CAkExE"}

package/dist/react/hooks/useChatFabDrag.js

@@ -0,0 +1,88 @@
+/**
+ * @module useChatFabDrag
+ *
+ * Drag and click share one pointer gesture, so the two have to be told apart: a press that moves
+ * less than {@link CHAT_FAB_DRAG_THRESHOLD_PX} is a click, anything more is a drag and does not
+ * fire `onClick`. Without that, every drag would also fire the click on release. Position is
+ * clamped to the viewport on drag and re-clamped on resize, because a button dragged to the right
+ * edge of a wide window is off-screen and unreachable in a narrower one.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+/** Movement below this is a click, not a drag. Roughly the slop of a deliberate tap. */
+export const CHAT_FAB_DRAG_THRESHOLD_PX = 4;
+/** Keeps the button fully on screen with a small margin. */
+export const CHAT_FAB_EDGE_MARGIN_PX = 8;
+/** Keeps a dragged position fully on screen, re-clamped on drag and on viewport resize. */
+export function clampChatFabToViewport(position, size) {
+    const maxX = Math.max(CHAT_FAB_EDGE_MARGIN_PX, globalThis.innerWidth - size.width - CHAT_FAB_EDGE_MARGIN_PX);
+    const maxY = Math.max(CHAT_FAB_EDGE_MARGIN_PX, globalThis.innerHeight - size.height - CHAT_FAB_EDGE_MARGIN_PX);
+    return {
+        x: Math.min(Math.max(position.x, CHAT_FAB_EDGE_MARGIN_PX), maxX),
+        y: Math.min(Math.max(position.y, CHAT_FAB_EDGE_MARGIN_PX), maxY),
+    };
+}
+export function useChatFabDrag(onClick) {
+    const buttonRef = useRef(null);
+    const [position, setPosition] = useState(null);
+    const drag = useRef(null);
+    useEffect(() => {
+        const onResize = () => {
+            const element = buttonRef.current;
+            if (!element)
+                return;
+            setPosition((current) => (current === null
+                ? null
+                : clampChatFabToViewport(current, { width: element.offsetWidth, height: element.offsetHeight })));
+        };
+        globalThis.addEventListener('resize', onResize);
+        return () => globalThis.removeEventListener('resize', onResize);
+    }, []);
+    const onPointerDown = useCallback((event) => {
+        const element = event.currentTarget;
+        const rect = element.getBoundingClientRect();
+        element.setPointerCapture(event.pointerId);
+        drag.current = {
+            pointerId: event.pointerId,
+            // Offset within the button, so it does not jump to centre itself under the cursor.
+            offsetX: event.clientX - rect.left,
+            offsetY: event.clientY - rect.top,
+            moved: false,
+        };
+    }, []);
+    const onPointerMove = useCallback((event) => {
+        const state = drag.current;
+        if (state === null || state.pointerId !== event.pointerId)
+            return;
+        const element = event.currentTarget;
+        const next = clampChatFabToViewport({ x: event.clientX - state.offsetX, y: event.clientY - state.offsetY }, { width: element.offsetWidth, height: element.offsetHeight });
+        const rect = element.getBoundingClientRect();
+        if (Math.abs(next.x - rect.left) > CHAT_FAB_DRAG_THRESHOLD_PX || Math.abs(next.y - rect.top) > CHAT_FAB_DRAG_THRESHOLD_PX) {
+            state.moved = true;
+        }
+        // Only commit a position once this is genuinely a drag. Setting it on every move meant a
+        // click with a pixel of jitter pinned the button to an inline `left`/`top` forever — which
+        // silently defeats the CSS default and made the button appear to wander on its own.
+        if (state.moved)
+            setPosition(next);
+    }, []);
+    const endDrag = useCallback((event) => {
+        const state = drag.current;
+        if (state === null || state.pointerId !== event.pointerId)
+            return;
+        drag.current = null;
+        if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+            event.currentTarget.releasePointerCapture(event.pointerId);
+        }
+        if (!state.moved)
+            onClick();
+    }, [onClick]);
+    return {
+        buttonRef,
+        position,
+        onPointerDown,
+        onPointerMove,
+        onPointerUp: endDrag,
+        onPointerCancel: endDrag,
+    };
+}
+//# sourceMappingURL=useChatFabDrag.js.map

package/dist/react/hooks/useChatFabDrag.js.map

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

package/dist/react/hooks/useComposer.d.ts

@@ -0,0 +1,48 @@
+import type { ChatAttachment } from '../../core/index.js';
+import type { AgentSelection, ComposerSlots, MentionResult, ProjectContextValue } from '../slots.js';
+export interface ComposerDraftPersistence {
+    read: () => string | null;
+    write: (draft: string) => void;
+}
+export interface UseComposerOptions {
+    initialDraft?: string;
+    initialAgent?: AgentSelection;
+    project?: ProjectContextValue;
+    composerSlots?: ComposerSlots;
+    persistence?: ComposerDraftPersistence;
+    /**
+     * The active conversation, used to key the per-conversation draft cache (see this module's doc).
+     * `null`/absent (an untitled, not-yet-created conversation) opts out of caching entirely — there is
+     * nothing to key on yet, and the draft lives only in this hook's own React state until an id
+     * exists.
+     */
+    conversationId?: string | null;
+}
+export interface MentionPopoverState {
+    open: boolean;
+    query: string;
+    results: MentionResult[];
+}
+export interface UseComposerResult {
+    draft: string;
+    setDraft: (next: string) => void;
+    attachments: ChatAttachment[];
+    /** Uploads via `project.uploadFiles` (when supplied) and stages the results; no-ops (with a rejected promise) when no upload port is wired. */
+    addAttachments: (files: File[]) => Promise<void>;
+    addAttachment: (attachment: ChatAttachment) => void;
+    removeAttachment: (id: string) => void;
+    clearAttachments: () => void;
+    agent: AgentSelection | undefined;
+    setAgent: (next: AgentSelection) => void;
+    mention: MentionPopoverState;
+    openMention: (query: string) => Promise<void>;
+    closeMention: () => void;
+    /** Applies a picked mention result to the draft (appends `insertText` or `@label`), then closes the popover. */
+    selectMention: (result: MentionResult) => void;
+    /** `true` once the draft has content or an attachment — a `<Composer>` gates its send button on this. */
+    canSubmit: boolean;
+    /** Clears the draft and staged attachments (called after a successful send). */
+    reset: () => void;
+}
+export declare function useComposer(options?: UseComposerOptions): UseComposerResult;
+//# sourceMappingURL=useComposer.d.ts.map

package/dist/react/hooks/useComposer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useComposer.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useComposer.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErG,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,cAAc,CAAC;IAC9B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,WAAW,CAAC,EAAE,wBAAwB,CAAC;IACvC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,+IAA+I;IAC/I,cAAc,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,aAAa,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,IAAI,CAAC;IACpD,gBAAgB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,KAAK,EAAE,cAAc,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,gHAAgH;IAChH,aAAa,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAC/C,yGAAyG;IACzG,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAID,wBAAgB,WAAW,CAAC,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CAmH/E"}

package/dist/react/hooks/useComposer.js

@@ -0,0 +1,121 @@
+/**
+ * @module useComposer
+ *
+ * Owns the composer's draft text, staged attachments, `@`-mention popover
+ * state, and the selected agent/model/sessionMode. Per
+ * `ADS-memory/reports/jini-port/recon/r4b-webui-design.md` §4: attachments reach the host
+ * only through `ProjectContextValue.uploadFiles`/`ComposerSlots`; no direct
+ * provider import. Draft persistence (OD's `ComposerDraftPort`,
+ * localStorage-backed) is likewise injectable, not hard-wired — this hook
+ * never touches `localStorage` itself; a host that wants persistence passes
+ * `persistence` (falling back to in-memory/no persistence when omitted).
+ *
+ * Origin pattern: OD's `features/chat-composer/hooks/useComposerDraft.hooks.ts`
+ * + `useComposerUpload.hooks.ts` + `useMentionPopover.hooks.ts` (branch
+ * `refactor/web-chat-composer-slice-pr`), generalized: the Lexical-editor-ref
+ * plumbing and localStorage port are OD/DOM-specific and dropped; the
+ * draft/attachment/mention/agent-selection *state shape* is kept.
+ *
+ * `conversationId` (when supplied) keys the draft — and, on a change, the staged attachments and
+ * mention popover — against `composer-draft-cache.ts`'s module-level cache, so a switch between
+ * conversations round-trips whatever was typed instead of losing it or leaking it into the wrong
+ * conversation. That cache is a separate, always-on mechanism from `persistence` above: `persistence`
+ * is a single opaque host-owned slot (e.g. localStorage, for surviving a page *reload*) that this
+ * hook still never touches directly; the cache instead survives a `ChatPane` remount within the same
+ * page session — see its own module doc for why a switch here so often means a full remount. Staged
+ * attachments and the mention popover are deliberately NOT cached across a switch (unlike the draft
+ * text): they reference an in-flight upload batch, and carrying them into a different conversation
+ * risks attaching the wrong files to the wrong thread, so they are cleared instead.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { readCachedDraft, writeCachedDraft } from './composer-draft-cache.js';
+const EMPTY_MENTION = { open: false, query: '', results: [] };
+export function useComposer(options = {}) {
+    const { project, composerSlots, persistence, conversationId } = options;
+    const [draft, setDraftState] = useState(() => options.initialDraft ?? persistence?.read() ?? readCachedDraft(conversationId) ?? '');
+    const [attachments, setAttachments] = useState([]);
+    const [agent, setAgent] = useState(options.initialAgent);
+    const [mention, setMention] = useState(EMPTY_MENTION);
+    const setDraft = useCallback((next) => {
+        setDraftState(next);
+        persistence?.write(next);
+        writeCachedDraft(conversationId, next);
+    }, [persistence, conversationId]);
+    // Re-keys the draft (and drops attachments/the mention popover — see this module's doc) when
+    // `conversationId` changes WITHOUT a remount — a host that keeps the composer mounted across
+    // conversations, unlike a host that remounts `ChatPane` via a conversation-keyed `key` (the
+    // `useState` initializer above already handles that case at mount time). Skips the very first
+    // render via the ref comparison so it never fights that initializer.
+    const previousConversationIdRef = useRef(conversationId);
+    useEffect(() => {
+        if (conversationId === previousConversationIdRef.current)
+            return;
+        previousConversationIdRef.current = conversationId;
+        setDraftState(readCachedDraft(conversationId) ?? '');
+        setAttachments([]);
+        setMention(EMPTY_MENTION);
+    }, [conversationId]);
+    const addAttachment = useCallback((attachment) => {
+        setAttachments((prev) => [...prev, attachment]);
+    }, []);
+    const addAttachments = useCallback(async (files) => {
+        if (files.length === 0)
+            return;
+        if (!project?.uploadFiles) {
+            throw new Error('addAttachments requires ProjectContextValue.uploadFiles to be wired by the host');
+        }
+        const uploaded = await project.uploadFiles(files);
+        setAttachments((prev) => [...prev, ...uploaded]);
+        for (const a of uploaded)
+            composerSlots?.onAttach?.(a);
+    }, [composerSlots, project]);
+    const removeAttachment = useCallback((id) => {
+        setAttachments((prev) => prev.filter((a) => a.path !== id));
+    }, []);
+    const clearAttachments = useCallback(() => setAttachments([]), []);
+    const openMention = useCallback(async (query) => {
+        setMention({ open: true, query, results: [] });
+        const sources = composerSlots?.mentionSources ?? [];
+        if (sources.length === 0)
+            return;
+        const results = (await Promise.all(sources.map(async (source) => {
+            try {
+                return await source.search(query);
+            }
+            catch {
+                return [];
+            }
+        }))).flat();
+        setMention((prev) => (prev.open && prev.query === query ? { ...prev, results } : prev));
+    }, [composerSlots]);
+    const closeMention = useCallback(() => setMention(EMPTY_MENTION), []);
+    const selectMention = useCallback((result) => {
+        const insertion = result.insertText ?? `@${result.label} `;
+        setDraft(`${draft}${insertion}`);
+        setMention(EMPTY_MENTION);
+    }, [draft, setDraft]);
+    const reset = useCallback(() => {
+        setDraft('');
+        clearAttachments();
+        closeMention();
+    }, [clearAttachments, closeMention, setDraft]);
+    const canSubmit = draft.trim().length > 0 || attachments.length > 0;
+    return useMemo(() => ({
+        draft,
+        setDraft,
+        attachments,
+        addAttachments,
+        addAttachment,
+        removeAttachment,
+        clearAttachments,
+        agent,
+        setAgent,
+        mention,
+        openMention,
+        closeMention,
+        selectMention,
+        canSubmit,
+        reset,
+    }), [draft, setDraft, attachments, addAttachments, addAttachment, removeAttachment, clearAttachments, agent, mention, openMention, closeMention, selectMention, canSubmit, reset]);
+}
+//# sourceMappingURL=useComposer.js.map

package/dist/react/hooks/useComposer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useComposer.js","sourceRoot":"","sources":["../../../src/react/hooks/useComposer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAE1E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAmD9E,MAAM,aAAa,GAAwB,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAEnF,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE;IAC1D,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IACxE,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,GAAG,QAAQ,CACrC,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,IAAI,WAAW,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC,cAAc,CAAC,IAAI,EAAE,CAC3F,CAAC;IACF,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAmB,EAAE,CAAC,CAAC;IACrE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAA6B,OAAO,CAAC,YAAY,CAAC,CAAC;IACrF,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAsB,aAAa,CAAC,CAAC;IAE3E,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,IAAY,EAAE,EAAE;QACf,aAAa,CAAC,IAAI,CAAC,CAAC;QACpB,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,gBAAgB,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC,EACD,CAAC,WAAW,EAAE,cAAc,CAAC,CAC9B,CAAC;IAEF,6FAA6F;IAC7F,6FAA6F;IAC7F,4FAA4F;IAC5F,8FAA8F;IAC9F,qEAAqE;IACrE,MAAM,yBAAyB,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IACzD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,cAAc,KAAK,yBAAyB,CAAC,OAAO;YAAE,OAAO;QACjE,yBAAyB,CAAC,OAAO,GAAG,cAAc,CAAC;QACnD,aAAa,CAAC,eAAe,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC;QACrD,cAAc,CAAC,EAAE,CAAC,CAAC;QACnB,UAAU,CAAC,aAAa,CAAC,CAAC;IAC5B,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAErB,MAAM,aAAa,GAAG,WAAW,CAAC,CAAC,UAA0B,EAAE,EAAE;QAC/D,cAAc,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IAClD,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,cAAc,GAAG,WAAW,CAChC,KAAK,EAAE,KAAa,EAAE,EAAE;QACtB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAC;QACrG,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAClD,cAAc,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;QACjD,KAAK,MAAM,CAAC,IAAI,QAAQ;YAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC,EACD,CAAC,aAAa,EAAE,OAAO,CAAC,CACzB,CAAC;IAEF,MAAM,gBAAgB,GAAG,WAAW,CAAC,CAAC,EAAU,EAAE,EAAE;QAClD,cAAc,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,gBAAgB,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAEnE,MAAM,WAAW,GAAG,WAAW,CAC7B,KAAK,EAAE,KAAa,EAAE,EAAE;QACtB,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAC/C,MAAM,OAAO,GAAG,aAAa,EAAE,cAAc,IAAI,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACjC,MAAM,OAAO,GAAG,CACd,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YAC3B,IAAI,CAAC;gBACH,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACpC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CACH,CACF,CAAC,IAAI,EAAE,CAAC;QACT,UAAU,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1F,CAAC,EACD,CAAC,aAAa,CAAC,CAChB,CAAC;IAEF,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC;IAEtE,MAAM,aAAa,GAAG,WAAW,CAC/B,CAAC,MAAqB,EAAE,EAAE;QACxB,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,IAAI,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC;QAC3D,QAAQ,CAAC,GAAG,KAAK,GAAG,SAAS,EAAE,CAAC,CAAC;QACjC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC5B,CAAC,EACD,CAAC,KAAK,EAAE,QAAQ,CAAC,CAClB,CAAC;IAEF,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QAC7B,QAAQ,CAAC,EAAE,CAAC,CAAC;QACb,gBAAgB,EAAE,CAAC;QACnB,YAAY,EAAE,CAAC;IACjB,CAAC,EAAE,CAAC,gBAAgB,EAAE,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE/C,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC;IAEpE,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,KAAK;QACL,QAAQ;QACR,WAAW;QACX,cAAc;QACd,aAAa;QACb,gBAAgB;QAChB,gBAAgB;QAChB,KAAK;QACL,QAAQ;QACR,OAAO;QACP,WAAW;QACX,YAAY;QACZ,aAAa;QACb,SAAS;QACT,KAAK;KACN,CAAC,EACF,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,KAAK,CAAC,CAC9K,CAAC;AACJ,CAAC"}

package/dist/react/hooks/useConversation.d.ts

@@ -0,0 +1,34 @@
+import type { ChatAttachment, ChatMessage } from '../../core/index.js';
+import type { ChatTransport, RunContext } from '../../core/index.js';
+export interface UseConversationOptions {
+    transport: ChatTransport;
+    initialMessages?: ChatMessage[];
+    conversationId?: string | null;
+    agentId?: string;
+    /** Defaults to a `crypto.randomUUID()`-based id generator when available, else a counter. */
+    createMessageId?: () => string;
+}
+export interface SendMessageOptions {
+    attachments?: ChatAttachment[];
+    context?: RunContext;
+    agentId?: string;
+}
+export interface UseConversationResult {
+    messages: ChatMessage[];
+    conversationId: string | null;
+    isStreaming: boolean;
+    error: Error | null;
+    /** `true` when new content just arrived and nothing has told the hook the user already scrolled away — a `<MessageList>` reads this to decide whether to auto-scroll. */
+    scrollIntent: boolean;
+    sendMessage: (content: string, options?: SendMessageOptions) => Promise<void>;
+    cancel: () => void;
+    /** Re-send the same content as a failed/canceled assistant message's preceding user turn. */
+    retry: (assistantMessageId: string) => Promise<void>;
+    setMessages: (updater: ChatMessage[] | ((prev: ChatMessage[]) => ChatMessage[])) => void;
+    /** Called by `<MessageList>` once it has scrolled to the newest content. */
+    acknowledgeScroll: () => void;
+    /** Called by `<MessageList>` when the user manually scrolls up, so the next event doesn't yank them back down. */
+    suppressScroll: () => void;
+}
+export declare function useConversation(options: UseConversationOptions): UseConversationResult;
+//# sourceMappingURL=useConversation.d.ts.map

package/dist/react/hooks/useConversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useConversation.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/useConversation.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAc,cAAc,EAAE,WAAW,EAAiB,MAAM,qBAAqB,CAAC;AAElG,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGrE,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,aAAa,CAAC;IACzB,eAAe,CAAC,EAAE,WAAW,EAAE,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,yKAAyK;IACzK,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,6FAA6F;IAC7F,KAAK,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,WAAW,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,CAAC,KAAK,IAAI,CAAC;IACzF,4EAA4E;IAC5E,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,kHAAkH;IAClH,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAiBD,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CA6ItF"}