@schlessera/brain-ui-react 0.12.1 → 0.13.1

package/src/components/viewer/zoom-viewer.tsx

@@ -0,0 +1,354 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { Minus, Plus, Maximize2, X } from "lucide-react";
+
+/**
+ * Full-screen, pan-and-zoom view of one visual thing — a diagram, an image,
+ * anything with a natural pixel size. Callers supply the content and any extra
+ * toolbar actions; everything about the gesture surface lives here.
+ *
+ * Hand-rolled on pointer events rather than pulling a pan/zoom library: the
+ * whole surface is two transforms and the repo has no other dependency of that
+ * shape. Touch gestures work because the stage sets `touch-action: none` —
+ * the browser hands us every pointer instead of scrolling the page, which is
+ * also why no preventDefault is needed on the touch path. Wheel is the one
+ * exception: React's onWheel is passive, so it is bound manually.
+ */
+
+const MIN_SCALE = 0.15;
+const MAX_SCALE = 12;
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+function clampScale(s: number): number {
+  return Math.min(MAX_SCALE, Math.max(MIN_SCALE, s));
+}
+
+export interface ZoomViewerProps {
+  children: React.ReactNode;
+  onClose: () => void;
+  /**
+   * Extra toolbar nodes, placed left of the close button — typically a share
+   * menu. Rendered inside the header, above the stage.
+   */
+  actions?: React.ReactNode;
+  /**
+   * Changes when the content's natural size may have changed (a streaming
+   * diagram growing, an image finishing its decode). Re-fits, but only while
+   * the user has not panned or zoomed — after that nothing moves behind them.
+   */
+  refitKey?: unknown;
+  /**
+   * Ceiling on the scale `fit()` may choose. Small diagrams may grow to fill
+   * the stage (blowing one up 8x reads as broken, hence a cap), but a raster
+   * image has real pixels: opening it above 100% only shows interpolation, so
+   * image callers pass 1.
+   */
+  maxFitScale?: number;
+  /** Aria label for the overlay. */
+  label?: string;
+}
+
+export function ZoomViewer({
+  children,
+  onClose,
+  actions,
+  refitKey,
+  maxFitScale = 2.5,
+  label = "Zoomed view",
+}: ZoomViewerProps) {
+  const stageRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState(1);
+  const [offset, setOffset] = useState<Point>({ x: 0, y: 0 });
+  const [ready, setReady] = useState(false);
+
+  // Live gesture state lives in refs: pointer maths must not wait for a render.
+  const pointers = useRef(new Map<number, Point>());
+  const pinch = useRef<{ dist: number; center: Point } | null>(null);
+  const panFrom = useRef<{ pointer: Point; offset: Point } | null>(null);
+  const view = useRef({ scale: 1, offset: { x: 0, y: 0 } });
+  /** The scale `fit()` last produced — the baseline double-click toggles against. */
+  const fitScale = useRef(1);
+  /** Set once the user pans/zooms; after that nothing may re-fit behind their back. */
+  const touched = useRef(false);
+
+  const apply = useCallback((next: { scale: number; offset: Point }) => {
+    view.current = next;
+    setScale(next.scale);
+    setOffset(next.offset);
+  }, []);
+
+  /** Natural (untransformed) size of the content — offsetWidth ignores transforms. */
+  const natural = useCallback((): { w: number; h: number } | null => {
+    const el = contentRef.current;
+    if (!el || !el.offsetWidth || !el.offsetHeight) return null;
+    return { w: el.offsetWidth, h: el.offsetHeight };
+  }, []);
+
+  const fit = useCallback(() => {
+    const stage = stageRef.current;
+    const size = natural();
+    if (!stage || !size) return;
+    const pad = 32;
+    const sx = (stage.clientWidth - pad * 2) / size.w;
+    const sy = (stage.clientHeight - pad * 2) / size.h;
+    const next = clampScale(Math.min(maxFitScale, Math.min(sx, sy)));
+    fitScale.current = next;
+    apply({
+      scale: next,
+      offset: {
+        x: (stage.clientWidth - size.w * next) / 2,
+        y: (stage.clientHeight - size.h * next) / 2,
+      },
+    });
+  }, [apply, natural, maxFitScale]);
+
+  useLayoutEffect(() => {
+    // Re-runs when the content itself changes, which happens while a message is
+    // still streaming — so a user who has already panned keeps their view.
+    if (!touched.current) fit();
+    setReady(true);
+  }, [fit, refitKey]);
+
+  /** Zoom about a stage-local anchor, so the point under the cursor/fingers stays put. */
+  const zoomAt = useCallback(
+    (factor: number, anchor: Point) => {
+      // Any deliberate zoom counts as touching the view — including the
+      // toolbar buttons and the wheel. Without this, content that is still
+      // streaming would re-fit itself out from under the reader's zoom.
+      touched.current = true;
+      const { scale: prev, offset: prevOffset } = view.current;
+      const next = clampScale(prev * factor);
+      if (next === prev) return;
+      const ratio = next / prev;
+      apply({
+        scale: next,
+        offset: {
+          x: anchor.x - (anchor.x - prevOffset.x) * ratio,
+          y: anchor.y - (anchor.y - prevOffset.y) * ratio,
+        },
+      });
+    },
+    [apply]
+  );
+
+  const zoomCenter = useCallback(
+    (factor: number) => {
+      const stage = stageRef.current;
+      if (!stage) return;
+      zoomAt(factor, { x: stage.clientWidth / 2, y: stage.clientHeight / 2 });
+    },
+    [zoomAt]
+  );
+
+  const stagePoint = (e: { clientX: number; clientY: number }): Point => {
+    const rect = stageRef.current?.getBoundingClientRect();
+    return { x: e.clientX - (rect?.left ?? 0), y: e.clientY - (rect?.top ?? 0) };
+  };
+
+  // Wheel must be bound manually: React's onWheel is passive, so it cannot
+  // preventDefault, and the page behind would scroll (or the browser would
+  // pinch-zoom the whole PWA on a ctrl+wheel trackpad gesture).
+  useEffect(() => {
+    const stage = stageRef.current;
+    if (!stage) return;
+    const onWheel = (e: WheelEvent) => {
+      e.preventDefault();
+      // A trackpad pinch arrives as ctrlKey+wheel with small deltas; a mouse
+      // wheel arrives as coarse notches. Both map to the same exponential.
+      const factor = Math.exp(-e.deltaY * (e.ctrlKey ? 0.01 : 0.0015));
+      zoomAt(factor, stagePoint(e));
+    };
+    stage.addEventListener("wheel", onWheel, { passive: false });
+    return () => stage.removeEventListener("wheel", onWheel);
+  }, [zoomAt]);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+      else if (e.key === "+" || e.key === "=") zoomCenter(1.25);
+      else if (e.key === "-" || e.key === "_") zoomCenter(0.8);
+      else if (e.key === "0") fit();
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [onClose, zoomCenter, fit]);
+
+  // Lock body scroll while open.
+  useEffect(() => {
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.body.style.overflow = prev;
+    };
+  }, []);
+
+  // Re-fit on rotation / resize only while the view is untouched, so a resize
+  // never yanks content the user has deliberately panned into place.
+  useEffect(() => {
+    const onResize = () => {
+      if (!touched.current) fit();
+    };
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [fit]);
+
+  const onPointerDown = (e: React.PointerEvent) => {
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    pointers.current.set(e.pointerId, stagePoint(e));
+    if (pointers.current.size === 2) {
+      const [a, b] = [...pointers.current.values()];
+      pinch.current = {
+        dist: Math.hypot(a.x - b.x, a.y - b.y),
+        center: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 },
+      };
+      panFrom.current = null;
+    } else if (pointers.current.size === 1) {
+      panFrom.current = { pointer: stagePoint(e), offset: view.current.offset };
+    }
+  };
+
+  const onPointerMove = (e: React.PointerEvent) => {
+    if (!pointers.current.has(e.pointerId)) return;
+    const p = stagePoint(e);
+    pointers.current.set(e.pointerId, p);
+
+    if (pointers.current.size >= 2 && pinch.current) {
+      const [a, b] = [...pointers.current.values()];
+      const dist = Math.hypot(a.x - b.x, a.y - b.y);
+      const center = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
+      if (pinch.current.dist > 0) {
+        touched.current = true;
+        // Pan and zoom in one step: the midpoint drift moves the content, the
+        // distance ratio scales it about that same midpoint.
+        const drift = {
+          x: center.x - pinch.current.center.x,
+          y: center.y - pinch.current.center.y,
+        };
+        // Committed through apply(), not written straight to the ref: two
+        // fingers moving in parallel (or a pinch already clamped at min/max)
+        // produce no scale change, and zoomAt() returns early — the drift
+        // would then be stranded in the ref and nothing would pan.
+        apply({
+          scale: view.current.scale,
+          offset: {
+            x: view.current.offset.x + drift.x,
+            y: view.current.offset.y + drift.y,
+          },
+        });
+        zoomAt(dist / pinch.current.dist, center);
+      }
+      pinch.current = { dist, center };
+      return;
+    }
+
+    if (panFrom.current) {
+      touched.current = true;
+      apply({
+        scale: view.current.scale,
+        offset: {
+          x: panFrom.current.offset.x + (p.x - panFrom.current.pointer.x),
+          y: panFrom.current.offset.y + (p.y - panFrom.current.pointer.y),
+        },
+      });
+    }
+  };
+
+  const endPointer = (e: React.PointerEvent) => {
+    pointers.current.delete(e.pointerId);
+    if (pointers.current.size >= 2) {
+      // Still pinching, but with a DIFFERENT pair (a stray third touch got
+      // lifted). Rebase the baseline, or the next move would compare the new
+      // pair's spread against the old pair's and jump.
+      const [a, b] = [...pointers.current.values()];
+      pinch.current = {
+        dist: Math.hypot(a.x - b.x, a.y - b.y),
+        center: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 },
+      };
+      return;
+    }
+    pinch.current = null;
+    if (pointers.current.size === 1) {
+      // Lifting one finger of a pinch must not teleport the content: re-anchor
+      // the pan to whichever pointer is still down.
+      const [remaining] = [...pointers.current.values()];
+      panFrom.current = { pointer: remaining, offset: view.current.offset };
+    } else if (pointers.current.size === 0) {
+      panFrom.current = null;
+    }
+  };
+
+  const onDoubleClick = (e: React.MouseEvent) => {
+    touched.current = true;
+    // Compared against the FIT scale, not against 1: content that fits at 125%
+    // would otherwise read as "already zoomed" and double-click would re-fit it
+    // to exactly where it already was.
+    if (view.current.scale > fitScale.current * 1.05) fit();
+    else zoomAt(2, stagePoint(e));
+  };
+
+  const btn =
+    "flex h-9 w-9 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-surface-raised hover:text-foreground";
+
+  // Portalled to <body>: message bubbles animate through framer-motion, and a
+  // transformed ancestor becomes the containing block for `fixed`, which would
+  // pin this overlay to the bubble instead of the viewport.
+  return createPortal(
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={label}
+      className="fixed inset-0 z-50 flex flex-col bg-background/95 backdrop-blur-sm"
+    >
+      <div
+        className="flex items-center justify-between gap-2 border-b border-border/60 px-3 py-2"
+        style={{ paddingTop: "calc(0.5rem + env(safe-area-inset-top))" }}
+      >
+        <span className="px-1 font-[family-name:var(--font-mono)] text-xs tabular-nums text-muted-foreground">
+          {Math.round(scale * 100)}%
+        </span>
+        <div className="flex items-center gap-1">
+          <button type="button" title="Zoom out" onClick={() => zoomCenter(0.8)} className={btn}>
+            <Minus className="h-4 w-4" />
+          </button>
+          <button type="button" title="Zoom in" onClick={() => zoomCenter(1.25)} className={btn}>
+            <Plus className="h-4 w-4" />
+          </button>
+          <button type="button" title="Fit to screen" onClick={fit} className={btn}>
+            <Maximize2 className="h-4 w-4" />
+          </button>
+          {actions}
+          <button type="button" title="Close" onClick={onClose} className={btn}>
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+      </div>
+
+      <div
+        ref={stageRef}
+        className="relative flex-1 cursor-grab touch-none overflow-hidden active:cursor-grabbing [&_img]:max-w-none [&_svg]:max-w-none"
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={endPointer}
+        onPointerCancel={endPointer}
+        onDoubleClick={onDoubleClick}
+      >
+        <div
+          ref={contentRef}
+          className="absolute left-0 top-0 origin-top-left"
+          style={{
+            transform: `translate(${offset.x}px, ${offset.y}px) scale(${scale})`,
+            visibility: ready ? "visible" : "hidden",
+          }}
+        >
+          {children}
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}

package/src/hooks/use-share-intake.ts

@@ -0,0 +1,190 @@
+import { useCallback, useEffect } from "react";
+import {
+  SHARE_STASH_TTL_MS,
+  type ShareIntakeResult,
+} from "@schlessera/brain-ui-sdk/protocol";
+import {
+  getShareStore,
+  pruneStoredShares,
+  readShareLaunchParams,
+  type StoredShare,
+} from "@schlessera/brain-ui-sdk/share-target";
+import { useChatStore } from "../stores/chat-store.js";
+import { useConnectionStore } from "../stores/connection-store.js";
+import { useShareStore } from "../stores/share-store.js";
+import { detectClientEnvironment } from "../lib/client-environment.js";
+import {
+  buildSharePrompt,
+  describeShareError,
+  describeUploadError,
+  dropShareClaim,
+  persistShareClaim,
+  readShareClaims,
+  shareImagesToAttachments,
+  uploadShare,
+} from "../lib/share-intake.js";
+import { sendClientMessage } from "./use-websocket.js";
+
+/**
+ * Pick up shares the service worker stashed, and file them once confirmed.
+ *
+ * Deliberately thin: every decision lives in `lib/share-intake.ts`, which is
+ * testable without a DOM. What is left here is the browser-only part — reading
+ * the launch URL, rewriting it, and driving the stores.
+ */
+
+/**
+ * Move `?share=<id>` out of the URL and into a durable claim.
+ *
+ * The parameter cannot stay: the shell reloads the page when a new service
+ * worker takes over, a reload preserves the query string, and a second pass
+ * over the same id while the first upload is in flight would file the share
+ * twice. (The claim is belt; `store.take()` is braces — it hands the record to
+ * exactly one caller.)
+ */
+function claimFromLocation(): { claimed: string[]; error?: string } {
+  if (typeof window === "undefined") return { claimed: [] };
+  const { shareId, error } = readShareLaunchParams(window.location.href);
+  if (shareId) {
+    persistShareClaim(shareId);
+    const url = new URL(window.location.href);
+    url.searchParams.delete("share");
+    url.searchParams.delete("share_error");
+    history.replaceState(null, "", url.toString());
+  } else if (error) {
+    const url = new URL(window.location.href);
+    url.searchParams.delete("share_error");
+    history.replaceState(null, "", url.toString());
+  }
+  return {
+    claimed: readShareClaims(),
+    ...(error ? { error: describeShareError(error) } : {}),
+  };
+}
+
+export function useShareIntake(): {
+  confirm: (record: StoredShare) => Promise<void>;
+  dismiss: (record: StoredShare) => void;
+} {
+  const enqueue = useShareStore((s) => s.enqueue);
+  const remove = useShareStore((s) => s.remove);
+  const setBusy = useShareStore((s) => s.setBusy);
+  const setError = useShareStore((s) => s.setError);
+  const setNotes = useShareStore((s) => s.setNotes);
+
+  useEffect(() => {
+    let disposed = false;
+    const { claimed, error } = claimFromLocation();
+    if (error) setError(error);
+
+    void (async () => {
+      const store = getShareStore();
+      try {
+        for (const id of claimed) {
+          const record = await store.take(id);
+          dropShareClaim(id);
+          if (record && !disposed) enqueue(record);
+        }
+
+        // Orphans: a share whose landing page never ran (the app opened
+        // offline on the fallback page, or the tab was closed before the
+        // parameter was read) leaves a record nobody holds the id for. The
+        // stash is the only place it still exists.
+        for (const record of await store.list()) {
+          const taken = await store.take(record.id);
+          if (taken && !disposed) enqueue(taken);
+        }
+
+        // The service worker's own prune runs after a stash, so it can never
+        // reach the newest record. This pass can.
+        await pruneStoredShares(store, SHARE_STASH_TTL_MS);
+      } catch (err) {
+        if (!disposed) {
+          setError(err instanceof Error ? err.message : "Could not read stashed shares");
+        }
+      }
+    })();
+
+    return () => {
+      disposed = true;
+    };
+  }, [enqueue, setError]);
+
+  const confirm = useCallback(
+    async (record: StoredShare) => {
+      const share = useShareStore.getState();
+      if (share.busy) return;
+      if (useConnectionStore.getState().wsStatus !== "connected") {
+        setError("Not connected yet — this will work as soon as the app reconnects.");
+        return;
+      }
+
+      setBusy(true);
+      setError(null);
+      setNotes([]);
+      try {
+        const outcome = await uploadShare(record);
+        if (!outcome.ok) {
+          setError(describeUploadError(outcome));
+          return;
+        }
+
+        const { attachments, errors } = await shareImagesToAttachments(record.files);
+        if (errors.length) setNotes(errors);
+
+        const prompt = buildSharePrompt(outcome.result as ShareIntakeResult);
+        const chat = useChatStore.getState();
+        // Always start from a fresh draft: `activeSessionId` is restored from
+        // localStorage at store creation, so on a cold boot it already points
+        // at whatever session was last open.
+        chat.clearMessages();
+        // Ownership of the preview URLs transfers to the message here — the
+        // chat store revokes them. Nothing below may revoke them again.
+        chat.addUserMessage(
+          null,
+          prompt,
+          "typed",
+          attachments.length
+            ? attachments.map((a) => ({
+                previewUrl: a.previewUrl,
+                mediaType: a.attachment.mediaType,
+              }))
+            : undefined
+        );
+        chat.startAssistantMessage(null);
+
+        const sent = sendClientMessage({
+          type: "chat_message",
+          text: prompt,
+          ...(attachments.length
+            ? { attachments: attachments.map((a) => a.attachment) }
+            : {}),
+          ...(detectClientEnvironment() ? { client: detectClientEnvironment() } : {}),
+        });
+        if (!sent) {
+          setError("The connection dropped before that could be sent.");
+          return;
+        }
+
+        remove(record.id);
+        dropShareClaim(record.id);
+      } finally {
+        setBusy(false);
+      }
+    },
+    [remove, setBusy, setError, setNotes]
+  );
+
+  const dismiss = useCallback(
+    (record: StoredShare) => {
+      remove(record.id);
+      dropShareClaim(record.id);
+      setError(null);
+      // Already taken out of the stash when it was claimed; dropping the queue
+      // entry is what discards it.
+    },
+    [remove, setError]
+  );
+
+  return { confirm, dismiss };
+}

package/src/hooks/use-websocket.ts

@@ -106,7 +106,11 @@ export function handleServerMessage(msg: ServerMessage) {
   // session's pre-binding frames) apply to the buffer in view.
   const frameSessionId = (msg as { sessionId?: string }).sessionId;
   if (frameSessionId) {
-    state.setRunState(frameSessionId, runStateForFrame(msg));
+    // `detail` on a queued status is the host's queue-pressure note; it rides
+    // along so the session's badge can show WHY it is queued deep.
+    const queueNote =
+      msg.type === "status" && msg.status === "queued" ? msg.detail : undefined;
+    state.setRunState(frameSessionId, runStateForFrame(msg), queueNote);
   }
 
   // Resolve the target buffer key for this frame.
@@ -380,6 +384,25 @@ function handleStatusChange(status: "connecting" | "connected" | "disconnected")
 // Singleton client - survives React re-renders
 let wsClient: WSClient | null = null;
 
+/**
+ * Send on the live socket from outside a component.
+ *
+ * `useWebSocket()` OWNS the socket — its construction guard is a per-instance
+ * ref, so a second caller would build a second client, overwrite this
+ * singleton, and orphan the first; unmounting either one would then close the
+ * socket for both. Anything that needs to send but not to own (the share
+ * intake) goes through here instead of calling the hook again.
+ *
+ * Returns false when there is no open socket, since `WSClient.send` drops
+ * silently in that case and a caller that just staged an upload needs to know.
+ */
+export function sendClientMessage(msg: ClientMessage): boolean {
+  if (!wsClient) return false;
+  if (useConnectionStore.getState().wsStatus !== "connected") return false;
+  wsClient.send(msg);
+  return true;
+}
+
 export function useWebSocket() {
   const initialized = useRef(false);
 

package/src/index.ts

@@ -46,9 +46,29 @@ export { useConnectionStore } from "./stores/connection-store.js";
 export { useProviderStore } from "./stores/provider-store.js";
 export { useVoiceStore } from "./voice/voice-store.js";
 
+// A stand-in for the system share sheet, so the share-target path can be
+// exercised without reinstalling the PWA. Meant for a dev route — it lists and
+// deletes stashed shares — so the shell should gate it behind a DEV check
+// rather than linking it from the app.
+export { ShareHarness } from "./components/dev/share-harness.js";
+
 // Connectivity probes.
 export { useVpnStatus } from "./hooks/use-vpn-status.js";
-export { useWebSocket, handleServerMessage, runStateForFrame } from "./hooks/use-websocket.js";
+export {
+  useWebSocket,
+  sendClientMessage,
+  handleServerMessage,
+  runStateForFrame,
+} from "./hooks/use-websocket.js";
+
+// Share intake. The shell needs `hasPendingShare` for its service-worker
+// reload guard: reloading mid-intake would file a share twice or lose it.
+export {
+  useShareStore,
+  hasPendingShare,
+  type ShareIntakeState,
+} from "./stores/share-store.js";
+export { ShareIntake } from "./components/chat/share-card.js";
 
 // API surface (typed REST client + backend URL helpers).
 export { api } from "./lib/api-client.js";