rift-ds 1.7.0 → 1.8.0

package/chat/starters.d.ts

@@ -0,0 +1,15 @@
+import { Starter } from './types';
+export type { Starter };
+/** How many chips the welcome screen shows, drawn from a pool. */
+export declare const STARTER_COUNT = 3;
+/** The named wording when it fits the chip, the unnamed one when it does not. */
+export declare const namedStarter: (withName: string, without: string) => string;
+export declare function hashString(input: string): number;
+export declare function mulberry32(seed: number): () => number;
+/**
+ * Draw STARTER_COUNT starters from a pool, deterministically for a given
+ * (seed, key) pair. A null seed returns the head of the pool unshuffled:
+ * pools lead with their strongest questions, so callers without a seed (and
+ * a server, if one ever renders this) get the curated order.
+ */
+export declare function pickStarters(pool: Starter[], seed: number | null, key: string): Starter[];

package/chat/starters.js

@@ -0,0 +1,38 @@
+import { fitsChip } from "./suggestions.js";
+const STARTER_COUNT = 3;
+const namedStarter = (withName, without) => fitsChip(withName) ? withName : without;
+function hashString(input) {
+  let hash = 2166136261;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+function mulberry32(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 | 0;
+    let t = Math.imul(state ^ state >>> 15, 1 | state);
+    t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t;
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function pickStarters(pool, seed, key) {
+  if (pool.length <= STARTER_COUNT) return pool;
+  if (seed === null) return pool.slice(0, STARTER_COUNT);
+  const rand = mulberry32(hashString(key) ^ Math.floor(seed * 4294967295));
+  const shuffled = [...pool];
+  for (let i = shuffled.length - 1; i > 0; i -= 1) {
+    const j = Math.floor(rand() * (i + 1));
+    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+  }
+  return shuffled.slice(0, STARTER_COUNT);
+}
+export {
+  STARTER_COUNT,
+  hashString,
+  mulberry32,
+  namedStarter,
+  pickStarters
+};

package/chat/suggestions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The chip budget for chat suggestions, in one place.
+ *
+ * Every suggestion the chat offers renders as a Chip inside PromptSuggestions,
+ * whether it is a conversation starter on the welcome screen or a follow-up
+ * question under an answer. A chip never wraps, which is what makes it a pill
+ * rather than a paragraph, so a label longer than the column runs past the
+ * edge of a docked panel and reads as broken.
+ *
+ * The narrowest place a suggestion is shown is a phone, where the panel drops
+ * its card chrome and fills the viewport: a 375px screen leaves the message
+ * column 362px, and this is the label length that fits it. A docked panel on
+ * a desktop is wider and has room to spare. Measured, not guessed: 44
+ * characters renders at 376px and runs past the edge of a small phone, which
+ * is what this number is set below.
+ *
+ * Every producer of a suggestion checks against it. A suggestion that will
+ * not fit is dropped, never truncated: half a question is not a question.
+ */
+export declare const SUGGESTION_MAX_CHARS = 40;
+/** Whether a suggestion label is one the chip row can actually show. */
+export declare function fitsChip(label: string): boolean;

package/chat/suggestions.js

@@ -0,0 +1,9 @@
+const SUGGESTION_MAX_CHARS = 40;
+function fitsChip(label) {
+  const trimmed = label.trim();
+  return trimmed !== "" && trimmed.length <= SUGGESTION_MAX_CHARS;
+}
+export {
+  SUGGESTION_MAX_CHARS,
+  fitsChip
+};

package/chat/threads.d.ts

@@ -0,0 +1,73 @@
+import { ThreadPanelGroup, ThreadPanelProject, ThreadPanelThread, ThreadPanelThreadAction } from '../components/ThreadPanel/ThreadPanel';
+import { ThreadTab } from '../components/ThreadTabs/ThreadTabs';
+import { ChatState } from './useChat';
+/**
+ * How long the shimmer runs after the first utterance before the name
+ * "arrives". Paced like a fast title-generation call, not a UI transition,
+ * so it is a schedule rather than a motion token.
+ */
+export declare const THREAD_NAMING_DELAY_MS = 1600;
+export interface ThreadsOptions {
+    /** The history to start from. The groups' labels are the host's. */
+    groups?: ThreadPanelGroup[];
+    /** The projects section, when the rail shows one. */
+    projects?: ThreadPanelProject[];
+    /** The group pinned threads move into. Created on first pin when absent. */
+    pinnedGroup?: string;
+    /** The group a new thread is born into. Defaults to the first non-pinned group. */
+    homeGroup?: string;
+    /**
+     * The name a new thread gets once its shimmer resolves. Called with the
+     * thread's ordinal; a host with a real title generator returns a promise.
+     */
+    nameThread?: (index: number) => string | Promise<string>;
+    /** How long the naming shimmer runs. */
+    namingDelayMs?: number;
+    /** Offer pin and unpin in each row's menu, and keep the pinned group. */
+    pins?: boolean;
+    /** Keep each row's detail anatomy (description, status, icon, meta). Off strips rows to bare titles. */
+    details?: boolean;
+    /** The label of the New chat row and tab. */
+    newThreadLabel?: string;
+    /** Called when a thread is selected, so a host can load its conversation. */
+    onSelect?: (threadId: string) => void;
+    onRename?: (threadId: string, title: string) => void;
+    onDelete?: (threadId: string) => void;
+    onPin?: (threadId: string, pinned: boolean) => void;
+}
+/** The thread lifecycle, shaped for ThreadPanel and ThreadTabs. */
+export interface ThreadsState {
+    /** The groups to hand ThreadPanel, shaped by the pins and details options. */
+    groups: ThreadPanelGroup[];
+    /** The selected thread, or '' on the greeting screen. */
+    activeThreadId: string;
+    /** Select a thread (and open its tab). */
+    select: (threadId: string) => void;
+    /** Back to the greeting: resets the conversation and deselects. */
+    startNew: () => void;
+    remove: (threadId: string) => void;
+    rename: (threadId: string, title: string) => void;
+    togglePin: (threadId: string) => void;
+    /** The thread whose row is showing the inline rename editor. */
+    renamingId: string | null;
+    setRenamingId: (threadId: string | null) => void;
+    /** Each row's overflow menu: pin or unpin (when pins are on), rename, delete. */
+    actionsFor: (thread: ThreadPanelThread) => ThreadPanelThreadAction[];
+    /** Run a row action by id: 'pin', 'rename' or 'delete'. */
+    runAction: (threadId: string, actionId: string) => void;
+    projects: ThreadPanelProject[];
+    activeProjectId: string | undefined;
+    selectProject: (projectId: string) => void;
+    createProject: () => void;
+    /** The open sessions, for ThreadTabs. Resolved live from the groups. */
+    tabs: ThreadTab[];
+    closeTab: (threadId: string) => void;
+    newThreadLabel: string;
+}
+/**
+ * The thread lifecycle over a conversation. `chat` is the state from
+ * `useChat` (the provider passes its own); the hook watches whether the
+ * conversation has an utterance to decide when a thread is born and when
+ * the selection clears.
+ */
+export declare function useThreads(chat: Pick<ChatState, 'turns' | 'live' | 'reset'>, options?: ThreadsOptions): ThreadsState;

package/chat/threads.js

@@ -0,0 +1,270 @@
+"use client";
+import { useMemo, useState, useRef, useEffect, useCallback } from "react";
+const THREAD_NAMING_DELAY_MS = 1600;
+const RENAME_ACTION = { id: "rename", label: "Rename", icon: "edit" };
+const DELETE_ACTION = {
+  id: "delete",
+  label: "Delete",
+  icon: "delete",
+  destructive: true
+};
+const DEFAULT_NAMES = ["New conversation"];
+function useThreads(chat, options = {}) {
+  const {
+    pins = true,
+    details = true,
+    namingDelayMs = THREAD_NAMING_DELAY_MS,
+    newThreadLabel = "New chat",
+    pinnedGroup = "Pinned",
+    onSelect,
+    onRename,
+    onDelete,
+    onPin
+  } = options;
+  const nameThreadOption = options.nameThread;
+  const nameThread = useMemo(
+    () => nameThreadOption ?? ((index) => DEFAULT_NAMES[index % DEFAULT_NAMES.length]),
+    [nameThreadOption]
+  );
+  const initialGroups = options.groups ?? [];
+  const homeGroup = options.homeGroup ?? initialGroups.find((group) => group.label !== pinnedGroup)?.label ?? "Recent";
+  const [groups, setGroups] = useState(initialGroups);
+  const [activeThreadId, setActiveThreadId] = useState("");
+  const [renamingId, setRenamingId] = useState(null);
+  const [projects, setProjects] = useState(options.projects ?? []);
+  const [activeProjectId, setActiveProjectId] = useState(
+    options.projects?.[0]?.id
+  );
+  const [openTabs, setOpenTabs] = useState([]);
+  const threadSeq = useRef(0);
+  const nameCursor = useRef(0);
+  const projectSeq = useRef(0);
+  const namingTimers = useRef(/* @__PURE__ */ new Map());
+  useEffect(() => {
+    const timers = namingTimers.current;
+    return () => timers.forEach((timer) => clearTimeout(timer));
+  }, []);
+  const updateThread = useCallback(
+    (id, patch) => {
+      setGroups(
+        (current) => current.map((group) => ({
+          ...group,
+          threads: group.threads.map((thread) => thread.id === id ? patch(thread) : thread)
+        }))
+      );
+    },
+    []
+  );
+  const beginThread = useCallback(() => {
+    threadSeq.current += 1;
+    const id = `thread-${threadSeq.current}`;
+    setGroups((current) => {
+      const hasHome = current.some((group) => group.label === homeGroup);
+      const withHome = hasHome ? current : [...current, { label: homeGroup, threads: [] }];
+      return withHome.map(
+        (group) => group.label === homeGroup ? { ...group, threads: [{ id, title: newThreadLabel, pending: true }, ...group.threads] } : group
+      );
+    });
+    setActiveThreadId(id);
+    setOpenTabs((tabs2) => tabs2.includes(id) ? tabs2 : [...tabs2, id]);
+    const ordinal = nameCursor.current;
+    nameCursor.current += 1;
+    const timer = setTimeout(async () => {
+      namingTimers.current.delete(id);
+      const title = await nameThread(ordinal);
+      updateThread(id, () => ({ id, title }));
+    }, namingDelayMs);
+    namingTimers.current.set(id, timer);
+  }, [homeGroup, nameThread, namingDelayMs, newThreadLabel, updateThread]);
+  const hasUtterance = chat.turns.length > 0 || chat.live !== null;
+  const hadUtteranceRef = useRef(hasUtterance);
+  const birthingRef = useRef(false);
+  useEffect(() => {
+    const had = hadUtteranceRef.current;
+    hadUtteranceRef.current = hasUtterance;
+    if (hasUtterance && activeThreadId === "") {
+      if (!birthingRef.current) {
+        birthingRef.current = true;
+        beginThread();
+      }
+    } else {
+      birthingRef.current = false;
+      if (!hasUtterance && had && activeThreadId !== "") {
+        setActiveThreadId("");
+        setRenamingId(null);
+      }
+    }
+  }, [hasUtterance, activeThreadId, beginThread]);
+  const { reset } = chat;
+  const startNew = useCallback(() => {
+    reset();
+    setActiveThreadId("");
+    setRenamingId(null);
+  }, [reset]);
+  const select = useCallback(
+    (id) => {
+      setActiveThreadId(id);
+      setOpenTabs((tabs2) => tabs2.includes(id) ? tabs2 : [...tabs2, id]);
+      updateThread(
+        id,
+        (thread) => thread.status === "unread" ? { ...thread, status: "idle" } : thread
+      );
+      onSelect?.(id);
+    },
+    [onSelect, updateThread]
+  );
+  const remove = useCallback(
+    (id) => {
+      const timer = namingTimers.current.get(id);
+      if (timer != null) {
+        clearTimeout(timer);
+        namingTimers.current.delete(id);
+      }
+      setGroups(
+        (current) => current.map((group) => ({
+          ...group,
+          threads: group.threads.filter((thread) => thread.id !== id)
+        }))
+      );
+      setOpenTabs((tabs2) => tabs2.filter((tab) => tab !== id));
+      setRenamingId((renaming) => renaming === id ? null : renaming);
+      if (activeThreadId === id) {
+        setActiveThreadId("");
+        reset();
+      }
+      onDelete?.(id);
+    },
+    [activeThreadId, onDelete, reset]
+  );
+  const rename = useCallback(
+    (id, title) => {
+      updateThread(id, (thread) => ({ ...thread, title }));
+      setRenamingId(null);
+      onRename?.(id, title);
+    },
+    [onRename, updateThread]
+  );
+  const togglePin = useCallback(
+    (id) => {
+      let nowPinned = false;
+      setGroups((current) => {
+        let moved;
+        let wasPinned = false;
+        const stripped = current.map((group) => ({
+          ...group,
+          threads: group.threads.filter((thread) => {
+            if (thread.id !== id) return true;
+            moved = thread;
+            wasPinned = Boolean(thread.pinned);
+            return false;
+          })
+        }));
+        const taken = moved;
+        if (!taken) return current;
+        nowPinned = !wasPinned;
+        const hasPinned = stripped.some((group) => group.label === pinnedGroup);
+        const withPinned = hasPinned || wasPinned ? stripped : [{ label: pinnedGroup, threads: [] }, ...stripped];
+        return withPinned.map((group) => {
+          if (!wasPinned && group.label === pinnedGroup) {
+            return { ...group, threads: [...group.threads, { ...taken, pinned: true }] };
+          }
+          if (wasPinned && group.label === homeGroup) {
+            return { ...group, threads: [{ ...taken, pinned: void 0 }, ...group.threads] };
+          }
+          return group;
+        });
+      });
+      onPin?.(id, nowPinned);
+    },
+    [homeGroup, onPin, pinnedGroup]
+  );
+  const closeTab = useCallback(
+    (id) => {
+      const index = openTabs.indexOf(id);
+      setOpenTabs((tabs2) => tabs2.filter((tab) => tab !== id));
+      if (activeThreadId === id) {
+        const neighbour = openTabs[index + 1] ?? openTabs[index - 1];
+        if (neighbour) select(neighbour);
+        else startNew();
+      }
+    },
+    [activeThreadId, openTabs, select, startNew]
+  );
+  const selectProject = useCallback((id) => setActiveProjectId(id), []);
+  const createProject = useCallback(() => {
+    projectSeq.current += 1;
+    const id = `project-${projectSeq.current}`;
+    setProjects((list) => [...list, { id, label: `New project ${projectSeq.current}`, meta: "now" }]);
+    setActiveProjectId(id);
+  }, []);
+  const actionsFor = useCallback(
+    (thread) => pins ? [
+      { id: "pin", label: thread.pinned ? "Unpin" : "Pin", icon: "keep" },
+      RENAME_ACTION,
+      DELETE_ACTION
+    ] : [RENAME_ACTION, DELETE_ACTION],
+    [pins]
+  );
+  const runAction = useCallback(
+    (threadId, actionId) => {
+      if (actionId === "rename") setRenamingId(threadId);
+      else if (actionId === "delete") remove(threadId);
+      else if (actionId === "pin") togglePin(threadId);
+    },
+    [remove, togglePin]
+  );
+  const shapedGroups = useMemo(() => {
+    let shaped = groups;
+    if (!pins) {
+      const pinned = shaped.find((group) => group.label === pinnedGroup)?.threads ?? [];
+      shaped = shaped.filter((group) => group.label !== pinnedGroup).map(
+        (group) => group.label === homeGroup ? {
+          ...group,
+          threads: [
+            ...pinned.map((thread) => ({ ...thread, pinned: void 0 })),
+            ...group.threads
+          ]
+        } : group
+      );
+    }
+    return shaped.map((group) => ({
+      ...group,
+      threads: group.threads.map((thread) => {
+        const row = details ? thread : { ...thread, description: void 0, status: void 0, icon: void 0, meta: void 0 };
+        return { ...row, actions: actionsFor(thread) };
+      })
+    }));
+  }, [groups, pins, pinnedGroup, homeGroup, details, actionsFor]);
+  const tabs = useMemo(() => {
+    const byId = /* @__PURE__ */ new Map();
+    for (const group of groups) for (const thread of group.threads) byId.set(thread.id, thread);
+    return openTabs.flatMap((id) => {
+      const thread = byId.get(id);
+      return thread ? [{ id, label: thread.title, icon: "chat_bubble", status: details ? thread.status : void 0 }] : [];
+    });
+  }, [openTabs, groups, details]);
+  return {
+    groups: shapedGroups,
+    activeThreadId,
+    select,
+    startNew,
+    remove,
+    rename,
+    togglePin,
+    renamingId,
+    setRenamingId,
+    actionsFor,
+    runAction,
+    projects,
+    activeProjectId,
+    selectProject,
+    createProject,
+    tabs,
+    closeTab,
+    newThreadLabel
+  };
+}
+export {
+  THREAD_NAMING_DELAY_MS,
+  useThreads
+};

package/chat/transport.d.ts

@@ -0,0 +1,49 @@
+import { ChatTransport } from './types';
+/**
+ * How long to wait for the first byte before giving up. Generous on purpose:
+ * a cold prompt cache costs several seconds before the model starts, and a
+ * false timeout is worse than a slow answer.
+ */
+export declare const FIRST_BYTE_TIMEOUT_MS = 15000;
+/** Turns sent upstream. The handler re-enforces this; sending less saves bytes. */
+export declare const MAX_TRANSPORT_TURNS = 10;
+/** The copy a failed request becomes, by its HTTP status. */
+export interface FetchTransportCopy {
+    /** The request could not be sent at all. */
+    unreachable: string;
+    /** 400: the server rejected the message shape. */
+    badRequest: string;
+    /** 429: too many requests. */
+    rateLimited: string;
+    /** 5xx. */
+    serverError: string;
+    /** Anything else. */
+    other: string;
+}
+export declare const DEFAULT_FETCH_COPY: FetchTransportCopy;
+export interface FetchTransportOptions {
+    /**
+     * The visitor's explicit model pick (a wire value from the host's model
+     * list), read at send time so a mid-conversation switch applies from the
+     * next message. Null means no pick was made: the server applies its own
+     * default, which is the distinction that lets a budget tier move the
+     * default without fighting a visitor who never touched the picker.
+     */
+    getModel?: () => string | null;
+    /**
+     * The context the request carries as `path`: by default the page the
+     * visitor is on, read at send time so a conversation that spans several
+     * pages sends each question with the page it was asked from. The handler
+     * treats it as untrusted input and sanitises it. Return null to send none.
+     */
+    getContext?: () => string | null;
+    /** Replacement copy for the failure messages. */
+    copy?: Partial<FetchTransportCopy>;
+}
+/**
+ * A transport over `fetch` to an NDJSON chat endpoint.
+ *
+ * `endpoint` defaults to `/api/chat`, which is where `npx rift-ds init chat`
+ * writes the server handler; a host with its own URL passes it.
+ */
+export declare function createFetchTransport(endpoint?: string, options?: FetchTransportOptions): ChatTransport;

package/chat/transport.js

@@ -0,0 +1,105 @@
+const FIRST_BYTE_TIMEOUT_MS = 15e3;
+const MAX_TRANSPORT_TURNS = 10;
+const DEFAULT_FETCH_COPY = {
+  unreachable: "Could not reach the chat backend. Check your connection and try again.",
+  badRequest: "That message did not go through. Try rephrasing it.",
+  rateLimited: "That is a lot of questions at once. Give it a minute and try again.",
+  serverError: "The chat backend is having trouble. Try again in a moment.",
+  other: "Something went wrong sending that. Try again."
+};
+function httpErrorMessage(status, copy) {
+  if (status === 400) return copy.badRequest;
+  if (status === 429) return copy.rateLimited;
+  if (status >= 500) return copy.serverError;
+  return copy.other;
+}
+function createFetchTransport(endpoint = "/api/chat", options = {}) {
+  const copy = { ...DEFAULT_FETCH_COPY, ...options.copy };
+  const getContext = options.getContext ?? (() => typeof window !== "undefined" ? window.location.pathname : null);
+  return async function* fetchTransport(messages, signal) {
+    const path = getContext() ?? void 0;
+    const model = options.getModel?.() ?? void 0;
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal.addEventListener("abort", abort);
+    let watchdog = setTimeout(
+      abort,
+      FIRST_BYTE_TIMEOUT_MS
+    );
+    const clearWatchdog = () => {
+      if (watchdog !== null) {
+        clearTimeout(watchdog);
+        watchdog = null;
+      }
+    };
+    let reader = null;
+    try {
+      let response;
+      try {
+        response = await fetch(endpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            /* Role and text, named field by field: a message may carry
+               attachment details for a scripted chat, and nothing about a
+               file is ever sent to the server. */
+            messages: messages.slice(-MAX_TRANSPORT_TURNS).map(({ role, content }) => ({ role, content })),
+            path,
+            model
+          }),
+          signal: controller.signal
+        });
+      } catch {
+        if (signal.aborted) return;
+        yield { type: "error", message: copy.unreachable };
+        return;
+      }
+      if (!response.ok || !response.body) {
+        yield { type: "error", message: httpErrorMessage(response.status, copy) };
+        return;
+      }
+      reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      while (true) {
+        if (signal.aborted) return;
+        const { done, value } = await reader.read();
+        clearWatchdog();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          const event = parseEvent(line);
+          if (!event) continue;
+          yield event;
+          if (signal.aborted) return;
+        }
+      }
+      const trailing = parseEvent(buffer);
+      if (trailing) yield trailing;
+    } finally {
+      clearWatchdog();
+      signal.removeEventListener("abort", abort);
+      if (reader) {
+        await reader.cancel().catch(() => {
+        });
+      }
+    }
+  };
+}
+function parseEvent(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+export {
+  DEFAULT_FETCH_COPY,
+  FIRST_BYTE_TIMEOUT_MS,
+  MAX_TRANSPORT_TURNS,
+  createFetchTransport
+};