@jini-ai/chat 0.5.4 → 0.5.5

package/dist/react/hooks/attachment-preview-cache.d.ts

@@ -37,7 +37,7 @@ export declare const MAX_CACHED_ATTACHMENT_PREVIEWS = 50;
 export declare function cacheAttachmentPreviewSource({ path, file }: {
     path: string;
     file: File;
-}): void;
+}, _options?: Record<string, never>): void;
 /**
  * Reads back the `File` cached for `path`, or `undefined` when this browser never staged it (a
  * different session, a reload, or eviction past the cap) - the only signal a preview needs to fall

package/dist/react/hooks/attachment-preview-cache.js

@@ -35,7 +35,7 @@ const sources = new Map();
  * if this would introduce a new entry past {@link MAX_CACHED_ATTACHMENT_PREVIEWS}.
  * @complexity Time/space: O(1) amortized.
  */
-export function cacheAttachmentPreviewSource({ path, file }) {
+export function cacheAttachmentPreviewSource({ path, file }, _options = {}) {
     if (!sources.has(path) && sources.size >= MAX_CACHED_ATTACHMENT_PREVIEWS) {
         const oldest = sources.keys().next().value;
         if (oldest !== undefined)

package/dist/react/hooks/composer-draft-cache.d.ts

@@ -131,7 +131,7 @@ export declare function readCachedAttachments({ conversationId }: {
  */
 export declare function readCachedAttachmentBatchId({ conversationId }: {
     conversationId: string | null | undefined;
-}): string | null;
+}, _options?: Record<string, never>): string | null;
 /**
  * Records the upload batch of an attachment about to be staged in `conversationId`'s composer.
  * Memory only: the stored envelope picks it up on the {@link writeCachedAttachments} that persists
@@ -142,7 +142,7 @@ export declare function readCachedAttachmentBatchId({ conversationId }: {
 export declare function writeCachedAttachmentBatchId({ conversationId, batchId }: {
     conversationId: string | null | undefined;
     batchId: string;
-}): void;
+}, _options?: Record<string, never>): void;
 /**
  * Stores `attachments` for `conversationId` in both tiers.
  *

package/dist/react/hooks/composer-draft-cache.js

@@ -370,7 +370,7 @@ export function readCachedAttachments({ conversationId }) {
  * written before batch ids were recorded) — the caller then starts a fresh batch.
  * @complexity Time/space: O(1) on an in-memory hit, O(n) in the stored count otherwise.
  */
-export function readCachedAttachmentBatchId({ conversationId }) {
+export function readCachedAttachmentBatchId({ conversationId }, _options = {}) {
     if (!conversationId)
         return null;
     if (readCachedAttachments({ conversationId: conversationId }) === null)
@@ -384,7 +384,7 @@ export function readCachedAttachmentBatchId({ conversationId }) {
  *
  * @complexity Time/space: O(1) amortized.
  */
-export function writeCachedAttachmentBatchId({ conversationId, batchId }) {
+export function writeCachedAttachmentBatchId({ conversationId, batchId }, _options = {}) {
     if (!conversationId)
         return;
     if (!stagedBatchIds.has(conversationId) && stagedBatchIds.size >= MAX_CACHED_CONVERSATION_DRAFTS) {

package/dist/react/hooks/fab-position.d.ts

@@ -0,0 +1,90 @@
+export interface FabPositionResult {
+    /** Inline `style` for the FAB button — `right` and `bottom`, in px, always resolved against
+     *  the *current* viewport (never a stale stored pixel value). Always both: the FAB is
+     *  positioned as an offset from the right/bottom edges regardless of where on screen it was
+     *  dropped, so there is no left-vs-right branch to keep in sync with the stored fractions. */
+    style: {
+        right: number;
+        bottom: number;
+    };
+    /** Attach to the FAB's `onPointerDown`. */
+    onPointerDown: (e: React.PointerEvent<HTMLButtonElement>) => void;
+    /**
+     * Call from the FAB's `onClick`, in place of the toggle callback directly — returns `true` if
+     * the click should be treated as a real activation (fire the toggle) and `false` if it is the
+     * tail end of a drag and should be swallowed.
+     *
+     * Deliberately NOT the `isDragging` boolean below checked inline at the call site: `pointerup`
+     * (which ends the drag) and `click` (which this guards) are two different events, dispatched
+     * back-to-back by the browser, and by the time `click` fires React may not have re-rendered
+     * with `isDragging`'s new value yet — reading a piece of React state that was *just* set a
+     * moment earlier in the same synchronous sequence is exactly the kind of timing this project's
+     * conventions call out as unreliable (see `use-settings-slice.hooks.ts`'s "read at run time, not
+     * schedule time" refrain, one level down in raw event timing rather than async scheduling).
+     * `consumeDragFlag` reads and clears a ref instead, which has no such lag.
+     */
+    consumeDragFlag: () => boolean;
+    /** For UI feedback only (e.g. suppressing the hover/press transition while dragging) — not to
+     *  be used to decide whether to swallow a click; use `consumeDragFlag` for that. */
+    isDragging: boolean;
+}
+/**
+ * @param options.dockOpen When the assistant dock/sheet is open, an UNTOUCHED or migrated-legacy
+ *   resting spot moves off it so it never sits over the dock's own composer/close controls by
+ *   accident — this mirrors what the old hard-coded `.chat-fab-dock-open` rule did for the
+ *   desktop-docked panel, generalized to the dragged position and to the mobile sheet's own
+ *   (viewport-fraction) height. A spot the operator explicitly dragged onto the dock is left alone
+ *   (see `pinnedByUser`'s own doc on `StoredFabPosition`) — this option only guards against an
+ *   unintentional overlap, not against a deliberate one.
+ * @param options.avoidBottomPx Extra clearance to hold above the bottom edge while `dockOpen` —
+ *   the caller passes the mobile sheet's current height here (0 at desktop, where the dock sits
+ *   to the *side*, not below, so no bottom clearance is needed there — see `App.tsx`).
+ * @param options.avoidRightPx Extra clearance to hold left of the right edge while `dockOpen` —
+ *   the caller passes the DESKTOP dock's current width here (0 in sheet mode, where the sheet
+ *   spans the full width and `avoidBottomPx` is the axis that matters).
+ *
+ *   This axis was missing until 2026-08-05, and its absence was a live defect rather than a
+ *   theoretical gap: the FAB is `position: fixed` and offset from the RIGHT edge, and the desktop
+ *   dock is also pinned to the right edge, so with the dock open the 56px FAB sat directly on top
+ *   of the dock's own composer send button and swallowed its clicks. Playwright caught it as
+ *   `<button class="chat-fab chat-fab-dock-open"> intercepts pointer events` while trying to send
+ *   a message — i.e. the assistant could not be used with a mouse at the default FAB position.
+ *
+ *   How it got lost is worth recording, because the code confidently said otherwise: the old
+ *   `.chat-fab-dock-open { right: calc(380px + 20px) }` rule moved the FAB SIDEWAYS. When this
+ *   hook replaced it, only the vertical axis was carried over, while the comment on
+ *   `effectiveBottom` below claimed `avoidBottomPx` "generalizes" what that rule did — it does
+ *   not, it generalizes a different axis, and desktop passes `avoidBottomPx: 0`, so on desktop
+ *   nothing displaced the FAB at all. The `.chat-fab-dock-open` class is still applied by
+ *   `ChatFab.tsx` and has had no CSS rule behind it since.
+ *
+ *   Measured by the caller rather than hard-coded back to 380px, for the same
+ *   resolution-independence reason this whole hook exists (see the module doc).
+ *
+ * @complexity O(1) per pointer event — no work scales with anything caller-controlled.
+ */
+export declare function useFabPosition(options: FabPositionInput, _optional?: Record<string, never>): FabPositionResult;
+/** Storage and DOM handles are host ports; geometry matches the host button CSS. */
+export interface FabPositionInput {
+    readonly dockOpen: boolean;
+    readonly avoidBottomPx: number;
+    readonly avoidRightPx?: number;
+    readonly storageKey: string;
+    readonly storage: Pick<Storage, "getItem" | "setItem">;
+    readonly viewport: Window;
+    readonly pointerEvents: Document;
+    /** Keeps the FAB's edge margin and the sheet-avoidance gap in one place instead of duplicating
+    *  the literal in both this file and `styles.css`. */
+    readonly edgeMargin: number;
+    /** Matches `.chat-fab`'s own `width`/`height` in `styles/assistant.css` — used only to keep a
+    *  dragged position from clamping the FAB half off-screen; if that CSS size ever changes, update
+    *  both together (there is no single source of truth to read the rendered size from here without
+    *  a layout measurement on every drag frame, which is not worth it for a constant that changes
+    *  approximately never). */
+    readonly sizePx: number;
+    /** Below this many pixels of net pointer movement, a pointerdown/up pair is treated as a click,
+    *  not a drag — small enough that an intentional drag is never mistaken for a tap, large enough
+    *  that a tap's inevitable few pixels of finger movement never gets misread as a drag and eaten. */
+    readonly dragThresholdPx: number;
+}
+//# sourceMappingURL=fab-position.d.ts.map

package/dist/react/hooks/fab-position.js

@@ -0,0 +1,271 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+function isLegacyShape(value) {
+    return (value.side === "left" || value.side === "right") && typeof value.bottomFraction === "number";
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function readPersisted({ storage, storageKey: STORAGE_KEY, viewport: window, edgeMargin: FAB_EDGE_MARGIN, sizePx: FAB_SIZE_PX }) {
+    try {
+        const raw = storage.getItem(STORAGE_KEY);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.rightFraction === "number" && typeof parsed.bottomFraction === "number") {
+            return {
+                rightFraction: clamp(parsed.rightFraction, 0, 1),
+                bottomFraction: clamp(parsed.bottomFraction, 0, 1),
+                // Absent on any value written before the `pinnedByUser` field existed — treated as `false`
+                // (same protection as the default spot) rather than assumed `true`, since a pre-existing
+                // stored drop is exactly the case `pinnedByUser`'s own doc calls out as unearned evidence.
+                pinnedByUser: parsed.pinnedByUser === true,
+            };
+        }
+        if (isLegacyShape(parsed)) {
+            // Map the edge to an x-fraction near that edge — the legacy shape never recorded a
+            // horizontal offset (it was always pinned flush to the edge margin), so "near that edge" is
+            // the most faithful reading of it available, not an approximation of a value that existed.
+            const rightFraction = parsed.side === "right"
+                ? FAB_EDGE_MARGIN / window.innerWidth
+                : (window.innerWidth - FAB_EDGE_MARGIN - FAB_SIZE_PX) / window.innerWidth;
+            return {
+                rightFraction: clamp(rightFraction, 0, 1),
+                bottomFraction: clamp(parsed.bottomFraction, 0, 1),
+                pinnedByUser: false,
+            };
+        }
+        // Unrecognized shape (corrupted value, a future format, hand-edited localStorage) — fall back
+        // to the default rather than risk propagating `NaN`/`undefined` into pixel math downstream.
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writePersisted(position, { storage, storageKey }) {
+    try {
+        storage.setItem(storageKey, JSON.stringify(position));
+    }
+    catch {
+        // Best-effort, same reasoning as `useSidebarRail`'s `writePersisted` — a user who cannot
+        // persist the position still gets a working, draggable FAB for the current tab.
+    }
+}
+/** A safe default before the first drag — bottom-right corner, matching the FAB's original
+ *  hard-coded `right: 20px; bottom: 20px`. Both fractions are `0` ("flush against the edge"),
+ *  not "off-screen at the corner" — `style` below clamps them up to `FAB_EDGE_MARGIN` regardless
+ *  of viewport size. */
+const DEFAULT_POSITION = { rightFraction: 0, bottomFraction: 0, pinnedByUser: false };
+/**
+ * @param options.dockOpen When the assistant dock/sheet is open, an UNTOUCHED or migrated-legacy
+ *   resting spot moves off it so it never sits over the dock's own composer/close controls by
+ *   accident — this mirrors what the old hard-coded `.chat-fab-dock-open` rule did for the
+ *   desktop-docked panel, generalized to the dragged position and to the mobile sheet's own
+ *   (viewport-fraction) height. A spot the operator explicitly dragged onto the dock is left alone
+ *   (see `pinnedByUser`'s own doc on `StoredFabPosition`) — this option only guards against an
+ *   unintentional overlap, not against a deliberate one.
+ * @param options.avoidBottomPx Extra clearance to hold above the bottom edge while `dockOpen` —
+ *   the caller passes the mobile sheet's current height here (0 at desktop, where the dock sits
+ *   to the *side*, not below, so no bottom clearance is needed there — see `App.tsx`).
+ * @param options.avoidRightPx Extra clearance to hold left of the right edge while `dockOpen` —
+ *   the caller passes the DESKTOP dock's current width here (0 in sheet mode, where the sheet
+ *   spans the full width and `avoidBottomPx` is the axis that matters).
+ *
+ *   This axis was missing until 2026-08-05, and its absence was a live defect rather than a
+ *   theoretical gap: the FAB is `position: fixed` and offset from the RIGHT edge, and the desktop
+ *   dock is also pinned to the right edge, so with the dock open the 56px FAB sat directly on top
+ *   of the dock's own composer send button and swallowed its clicks. Playwright caught it as
+ *   `<button class="chat-fab chat-fab-dock-open"> intercepts pointer events` while trying to send
+ *   a message — i.e. the assistant could not be used with a mouse at the default FAB position.
+ *
+ *   How it got lost is worth recording, because the code confidently said otherwise: the old
+ *   `.chat-fab-dock-open { right: calc(380px + 20px) }` rule moved the FAB SIDEWAYS. When this
+ *   hook replaced it, only the vertical axis was carried over, while the comment on
+ *   `effectiveBottom` below claimed `avoidBottomPx` "generalizes" what that rule did — it does
+ *   not, it generalizes a different axis, and desktop passes `avoidBottomPx: 0`, so on desktop
+ *   nothing displaced the FAB at all. The `.chat-fab-dock-open` class is still applied by
+ *   `ChatFab.tsx` and has had no CSS rule behind it since.
+ *
+ *   Measured by the caller rather than hard-coded back to 380px, for the same
+ *   resolution-independence reason this whole hook exists (see the module doc).
+ *
+ * @complexity O(1) per pointer event — no work scales with anything caller-controlled.
+ */
+export function useFabPosition(options, _optional = {}) {
+    // Storage/DOM handles and CSS geometry are fixed for this mounted button; dock clearances stay live.
+    const environment = useRef(options).current;
+    const { viewport: window, pointerEvents: document, edgeMargin: FAB_EDGE_MARGIN, sizePx: FAB_SIZE_PX, dragThresholdPx: DRAG_THRESHOLD_PX } = environment;
+    const { dockOpen, avoidBottomPx } = options;
+    const avoidRightPx = options.avoidRightPx ?? 0;
+    const [persisted, setPersisted] = useState(() => readPersisted(environment) ?? DEFAULT_POSITION);
+    const [isDragging, setIsDragging] = useState(false);
+    /**
+     * All the mutable drag bookkeeping lives in refs, not state, and is read/written only inside
+     * the `pointermove`/`pointerup` handlers below.
+     *
+     * This is deliberate, not an optimization: `document.addEventListener("pointermove", handler)`
+     * binds to whatever `handler` closure existed at `pointerdown` time and is never re-subscribed
+     * mid-drag. If this logic instead branched on the REACT STATE `isDragging` — which is exactly
+     * what an earlier version of this hook did — every handler invoked after the first `pointermove`
+     * would still see the `isDragging=false` closure captured at `pointerdown`, because the state
+     * update that flips it to `true` doesn't re-create (and re-attach) the listener. Concretely,
+     * that made `handlePointerUp`'s `if (isDragging)` check always false, so a real drag's end
+     * position was silently never persisted. Refs have no such staleness — they are the same
+     * mutable cell on every read regardless of which render's closure is doing the reading.
+     */
+    const draggingRef = useRef(false);
+    const didDragRef = useRef(false);
+    const liveRef = useRef(null);
+    const dragStart = useRef(null);
+    /** Bumped to force a re-render on every pointermove and on resize — `liveRef`/`window.innerWidth`
+     *  are read directly in `style`'s `useMemo` below, neither of which React tracks as a reactive
+     *  dependency on its own, so without this counter in that hook's dependency array the memo
+     *  would never invalidate and the FAB would visually freeze mid-drag. */
+    const [renderTick, forceRender] = useState(0);
+    // Re-clamp on resize/orientationchange — `rightFraction`/`bottomFraction` are already
+    // resolution-independent on their own axes, but this still forces a re-render so any consumer
+    // computing pixels from `window.innerWidth`/`innerHeight` (this hook included, in `style`
+    // below) recomputes rather than holding a value measured against the previous viewport.
+    useEffect(() => {
+        function onResize() {
+            forceRender((n) => n + 1);
+        }
+        window.addEventListener("resize", onResize);
+        window.addEventListener("orientationchange", onResize);
+        return () => {
+            window.removeEventListener("resize", onResize);
+            window.removeEventListener("orientationchange", onResize);
+        };
+    }, []);
+    // Stable identities (empty dep arrays) — see the `draggingRef` doc above for why these must
+    // never depend on state that would force a re-subscribe mid-gesture.
+    const handlePointerMove = useCallback((e) => {
+        const start = dragStart.current;
+        if (!start)
+            return;
+        const dx = e.clientX - start.startX;
+        const dy = e.clientY - start.startY;
+        if (!draggingRef.current && Math.hypot(dx, dy) > DRAG_THRESHOLD_PX) {
+            draggingRef.current = true;
+            didDragRef.current = true;
+            setIsDragging(true);
+        }
+        if (draggingRef.current) {
+            // Dragging moves the FAB's bottom-right-anchored box: moving the pointer right shrinks
+            // `right` (px from the right edge); moving it down shrinks `bottom`.
+            liveRef.current = { right: start.startRight - dx, bottom: start.startBottom - dy };
+            forceRender((n) => n + 1);
+        }
+    }, []);
+    const handlePointerUp = useCallback((e) => {
+        const start = dragStart.current;
+        if (!start)
+            return;
+        e.target.releasePointerCapture?.(start.pointerId);
+        document.removeEventListener("pointermove", handlePointerMove);
+        document.removeEventListener("pointerup", handlePointerUp);
+        document.removeEventListener("pointercancel", handlePointerUp);
+        const live = liveRef.current;
+        const wasDragging = draggingRef.current;
+        dragStart.current = null;
+        liveRef.current = null;
+        draggingRef.current = false;
+        if (live && wasDragging) {
+            // Persist exactly where it was dropped — no edge-snap (see file header). Clamped to
+            // `[0, 1]` here only to keep the *fraction* well-formed; the margin-aware on-screen clamp
+            // happens once, in `style` below, the same way it already did for the vertical axis alone —
+            // so a drop near an edge still ends up fully on-screen after conversion back to pixels, on
+            // this viewport and any other.
+            const next = {
+                rightFraction: clamp(live.right / window.innerWidth, 0, 1),
+                bottomFraction: clamp(live.bottom / window.innerHeight, 0, 1),
+                // A completed drag-and-drop is exactly the deliberate placement `pinnedByUser` exists to
+                // recognize — see its own doc for what this unlocks in `style` below.
+                pinnedByUser: true,
+            };
+            setPersisted(next);
+            writePersisted(next, environment);
+        }
+        setIsDragging(false);
+        // `didDragRef` is intentionally NOT cleared here — `consumeDragFlag` (called from `onClick`,
+        // which fires after this handler) is what clears it, once. Clearing it here would defeat the
+        // whole point: `click` always follows `pointerup`, so the flag has to survive until then.
+    }, [handlePointerMove]);
+    const onPointerDown = useCallback((e) => {
+        // Right-button/non-primary pointers don't start a drag — a right-click should still be
+        // able to open a context menu, not get captured as a failed drag gesture.
+        if (e.button !== 0)
+            return;
+        const rect = e.currentTarget.getBoundingClientRect();
+        dragStart.current = {
+            pointerId: e.pointerId,
+            startX: e.clientX,
+            startY: e.clientY,
+            startRight: window.innerWidth - rect.right,
+            startBottom: window.innerHeight - rect.bottom,
+        };
+        e.currentTarget.setPointerCapture(e.pointerId);
+        document.addEventListener("pointermove", handlePointerMove);
+        document.addEventListener("pointerup", handlePointerUp);
+        document.addEventListener("pointercancel", handlePointerUp);
+    }, [handlePointerMove, handlePointerUp]);
+    const consumeDragFlag = useCallback(() => {
+        const dragged = didDragRef.current;
+        didDragRef.current = false;
+        return dragged;
+    }, []);
+    // `renderTick`/`isDragging` are read only to force recomputation while dragging (their values
+    // are not otherwise used in the body — the live position comes from `liveRef`/`draggingRef`
+    // directly, per the staleness note above) — expected extra deps, not a lint miss.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: renderTick/isDragging force recompute while dragging; not otherwise used in the body.
+    const style = useMemo(() => {
+        const live = liveRef.current;
+        if (draggingRef.current && live) {
+            // Clamped live so a fast drag can't throw the FAB fully off-screen mid-gesture, only to
+            // have it snap back on release — the same margin used for the resting position below.
+            return {
+                right: clamp(live.right, FAB_EDGE_MARGIN, window.innerWidth - FAB_EDGE_MARGIN - FAB_SIZE_PX),
+                bottom: clamp(live.bottom, FAB_EDGE_MARGIN, window.innerHeight - FAB_EDGE_MARGIN - FAB_SIZE_PX),
+            };
+        }
+        const rightPx = clamp(persisted.rightFraction * window.innerWidth, FAB_EDGE_MARGIN, window.innerWidth - FAB_EDGE_MARGIN - FAB_SIZE_PX);
+        const bottomPx = clamp(persisted.bottomFraction * window.innerHeight, FAB_EDGE_MARGIN, window.innerHeight - FAB_EDGE_MARGIN - FAB_SIZE_PX);
+        // While the dock/sheet is open, hold clear of it — but only at the UNTOUCHED default spot or a
+        // migrated legacy one (`!persisted.pinnedByUser`); an operator who explicitly dragged the FAB
+        // somewhere, including onto the open dock, gets that placement respected instead of vetoed (see
+        // `pinnedByUser`'s own doc for the 2026-08-05 bug this distinction fixes: the avoidance below
+        // was pushing ANY drop inside the dock's width back out onto the page on every release, because
+        // it did not yet know a drop was deliberate).
+        //
+        // TWO axes, because the dock occupies a different edge depending on mode, and getting this
+        // wrong is not cosmetic — a FAB overlapping the composer's send button eats the click:
+        //   - sheet mode (mobile): the sheet spans the full width along the BOTTOM, so `avoidBottomPx`
+        //     (its measured height) is the axis that matters.
+        //   - docked mode (desktop): the dock is pinned to the RIGHT edge, which is the same edge the
+        //     FAB offsets from, so `avoidRightPx` (its measured width) is the axis that matters.
+        // The old `.chat-fab-dock-open { right: calc(380px + 20px) }` rule covered only the second of
+        // those, and only at one hard-coded width; an earlier version of this comment claimed
+        // `avoidBottomPx` generalized it, which was wrong — different axis. See the `avoidRightPx`
+        // param doc for what that cost.
+        //
+        // Re-clamped against the viewport, and that clamp is load-bearing rather than defensive.
+        // `avoidBottomPx` is a raw PIXEL measurement of another element (`App.tsx` measures the sheet),
+        // so it is the one input here that is not viewport-relative by construction — everything else
+        // on this path is a 0-1 fraction re-derived against the current window. A sheet taller than
+        // `innerHeight - FAB_EDGE_MARGIN - FAB_SIZE_PX` therefore pushes the FAB clean off the top
+        // edge, where it is unreachable and looks simply missing. Reported by the operator as "hidden
+        // and not shown at the bottom" and identified by reading this expression — the specific
+        // viewport it reproduces at has NOT been pinned down, so treat the clamp as the fix and this
+        // sentence as the limit of what was confirmed. Bounded below by the margin too, so an
+        // unmeasured sheet reporting 0 cannot pin the FAB flush to the edge either.
+        const avoidDock = dockOpen && !persisted.pinnedByUser;
+        const effectiveBottom = clamp(avoidDock ? Math.max(bottomPx, avoidBottomPx + FAB_EDGE_MARGIN) : bottomPx, FAB_EDGE_MARGIN, Math.max(FAB_EDGE_MARGIN, window.innerHeight - FAB_EDGE_MARGIN - FAB_SIZE_PX));
+        // Same shape, same clamp, and the clamp is load-bearing for the same reason: `avoidRightPx` is
+        // a raw pixel measurement of another element, so a dock wider than the viewport allows would
+        // otherwise push the FAB off the left edge where it looks simply missing.
+        const effectiveRight = clamp(avoidDock ? Math.max(rightPx, avoidRightPx + FAB_EDGE_MARGIN) : rightPx, FAB_EDGE_MARGIN, Math.max(FAB_EDGE_MARGIN, window.innerWidth - FAB_EDGE_MARGIN - FAB_SIZE_PX));
+        return { right: effectiveRight, bottom: effectiveBottom };
+    }, [persisted, dockOpen, avoidBottomPx, avoidRightPx, renderTick, isDragging]);
+    return { style, onPointerDown, consumeDragFlag, isDragging };
+}
+//# sourceMappingURL=fab-position.js.map

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

@@ -1,6 +1,7 @@
+import { type UserTextRedactionOptions } from '../../core/user-text-redaction.js';
 import type { ChatAttachment, ChatMessage } from '../../core/index.js';
 import type { ChatTransport, RunContext } from '../../core/index.js';
-export interface UseConversationOptions {
+export interface UseConversationOptions extends UserTextRedactionOptions {
     transport: ChatTransport;
     initialMessages?: ChatMessage[];
     conversationId?: string | null;
@@ -9,6 +10,8 @@ export interface UseConversationOptions {
     createMessageId?: () => string;
 }
 export interface SendMessageOptions {
+    /** Non-secret signal from a composer that already sanitized the content before this boundary. */
+    secretRedaction?: ChatMessage['secretRedaction'];
     attachments?: ChatAttachment[];
     context?: RunContext;
     agentId?: string;

package/dist/react/hooks/useConversation.js

@@ -1,3 +1,4 @@
+import { redactUserHistory, redactUserMessage } from '../../core/user-text-redaction.js';
 import { preserveAssistantContent, mergeRunEvents } from '../../core/durable-projection.js';
 /**
  * @module useConversation
@@ -23,7 +24,7 @@ function defaultCreateMessageId() {
 }
 export function useConversation(options) {
     const { transport, conversationId = null, agentId, createMessageId = defaultCreateMessageId } = options;
-    const [messages, setMessagesState] = useState(options.initialMessages ?? []);
+    const [messages, setMessagesState] = useState(() => redactUserHistory({ history: options.initialMessages ?? [] }, { ...(options.redactUserText ? { redactUserText: options.redactUserText } : {}) }));
     const [scrollIntent, setScrollIntent] = useState(false);
     const run = useRunStream({ transport });
     // The assistant message id the currently-active run is writing into.
@@ -134,13 +135,14 @@ export function useConversation(options) {
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [run.events, run.status, run.runId]);
     const sendMessage = useCallback(async (content, sendOptions = {}) => {
-        const userMessage = {
-            id: createMessageId(),
-            role: 'user',
-            content,
-            createdAt: Date.now(),
-            ...(sendOptions.attachments ? { attachments: sendOptions.attachments } : {}),
-        };
+        const userMessage = redactUserMessage({ message: {
+                id: createMessageId(),
+                role: 'user',
+                content,
+                createdAt: Date.now(),
+                ...(sendOptions.secretRedaction ? { secretRedaction: sendOptions.secretRedaction } : {}),
+                ...(sendOptions.attachments ? { attachments: sendOptions.attachments } : {}),
+            } }, options).message;
         const resolvedAgentId = sendOptions.agentId ?? agentId;
         const assistantMessage = {
             id: createMessageId(),
@@ -152,7 +154,7 @@ export function useConversation(options) {
             startedAt: Date.now(),
         };
         activeAssistantIdRef.current = assistantMessage.id;
-        const history = [...messagesRef.current, userMessage];
+        const history = redactUserHistory({ history: [...messagesRef.current, userMessage] }, options);
         // Functional, never `[...history, assistantMessage]`: `messagesRef` is the last RENDER's
         // snapshot, and a host that sends from an effect (`useChatPane`'s queued-prompt flush) runs in
         // the same commit as the reconciliation effect that just marked the previous turn terminal.
@@ -169,7 +171,7 @@ export function useConversation(options) {
             ...(sendOptions.attachments !== undefined ? { attachments: sendOptions.attachments } : {}),
             ...(sendOptions.context !== undefined ? { context: sendOptions.context } : {}),
         });
-    }, [agentId, conversationId, createMessageId, run]);
+    }, [agentId, conversationId, createMessageId, run, options.redactUserText, options.onSecretRedacted]);
     const retry = useCallback(async (assistantMessageId) => {
         const idx = messagesRef.current.findIndex((m) => m.id === assistantMessageId);
         if (idx <= 0)
@@ -177,7 +179,7 @@ export function useConversation(options) {
         const priorUser = messagesRef.current[idx - 1];
         if (!priorUser || priorUser.role !== 'user')
             return;
-        const history = messagesRef.current.slice(0, idx);
+        const history = redactUserHistory({ history: messagesRef.current.slice(0, idx) }, options);
         const resetAssistant = { ...messagesRef.current[idx], content: '', events: [], runStatus: 'queued' };
         activeAssistantIdRef.current = resetAssistant.id;
         // Functional for the same reason as `sendMessage`'s: keep a just-queued terminal update.
@@ -200,7 +202,7 @@ export function useConversation(options) {
             conversationId,
             ...(priorUser.attachments !== undefined ? { attachments: priorUser.attachments } : {}),
         });
-    }, [agentId, conversationId, run]);
+    }, [agentId, conversationId, run, options.redactUserText, options.onSecretRedacted]);
     const cancel = useCallback(() => run.cancel(), [run]);
     const acknowledgeScroll = useCallback(() => setScrollIntent(false), []);
     const suppressScroll = useCallback(() => setScrollIntent(false), []);

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

@@ -0,0 +1,11 @@
+import { type SecretRedactionSignal, type UserTextRedactionOptions } from '../../core/user-text-redaction.js';
+/** Shared notice state for composer and question answers. Effects see only a count, never text. */
+export declare function useUserTextGuard(options: UserTextRedactionOptions, _optional?: Record<string, never>): {
+    secretRedacted: boolean;
+    redact: ({ text }: {
+        text: string;
+    }, _options?: {}) => import("../../core/user-text-redaction.js").UserTextRedaction;
+    redactText: (text: string) => string;
+    notifyRedaction: (signal: SecretRedactionSignal) => void;
+};
+//# sourceMappingURL=useUserTextGuard.d.ts.map

package/dist/react/hooks/useUserTextGuard.js

@@ -0,0 +1,19 @@
+import { useCallback, useState } from 'react';
+import { redactUserText } from '../../core/user-text-redaction.js';
+/** Shared notice state for composer and question answers. Effects see only a count, never text. */
+export function useUserTextGuard(options, _optional = {}) {
+    const [secretRedacted, setSecretRedacted] = useState(false);
+    const notifyRedaction = useCallback((signal) => {
+        setSecretRedacted(true);
+        options.onSecretRedacted?.(signal);
+    }, [options.onSecretRedacted]);
+    const redact = useCallback(({ text }, _options = {}) => {
+        const result = (options.redactUserText ?? redactUserText)({ text }, {});
+        if (result.secretRedacted)
+            notifyRedaction({ secretRedacted: true, count: result.count });
+        return result;
+    }, [options.redactUserText, notifyRedaction]);
+    const redactText = useCallback((text) => redact({ text }, {}).text, [redact]);
+    return { secretRedacted, redact, redactText, notifyRedaction };
+}
+//# sourceMappingURL=useUserTextGuard.js.map

package/dist/react/index.d.ts

@@ -1,25 +1,7 @@
 /**
- * @jini-ai/chat-react — headless hooks + presentational components + slots for
- * a chat/artifact frontend, built on `@jini-ai/chat/core`'s framework-free
- * vocabulary. See ADS-memory/reports/jini-port/recon/r4b-webui-design.md §1/§2/§4 for the
- * spec this package implements, and archived provenance ledger for provenance.
- *
- * This barrel is filled in incrementally as each layer lands (hooks first,
- * then presentational components, then the `<JiniChatProvider>` composition
- * root) — see archived provenance ledger's "Status" section for what's shipped so far.
- *
- * ## Every export here is explicit. Do not reintroduce `export *`.
- *
- * This file used 15 `export * from` statements until 2026-08-05. That made the package's public
- * API *implicit*: whatever any of those modules happened to export was public, so renaming an
- * internal helper shipped a breaking change nobody reviewed, and no one could read this file and
- * say what the package exports. It is also the likeliest reason consumers reach past this barrel
- * into `@jini-ai/chat/core` deep paths — a grab-bag invites bypassing.
- *
- * The expansion was mechanical and provably surface-preserving: 193 symbols before and after,
- * identical in name AND in value-vs-type kind. `features/chat-pane/index.ts` is the style model.
- *
- * When adding an export, add the name here deliberately. That edit IS the API review.
+ * @jini-ai/chat/react — headless hooks, presentational components and slots over framework-free
+ * chat/core vocabulary. Every export is explicit: adding or renaming a name here is a public API
+ * review, so internal module exports cannot silently become public. Do not use export *.
  */
 export type { ChatTransport, FeedbackChange, OnFeedback, ReattachRunOptions, RunContext, RunHandlers, StartRunInput, } from '../core/index.js';
 export { RendererRegistry, } from './artifact-types.js';
@@ -165,4 +147,13 @@ export type { FrontendSessionBridge, FrontendSessionBridgeArgs, FrontendSessionB
 export { createDomPageDriver, currentAgentPage, type DomPageDriverOptions } from '@jini-ai/agentic/dom';
 export { createBrowserComposerHistoryStorage } from './hooks/composer-history-storage.js';
 export type { ComposerHistoryStoragePort } from '../core/composer-history.js';
+export { SECRET_REDACTED_NOTICE, redactUserText } from '../core/user-text-redaction.js';
+export type { UserTextRedactionOptions } from '../core/user-text-redaction.js';
+export { useUserTextGuard } from './hooks/useUserTextGuard.js';
+export { cacheAttachmentPreviewSource } from './hooks/attachment-preview-cache.js';
+export { readCachedAttachmentBatchId, writeCachedAttachmentBatchId } from './hooks/composer-draft-cache.js';
+export { createAssistantChatsClient } from "./hooks/assistant-chats.js";
+export type { AssistantChatsPort, AssistantChatsClientPorts, AssistantChatsClient, UseAssistantChats } from "./hooks/assistant-chats-contracts.js";
+export { useFabPosition } from "./hooks/fab-position.js";
+export type { FabPositionInput, FabPositionResult } from "./hooks/fab-position.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.js

@@ -122,4 +122,11 @@ export { JiniChatProvider, useJiniChatSlots, useOnFeedback } from './components/
 export { createFrontendSessionBridge } from './agent-bridge/frontend-session-bridge.js';
 export { createDomPageDriver, currentAgentPage } from '@jini-ai/agentic/dom';
 export { createBrowserComposerHistoryStorage } from './hooks/composer-history-storage.js';
+// ChatPane consumers share the same redaction and draft/preview state owners.
+export { SECRET_REDACTED_NOTICE, redactUserText } from '../core/user-text-redaction.js';
+export { useUserTextGuard } from './hooks/useUserTextGuard.js';
+export { cacheAttachmentPreviewSource } from './hooks/attachment-preview-cache.js';
+export { readCachedAttachmentBatchId, writeCachedAttachmentBatchId } from './hooks/composer-draft-cache.js';
+export { createAssistantChatsClient } from "./hooks/assistant-chats.js";
+export { useFabPosition } from "./hooks/fab-position.js";
 //# sourceMappingURL=index.js.map

package/dist/server/durable-runs/accept.d.ts

@@ -0,0 +1,25 @@
+import type { AcceptedRunRequest, DurableRun, DurableRunStore } from "../../core/durable-runs/ports.js";
+export interface RunAcceptancePorts {
+    readonly store: DurableRunStore;
+    /** Sanitize the host envelope before it is durably accepted. */
+    readonly sanitizeContextRef: (required: {
+        contextRef: string;
+    }, optional: {}) => string;
+    readonly now: () => number;
+    readonly mintRunId: () => string;
+    readonly launch: (required: {
+        run: DurableRun;
+        request: AcceptedRunRequest;
+    }, optional: {}) => Promise<void>;
+    readonly attach: (required: DurableRun, optional: {}) => void;
+}
+export declare function createRunAcceptance(ports: RunAcceptancePorts, _optional?: {}): {
+    accept(required: {
+        principalId: string;
+        workspaceId: string;
+        conversationId: string;
+        messageId: string;
+        request: AcceptedRunRequest;
+    }, _options?: {}): Promise<DurableRun | null>;
+};
+//# sourceMappingURL=accept.d.ts.map