@teaflask/assistant 0.0.0 → 0.3.0

package/src/components/reasoning-row.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+// The adopted register — assistant-ui `reasoning` as the visual reference:
+// the model's native reasoning as a quiet collapsible line above the
+// answer. While the reasoning streams the line reads "Thinking…" under
+// the moving gradient and the body holds itself open so the thought reads
+// as it arrives; once the answer starts it collapses to a static
+// "Thought about it". No duration on the label: the run events carry no
+// timestamps, and a client-side clock would lie on every replay.
+
+import { LightbulbIcon } from "lucide-react";
+
+import {
+  REASONING_SETTLED_LABEL,
+  REASONING_STREAMING_LABEL,
+} from "../core/reasoning-copy.js";
+import type { ReasoningRow as ReasoningRowModel } from "../core/transcript-rows.js";
+import { Disclosure, DisclosureChevron } from "./primitives/disclosure.js";
+import { ShimmerText } from "./streaming-states.js";
+
+// One form only: every reasoning row lives on an activity rail (the
+// grouping in use-transcript-folds.ts folds all reasoning into a group), so the
+// rail geometry — leading state mark, gap-3, ps-7 body — IS the row.
+export function ReasoningRow({ view }: { view: ReasoningRowModel }) {
+  return (
+    <Disclosure
+      variant="bare"
+      open={view.streaming || undefined}
+      className="tf:w-full"
+      summaryClassName="tf:flex tf:w-fit tf:items-center tf:gap-3 tf:py-1.5 tf:text-tf-label tf:text-tf-muted-foreground tf:hover:text-tf-foreground"
+      bodyClassName="tf:ps-7 tf:pt-1 tf:pb-2"
+      summary={
+        <>
+          <span
+            // The reasoning mark: a distinct semantic row, deliberately
+            // outside the tool icon vocabulary — dimmed while the
+            // thought streams, settled ink after, never a universal
+            // tick. State is worded for assistive tech; the label
+            // alongside says it for everyone else.
+            data-tf-reasoning-mark=""
+            className={
+              view.streaming
+                ? "tf:grid tf:size-4 tf:shrink-0 tf:place-items-center tf:opacity-45"
+                : "tf:grid tf:size-4 tf:shrink-0 tf:place-items-center"
+            }
+          >
+            <LightbulbIcon aria-hidden className="tf:size-4" />
+            <span className="tf:sr-only">
+              {view.streaming ? "Thinking" : "Thought"}
+            </span>
+          </span>
+          {view.streaming ? (
+            <ShimmerText className="tf:leading-none">
+              {REASONING_STREAMING_LABEL}
+            </ShimmerText>
+          ) : (
+            <span className="tf:leading-none">{REASONING_SETTLED_LABEL}</span>
+          )}
+          <DisclosureChevron revealOnInteraction />
+        </>
+      }
+    >
+      <p className="tf:text-tf-label tf:whitespace-pre-wrap tf:text-tf-muted-foreground">
+        {view.text}
+      </p>
+    </Disclosure>
+  );
+}

package/src/components/receipt-rows.tsx

@@ -0,0 +1,47 @@
+"use client";
+
+import { CircleAlertIcon } from "lucide-react";
+
+// The turn-level failure receipt — the ONE standalone receipt row left
+// after the meta-receipt class was deleted: a turn that dies mid-way
+// otherwise stops with no answer and no explanation. Its quiet
+// siblings (the turn_voided stamp rows, the approval/decline settled
+// statements, the resume divider) no longer render at all; their
+// markers stay on the wire and in the store, but the transcript carries
+// no narration for them. A member's own stop (turn_stopped) projects no
+// row either; the paired quiet RUN_FINISHED — not any marker — is what
+// closes a pause's cards and settles the composer.
+
+// The turn-level terminal failure receipt: a turn that ended failed
+// outside any single tool, rendered where the answer broke off —
+// explicit and calm, never an assistant-voiced paragraph and never a
+// detached banner. Deliberately distinct from an operation-level
+// failure, which is an in-row pill on the affected tool row. The glyph
+// shape plus the sentence are the non-colour signal; the sentence
+// itself is the wire's reader-aware copy, so the row exposes exactly
+// the safe detail the REST wire already serves. Zero motion — a failed
+// turn never leaves anything spinning.
+export function TurnFailedReceiptRows({
+  receipts,
+}: {
+  receipts: readonly string[];
+}) {
+  return (
+    <div className="tf:flex tf:flex-col tf:gap-1 tf:py-1">
+      {receipts.map((receipt, index) => (
+        <p
+          key={`${receipt}-${String(index)}`}
+          data-tf-turn-failed-receipt=""
+          className="tf:flex tf:items-center tf:gap-2 tf:text-xs tf:text-tf-muted-foreground"
+        >
+          <CircleAlertIcon
+            aria-hidden
+            className="tf:size-3.5 tf:shrink-0 tf:text-tf-destructive"
+          />
+          <span className="tf:sr-only">Turn failed:</span>
+          <span className="tf:min-w-0">{receipt}</span>
+        </p>
+      ))}
+    </div>
+  );
+}

package/src/components/run-status-announcer.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import { announcedStatusOf } from "../core/run-status.js";
+import type { TurnStatus } from "../contract/threads.js";
+
+// The transcript's status live region. The conversation chrome makes no
+// visible run-state claims — the shelf's status line was deleted (its
+// work-in-progress story belongs to the subagent pill, the fold's own
+// "Working…" content headline, and the Stop control; its waiting story
+// belongs to the decision surface itself) — but a screen reader still
+// needs the transitions the visuals no longer spell out. Rules carried
+// over from the line it replaces:
+//
+// - Mounted UNCONDITIONALLY (an empty sr-only span while idle): screen
+//   readers announce MUTATIONS of an existing live region, and generally
+//   skip a node that arrives already carrying role="status" and its
+//   text — so the element must pre-exist every phrase change. sr-only is
+//   absolutely positioned, so it costs the region no layout height, and
+//   it lives OUTSIDE the shelf's slots so a permanent occupant cannot
+//   defeat their :empty collapse.
+// - Throttled by construction: the phrase changes only on status-class
+//   transitions (idle ↔ working ↔ waiting), never per streamed token and
+//   never per elapsed second.
+// - Honest about who is waited on: "Waiting for your input" is claimed
+//   only while an actionable decision surface exists — a pause with no
+//   pending decision (a subagent park, the execution driver's window)
+//   announces the machine's time, "The assistant is working".
+export function RunStatusAnnouncer({
+  status,
+  decisionsPending,
+}: {
+  status: TurnStatus | null;
+  /** True while a member-actionable decision is live (the suspension
+   *  slot's own predicates — approvals awaiting the member, questions
+   *  still collecting). Never inferred from what rendered. */
+  decisionsPending: boolean;
+}) {
+  const state = announcedStatusOf(status, decisionsPending);
+  return (
+    <span data-tf-status-announcer="" role="status" className="tf:sr-only">
+      {state === "waiting"
+        ? "Waiting for your input"
+        : state === null
+          ? ""
+          : "The assistant is working"}
+    </span>
+  );
+}

package/src/components/scroll-follow-guards.tsx

@@ -0,0 +1,282 @@
+"use client";
+
+import { useEffect } from "react";
+import {
+  useStickToBottomContext,
+  type StickToBottomContext,
+} from "use-stick-to-bottom";
+
+// Repairs to use-stick-to-bottom's follow contract, all through its
+// public context — no fork, no patched internals. The library observes
+// only its CONTENT element and trusts its own scroll handler for
+// escapes AND re-engages; the three holes that leaves, and each
+// guard's reasoning, are docs/scroll-follow-guards.md. stopScroll() is
+// the library's complete escape primitive: it sets escapedFromLock and
+// clears isAtBottom, which aborts any in-flight follow.
+
+// Accumulated upward travel that counts as the visitor taking over
+// (guard 3): above the per-frame jitter a horizontal trackpad pan chains
+// into the transcript (reset every mid-stream growth frame), below the
+// smallest deliberate gesture (an arrow key is ~40px, PageUp a viewport).
+const TAKEOVER_TRAVEL_PX = 16;
+
+export function ScrollFollowGuards() {
+  const { scrollRef, state, stopScroll, scrollToBottom } =
+    useStickToBottomContext();
+
+  useEffect(() => {
+    const scrollElement = scrollRef.current;
+    if (scrollElement === null) {
+      return;
+    }
+    const teardowns = [
+      _installShrinkRefollow(scrollElement, state, scrollToBottom),
+      _installWheelEscape(scrollElement, state, stopScroll),
+      _installTravelGuards(scrollElement, state, stopScroll, scrollToBottom),
+    ];
+    return () => {
+      for (const teardown of teardowns) {
+        teardown();
+      }
+    };
+    // Every dependency is identity-stable in the library (state is a
+    // mount-scoped memo; the callbacks close over stable refs), so this
+    // installs once per mounted scroller.
+  }, [scrollRef, scrollToBottom, state, stopScroll]);
+
+  return null;
+}
+
+type FollowState = StickToBottomContext["state"];
+type ScrollToBottom = StickToBottomContext["scrollToBottom"];
+type StopScroll = StickToBottomContext["stopScroll"];
+
+// Guard 1 — viewport shrink re-follow, keyed to the SCROLL element's
+// height so content settles never trip it. state.isAtBottom is the
+// ONLY flag consulted (escapedFromLock sits stale-true on the escape
+// → jump → follow path). The landing write is synchronous — after two
+// rAFs the transcript is at its bottom — and goes through the
+// library's state.scrollTop setter, never the raw property (it forces
+// scroll-behavior:auto and records the echo in ignoreScrollToTop);
+// the trailing scrollToBottom keeps the library's bookkeeping coherent.
+function _installShrinkRefollow(
+  scrollElement: HTMLElement,
+  state: FollowState,
+  scrollToBottom: ScrollToBottom,
+): () => void {
+  // The follow-liveness proof. PREMISE: guard 1 may re-land a reader
+  // only on a page whose clock advances across frames — under a pinned
+  // clock the library's wait:true follows never complete and
+  // state.isAtBottom sits stale-true at the top of history. The probe
+  // reads Date.now() across frames and nothing else (never a follow's
+  // settlement, never a write). A shrink seen before the proof is
+  // remembered, not dropped: both paths that reach it are in
+  // docs/scroll-follow-guards.md; the latch counts are in the
+  // scroll-follow guard latch measurement record.
+  const clockStart = Date.now();
+  let clockProven = false;
+  let shrinkPendingProof = false;
+  const landAtBottom = () => {
+    state.scrollTop = scrollElement.scrollHeight - scrollElement.clientHeight;
+    void scrollToBottom({
+      animation: "instant",
+      wait: true,
+      preserveScrollPosition: true,
+    });
+  };
+  let proofFrame = requestAnimationFrame(function proveClock() {
+    if (Date.now() > clockStart) {
+      clockProven = true;
+      // The reader must still be followed at flush time — an escape
+      // between the remembered shrink and the proof wins.
+      if (shrinkPendingProof && state.isAtBottom) {
+        shrinkPendingProof = false;
+        landAtBottom();
+      }
+      return;
+    }
+    proofFrame = requestAnimationFrame(proveClock);
+  });
+
+  let lastClientHeight: number | null = null;
+  const observer = new ResizeObserver(() => {
+    const height = scrollElement.clientHeight;
+    const previousHeight = lastClientHeight;
+    lastClientHeight = height;
+    const viewportShrank = previousHeight !== null && height < previousHeight;
+    if (!viewportShrank || !state.isAtBottom) {
+      return;
+    }
+    // The proof's verdict: until the clock is proven, isAtBottom is
+    // not honest and no re-land is safe — a shrink that beats the
+    // first proving frame is remembered, never dropped.
+    if (!clockProven) {
+      shrinkPendingProof = true;
+      return;
+    }
+    landAtBottom();
+  });
+  observer.observe(scrollElement);
+
+  return () => {
+    cancelAnimationFrame(proofFrame);
+    observer.disconnect();
+  };
+}
+
+// Guard 2 — the wheel escape, minus the library's dead zone (it bails
+// unless the first overflow:auto ancestor IS the scroller). We escape
+// unless something between the pointer and the scroller will consume
+// the upward wheel — an inner scroller that can still scroll up; one
+// at its own top chains the wheel to the transcript, so it escapes.
+function _installWheelEscape(
+  scrollElement: HTMLElement,
+  state: FollowState,
+  stopScroll: StopScroll,
+): () => void {
+  const handleWheel = (event: WheelEvent) => {
+    // Vertical dominance, not just a negative deltaY: a trackpad's
+    // horizontal pan carries small negative deltaY jitter beside a large
+    // deltaX, and panning a long code line mid-stream must not release
+    // the lock. |deltaY| > |deltaX| is the browser's own axis call.
+    const wheelingUp =
+      event.deltaY < 0 && Math.abs(event.deltaY) > Math.abs(event.deltaX);
+    const transcriptOverflows =
+      scrollElement.scrollHeight > scrollElement.clientHeight;
+    if (
+      wheelingUp &&
+      transcriptOverflows &&
+      state.animation?.ignoreEscapes !== true &&
+      !wheelConsumedBelow(event.target, scrollElement)
+    ) {
+      stopScroll();
+    }
+  };
+  scrollElement.addEventListener("wheel", handleWheel, {
+    passive: true,
+    capture: true,
+  });
+  return () => {
+    scrollElement.removeEventListener("wheel", handleWheel, {
+      capture: true,
+    });
+  };
+}
+
+// Guards 3 and 4 — the non-wheel escape and its mirror, which the
+// library cannot deliver from inside its resizeDifference gate.
+// Capture on an ANCESTOR is load-bearing: scroll events capture-
+// descend, and the library's at-target listener synchronously clears
+// ignoreScrollToTop — running before it is the only way to tell its
+// writes from the visitor's. The ancestor is the scroller's root node,
+// not window: scroll is neither bubbling nor composed, so in the
+// embeds' open shadow root a window listener would never fire.
+//
+// Escape (guard 3): accumulated upward travel that is not a library
+// write, not the browser clamping under a content shrink, and not
+// overscroll settle at the bottom. The ACCUMULATOR (not a per-event
+// threshold) is what lets chained pan jitter never accrue — the
+// follow resets it every growth frame — while a slow drag still
+// crosses TAKEOVER_TRAVEL_PX within a move or two.
+//
+// Re-engage (guard 4): a downward move that CLOSES the gap and LANDS
+// at the bottom while unfollowed. The landing gate (bottomGap <= 1)
+// is load-bearing: our scrollToBottom repositions, and doing so
+// anywhere inside the near-bottom band would fight a scrollbar or
+// touch drag (snap down, pointer pulls up, guard 3 escapes, repeat);
+// at bottomGap <= 1 it is a pure re-arm. "Closes the gap" rules out
+// scroll anchoring, which bumps scrollTop while holding the gap.
+function _installTravelGuards(
+  scrollElement: HTMLElement,
+  state: FollowState,
+  stopScroll: StopScroll,
+  scrollToBottom: ScrollToBottom,
+): () => void {
+  let lastScrollTop = scrollElement.scrollTop;
+  let lastScrollHeight = scrollElement.scrollHeight;
+  let lastBottomGap =
+    scrollElement.scrollHeight -
+    scrollElement.clientHeight -
+    scrollElement.scrollTop;
+  let upwardTravel = 0;
+  const handleScroll = (event: Event) => {
+    if (event.target !== scrollElement) {
+      return;
+    }
+    const { scrollTop, scrollHeight, clientHeight } = scrollElement;
+    const bottomGap = scrollHeight - clientHeight - scrollTop;
+    const previousTop = lastScrollTop;
+    const previousScrollHeight = lastScrollHeight;
+    const previousBottomGap = lastBottomGap;
+    lastScrollTop = scrollTop;
+    lastScrollHeight = scrollHeight;
+    lastBottomGap = bottomGap;
+
+    const libraryWroteIt = scrollTop === state.ignoreScrollToTop;
+    const movedUp = scrollTop < previousTop;
+    const movedDown = scrollTop > previousTop;
+    const contentShrankUnderUs =
+      scrollHeight < previousScrollHeight || state.resizeDifference < 0;
+    const overscrollSettleAtBottom = bottomGap <= 1;
+
+    if (libraryWroteIt || movedDown) {
+      upwardTravel = 0;
+    }
+    if (
+      movedUp &&
+      !libraryWroteIt &&
+      !contentShrankUnderUs &&
+      !overscrollSettleAtBottom &&
+      state.animation?.ignoreEscapes !== true
+    ) {
+      upwardTravel += previousTop - scrollTop;
+      if (upwardTravel > TAKEOVER_TRAVEL_PX) {
+        upwardTravel = 0;
+        stopScroll();
+        return;
+      }
+    }
+
+    const closingTheGap = movedDown && previousBottomGap - bottomGap > 1;
+    if (!state.isAtBottom && closingTheGap && bottomGap <= 1) {
+      void scrollToBottom({ animation: "instant" });
+    }
+  };
+  const scrollRoot = scrollElement.getRootNode();
+  scrollRoot.addEventListener("scroll", handleScroll, {
+    passive: true,
+    capture: true,
+  });
+  return () => {
+    scrollRoot.removeEventListener("scroll", handleScroll, {
+      capture: true,
+    });
+  };
+}
+
+// True when an element between the wheel's target and the scroller
+// (inclusive of the target) would consume an upward wheel itself: it can
+// still scroll up AND its overflow-y actually scrolls. Mirrors native
+// scroll chaining — the browser only hands the wheel to the transcript
+// once every inner scroller is at its top. The geometry reads come first
+// so getComputedStyle stays off the hot path.
+function wheelConsumedBelow(
+  target: EventTarget | null,
+  scrollElement: HTMLElement,
+): boolean {
+  let element = target instanceof Element ? target : null;
+  while (element !== null && element !== scrollElement) {
+    const canStillScrollUp =
+      element.scrollTop > 0 && element.scrollHeight > element.clientHeight;
+    if (
+      canStillScrollUp &&
+      ["auto", "scroll", "overlay"].includes(
+        getComputedStyle(element).overflowY,
+      )
+    ) {
+      return true;
+    }
+    element = element.parentElement;
+  }
+  return false;
+}

package/src/components/served-suggestions.ts

@@ -0,0 +1,62 @@
+// Picking the served suggestion set for the page the visitor is on.
+// Lives beside the drawer body so it rides the drawer's lazy chunk —
+// the eager element shell never pays for it. Matching is computed per
+// render from the pathname the caller reads; the package deliberately
+// holds no route subscription.
+
+import type {
+  ServedRouteSuggestions,
+  ServedSuggestionsConfig,
+} from "../contract/assistant-config.js";
+import type { AssistantSuggestion } from "./conversation-view.js";
+
+/**
+ * The longest-prefix route's set, or the default set when no route
+ * covers the path. A matched route's EMPTY set is honored — it authors
+ * "no suggestions on this route" — which is why this never falls back
+ * from a match.
+ */
+export function servedSuggestionsForPath(
+  config: ServedSuggestionsConfig,
+  pathname: string,
+): readonly AssistantSuggestion[] {
+  const route = _longestCoveringRoute(config.routes ?? [], pathname);
+  const items =
+    route === null ? (config.default ?? []) : (route.suggestions ?? []);
+  return items.map((item) => ({ prompt: item.prompt, kind: item.kind }));
+}
+
+function _longestCoveringRoute(
+  routes: readonly ServedRouteSuggestions[],
+  pathname: string,
+): ServedRouteSuggestions | null {
+  let covering: ServedRouteSuggestions | null = null;
+  let coveringLength = -1;
+  for (const route of routes) {
+    const fence = _fenceOf(route.path_prefix);
+    if (!_aFenceCovers(fence, pathname)) {
+      continue;
+    }
+    // Strictly longer wins; a duplicate-length tie keeps the first
+    // (duplicates are unstorable anyway — the write gate rejects them).
+    if (fence.length > coveringLength) {
+      covering = route;
+      coveringLength = fence.length;
+    }
+  }
+  return covering;
+}
+
+// The navigate fence's grammar (mirrors _a_prefix_covers in the backend):
+// segment-aware — "/docs" covers "/docs/x", never "/docsy"; a trailing
+// slash on the prefix is cosmetic; an all-slash prefix covers everything.
+function _fenceOf(prefix: string): string {
+  return prefix.replace(/\/+$/, "");
+}
+
+function _aFenceCovers(fence: string, pathname: string): boolean {
+  if (fence === "") {
+    return true;
+  }
+  return pathname === fence || pathname.startsWith(fence + "/");
+}

package/src/components/slot-boundary.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import { Component, type ReactNode } from "react";
+
+import { hostFillDeclines } from "../core/host-fill.js";
+import { useOptionalAssistantSession } from "./teaflask-assistant-provider.js";
+
+// The host-slot isolation wrapper: every host-supplied slot on
+// AssistantTranscript EXCEPT `input` mounts inside one of these (the
+// input-region rule — that slot is deliberately unbounded), so a throwing
+// fill costs its own slot and nothing else. Two laws by construction: the
+// FALLBACK is the package's own rendering, rendered by this boundary and
+// never as a sibling inside the children (mandatory frame elements render
+// OUTSIDE it at the call site), so a broken fill cannot take the default
+// with it; and a slot that threw is latched for that mount — a new row's key gets a fresh boundary.
+
+export function HostSlotBoundary({
+  slot,
+  fallback,
+  children,
+}: {
+  /** Which slot this isolates — names the failure in the console line. */
+  slot: string;
+  fallback: ReactNode;
+  children: ReactNode;
+}) {
+  // Tolerant on purpose: agent-mode hosts (the run viewer, the playground)
+  // mount with no session provider; the console line is the report there.
+  const session = useOptionalAssistantSession();
+  return (
+    <_SlotCatch
+      slot={slot}
+      fallback={fallback}
+      reportError={session?.reportError}
+    >
+      {children}
+    </_SlotCatch>
+  );
+}
+
+class _SlotCatch extends Component<
+  {
+    slot: string;
+    fallback: ReactNode;
+    reportError: ((error: Error) => void) | undefined;
+    children: ReactNode;
+  },
+  { failed: boolean }
+> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  componentDidCatch(error: unknown) {
+    const shaped = error instanceof Error ? error : new Error(String(error));
+    // The host's observer hears it, and the console names the slot for
+    // whoever is actually debugging the page.
+    this.props.reportError?.(shaped);
+    console.error(
+      `[teaflask-assistant] The host "${this.props.slot}" slot threw; the package rendering took over.`,
+      shaped,
+    );
+  }
+
+  render() {
+    if (this.state.failed) {
+      return <>{this.props.fallback}</>;
+    }
+    return <>{this.props.children}</>;
+  }
+}
+
+/** The fill decision, made INSIDE the boundary: the render callback runs
+ *  here so a synchronous throw is caught, and a null/undefined return
+ *  falls through to the same package default the boundary would fall back
+ *  to — one default, two routes to it.
+ *
+ *  THE KEYING LAW: frame behavior attached to a slot must key on the fill
+ *  having ACTUALLY RENDERED, never on the prop having been supplied —
+ *  both fallback routes land on the package default, which carries its
+ *  own signals, and a prop-keyed extra would double them. The per-slot
+ *  enumeration is in docs/transcript-surfaces.md, "The keying law". The
+ *  toolRow annex (filledAnnex, the status word) weakens no isolation law:
+ *  fill rendered → the annex, package-rendered and unreachable by the
+ *  fill; null return or throw → the package ToolRow's own state pill. */
+export function SlotOrDefault({
+  render,
+  fallback,
+  filledAnnex,
+}: {
+  render: () => ReactNode;
+  fallback: ReactNode;
+  /** Package-owned content rendered beside the fill exactly when the
+   *  fill rendered — never beside the fallback. */
+  filledAnnex?: ReactNode;
+}) {
+  const filled = render();
+  // THE FALL-THROUGH RULE (core/host-fill.ts): null, undefined and both
+  // booleans decline; renderable emptiness is the host's deliberate
+  // choice of empty content and counts as filled.
+  if (hostFillDeclines(filled)) {
+    return <>{fallback}</>;
+  }
+  return (
+    <>
+      {filled}
+      {filledAnnex}
+    </>
+  );
+}