Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

98.2 KB
Raw Blame
import type { ActivityMessage, Message } from "@ag-ui/core";
import type { Attachment } from "@copilotkit/react-core/v2";
import {
  useCopilotKit,
  useRenderActivityMessage,
  useRenderToolCall,
} from "@copilotkit/react-core/v2";
import { useQuery } from "@tanstack/react-query";
import {
  readConnectPrompt,
  SHOW_APP_ACCESS_TOOL,
} from "@openbot/shared/connect-prompt";
import {
  IconAlertTriangle,
  IconBox,
  IconChevronDown,
  IconClock,
  IconFile,
  IconX,
} from "@tabler/icons-react";
import { motion, useReducedMotion } from "motion/react";
import {
  createContext,
  memo,
  useCallback,
  useContext,
  useEffect,
  useLayoutEffect,
  useMemo,
  useRef,
  useState,
} from "react";
import { Streamdown } from "streamdown";
import { ArgumentsArrivingContext } from "@/components/gallery/streaming";
import { Bubble, BubbleContent } from "@/components/ui/bubble";
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";
import {
  MessageContent,
  MessageFooter,
  Message as MessageRow,
} from "@/components/ui/message";
import {
  MessageScroller,
  MessageScrollerButton,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerProvider,
  MessageScrollerViewport,
} from "@/components/ui/message-scroller";
import { Skeleton } from "@/components/ui/skeleton";
import { attachmentUrl } from "@/lib/channels/attachments";
import { readResponsibilityTurn } from "@/lib/channels/responsibility-turn";
import { readFiring } from "@/lib/channels/routine-firing";
import type { CardPlace } from "@/lib/copilot/carry-on";
import { ToolPlaceContext } from "@/lib/copilot/tool-place";
import { markdownComponents } from "@/lib/markdown";
import { EASE_OUT, ENTRANCE_SECONDS } from "@/lib/motion";
import { readToolName } from "@/lib/plugins/tool-name";
import {
  asText,
  forDisplay,
  REFUSAL_MARKER,
  toolResultFailed,
} from "@/lib/plugins/tool-result";
import { readTeamBotConsent } from "@/lib/team-bots";
import { cn } from "@/lib/utils";
import { VOICE_CHAT_ACTIVITY, type VoiceChatEntry } from "@/lib/voice/archive";
import { deploymentCapabilitiesQueryOptions } from "@/lib/deployment/queries";
import { AppAccessCard } from "./app-access-card";
import { isBrowserStep } from "./browser-activity";
import {
  attachmentModality,
  type SentAttachment,
  toVisibleChatItems,
} from "./chat-messages";
import { splitChatOrigin } from "./chat-origin";
import type { QueuedMessage } from "./composer";
import { FollowScroll, RESUME_PX, useFollowIntent } from "./follow-intent";
import { LateRenderersContext, LateRenderersWatch } from "./late-renderers";
import { usePacedReveal } from "./paced-reveal";
import { TeamBotConsentCard } from "./team-bot-consent";
import {
  dropRepeatedAppCards,
  groupToolSteps,
  ToolActivity,
  type ToolGroup,
  type TranscriptItem,
  useDrawnTool,
} from "./tool-activity";
import { ToolRenderBoundary, toolCallFinal } from "./tool-boundary";
import { shouldDrawEarlier, useTranscriptPages } from "./transcript-pages";
import { TranscriptRail } from "./transcript-rail";
import {
  AT_END_PX,
  currentTurn,
  isPersonSentMessage,
  type Turn,
  turnsOf,
} from "./transcript-turns";
import { ToolLine } from "./tool-line";
import { VoiceChatCard } from "./voice-chat-card";

type ChatTranscriptProps = {
  busy?: boolean;
  /** Comma-separated `/` command names, used to tell a skill chip from a leading slash. */
  commandNames?: string;
  messages: ReadonlyArray<Readonly<Message>>;
  /**
   * Typed while the Bot had the turn, and waiting for it to finish. Empty on a screen that does not
   * offer queueing at all.
   */
  queued?: readonly QueuedMessage[];
  /** Take one back before it runs. Without it a queued line is shown but cannot be undone. */
  onRemoveQueued?: (id: string) => void;
  /** History has been asked for and has not arrived. Drawn only when there is nothing else to draw. */
  restoring?: boolean;
  /**
   * Why the last turn ended without an answer, if it did.
   *
   * A sentence rather than a flag, because the reasons are not interchangeable: a Bot that refused,
   * a Bot whose endpoint is down and a Bot that simply stopped talking are three different things to
   * be told, and only the thing that ended the turn knows which one happened.
   */
  stopped?: string;
  /**
   * Work this conversation is waiting on that is not this tab's run: a Bot it asked, a routine.
   * Drawn in the same slot as `Thinking`, under the last thing said, because that is where the
   * answer will appear.
   */
  working?: React.ReactNode;
};

/** One shared empty array, so a screen without a queue does not hand down a new one per render. */
const EMPTY_QUEUE: readonly QueuedMessage[] = [];

/**
 * Split a person's message into the skill they invoked and the rest of what they typed.
 *
 * ONLY A KNOWN COMMAND COUNTS. "/etc/hosts is broken" is a sentence, not a skill, and drawing a chip
 * around it would invent a thing that never happened. The names come from the same list the `/` menu
 * was built from, so this stays true as skills are granted and revoked.
 *
 * The trigger only opens at the start of a line, so the chip is the first token or there is none.
 */
function splitSkillChip(
  text: string,
  commandNames: string,
): { chip: string; rest: string } | null {
  const match = /^\/([a-z0-9][a-z0-9-]*)(\s|$)/.exec(text);
  if (!match) {
    return null;
  }
  const known = commandNames.split(",").filter(Boolean);
  if (!known.includes(match[1])) {
    return null;
  }
  return { chip: match[1], rest: text.slice(match[0].length) };
}

/**
 * The shape of a conversation, while it is still being fetched. Shaped like what is coming rather
 * than like a loading widget, on the same line pitch so the column does not jump when words land.
 */
const RESTORING_ANSWER_LINES = [
  { id: "line-1", width: "w-full" },
  { id: "line-2", width: "w-11/12" },
  { id: "line-3", width: "w-full" },
  { id: "line-4", width: "w-10/12" },
  { id: "line-5", width: "w-11/12" },
  { id: "line-6", width: "w-full" },
  { id: "line-7", width: "w-11/12" },
  { id: "line-8", width: "w-2/3" },
] as const;

function RestoringTranscript() {
  return (
    // One announcement, with every bar hidden from it: nine empty shapes read aloud is worse.
    <div aria-label="Loading this conversation" role="status">
      <div aria-hidden="true" className="flex justify-end pb-7">
        <Skeleton className="h-10 w-64 rounded-xl bg-muted/40 motion-reduce:animate-none" />
      </div>
      <div aria-hidden="true" className="flex flex-col gap-3">
        {RESTORING_ANSWER_LINES.map((line) => (
          <Skeleton
            className={`h-4 bg-muted/40 motion-reduce:animate-none ${line.width}`}
            key={line.id}
          />
        ))}
      </div>
    </div>
  );
}

/**
 * The Bot has the turn and has produced nothing yet.
 *
 * THE GAP THIS FILLS IS THE WORST ONE IN THE CONVERSATION. Between pressing send and the first token
 * there was `aria-busy` and nothing else: announced to a screen reader, invisible to everybody else.
 * A person who has just asked something watches their own message sit there, and a Bot that is
 * thinking is indistinguishable from a Bot that failed silently — which this app has shipped before.
 *
 * It borrows the shimmer a running tool line uses, so "working on it" reads the same whether the
 * work is a tool call or a model that has not spoken yet.
 */
function Thinking() {
  return (
    <p
      className="tool-line-running text-muted-foreground text-sm"
      // `status` rather than `alert`: this is progress, not something that interrupts what somebody
      // is doing. The text says it, so a screen reader is told the same thing the shimmer implies.
      role="status"
    >
      Thinking
    </p>
  );
}

/**
 * The turn ended and no answer came.
 *
 * In the same slot as `Thinking`, and for the same reason it is there: the person is looking at the
 * bottom of the transcript, immediately under their own message, because that is where the answer
 * was going to appear. Saying so above the composer put the explanation in a different part of the
 * screen from the gap it explains, and left the last thing in the conversation looking unfinished.
 *
 * NOT A MESSAGE, deliberately. It has no id, is never anchored, and is gone the moment the next turn
 * starts. Making it a transcript row would put a sentence into the conversation that nobody said,
 * and the conversation is sent back to the model on the next turn, so the Bot would then read its
 * own obituary as something it had written.
 */
function Stopped({ reason }: { reason: string }) {
  return (
    <p
      className="text-destructive text-sm"
      data-testid="transcript-stopped"
      role="alert"
    >
      {reason}
    </p>
  );
}

/**
 * A file staged on the composer, described the way a sent one is.
 *
 * So that a parked message draws the SAME tiles the turn will draw once it runs, rather than a
 * second rendering of an attachment that has to be kept in step with this one. The composer's
 * `onUpload` has already put the row on the server and handed back its url — `canSendDraft` refuses
 * to send, and therefore to park, anything still uploading — so there is always something to point
 * at by the time one of these reaches here.
 *
 * Anything that is not a picture becomes a document tile, which is what the sent row does with the
 * modalities it has no preview for: a card naming the file is the honest drawing of "this came
 * along", and the alternative is a broken thumbnail.
 *
 * WHICH ONES ARE PICTURES IS ASKED OF THE SERVER'S ANSWER, NOT OF `attachment.type`, and this is
 * the one surface in the browser where that answer is actually in hand. `attachment.type` is the
 * SDK's `getModalityFromMimeType(file.type)` from before the upload, never revisited when the
 * upload replies; `attachment.source.mimeType` is what OUR `onUpload` put there, and that is
 * `body.mimeType` — the type the server earned from `sniffMimeType` over the bytes
 * (`composer/attachments.ts`). A PNG the browser called `text/plain` has `type: "document"` and
 * `source.mimeType: "image/png"`, and this used to draw a grey card over it.
 *
 * A PARKED MESSAGE HOLDS THE LIVE `Attachment`, WHICH IS WHY THIS CAN BE PUT RIGHT AND THE SENT ROW
 * CANNOT. `QueuedMessage.attachments` is `Attachment[]` — the staged object itself, source and all
 * — whereas a sent turn has been through `toAttachmentPart` (`channel-chat.tsx`), which rebuilds
 * the source as `{ type: "url", value }` and drops the `mimeType` on the floor. So the two tiles
 * genuinely can disagree for as long as that line stands: a mislabelled picture draws correctly
 * here and reverts to a file card the moment the turn runs.
 *
 * That flip is a real cost and it is still the right way round. It is the symptom of the missing
 * line rather than a reason to keep this tile wrong on purpose, and the alternative — throwing away
 * an answer we hold so that both surfaces are wrong together — is the kind of consistency that
 * hides the defect instead of paying it down. `attachmentModality` is shared with the sent path
 * precisely so that fixing the source there needs no second change here.
 */
function parkedTiles(attachments: readonly Attachment[]): SentAttachment[] {
  return attachments.map((attachment) => {
    const attachmentId = (attachment.metadata as { attachmentId?: unknown })
      ?.attachmentId;
    /*
     * Narrowed rather than read straight through, for the reason the sent path narrows the same
     * field: `Attachment["source"]` is a union whose `data` member REQUIRES `mimeType` and whose
     * `url` member does not, and a `data` source here carries `file.type` — the browser's claim,
     * which is the very thing this is refusing to trust. Only a url source has been near the
     * server. A staged attachment still uploading is exactly that case (`{ type: "data", value: "",
     * mimeType: file.type }`), and while `canSendDraft` refuses to park one, this costs nothing and
     * means the guard does not depend on that staying true.
     */
    const { source } = attachment;
    const mimeType =
      source.type === "url" && source.mimeType ? source.mimeType : undefined;

    return {
      id: attachment.id,
      attachmentId:
        typeof attachmentId === "string" ? attachmentId : attachment.id,
      url: source.value,
      ...(attachment.filename ? { filename: attachment.filename } : {}),
      modality: attachmentModality(attachment.type, mimeType),
    };
  });
}

/** What a parked message is called, for somebody who cannot see it: its words, or else its files. */
function describeParked(
  text: string,
  files: readonly SentAttachment[],
): string {
  if (text) {
    return text;
  }
  const named = files
    .map((file) => file.filename)
    .filter((filename) => filename !== undefined);

  return named.length > 0 ? named.join(", ") : "attachment";
}

/**
 * Something the person said while the Bot was working, waiting its turn.
 *
 * IT IS DRAWN AS THEIR MESSAGE, NOT AS A NOTICE ABOUT ONE. The whole point of letting somebody type
 * mid-turn is that they can see their words landed, and a status line saying "1 message queued"
 * does not do that — they would still be wondering whether the sentence they typed is the sentence
 * that will run. So it is the same bubble, in the same column, with the same wrapping, and only two
 * things say it has not run yet: it is faded, and it says so underneath.
 *
 * The footer carries the taking-back too, because that is where the reader's eye already is once
 * they have decided this was a mistake, and because a control on the bubble itself would have to
 * hover over the words it is offering to delete.
 */
function Queued({
  attachments,
  text,
  onRemove,
}: {
  attachments: readonly Attachment[];
  text: string;
  onRemove?: (() => void) | undefined;
}) {
  /*
   * THE FILES COME WITH IT, and until they did they were on NO SURFACE IN THE APP AT ALL. Parking
   * consumes the draft, so the composer's strip empties in the same beat this line appears; drawing
   * only `text` meant somebody who attached a screenshot mid-turn watched it vanish from the
   * composer and never show up anywhere else. Same tiles as a sent turn, in the same order —
   * pictures above the words — because this IS their message, just not yet run.
   */
  const files = parkedTiles(attachments);

  return (
    <MessageRow align="end">
      <MessageContent>
        {files.length > 0 ? (
          <AttachmentTiles attachments={files} className="opacity-60" />
        ) : null}
        {/*
         * NO WORDS, NO BUBBLE. A screenshot pasted mid-turn with nothing typed is the ordinary way
         * this gets used, and it drew an empty muted bubble above the footer — which reads as a
         * message sent by mistake rather than as a file waiting its turn.
         */}
        {text ? (
          <Bubble align="end" className="opacity-60" variant="muted">
            <BubbleContent>
              {/* Shown exactly as typed, for the same reason a sent message is. */}
              <span className="whitespace-pre-wrap">{text}</span>
            </BubbleContent>
          </Bubble>
        ) : null}
        <MessageFooter>
          {/*
           * `status` rather than `alert`, matching the thinking line: a person who has just chosen
           * to queue something is not being interrupted by the news that it is queued.
           */}
          <span role="status">Queued</span>
          {onRemove ? (
            <button
              /*
               * The sentence it deletes, in the name. Three parked corrections put three buttons
               * called "Remove" in a row, and somebody reading by name alone is told what they can
               * do and nothing about which one it would happen to. The visible word stays short
               * because the bubble it sits under is the answer for everybody who can see it.
               *
               * With no sentence to name it by, the FILES are what it deletes — see
               * `describeParked`. An attachment-only message named the label after an empty string
               * and read as "Remove queued message:", which is the same nothing three times over.
               */
              aria-label={`Remove queued message: ${describeParked(text, files)}`}
              className="ml-2 underline underline-offset-2 hover:text-foreground focus-visible:outline-none focus-visible:ring-3 focus-visible:ring-ring/50"
              onClick={onRemove}
              type="button"
            >
              Remove
            </button>
          ) : null}
        </MessageFooter>
      </MessageContent>
    </MessageRow>
  );
}

/**
 * Put the newest queued message where the person who just typed it can see it.
 *
 * WITHOUT THIS THE AFFORDANCE IS INVISIBLE EXACTLY WHEN IT MATTERS. The scroller holds its anchor on
 * the turn being answered rather than following the bottom, so during a long streamed answer the
 * transcript sits a screen or so above the end — and a line appended below it lands off screen.
 * Measured at the point somebody would actually use this: eighty-odd pixels under the fold, with
 * the composer emptying at the same moment. They would have watched their correction vanish.
 *
 * Keyed on the newest queued id rather than on the list, so it does not fire again for every chunk
 * of the answer still streaming above it. It does fire when the bottom-most queued line is taken
 * back, which is a scroll nobody asked for and which lands on the end of the conversation anyway,
 * and it stays quiet on a drain, when the id goes to null.
 *
 * IT COSTS THE ANCHOR, AND THAT IS THE PRICE OF THE SCROLL RATHER THAN A SIDE EFFECT OF IT.
 * `scrollToEnd` drops whatever turn the scroller was holding its position against and starts
 * following the bottom instead, so the rest of that answer streams past under the reader rather
 * than staying put beneath the question. Somebody who has just typed at the bottom of the
 * conversation has asked to be at the bottom of the conversation, so following it is the reading
 * they chose; but they chose it for the whole turn and not only for the moment, and the button
 * back to the anchored view is the scroller's own, not ours to restore.
 *
 * Rendering nothing and living inside the provider is what buys access to the scroller at all; the
 * alternative is threading a ref out through three components with no other reason to know a
 * scroller exists.
 */
function ScrollNewestQueuedIntoView({
  newest,
  onQueued,
}: {
  newest: string | null;
  onQueued: () => void;
}) {
  useEffect(() => {
    if (newest === null) {
      return;
    }
    // Through the follow state, so the view is told to follow before it is sent to the end.
    onQueued();
  }, [newest, onQueued]);

  return null;
}

/**
 * How many of the newest rows render in when a conversation opens, and how far apart.
 *
 * The view has already landed at the bottom before the first paint, so these are the rows on
 * screen; the stagger runs top of the screen first, newest last. Short on purpose: eight rows 30ms
 * apart is a little over 200ms before the last one starts, which reads as the conversation
 * appearing rather than as it loading. Older rows, above the fold, are simply there.
 */
const OPENING_STAGGER_COUNT = 8;
const OPENING_STAGGER_MS = 30;

/**
 * The opening stagger, decided once from the rows present when the conversation opens.
 *
 * Applied as a CSS animation on the scroller's row wrapper, not on the memoised row inside it: the
 * row's props stay the same and a streaming answer can never replay it, and a transform composites
 * without moving the layout box the scroller just landed on. Exported for its tests.
 */
export function openingStagger(ids: readonly string[]): Map<string, string> {
  const start = Math.max(0, ids.length - OPENING_STAGGER_COUNT);
  return new Map(
    ids
      .slice(start)
      .map((id, index) => [id, `${index * OPENING_STAGGER_MS}ms`] as const),
  );
}

/** Where a turn jumped to from the rail sits below the top of the view. */
const TURN_INSET_PX = 24;

/**
 * Since when a row mounting now is arriving live, rather than having been there when the
 * conversation opened: null while it is not.
 *
 * A ref, not state: it is read once, at a row's first render, and setting it must not re-render
 * anything. `ArrivalsLive` provides a fresh one with the scroller, so it is null for the commit that
 * mounts the whole history and set to the time in the effect after it; every row mounted from then
 * on is something that arrived while the person was here. The time is for a row that can say when
 * what it shows happened (see `useArrivedLive`).
 */
const ArrivalsLiveContext = createContext<React.RefObject<
  number | null
> | null>(null);

/*
 * For rows drawn later but older than everything on screen: an earlier page added above as the
 * reader scrolls up (`useTranscriptPages`). They are history, so they draw at rest.
 */
const AT_REST: React.RefObject<number | null> = { current: null };

function ArrivalsLive({ children }: { children: React.ReactNode }) {
  const live = useRef<number | null>(null);
  useEffect(() => {
    live.current = Date.now();
  }, []);
  return (
    <ArrivalsLiveContext.Provider value={live}>
      {children}
    </ArrivalsLiveContext.Provider>
  );
}

/**
 * Whether this row arrived while the conversation was open, decided once at its first render (see
 * `ArrivalsLiveContext`), so a reply streaming into it can never change the answer.
 *
 * `happenedAt` is for a row that is late rather than new: a voice chat from before the conversation
 * opened, when the voice service answered after the conversation was already showing. It mounts
 * among rows on screen but is history, and draws at rest.
 */
function useArrivedLive(happenedAt?: string): boolean {
  const liveRef = useContext(ArrivalsLiveContext);
  const [live] = useState(() => {
    if (liveRef === null) return true;
    const since = liveRef.current;
    if (since === null) return false;
    return happenedAt === undefined || !(Date.parse(happenedAt) < since);
  });
  return live;
}

/**
 * How Streamdown draws a Bot's message, decided once when the message mounts. History is finished
 * text and takes the static renderer, which does no repair of half-written markdown; anything that
 * arrived live, or was still streaming when the conversation opened, takes the streaming one and
 * keeps it after it finishes, so the renderer never changes under the reader. Exported for its test.
 */
export function messageMode(
  live: boolean,
  streaming: boolean,
): "static" | "streaming" {
  return live || streaming ? "streaming" : "static";
}

/**
 * A turn arriving in the transcript.
 *
 * WHY IT ANIMATES AT ALL: a message currently pops into existence at full opacity, and the eye has
 * nothing to follow from the composer to the transcript. This bridges that, and nothing more — it
 * is not decoration on something the reader is trying to read.
 *
 * IT RUNS ONCE, ON MOUNT. `initial`/`animate` fire when the element mounts, and the memoised parents
 * mean a streaming answer re-renders without remounting — so the fade plays when the message first
 * appears and never again while its text is still arriving. Animating per chunk would strobe.
 *
 * TRANSFORM AND OPACITY ONLY, so the scroller can still measure. `MessageScroller` sizes items and
 * places its anchor and spacer from layout; a transform is composited and changes no layout box, so
 * a message can fade in without moving the thing the scroller just measured.
 *
 * The full transform string rather than motion's `y` shorthand: the shorthand is not hardware
 * accelerated and drops frames exactly when the main thread is busy, which here is while a reply is
 * streaming.
 *
 * ONLY FOR WHAT ARRIVES WHILE THE CONVERSATION IS OPEN. A row mounted with the history draws at
 * rest here and takes the opening stagger instead (`openingStagger`); `ArrivalsLiveContext` says
 * which is which, decided once at the row's first render so a streaming answer can never replay it.
 */
function Arriving({
  children,
  happenedAt,
}: {
  children: React.ReactNode;
  /** When what the row shows happened, if it can say; see `useArrivedLive`. */
  happenedAt?: string;
}) {
  const shouldReduceMotion = useReducedMotion();
  const live = useArrivedLive(happenedAt);

  return (
    <motion.div
      animate={{ opacity: 1, transform: "translateY(0px)" }}
      /*
       * `data-slot` IS LOAD-BEARING, NOT DECORATION. `MessageContent` right-aligns a person's own
       * message with `group-data-[align=end]/message:*:data-slot:self-end` — a selector that reaches
       * DIRECT CHILDREN CARRYING A data-slot. Wrapping the bubble in a plain div made this the direct
       * child, the selector matched nothing, and every message a person sent quietly moved to the
       * left column and read as though the Bot had said it.
       */
      data-slot="message-arriving"
      /*
       * FULL WIDTH, AND A FLEX COLUMN, because that is what it displaced. `Bubble` is
       * `w-fit max-w-[80%]` and aligns itself with `group-data-[align=end]/message:self-end`. Both
       * need the parent this wrapper replaced: against a shrink-to-fit box the 80% resolves against
       * the bubble's own width and short messages wrap for no reason, and `self-end` does nothing at
       * all outside a flex container.
       */
      className="flex w-full flex-col"
      initial={
        live
          ? {
              opacity: 0,
              // Reduced motion keeps the fade and drops the movement: gentler, not absent.
              transform: shouldReduceMotion ? "none" : "translateY(8px)",
            }
          : false
      }
      transition={{
        duration: ENTRANCE_SECONDS,
        ease: EASE_OUT,
      }}
    >
      {children}
    </motion.div>
  );
}

/**
 * A turn a schedule asked for, drawn as the event it is.
 *
 * The frame around a firing is addressed to the model — see `shared/routine-firing.ts` — and it
 * reached the transcript wearing `role: "user"`, which drew it as a muted bubble on the right, in
 * the exact style of something the person typed. Somebody reading back through a channel found
 * three sentences of instructions to a model in their own voice, telling their Bot what it may not
 * do. For a product whose whole claim is that a Bot is a coworker you can hold to account, a record
 * that misattributes who said what is the one thing it cannot afford.
 *
 * So: start-aligned and muted, because this is not the person speaking; the clock, because that is
 * what a routine already is everywhere else in the app; and the instruction ALONE, because that is
 * the part a person wrote and the only part addressed to them.
 */
function RoutineFiring({ instruction }: { instruction: string }) {
  const responsibility = readResponsibilityTurn(instruction);
  if (responsibility) {
    return <ResponsibilityFiring raw={instruction} turn={responsibility} />;
  }
  return (
    <div className="flex min-w-0 items-baseline gap-2 text-muted-foreground text-sm">
      <IconClock aria-hidden className="size-4 shrink-0 translate-y-0.5" />
      <span className="min-w-0">
        <span className="font-medium">Routine ran.</span>{" "}
        <span className="whitespace-pre-wrap">{instruction}</span>
      </span>
    </div>
  );
}

/** `manual/requested` reads as "manual"; anything else keeps its event type beside the source. */
function describeTrigger(trigger: string): string {
  const [source, type] = trigger.split("/", 2);
  if (!type || type === "requested") return source ?? trigger;
  return `${source} · ${type}`;
}

/**
 * A responsibility's turn, drawn as the event it is.
 *
 * The message a responsibility sends its Bot carries the success criteria, the progress so far, the
 * trigger, the event payload in its untrusted envelope and a reminder naming the report tool — all
 * of it addressed to the model. Drawn inline, a person scrolling their conversation read a page of
 * scaffolding every time the responsibility ran. So the line says what happened and what the person
 * asked for, and the whole message sits behind "Details" for anyone checking what the Bot was told.
 */
function ResponsibilityFiring({
  raw,
  turn,
}: {
  raw: string;
  turn: { instruction: string; trigger: string };
}) {
  return (
    <div className="flex min-w-0 items-baseline gap-2 text-muted-foreground text-sm">
      <IconClock aria-hidden className="size-4 shrink-0 translate-y-0.5" />
      <div className="min-w-0">
        <p>
          <span className="font-medium">Responsibility ran.</span> Trigger:{" "}
          {describeTrigger(turn.trigger)}
        </p>
        <p className="whitespace-pre-wrap">{turn.instruction}</p>
        <details className="group mt-1">
          <summary className="inline-flex cursor-pointer list-none items-center gap-1 rounded-sm text-xs outline-none focus-visible:ring-2 focus-visible:ring-ring [&::-webkit-details-marker]:hidden">
            Details
            <IconChevronDown
              aria-hidden
              className="size-3 transition-transform group-open:rotate-180 motion-reduce:transition-none"
            />
          </summary>
          <p className="mt-1 whitespace-pre-wrap break-words text-xs">{raw}</p>
        </details>
      </div>
    </div>
  );
}

/**
 * One drawn message, and it is memoised on PRIMITIVES ON PURPOSE.
 *
 * A streamed answer changes `messages` on every chunk, and `toVisibleChatItems` builds fresh objects
 * from it each time — so a memo comparing item objects would miss on every single one and buy
 * nothing. Passing role and text means an untouched message compares equal and is skipped.
 *
 * MEASURED, BEFORE AND AFTER. One reply into a 25-message thread cost 76 transcript renders and
 * 1,890 message renders, because every message in the history re-parsed its markdown on every
 * chunk. That is the jank: the scroll was following a list that rebuilt itself 76 times.
 *
 * It is also what keeps the entrance honest — no remount means no replay of the fade.
 */
const TranscriptMessage = memo(function TranscriptMessage({
  commandNames = "",
  role,
  streaming = false,
  text,
}: {
  commandNames?: string;
  role: "user" | "assistant";
  /* This is the Bot's reply still being written: the last row of a turn in flight. */
  streaming?: boolean;
  text: string;
}) {
  const isUser = role === "user";
  const live = useArrivedLive();
  const [mode] = useState(() => messageMode(live, streaming));
  // A person's message arrives whole; only a Bot's reply is paced.
  const revealed = usePacedReveal(text, {
    live: live && !isUser,
    streaming,
  });
  /*
   * Checked before anything else a person's message gets. A firing is not a person's message: the
   * chip split, the end alignment and the bubble are all wrong for it, and each one of them would
   * have to learn about firings separately if this branched any later.
   */
  const firing = isUser ? readFiring(text) : null;
  if (firing !== null) {
    return (
      <MessageRow align="start">
        <MessageContent>
          <Arriving>
            <RoutineFiring instruction={firing} />
          </Arriving>
        </MessageContent>
      </MessageRow>
    );
  }
  const align = isUser ? "end" : "start";
  // Slack/Teams turns carry a model-facing participant line; show a marker instead of the line.
  const origin = isUser ? splitChatOrigin(text) : null;
  const said = origin ? origin.text : text;
  const invoked = isUser ? splitSkillChip(said, commandNames) : null;

  return (
    <MessageRow align={align}>
      <MessageContent>
        <Arriving>
          {/*
            A Bot's message takes the whole column, not the width of its words: block content
            inside it — a fenced code block, a table — should span the transcript rather than
            shrink to its own text. A person's bubble keeps fitting what they said.
          */}
          <Bubble
            align={align}
            variant={isUser ? "muted" : "ghost"}
            className={isUser ? undefined : "w-full"}
          >
            <BubbleContent className={isUser ? undefined : "w-full"}>
              {isUser ? (
                // A person's own message is shown exactly as they typed it. Rendering it as markdown
                // would silently reformat what they said, and an asterisk in a sentence is not
                // emphasis. The chip is the one exception, and it is not reformatting: it is drawing
                // the thing that was already a chip in the composer as a chip here too, so the
                // transcript shows a skill was used rather than a slash that was typed.
                <span className="whitespace-pre-wrap">
                  {origin && (
                    <span className="mr-1.5 inline-flex items-center rounded bg-foreground/10 px-1.5 py-0.5 align-middle text-foreground/70 text-xs">
                      via {origin.via}
                    </span>
                  )}
                  {invoked ? (
                    <>
                      {/*
                       * The same icon the sidebar uses for Skills, so the badge says WHAT KIND of
                       * thing was invoked before it says which one. `inline-flex` with
                       * `align-middle` rather than a block: this sits mid-sentence, and a badge that
                       * breaks the line it is in reads as a separate message.
                       */}
                      <span className="mr-1 inline-flex items-center gap-1 rounded bg-foreground/10 px-1.5 py-0.5 align-middle font-mono text-foreground/80 text-xs">
                        <IconBox className="size-3 shrink-0" />/{invoked.chip}
                      </span>
                      {invoked.rest}
                    </>
                  ) : (
                    said
                  )}
                </span>
              ) : (
                /*
                 * A Bot's prose is markdown, and it arrives in pieces.
                 *
                 * Rendered with a streaming-aware renderer rather than an ordinary one: half a fenced
                 * code block or an unclosed bold marker is the NORMAL state for most of a run, and a
                 * plain markdown parser draws that as literal asterisks and backticks until the
                 * closing token arrives, so the answer visibly rewrites itself as it lands. This
                 * closes them for the duration.
                 */
                <Streamdown components={markdownComponents} mode={mode}>
                  {revealed}
                </Streamdown>
              )}
            </BubbleContent>
          </Bubble>
        </Arriving>
      </MessageContent>
    </MessageRow>
  );
});

/**
 * The one shape an attachment url is allowed to have, taken from the helper that builds it rather
 * than written out again, so the check cannot drift from the route that serves the file.
 */
const ATTACHMENT_URL_PREFIX = attachmentUrl("");

/**
 * THE FILES A PERSON ATTACHED TO ONE TURN, drawn as a row where their own message would be.
 *
 * ALWAYS THE PERSON'S OWN, so it aligns end like their bubble does — `toVisibleChatItems` only ever
 * produces this kind from a user turn's content, and there is no assistant equivalent to confuse it
 * with. `justify-end` is what actually puts a short row against the right edge; `align="end"` gets
 * the row there, not the tiles inside it.
 *
 * SQUARE, AND ALL THE SAME SIZE. Three photos of different shapes drawn at their own aspect ratios
 * make a ragged row whose only signal is which camera took what, and a single tall screenshot drawn
 * at its own aspect pushed the rest of the turn off the screen. A grid of equal tiles says "three
 * files" at a glance, which is the thing worth saying here; the picture itself is one click away.
 */
type AttachmentRowProps = {
  attachments: readonly SentAttachment[];
};

/**
 * Whether two renders of this row are the same row, compared BY VALUE because identity says no
 * every time.
 *
 * `toVisibleChatItems` runs on every render of the transcript — deliberately, and the comment on
 * that call says why: the agent hands back the same array and mutates it, so a `useMemo` over it
 * never invalidates and a reply never appears. The price is that `attachments` is a fresh array of
 * fresh objects on every chunk of a streaming answer, and `memo`'s default `Object.is` on two
 * different arrays is false however identical they are. So this memo missed EVERY time, and every
 * tile in a channel's history — each one carrying an image `Dialog` — re-rendered on every token
 * of an answer being typed further down. The memoised message rows above it were paying for this
 * one's misses.
 *
 * Field by field, because the fields are what the tiles draw: a row whose files have the same ids,
 * urls, names and kinds in the same order draws exactly the same pixels.
 *
 * Exported so it can be checked without mounting anything, the same reason `isPersonSentMessage`
 * is.
 */
export function sameAttachmentRow(
  previous: AttachmentRowProps,
  next: AttachmentRowProps,
): boolean {
  if (previous.attachments.length !== next.attachments.length) {
    return false;
  }

  return previous.attachments.every((attachment, index) => {
    const other = next.attachments[index];
    return (
      other !== undefined &&
      attachment.id === other.id &&
      attachment.attachmentId === other.attachmentId &&
      attachment.url === other.url &&
      attachment.filename === other.filename &&
      attachment.modality === other.modality
    );
  });
}

export const TranscriptAttachments = memo(function TranscriptAttachments({
  attachments,
}: AttachmentRowProps) {
  return (
    <MessageRow align="end">
      <MessageContent>
        <Arriving>
          <AttachmentTiles attachments={attachments} />
        </Arriving>
      </MessageContent>
    </MessageRow>
  );
}, sameAttachmentRow);

/**
 * The tiles themselves, as one row.
 *
 * Its own component because the QUEUE draws this row too, faded, for a message parked mid-turn —
 * and two copies of a list of tiles is two places for the alignment below to be got right.
 *
 * `self-end` because `align="end"` does not reach this far on its own: both callers put this
 * inside a `flex w-full flex-col` — `Arriving` for a sent turn, `MessageContent` for a parked one —
 * so a block child stretches to the transcript's full width and its contents draw hard against the
 * LEFT edge, under the person's own right-aligned bubble, reading as though the Bot had sent them.
 * `Bubble` escapes this because it carries its own `group-data-[align=end]/message:self-end`.
 */
function AttachmentTiles({
  attachments,
  className,
}: {
  attachments: readonly SentAttachment[];
  className?: string;
}) {
  return (
    <ul
      className={cn(
        "flex w-fit flex-wrap items-start justify-end gap-2 self-end",
        className,
      )}
    >
      {attachments.map((attachment) => (
        <li key={attachment.id}>
          <SentAttachmentTile attachment={attachment} />
        </li>
      ))}
    </ul>
  );
}

/**
 * One tile in that row, and all three shapes are the same size on purpose.
 *
 * A document used to draw as a `ToolLine`, which was the right call while an attachment was a row
 * of its own: that component is one line for one thing a Bot did, and a filename beside a label is
 * exactly that shape. It is the wrong thing inside a ROW. `ToolLine` has no width of its own, so
 * two documents and a photo came out as a pair of bare sentences stretched across the empty half of
 * the line with the picture stranded at the end — the same tiles, laid out as if they were prose.
 *
 * So a document gets a card the height of a thumbnail instead. What the row is saying is "these
 * files came with this message", and it can only say it if every tile in it reads as a file.
 *
 * A BROKEN-IMAGE GLYPH SAYS NOTHING TO THE READER — the browser's placeholder tells them a box
 * failed to load, not that a file is gone. `onError` catches that and swaps it for a sentence in the
 * file's own name, in the same destructive vocabulary `Stopped` already uses for "the thing that was
 * supposed to be here isn't." It borrows the LOOK and not the urgency: see the missing tile below
 * for why the same absence is a note here and an alert there.
 */
/**
 * The probes currently outstanding, so that two tiles asking the same question ask it once.
 *
 * ONE TURN CAN CARRY THE SAME FILE TWICE — `toVisibleChatItems` keys tiles on the PART index
 * precisely so that it can — and a message parked mid-turn draws its files a second time beside the
 * sent row while the queue holds it. Each of those tiles mounts its own effect, and each one used
 * to send its own request for an answer that is the same by construction.
 *
 * WHAT THAT SHARING IS WORTH, CORRECTED. This comment used to say a duplicate probe was "a
 * duplicate megabyte read, not a duplicate status line", because at the time a HEAD reached a
 * handler whose single statement selected `attachments.bytes`. It does not any more: the route
 * grew a branch that answers a HEAD from `name, mimeType, sizeBytes` and never touches the bytes.
 * A duplicate probe is now exactly the duplicate status line this once said it was not.
 *
 * IT STILL EARNS ITS KEEP, FOR A REASON THAT DOES NOT DEPEND ON THE OLD COST. Nothing else in the
 * stack will coalesce these: the route serves `private, no-cache`, so the browser's HTTP cache is
 * required to revalidate every probe rather than answer one from the other, and two tiles for one
 * file are two components with two effects and no knowledge of each other. Without this map the
 * same question goes over the wire once per tile, every time the transcript mounts. It is a dozen
 * lines to ask it once, and cheap-per-answer is not the same as free-per-answer.
 *
 * IN FLIGHT ONLY, AND DELIBERATELY NOT A CACHE OF THE ANSWERS — and THIS is the half the old cost
 * model was never holding up. Holding onto "this file is still there" across remounts is exactly
 * the lie this hook exists to stop: a file deleted while the reader has the app open would go on
 * drawing as an intact card for as long as the tab lived, which is the "worse of the two lies" the
 * comment below names. That was the argument then and it is the whole argument now. Holding onto
 * "this file is GONE" is sound, deletion being terminal, but it buys nothing worth the branch.
 */
const probesInFlight = new Map<string, Promise<boolean>>();

/**
 * Asks the route whether this file is missing, and answers the SAME question only once at a time.
 *
 * Resolves true for 404 and false for every other answer; a fetch that never arrives rejects, and
 * the caller declines to draw a conclusion from it.
 */
function probeDocument(url: string): Promise<boolean> {
  const existing = probesInFlight.get(url);
  if (existing) return existing;

  const probe = fetch(url, { method: "HEAD", credentials: "include" })
    .then((response) => response.status === 404)
    .finally(() => {
      // Cleared however it settled, so the next mount asks again rather than inheriting an answer
      // that has had time to stop being true.
      probesInFlight.delete(url);
    });

  probesInFlight.set(url, probe);
  return probe;
}

/**
 * Whether the row behind a document has been deleted, asked of the server that serves it.
 *
 * A DOCUMENT HAS NO OTHER WAY TO FIND OUT. The picture beside it learns its file is gone by
 * fetching it: the `<img>` requests the url, the route answers 404, and `onError` fires. A document
 * tile is a filename and a label — it requests nothing, so no event about the file can ever reach
 * it — and `failedToLoad` was the only thing feeding the absent branch. A deleted document
 * therefore kept drawing as an intact card naming a file the server was answering 404 for, which
 * is the worse of the two lies: a broken picture at least looks broken.
 *
 * `HEAD` because the question is whether the row exists and the status line is the whole answer, so
 * the reader is not made to download a PDF to learn it is still there. AND IT IS NOW CHEAP ON THE
 * SERVER TOO, WHICH IT ONCE WAS NOT AND WHICH THIS COMMENT WENT ON ASSERTING AFTER IT STOPPED BEING
 * TRUE. The old paragraph was right about the mechanism — Hono does answer a HEAD by dispatching
 * the GET handler in full and dropping the body at the last step — and it concluded that the server
 * therefore still read the whole file out of Postgres, and that a route which could answer "is it
 * there" without the bytes "is not this file's to write". Somebody wrote it. The attachment route
 * now branches on the method INSIDE the handler Hono actually dispatches, selects `sizeBytes`
 * instead of `bytes`, and sets `Content-Length` by hand; the access join, the statuses and the
 * revalidation are the GET's exactly, so a probe still learns nothing a fetch would not tell you.
 *
 * That is recorded here rather than quietly deleted because this file spent two review rounds being
 * read as evidence that the cheap probe did not exist. A comment describing a path as broken, about
 * a path that works, costs more than no comment at all.
 *
 * A REQUEST THAT NEVER ARRIVED IS NOT A DELETED FILE, so a rejected fetch — offline, a dropped
 * connection, a proxy in the way — leaves the card alone rather than accusing the server of having
 * lost somebody's file.
 *
 * AND NEITHER IS A REQUEST THE SERVER REFUSED, which is the same rule and was the bug. This asked
 * `!response.ok`, which is every status outside 200-299, when exactly one of them means what the
 * tile then says. The route collapses "no such row", "channel deleted" and "not a channel of
 * yours" into 404 precisely so that probing ids learns nothing — that is the one status that means
 * "there is no file here for you". Everything else is a fact about the request:
 *
 *   - 401 is a session that expired while the channel sat open, and it turned EVERY document tile
 *     in the transcript into a red card asserting, in each file's own name, that somebody's files
 *     had been deleted. Nothing had been; they need to sign in again.
 *   - 500 is a bad moment on the server, and it stuck: the deps below are stable, so nothing asks
 *     again and the accusation stands until the component remounts.
 *   - 304 is the strongest proof of PRESENCE this route can give — the row was found AND the
 *     membership join passed — and `Response.ok` is false for it.
 *
 * That is the same lie this hook exists to stop, pointing the other way, and it is the louder one:
 * drawn in the destructive vocabulary, naming the file. So absence is claimed on 404 alone, which
 * also puts a document back in step with the picture beside it — an `<img>` handed a 401 shows a
 * broken image, not a sentence swearing the file was deleted.
 */
function useDocumentIsGone(url: string, ask: boolean): boolean {
  const [gone, setGone] = useState(false);

  useEffect(() => {
    if (!ask) {
      return;
    }
    // A tile reused at the same position for a different file starts the question over rather than
    // inheriting the previous file's answer.
    setGone(false);

    let cancelled = false;
    void probeDocument(url)
      .then((missing) => {
        if (!cancelled && missing) {
          setGone(true);
        }
      })
      .catch(() => {
        // Deliberately nothing: see above. Not knowing is not the same as knowing it is gone.
      });

    return () => {
      cancelled = true;
    };
  }, [ask, url]);

  return gone;
}

function SentAttachmentTile({ attachment }: { attachment: SentAttachment }) {
  const [failedToLoad, setFailedToLoad] = useState(false);
  const { filename, modality, url } = attachment;
  /*
   * An off-site url is treated as a missing file, whatever kind of file it says it is.
   *
   * `toVisibleChatItems` passes on whatever a `url` source carried, and nothing between here and
   * the wire narrows it. A sent message only ever carries the relative form — `shared/attachments.ts`
   * says the url "is never fetched by a provider", and `copilot.ts` swaps the source for the bytes
   * as the run is built — so an absolute url arriving here did not come from this app's composer,
   * and putting it in `src` would have the reader's browser fetch a third party the instant the
   * transcript drew, announcing to whoever owns it that this person opened this channel.
   */
  const servable = url.startsWith(ATTACHMENT_URL_PREFIX);
  /*
   * ONLY OURS IS EVER ASKED ABOUT, and that is the same rule as the line above rather than a second
   * one: a probe is a request like any other, so asking a third party whether a file is still there
   * announces the reader exactly as fetching it would. An off-site url is already unavailable
   * without anybody being asked.
   */
  const gone = useDocumentIsGone(url, servable && modality === "document");
  const unavailable = failedToLoad || gone || !servable;

  /*
   * ABSENCE IS DECIDED BEFORE MODALITY IS, and that ordering is the whole point of this block
   * sitting above the document card rather than below it. A document whose url is not ours to
   * serve, or whose row `useDocumentIsGone` found deleted, drew as an intact card naming a file
   * that is not there. A missing picture at least looked missing; a missing document looked
   * present. Whether the file can be shown at all is the first question either kind asks.
   */
  if (unavailable) {
    return (
      /*
       * `note`, NOT `alert`, AND THE DIFFERENCE IS WHO IS INTERRUPTED. An alert is an assertive
       * live region: it cuts across whatever a screen reader is saying the moment it appears. That
       * is right for `Stopped`, which reports something that just happened in answer to what
       * somebody did, and wrong for every one of these — a transcript with three deleted files
       * fired three interruptions on mount, before the reader had heard a word of the conversation,
       * to report absences that predate their opening the channel.
       *
       * `note` is not a live region at all, so nothing is announced over anything; it still marks
       * the tile as a thing to stop on, and the sentence inside it — unchanged, in the file's own
       * name — is what says the file is gone when the reader reaches it.
       */
      <div
        className="flex h-32 w-44 flex-col justify-center gap-2 rounded-xl border border-destructive border-dashed p-3 text-destructive"
        role="note"
      >
        <IconAlertTriangle className="size-6" />
        <p className="text-sm">{unavailableSentence(filename)}</p>
      </div>
    );
  }

  if (modality === "document") {
    return (
      <div className="flex h-32 w-44 flex-col justify-between rounded-xl border border-border bg-muted/40 p-3">
        <IconFile className="size-6 text-muted-foreground" />
        <div className="min-w-0">
          {/* `title` because the tile is fixed-width and a long name is cut, not wrapped. */}
          <p className="truncate font-medium text-sm" title={filename}>
            {filename ?? "Untitled file"}
          </p>
          <p className="text-muted-foreground text-xs">Attachment</p>
        </div>
      </div>
    );
  }

  return (
    <AttachmentLightbox filename={filename} url={url}>
      <img
        alt={filename ? `Attachment: ${filename}` : "Attachment"}
        className="size-32 rounded-xl object-cover"
        onError={() => setFailedToLoad(true)}
        src={url}
      />
    </AttachmentLightbox>
  );
}

/**
 * What an absent file is called, in one place, because two surfaces now say it.
 *
 * The tile said it and the lightbox behind the tile said nothing at all. Sharing the wording rather
 * than writing it twice is what keeps them from drifting into two different accounts of the same
 * absence — the tile naming the file and the dialog saying something vaguer, or worse, later.
 *
 * A file with no name still gets a sentence rather than a blank: the reader clicked on something,
 * and "this attachment" is the honest way to refer to a thing whose name we never had.
 */
function unavailableSentence(filename?: string): string {
  return filename
    ? `${filename} is unavailable.`
    : "This attachment is unavailable.";
}

/**
 * The full-size picture inside the lightbox, and what it draws when the file will not load.
 *
 * IT NEEDED A FAILURE STATE AND HAD NONE. The tile in front of it has had one from the start — an
 * `onError` swapping the broken-image box for a sentence, with a comment above it about why the
 * browser's own placeholder "says nothing to the reader" — and this `<img>`, the one drawn at full
 * size against a dark backdrop with the reader's whole attention on it, had no `onError` at all. A
 * file deleted between the tile painting and the reader clicking it opened a dialog containing
 * exactly the placeholder the tile path exists to avoid.
 *
 * THE TILE CANNOT COVER THIS ONE. Its own `<img>` has already loaded by the time there is anything
 * to click, and a loaded image does not fire `error` again because the file behind it went away; the
 * request that finds out is this one. Nor can the probe beside it: `useDocumentIsGone` deliberately
 * never asks about a picture, because a picture's own load is supposed to be the answer — and this
 * is the load it meant.
 *
 * IT STAYS OPEN AND SAYS SO, rather than closing itself. The reader opened this deliberately, and a
 * dialog that vanishes on its own leaves them looking at the transcript with no idea what happened
 * and their focus wherever the close put it. The sentence in place answers the question they
 * actually asked. Escape and the close button still work, and the state resets when the popup
 * unmounts, so reopening genuinely tries again rather than remembering a failure.
 *
 * ITS OWN COMPONENT, AND EXPORTED, SO THE FAILURE CAN BE TESTED AT ALL: Base UI portals this popup
 * and under happy-dom the portal never mounts — checked, and recorded in the test named "a thumbnail
 * is a crop" — so there is no way to reach this `<img>` through the trigger. Same reason
 * `sameAttachmentRow` is exported: the behaviour is worth pinning and the thing it lives inside
 * cannot be mounted here.
 */
export function LightboxPicture({
  filename,
  url,
}: {
  filename?: string;
  url: string;
}) {
  const [failedToLoad, setFailedToLoad] = useState(false);

  if (failedToLoad) {
    return (
      /*
       * `note` rather than `alert`, for the reason the tile's own missing card gives at length: an
       * assertive live region cuts across whatever a screen reader is saying, and this is an answer
       * to something the reader just did rather than an emergency. Light-on-dark because it is
       * drawn against the lightbox's own backdrop, where `text-destructive` is unreadable.
       */
      <div
        className="flex flex-col items-center gap-3 p-8 text-center text-white"
        role="note"
      >
        <IconAlertTriangle className="size-8" />
        <p className="text-sm">{unavailableSentence(filename)}</p>
      </div>
    );
  }

  return (
    <img
      alt={filename ?? "Attachment"}
      className="max-h-[88svh] max-w-[92vw] rounded-lg object-contain"
      onError={() => setFailedToLoad(true)}
      src={url}
    />
  );
}

/**
 * The square, opened.
 *
 * The tile is a crop — that is the price of a tidy row — so there has to be a way to see the whole
 * picture, and it used to be `target="_blank"`. A new tab is a worse answer than it looks: it drops
 * the reader out of the conversation they were reading, the browser shows the raw file against its
 * own chrome with no way back but the back button, and on a phone it is a context switch away from
 * the channel entirely. A dialog closes on Escape and puts them back exactly where they were.
 *
 * Built on the app's `Dialog` so focus trapping, scroll locking and Escape behave the way they do
 * everywhere else, but with its card stripped off: `max-w-none border-0 bg-transparent p-0
 * shadow-none` leaves the picture as the only lit thing against a dark backdrop.
 *
 * THE CLOSE BUTTON IS FIXED TO THE VIEWPORT, not to the popup, which is why `showCloseButton` is
 * off and this draws its own. Pinned to the popup it would sit on the picture — invisible over a
 * pale one, and moving with every image's shape.
 */
function AttachmentLightbox({
  children,
  filename,
  url,
}: {
  children: React.ReactNode;
  filename?: string;
  url: string;
}) {
  const label = filename ?? "Attachment";
  /*
   * Controlled only so that clicking the dark space around the picture closes it, the way every
   * lightbox a reader has used does. The popup covers the viewport (see below), so it — not the
   * backdrop underneath — is what receives that click, and Base UI's own dismiss never fires.
   */
  const [open, setOpen] = useState(false);

  return (
    <Dialog onOpenChange={setOpen} open={open}>
      <DialogTrigger
        // A button, not a link: it opens something on this page, and a middle-click offering a new
        // tab to a raw image file is not the promise this makes. `block` so the tile is not sitting
        // on a text baseline with a stray gap under it.
        className="block cursor-zoom-in overflow-hidden rounded-xl"
        render={<button aria-label={`Open ${label}`} type="button" />}
      >
        {children}
      </DialogTrigger>
      <DialogContent
        /*
         * THE CARD IS STRIPPED OFF AND THE POPUP IS MADE FULL-SCREEN, and the second half is not
         * cosmetic. `DialogContent` centres itself with `-translate-x-1/2 -translate-y-1/2`, and a
         * transform on an ancestor is what `position: fixed` resolves against — so a close button
         * "fixed to the viewport" inside it landed 72px down and 30px in from the corner instead of
         * at it. Measured, not guessed. A popup that already IS the viewport has no transform, and
         * `absolute` in it means the corner it looks like it means.
         *
         * Centring by flex rather than by width also lets the picture keep its own shape: as a
         * stretched flex child it was drawn 1012px wide for a 644px image, letterboxed inside a box
         * far bigger than itself.
         */
        className="inset-0 top-0 left-0 h-full max-h-none w-full max-w-none translate-x-0 translate-y-0 items-center justify-center rounded-none border-0 bg-transparent p-0 shadow-none"
        onClick={(event) => {
          if (event.target === event.currentTarget) setOpen(false);
        }}
        overlayClassName="bg-black/80 supports-backdrop-filter:backdrop-blur-sm"
        showCloseButton={false}
      >
        {/* Named for a screen reader; the picture carries the same name in its alt text. */}
        <DialogTitle className="sr-only">{label}</DialogTitle>
        <LightboxPicture filename={filename} url={url} />
        <DialogClose
          render={
            <button
              aria-label="Close"
              className="absolute top-4 right-4 grid size-9 place-items-center rounded-full bg-white/10 text-white transition-colors hover:bg-white/20"
              type="button"
            />
          }
        >
          <IconX className="size-5" />
        </DialogClose>
      </DialogContent>
    </Dialog>
  );
}

/**
 * What a failed activity is called on screen.
 *
 * An `activityType` is a protocol name and reads like one, so the boundary's sentence gets a phrase
 * a person can read instead. An unknown type falls back to its own name rather than to something
 * vague: whoever registered it will recognise it, and nobody else can act on either wording.
 */
function activityName(activityType: string): string {
  return activityType === "open-generative-ui"
    ? "This Bot's generated interface"
    : activityType;
}

/**
 * One activity, drawn by whichever renderer claims its type.
 *
 * The renderer comes from the SDK's registry, so an activity nobody registered draws nothing and
 * this returns null rather than an empty row — unlike a tool call, which always has a line to fall
 * back to because a call that happened is worth reporting even undrawn. An activity is the drawing;
 * with no renderer there is nothing to say about it.
 *
 * The memo boundary earns its place differently here than on a tool call. It cannot spare this
 * component its own churn — a generated interface streams, and `content` is a new object on every
 * chunk, which is exactly when it must re-render — but it does stop the sentence being typed after it
 * from re-rendering a mounted iframe.
 */
const TranscriptActivity = memo(function TranscriptActivity({
  message,
}: {
  message: ActivityMessage;
}) {
  const { renderActivityMessage } = useRenderActivityMessage();
  /*
   * Drawn before generative UI was switched on (a cold load: the capabilities answer or the runtime
   * connection still on its way), an activity found no renderer. Read so it redraws when the
   * renderers arrive, rather than staying blank until its own message next changes; see
   * `LateRenderersWatch`, which the transcript mounts once for all of them.
   */
  useContext(LateRenderersContext);
  const call =
    message.activityType === VOICE_CHAT_ACTIVITY
      ? (message.content.call as VoiceChatEntry)
      : null;
  const drawn = call ? (
    <VoiceChatCard call={call} />
  ) : (
    renderActivityMessage(message)
  );
  if (!drawn) return null;

  return (
    <Arriving happenedAt={call?.startedAt}>
      <ToolRenderBoundary name={activityName(message.activityType)}>
        {drawn}
      </ToolRenderBoundary>
    </Arriving>
  );
});

/**
 * One drawn tool call, memoised on the same terms.
 *
 * The `toolCall` object is rebuilt here from its parts rather than passed down, because the one on
 * the message is a new object on every chunk and would defeat the memo exactly as the text items
 * did. A finished chart re-rendering on every token of the sentence after it is not free.
 *
 * `useRenderToolCall` is called HERE rather than passed in as a prop: a function whose identity the
 * parent cannot guarantee is the classic way to make a memo boundary useless.
 */
const ToolCallBody = memo(function ToolCallBody({
  toolCallId,
  name,
  args,
  result,
  latest,
  spokeAfter,
}: {
  toolCallId: string;
  name: string;
  args: string;
  result?: string;
  /** Nothing said or queued since this call, and the Bot is not working. See `CardPlace`. */
  latest: boolean;
  /** The Bot said something after this call in its turn. See `ToolPlace`. */
  spokeAfter: boolean;
}) {
  const renderToolCall = useRenderToolCall();
  const toolCall = useMemo(
    () => ({
      id: toolCallId,
      type: "function" as const,
      function: { name, arguments: args },
    }),
    [toolCallId, name, args],
  );

  const drawn = renderToolCall({
    toolCall,
    ...(result === undefined
      ? {}
      : {
          toolMessage: {
            id: `${toolCallId}-result`,
            role: "tool",
            toolCallId,
            content: result,
          },
        }),
  });

  const place = useMemo(
    () => ({ toolCallId, latest, spokeAfter }),
    [toolCallId, latest, spokeAfter],
  );

  return (
    <ToolRenderBoundary
      final={toolCallFinal(args, result)}
      name={name}
      resetKey={args}
    >
      <ToolPlaceContext.Provider value={place}>
        {/*
         * A TOOL WITH NO REGISTERED RENDERER STILL HAPPENED, and since tools moved to the server
         * that is now the ordinary case rather than the exception: MCP tools execute in the runtime
         * and register no renderer here at all. `renderToolCall` still draws the components the app
         * registers, and everything else lands below.
         *
         * What was called, shimmering until its result arrives, and then the server's own words
         * drawn the way a Bot's prose is drawn.
         */}
        {drawn ?? (
          <ServerToolLine
            name={name}
            place={{ toolCallId, latest }}
            result={result}
          />
        )}
      </ToolPlaceContext.Provider>
    </ToolRenderBoundary>
  );
});

/**
 * A row of tool calls, drawn by ONE component whatever it holds, so a row is never rebuilt as its
 * calls change. A lone call is the line or card it always was; a run, or a browser step, is the
 * folded group. Both a `tools` group and a single `tool` item come through here, because a lone call
 * can be either over its life (it stops folding once its answer asks the person) under one key; see
 * `groupToolSteps`.
 */
type ToolRowProps = {
  id: string;
  steps: ToolGroup["steps"];
  active: boolean;
  latest: boolean;
  /** The Bot said something after this row in its turn. See `ToolPlace`. */
  spokeAfter: boolean;
};

/**
 * Whether a tool row would draw the same thing. `groupToolSteps` builds new step objects and a new
 * array on every render (it has to: the agent mutates the messages in place), so the default memo
 * check saw a change on every token of a reply streaming below and redrew every finished tool group
 * in the history, markdown inside collapsed details included. What a row draws is its steps' calls
 * and results, and those are what is compared. Exported for its test.
 */
export function sameToolRow(a: ToolRowProps, b: ToolRowProps): boolean {
  return (
    a.id === b.id &&
    a.active === b.active &&
    a.latest === b.latest &&
    a.spokeAfter === b.spokeAfter &&
    a.steps.length === b.steps.length &&
    a.steps.every((step, index) => {
      const other = b.steps[index];
      return (
        other !== undefined &&
        step.id === other.id &&
        step.result === other.result &&
        step.toolCall.function.name === other.toolCall.function.name &&
        step.toolCall.function.arguments === other.toolCall.function.arguments
      );
    })
  );
}

const ToolRow = memo(function ToolRow({
  id,
  steps,
  active,
  latest,
  spokeAfter,
}: ToolRowProps) {
  const [only] = steps;
  return (
    <Arriving>
      {steps.length === 1 && only && !isBrowserStep(only) ? (
        <ArgumentsArrivingContext.Provider value={active}>
          <ToolCallBody
            args={only.toolCall.function.arguments}
            latest={latest}
            name={only.toolCall.function.name}
            result={only.result}
            spokeAfter={spokeAfter}
            toolCallId={only.toolCall.id}
          />
        </ArgumentsArrivingContext.Provider>
      ) : (
        <ToolActivity active={active} group={{ kind: "tools", id, steps }} />
      )}
    </Arriving>
  );
}, sameToolRow);

/**
 * A tool the runtime executed, drawn for the person watching.
 *
 * Named from the reader's side: what was done, against which server, with the server's own words
 * behind a disclosure. The identifier the model was offered never reaches the screen.
 *
 * Exported for its tests, which draw it without the CopilotKit provider `ToolCallBody` needs.
 */
export function ServerToolLine({
  name,
  result,
  place,
}: {
  name: string;
  result?: string;
  /** Where this call sits in the conversation, for an app card that may carry the task on. */
  place?: CardPlace;
}) {
  const running = result === undefined;
  const { label, detail } = readToolName(name, running);
  /*
   * A refusal is not a result, and must not read like one.
   *
   * The server says which it is rather than the browser inferring it from the wording, because the
   * wording is a policy message an administrator can rewrite and the first rephrasing would break
   * any guess made here. See REFUSAL_MARKER in server/src/plugins/tools.ts.
   */
  const answer = result === undefined ? undefined : asText(result);
  const refused = answer?.startsWith(REFUSAL_MARKER) ?? false;
  const failed = !refused && toolResultFailed(result);
  /*
   * The marker is for this component, not for the reader. Left in, a refusal reads "Blocked" in the
   * label and then "Refused." again in the first two words of the body, which is the same fact three
   * times over by the end of the sentence. Stripped here rather than on the server, because the
   * server's copy is what the model is told and "Refused." in front of a reason is right for it.
   */
  const body = refused ? answer?.slice(REFUSAL_MARKER.length).trim() : answer;
  // A Team Bot asking to use this person's own account draws its consent card, not the sentence.
  const consent = refused ? readTeamBotConsent(body) : null;
  if (consent) return <TeamBotConsentCard {...consent} />;
  /*
   * An app this call could not use draws a card with the step that fixes it, not the name of a
   * screen: a refusal carrying the marker, or the answer of the one tool whose whole job is to put
   * that card on screen. Only that tool's ordinary answer is read for a marker — any other result
   * is somebody else's text, and a card must not be conjured out of it.
   */
  const card = refused
    ? readConnectPrompt(body)
    : name === SHOW_APP_ACCESS_TOOL
      ? readConnectPrompt(answer)
      : null;
  if (card) return <AppAccessCard place={place} prompt={card} />;
  /*
   * THAT TOOL'S OTHER ANSWERS ARE FOR THE MODEL. An app nobody can name comes back as plain text
   * telling the Bot to say so plainly and not to browse to it — an instruction, which read by the
   * person looks like the Bot being told off in front of them. The line still says the check
   * happened; the Bot's own reply says what it found.
   */
  const shown = name === SHOW_APP_ACCESS_TOOL ? undefined : body;
  return (
    <ToolLine
      {...(detail ? { detail } : {})}
      label={label}
      refused={refused}
      failed={failed}
      running={running}
    >
      {shown ? (
        <Streamdown components={markdownComponents}>
          {forDisplay(shown)}
        </Streamdown>
      ) : null}
    </ToolLine>
  );
}

/* Moved beside the turns it also decides; re-exported for the callers that read it from here. */
export { isPersonSentMessage };

/**
 * WHERE THE CONVERSATION HAS GOT TO, for an app card that may carry its task on once the app is
 * ready (see `lib/copilot/carry-on.ts`): the index from which a row is still the latest thing, or
 * past the end when none is.
 *
 * A card is the latest thing while nothing has been said to the Bot since it, nothing is queued, and
 * the Bot is not working: past that, the conversation has moved on, and an older task is not picked
 * up again underneath it. ANY USER TURN COUNTS, a routine firing included — unlike the scroll
 * machinery's `isPersonSentMessage`. A firing is not the person speaking, but it is a new task the
 * Bot has answered, and "please carry on" sent after it would land on the routine's work rather than
 * on the task the card interrupted. Exported so it can be checked without mounting anything.
 */
export function latestFrom(
  items: readonly TranscriptItem[],
  { busy, queued }: { busy: boolean; queued: number },
): number {
  if (busy || queued > 0) return items.length;
  return (
    items.findLastIndex(
      (item) =>
        (item.kind === "text" && item.role === "user") ||
        item.kind === "attachments",
    ) + 1
  );
}

/**
 * The turn a row belongs to.
 *
 * The attachments row is identified as `${messageId}:attachments` by `toVisibleChatItems`, so that
 * it and the caption beneath it can be told apart while still belonging to one turn. The id of the
 * message they were sent in is the part before the last colon.
 */
function turnOf(item: TranscriptItem): string {
  if (item.kind !== "attachments") {
    return item.id;
  }
  const separator = item.id.lastIndexOf(":");
  return separator === -1 ? item.id : item.id.slice(0, separator);
}

/**
 * Which rows the scroller may lift to the top of the viewport: THE FIRST ROW OF EACH TURN THE
 * PERSON SENT, and only that one.
 *
 * The scroller reads `data-scroll-anchor` off the rows appended in one go, takes the first it finds
 * and scrolls it to the top with a peek of the answer above it — but finding MORE THAN ONE among
 * that same batch it gives up on the ambiguity and jumps to the end instead. One turn is very often
 * several rows: a caption and its screenshot, or three files pasted together, all arrive at once.
 * So "every row a person sent" is not the rule; "the first row of every turn a person sent" is, and
 * the difference between them is the whole anchoring behaviour of an ordinary captioned message.
 *
 * A Bot's prose is never an anchor — the anchor exists to hold the QUESTION at the top while the
 * answer streams in underneath it — and neither is a routine firing, which arrived wearing
 * `role: "user"` without anybody having typed anything.
 *
 * Order is `toVisibleChatItems`' order, which puts a turn's attachments before its caption, so a
 * turn carrying a file is anchored on the first file and a plain one on its text. That is the right
 * end to hold: the picture is the top of what the person sent, and anchoring on the caption
 * underneath it would scroll the picture off the top of the pane.
 */
function anchorRowIds(items: readonly TranscriptItem[]): Set<string> {
  const anchors = new Set<string>();
  const claimed = new Set<string>();

  for (const item of items) {
    const sent =
      item.kind === "attachments" ||
      (item.kind === "text" && isPersonSentMessage(item.role, item.text));
    if (!sent) continue;

    const turn = turnOf(item);
    if (claimed.has(turn)) continue;
    claimed.add(turn);
    anchors.add(item.id);
  }

  return anchors;
}

/**
 * The only way to actually enforce exhaustiveness over `VisibleChatItem`: the
 * `item` parameter is typed `never`, so a branch that reaches here with a
 * member of the union still unhandled fails to compile, rather than a
 * trailing `: null` that accepts anything and renders nothing for it.
 */
function assertNever(_item: never): null {
  return null;
}

const SEND_SCROLL_MS = 700;

/**
 * Whether the viewport should glide for a beat because the person just sent something.
 *
 * ONLY FOR A SEND MADE WHILE THE CONVERSATION IS OPEN. The newest person-sent id also changes while
 * history is restored, batch by batch, and gliding then animated the scroller's jump to the bottom
 * of a channel being opened: the conversation visibly loaded and then slid. The first id seen once
 * history is in is the baseline, never a send.
 *
 * Exported so it can be checked without mounting anything.
 */
export function shouldGlideOnSend({
  previous,
  next,
  restoring,
  reducedMotion,
}: {
  previous: string | null;
  next: string | null;
  restoring: boolean;
  reducedMotion: boolean;
}): boolean {
  return (
    !restoring &&
    !reducedMotion &&
    previous !== null &&
    next !== null &&
    previous !== next
  );
}

function useSmoothSendScroll(
  viewport: React.RefObject<HTMLDivElement | null>,
  newestUserMessageId: string | null,
  restoring: boolean,
  onSend: () => void,
) {
  const reducedMotion = useReducedMotion();
  const seenRef = useRef<string | null>(null);
  /*
   * Whether the conversation has been seen open since it was restored. Separate from `seenRef`:
   * the glide needs a previous message to compare with, but a send does not. In a routine's channel
   * that holds only firings, the person's first message has nothing before it and is still a send.
   */
  const openRef = useRef(false);

  useLayoutEffect(() => {
    const element = viewport.current;
    const previous = seenRef.current;
    const wasOpen = openRef.current;
    // Nothing is recorded while restoring, so the first id after it is a baseline (see above).
    seenRef.current = restoring ? null : newestUserMessageId;
    openRef.current = !restoring;

    // A send picks following back up whatever the motion setting; only the glide depends on it.
    if (
      wasOpen &&
      !restoring &&
      newestUserMessageId !== null &&
      newestUserMessageId !== previous
    ) {
      onSend();
    }

    if (
      element === null ||
      !shouldGlideOnSend({
        previous,
        next: newestUserMessageId,
        restoring,
        reducedMotion: reducedMotion ?? false,
      })
    ) {
      return;
    }

    element.style.scrollBehavior = "smooth";
    const timer = window.setTimeout(() => {
      element.style.scrollBehavior = "";
    }, SEND_SCROLL_MS);

    return () => {
      window.clearTimeout(timer);
      element.style.scrollBehavior = "";
    };
  }, [newestUserMessageId, onSend, reducedMotion, restoring, viewport]);
}

/** The transcript's one `LateRenderersWatch`, with what it needs from the provider and the server. */
function TranscriptRenderersWatch({
  onVersion,
}: {
  onVersion: (version: number) => void;
}) {
  const { copilotkit } = useCopilotKit();
  const { data: capabilities } = useQuery(deploymentCapabilitiesQueryOptions());
  return (
    <LateRenderersWatch
      core={copilotkit}
      onVersion={onVersion}
      settled={capabilities?.generativeUi}
    />
  );
}

export function ChatTranscript({
  busy = false,
  commandNames = "",
  messages,
  onRemoveQueued,
  queued = EMPTY_QUEUE,
  restoring = false,
  stopped,
  working,
}: ChatTranscriptProps) {
  const isDrawn = useDrawnTool();
  /*
   * NOT MEMOISED, AND THAT IS DELIBERATE. `useMemo` keyed on `messages` looks obviously right and
   * silently broke the transcript: the agent hands back the SAME array and mutates it, so the
   * dependency never changed, the cached items were kept forever and a reply never appeared. A Bot
   * that answered looked like a Bot that had not.
   *
   * It was never the expensive part either. Rebuilding this list is a flatMap over messages; the
   * cost was markdown parsing and chart SVGs, and those are skipped by the memoised children below,
   * which is where the 25x came from. This runs per render and is not worth guarding.
   */
  /* Which row each tool step was drawn in, so a row keeps its key; see `groupToolSteps`. */
  const rowIdsRef = useRef(new Map<string, string>());
  const items = groupToolSteps(
    dropRepeatedAppCards(toVisibleChatItems(messages)),
    isDrawn,
    rowIdsRef.current,
  );

  /*
   * ONLY WHILE THERE IS NOTHING ELSE TO LOOK AT. Once a reply starts streaming, or a tool line
   * appears, the transcript is already saying the Bot is working — a second indicator under a
   * half-written answer would claim it had stopped and started again.
   *
   * So: the turn is in flight AND the last thing in the conversation is still the person's own
   * message. A tool call that is running shimmers on its own line and needs nothing from here.
   */
  const lastItem = items.at(-1);
  const waitingOnFirstToken =
    busy &&
    ((lastItem?.kind === "text" && lastItem.role === "user") ||
      /*
       * A screenshot pasted with no caption is still a person sending something, and they are
       * watching the same spot under it for the Bot's answer as they would under a typed question.
       * `toVisibleChatItems` only ever produces an `attachment` item from a user turn, so seeing one
       * last means the person went last — without this an attachment-only turn silently swallowed
       * the Thinking indicator.
       */
      lastItem?.kind === "attachments");

  const viewportRef = useRef<HTMLDivElement | null>(null);
  const newestUserMessageId =
    items.findLast(
      (item) =>
        (item.kind === "text" && isPersonSentMessage(item.role, item.text)) ||
        /*
         * Same reasoning as `waitingOnFirstToken` above: an attachment is always the person's own,
         * so a turn that is only a file still counts as them sending something. This id decides
         * nothing but whether the viewport scrolls smoothly for a beat; where it lands is
         * `anchoredTurns` below.
         */
        item.kind === "attachments",
    )?.id ?? null;
  /* Whether the view follows a streaming reply; see `follow-intent`. */
  const follow = useFollowIntent(viewportRef, restoring);
  const { dispatch: dispatchFollow } = follow;
  const followOnSend = useCallback(
    () => dispatchFollow({ type: "send" }),
    [dispatchFollow],
  );
  const followOnQueued = useCallback(
    () => dispatchFollow({ type: "queued" }),
    [dispatchFollow],
  );
  useSmoothSendScroll(
    viewportRef,
    newestUserMessageId,
    restoring,
    followOnSend,
  );

  /* Which tool calls are still the latest thing, for an app card: see `latestFrom`. */
  const latestIndex = latestFrom(items, { busy, queued: queued.length });
  /* The last thing the Bot said, so a call can tell whether its turn went on to say anything: see `ToolPlace`. */
  const lastBotWords = items.findLastIndex(
    (item) => item.kind === "text" && item.role === "assistant",
  );

  /* One rule for both kinds of row — see `anchorRowIds`, which is where it is written down. */
  const anchorRows = anchorRowIds(items);

  /*
   * Decided once, from the rows present when the scroller mounts, and forgotten while restoring so
   * a conversation opened again staggers again. Rows that arrive later are not in it: they have
   * their own entrance (`Arriving`).
   */
  const openingRef = useRef<Map<string, string> | null>(null);
  if (restoring) {
    openingRef.current = null;
  } else if (openingRef.current === null) {
    openingRef.current = openingStagger(items.map((item) => item.id));
  }
  const opening = openingRef.current;
  const openingProps = (id: string) => {
    const delay = opening?.get(id);
    return delay === undefined
      ? {}
      : {
          className: "history-arrive",
          style: { "--arrive-delay": delay } as React.CSSProperties,
        };
  };

  /* Which rows are drawn; see `useTranscriptPages`. */
  const pages = useTranscriptPages(
    items.map((item) => item.id),
    restoring,
  );
  const { drawEarlier, drawTo, from: pagesFrom } = pages;
  const drawEarlierNearTop = useCallback(
    (from: number) => {
      const element = viewportRef.current;
      if (
        element !== null &&
        shouldDrawEarlier({
          from,
          scrollTop: element.scrollTop,
          scrollHeight: element.scrollHeight,
        })
      ) {
        drawEarlier();
      }
    },
    [drawEarlier],
  );
  /*
   * After every page: a page that does not reach LOAD_MARGIN_PX above the fold (short rows, a tall
   * screen) draws the one before it. ON THE NEXT FRAME, NOT IN THIS COMMIT. The scroller puts the
   * reader back after a prepend from a MutationObserver callback, which runs after layout effects;
   * checked here, a reader at the very top (where the browser has nothing to anchor against) still
   * read `scrollTop` 0, drew another page, read 0 again, and drew the whole history in one burst,
   * which past about fifty pages is more nested updates than React allows. A frame later the
   * position is the restored one, and a page is only drawn if the reader really is still near the
   * top. Each extra page lands above the fold and is held in place, so the wait is never seen.
   */
  useLayoutEffect(() => {
    if (restoring) return;
    const frame = window.requestAnimationFrame(() =>
      drawEarlierNearTop(pagesFrom),
    );
    return () => window.cancelAnimationFrame(frame);
  }, [pagesFrom, restoring, drawEarlierNearTop]);

  /* Activities that may be waiting on their renderers; see `LateRenderersWatch`. */
  const [renderersVersion, setRenderersVersion] = useState(0);
  const hasActivities = items.some(
    (item) =>
      item.kind === "activity" &&
      item.message.activityType !== VOICE_CHAT_ACTIVITY,
  );

  /* The rail's marks, and which turn is being read; see `TranscriptRail`. */
  const turns = turnsOf(items);
  const turnIds = turns.map((turn) => turn.id).join("\n");
  const [activeTurn, setActiveTurn] = useState<string | null>(null);
  /*
   * Read at most once a frame, with one query: while a reply streams the scroller scrolls on every
   * resize, and a lookup and a layout read per turn per scroll event was real work on a long
   * conversation.
   */
  const activeFrameRef = useRef<number | null>(null);
  const readActiveTurnNow = useCallback(() => {
    activeFrameRef.current = null;
    const element = viewportRef.current;
    if (element === null || turnIds === "") return;
    const wanted = new Set(turnIds.split("\n"));
    const view = element.getBoundingClientRect();
    const rows: { id: string; top: number }[] = [];
    for (const row of element.querySelectorAll<HTMLElement>(
      "[data-message-id]",
    )) {
      const id = row.dataset.messageId;
      if (id !== undefined && wanted.has(id)) {
        rows.push({ id, top: row.getBoundingClientRect().top - view.top });
      }
    }
    setActiveTurn(
      currentTurn(
        rows,
        element.clientHeight / 3,
        element.scrollHeight - element.scrollTop - element.clientHeight <=
          AT_END_PX,
      ),
    );
  }, [turnIds]);
  const readActiveTurn = useCallback(() => {
    if (activeFrameRef.current !== null) return;
    activeFrameRef.current = window.requestAnimationFrame(readActiveTurnNow);
  }, [readActiveTurnNow]);
  useEffect(
    () => () => {
      if (activeFrameRef.current !== null) {
        window.cancelAnimationFrame(activeFrameRef.current);
      }
    },
    [],
  );
  useLayoutEffect(() => {
    if (!restoring) readActiveTurnNow();
  }, [restoring, readActiveTurnNow]);

  /*
   * A jump from the rail. A turn already drawn is gone to now; one in a page not drawn yet draws
   * every page down to it first, and is gone to a frame after that commit, once the scroller has put
   * the reader back where they were (the same wait as the fill check above). Instant, never smooth:
   * a smooth scroll up passes the top margin and draws pages above while it is moving, and the
   * scroller's hold on the reader's place would fight it.
   */
  const jumpRef = useRef<string | null>(null);
  const goToTurn = useCallback((id: string) => {
    const element = viewportRef.current;
    const row = element?.querySelector(`[data-message-id="${CSS.escape(id)}"]`);
    if (!element || !row) return;
    // Less the transcript's own top padding (`py-6`), so the turn sits where a first row would.
    element.scrollTop +=
      row.getBoundingClientRect().top -
      element.getBoundingClientRect().top -
      TURN_INSET_PX;
  }, []);
  /*
   * Following stops as the view moves, not before the pages are drawn: the scroller holds the
   * reader's place across a prepend by moving `scrollTop` down by what was added, and at the end of
   * the conversation that reads exactly like the person scrolling back to the end, which picks
   * following up again (`nextFollow`).
   */
  const goToTurnStill = useCallback(
    (id: string) => {
      goToTurn(id);
      /*
       * Not when the move left the view at the end: a short last turn is clamped there, nothing
       * scrolls, and nothing would ever pick following up again.
       */
      const element = viewportRef.current;
      if (
        element !== null &&
        element.scrollHeight - element.scrollTop - element.clientHeight >
          RESUME_PX
      ) {
        dispatchFollow({ type: "jump" });
      }
    },
    [dispatchFollow, goToTurn],
  );
  const jump = useCallback(
    (turn: Turn) => {
      setActiveTurn(turn.id);
      if (turn.index < pagesFrom) {
        jumpRef.current = turn.id;
        drawTo(turn.index);
      } else {
        goToTurnStill(turn.id);
      }
    },
    [drawTo, goToTurnStill, pagesFrom],
  );
  // biome-ignore lint/correctness/useExhaustiveDependencies: runs after the commit that drew the pages a jump asked for, which is a change of `pagesFrom`.
  useLayoutEffect(() => {
    const id = jumpRef.current;
    if (id === null) return;
    const frame = window.requestAnimationFrame(() => {
      jumpRef.current = null;
      goToTurnStill(id);
    });
    return () => window.cancelAnimationFrame(frame);
  }, [pagesFrom, goToTurnStill]);

  /*
   * NOTHING BUT THE PLACEHOLDER UNTIL HISTORY IS COMPLETE, AND THE SCROLLER MOUNTED FRESH AFTER IT.
   *
   * History arrives in pieces: the gateway snapshot, then the stored thread merged into it, then
   * the voice archive. Drawing each piece as it came showed a conversation that loaded and then
   * moved. And the scroller decides where to land ONCE, in a layout effect, the first time it sees
   * any child (`defaultScrollPosition`, applied by `ie()` in `@shadcn/react`'s message-scroller).
   * Mounted early, it spent that on the always-present `contents` block below, and the restored
   * rows then took the "rows appended" path, which pins a lone person's message to the top instead
   * of going to the end. Mounted here, with every row in the same commit, its one landing is the
   * bottom of the whole conversation, before the browser paints anything.
   */
  if (restoring) {
    return (
      <div className="flex size-full min-h-0 flex-col overflow-hidden">
        <div className="mx-auto flex w-full max-w-2xl flex-col gap-6 px-4 py-6">
          <RestoringTranscript />
          {/*
           * A message typed while history loads is parked, not lost, and must be seen to be: a
           * composer that cleared with nothing appearing reads as a message that vanished, and the
           * person types it again.
           */}
          {queued.map((message) => (
            <Queued
              attachments={message.attachments}
              key={message.id}
              onRemove={
                onRemoveQueued ? () => onRemoveQueued(message.id) : undefined
              }
              text={message.text}
            />
          ))}
        </div>
      </div>
    );
  }

  /*
   * One row, wherever it is drawn. `index` is the row's place in `items`, not in the slice being
   * drawn, so "the last row" and "latest" mean the same with or without older pages above.
   */
  const renderRow = (item: TranscriptItem, index: number) =>
    item.kind === "tools" || item.kind === "tool" ? (
      <MessageScrollerItem
        key={item.id}
        messageId={item.id}
        {...openingProps(item.id)}
      >
        <ToolRow
          active={busy && index === items.length - 1}
          id={item.id}
          latest={index >= latestIndex}
          spokeAfter={lastBotWords > index}
          steps={item.kind === "tools" ? item.steps : [item]}
        />
      </MessageScrollerItem>
    ) : item.kind === "activity" ? (
      <MessageScrollerItem
        key={item.id}
        messageId={item.id}
        {...openingProps(item.id)}
      >
        <TranscriptActivity message={item.message} />
      </MessageScrollerItem>
    ) : item.kind === "text" ? (
      <MessageScrollerItem
        key={item.id}
        messageId={item.id}
        scrollAnchor={anchorRows.has(item.id)}
        {...openingProps(item.id)}
      >
        <TranscriptMessage
          commandNames={commandNames}
          role={item.role}
          streaming={
            busy && item.role === "assistant" && index === items.length - 1
          }
          text={item.text}
        />
      </MessageScrollerItem>
    ) : item.kind === "attachments" ? (
      <MessageScrollerItem
        key={item.id}
        messageId={item.id}
        scrollAnchor={anchorRows.has(item.id)}
        {...openingProps(item.id)}
      >
        <TranscriptAttachments attachments={item.attachments} />
      </MessageScrollerItem>
    ) : (
      // Every member of the union is handled above. `assertNever` types `item` as
      // `never` here, so a future addition to `VisibleChatItem` fails to typecheck at
      // this call instead of silently falling into this branch and rendering nothing.
      assertNever(item)
    );

  return (
    <ArrivalsLive>
      {hasActivities ? (
        <TranscriptRenderersWatch onVersion={setRenderersVersion} />
      ) : null}
      <LateRenderersContext.Provider value={renderersVersion}>
        <MessageScrollerProvider
          autoScroll={follow.following}
          scrollPreviousItemPeek={48}
        >
          <MessageScroller className="@container">
            <MessageScrollerViewport
              {...follow.viewportHandlers}
              data-following={follow.following}
              onScroll={(event) => {
                follow.viewportHandlers.onScroll?.(event);
                drawEarlierNearTop(pagesFrom);
                readActiveTurn();
              }}
              ref={viewportRef}
            >
              <MessageScrollerContent
                aria-busy={busy}
                className="mx-auto w-full max-w-2xl px-4 py-6"
                spacerClassName="order-2"
              >
                {/*
                 * DRAWN LAST, WRITTEN FIRST, AND THE SCROLLER IS WHY. Three reviewers have now arrived
                 * at this block, worked the mechanism out from the library's bundle, and reached the
                 * same place; it had no comment for any of them to read. This is that comment.
                 *
                 * `MessageScrollerContent` is `flex flex-col`, so `order` is live: the spacer takes
                 * `order-2`, these children take `order-1`, and the transcript rows below keep the
                 * default `0`. Visual order is therefore items, then anything parked or in flight, then
                 * the spacer — while DOM order puts this block first.
                 *
                 * IT CANNOT SIMPLY BE MOVED DOWN. The scroller finds a newly appended row POSITIONALLY.
                 * On every content change it takes `Array.from(content.children)` minus the spacer,
                 * compares the length against the previous length, and when it grew scans FROM THE OLD
                 * LENGTH FORWARD for the next `data-scroll-anchor="true"` (`je(a, T)` in
                 * `@shadcn/react/dist/message-scroller`). A new row is only found when it lands at the
                 * very end of that list. Put this block after `items.map` and every appended row lands
                 * one slot short of the end, the scan finds this div instead, returns null, and the
                 * caller falls through to its follow-the-bottom branch — so a new turn stops aligning
                 * to the top of the viewport with a peek of the previous one, silently, with no test
                 * failing.
                 *
                 * OLDER PAGES GO BEFORE THIS BLOCK, AND THAT IS THE SAME MECHANISM USED ON PURPOSE.
                 * When the reader nears the top, the page before is drawn (`useTranscriptPages`). Drawn
                 * here, ahead of this block, it moves whatever was the first child, and a first child
                 * that moved is the scroller's own "rows were prepended" case: it puts the row the
                 * reader was looking at back where it was (`de()`), and never runs the scan above, which
                 * would read the shifted rows as new ones and jump to an old turn. Rows that arrive
                 * live still go after this block, at the end, where that scan looks for them.
                 *
                 * ONE CASE IT DOES NOT COVER. The scroller takes one path per batch of changes, so a page
                 * drawn above and a sent message landing in the SAME commit would be held in place and
                 * the new turn not aligned to the top. They come from different updates (a scroll near
                 * the top, a send at the bottom) and in practice never commit together; if they ever
                 * do, the turn is not aligned when it arrives, and a later change that keeps the row
                 * count can align to it then instead (the scroller's `Ge`), a beat late.
                 *
                 * `display: contents` IS LOAD-BEARING FOR THE SAME REASON, and not a layout trick. It
                 * promotes these children to flex items of the column so they can carry `order`, while
                 * the div itself stays a single, always-present entry in `content.children` — one
                 * stable slot the row count can be offset by. Wrapping `items.map` the same way would
                 * be the natural symmetry and is fatal: the rows would leave `content.children`
                 * entirely and the scroller would see a transcript of two elements, neither carrying a
                 * `data-message-id`, so nothing would register, be tracked as visible, or anchor.
                 *
                 * WHAT THIS COSTS, STATED RATHER THAN LEFT TO BE REDISCOVERED. `order` moves paint and
                 * not the DOM, so it moves neither focus order nor the reading order of the enclosing
                 * `role="log"`. A keyboard user tabbing in reaches the "Remove queued message: …"
                 * button of every parked message before any control in the conversation, though those
                 * lines are drawn at the very bottom (WCAG 2.4.3); a screen reader reading the log
                 * linearly hears the parked messages, and `Stopped`, ahead of the conversation they
                 * follow on screen (WCAG 1.3.2).
                 *
                 * THAT IS A KNOWN, UNPAID DEBT AND NOT AN OVERSIGHT. The fixes available from inside
                 * this file were each tried on paper and each breaks something worse: `aria-owns` needs
                 * a generated id per row and re-sequences only the accessibility tree, leaving tab
                 * order inverted; positive `tabIndex` hijacks the tab sequence of the whole page;
                 * hoisting the queue out of `MessageScrollerContent` into a sibling region — the
                 * cleanest END STATE, since a parked message is genuinely not a log entry — puts it
                 * outside a column that is `min-h-full`, so it lands below the fold on a short
                 * transcript, outside the `gap-6` rhythm, and outside the spacer's height arithmetic.
                 * Paying it properly means the scroller identifying new rows by identity rather than by
                 * position, which is the library's to change and is worth asking for.
                 */}
                <ArrivalsLiveContext.Provider value={AT_REST}>
                  {items
                    .slice(pages.from, pages.split)
                    .map((item, offset) =>
                      renderRow(item, pages.from + offset),
                    )}
                </ArrivalsLiveContext.Provider>
                <div className="contents [&>*]:order-1">
                  {stopped ? (
                    <Stopped reason={stopped} />
                  ) : waitingOnFirstToken ? (
                    <Thinking />
                  ) : null}
                  {working}
                  {queued.map((message) => (
                    <Queued
                      attachments={message.attachments}
                      key={message.id}
                      onRemove={
                        onRemoveQueued
                          ? () => onRemoveQueued(message.id)
                          : undefined
                      }
                      text={message.text}
                    />
                  ))}
                </div>
                {items
                  .slice(pages.split)
                  .map((item, offset) => renderRow(item, pages.split + offset))}
              </MessageScrollerContent>
            </MessageScrollerViewport>
            <MessageScrollerButton
              onClick={(event) => {
                // Ours, not the scroller's: it would scroll before it had been told to follow again.
                event.preventDefault();
                dispatchFollow({ type: "button" });
              }}
            />
            <ScrollNewestQueuedIntoView
              newest={queued.at(-1)?.id ?? null}
              onQueued={followOnQueued}
            />
            <FollowScroll request={follow.request} />
            <TranscriptRail active={activeTurn} onJump={jump} turns={turns} />
          </MessageScroller>
        </MessageScrollerProvider>
      </LateRenderersContext.Provider>
    </ArrivalsLive>
  );
}