@teaflask/assistant 0.3.0 → 0.7.0

package/src/components/reasoning-row.tsx

@@ -1,68 +0,0 @@
-"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

@@ -1,47 +0,0 @@
-"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

@@ -1,48 +0,0 @@
-"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

@@ -1,282 +0,0 @@
-"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

@@ -1,62 +0,0 @@
-// 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

@@ -1,112 +0,0 @@
-"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}
-    </>
-  );
-}