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.
import {
type Attachment,
type AttachmentsConfig,
useAttachments,
} from "@copilotkit/react-core/v2";
import {
IconArrowUp,
IconPlayerStopFilled,
IconPlus,
} from "@tabler/icons-react";
import { PromptArea, type PromptAreaHandle } from "prompt-area";
import {
isSegmentsEmpty,
mergeAdjacentTextSegments,
type Segment,
text,
} from "prompt-area/helpers";
import {
type ChangeEvent,
type DragEvent,
type FormEvent,
useCallback,
useEffect,
useMemo,
useRef,
useState,
} from "react";
import { attachmentModality } from "@/components/channels/chat-messages";
import { IconWaveform } from "@/components/icons/waveform";
import {
attachmentUrl,
classifyAttachment,
MAX_ATTACHMENTS_PER_MESSAGE,
mayBeTruncatedForModel,
mediaTypeOf,
shouldClaimPaste,
} from "@/lib/channels/attachments";
import { newId } from "@/lib/new-id";
import { cn } from "@/lib/utils";
import { Button } from "../../ui/button";
import { AttachmentStrip } from "./attachment-strip";
import {
attachmentsConfigFor,
FILE_PICKER_ACCEPT,
stagedRowId,
} from "./attachments";
import { DictationButton, DictationSurface } from "./dictation-controls";
import { appendDictation } from "./dictation-draft";
import {
applyCommandChips,
type CommandOption,
type ComposerDraft,
canSendDraft,
enforceSingleAgent,
toDraft,
} from "./draft";
import { screenPickedFiles } from "./picked-files";
import { type RejectedFile, RejectedFiles } from "./rejected-files";
import { PLACEHOLDER_COMMANDS } from "./sources";
import { type AgentOption, buildTriggers } from "./triggers";
import { useDictation } from "./use-dictation";
/**
* The SDK's upload failure, derived rather than imported for the reason `attachments.ts` records
* against the same derivation: `@copilotkit/shared` declares `AttachmentUploadError` and is not a
* dependency of `app/`, so the only public spelling of this shape is the config it is passed to.
*/
type UploadFailure = Parameters<
NonNullable<AttachmentsConfig["onUploadFailed"]>
>[0];
/**
* WHY A STAGED ATTACHMENT LEFT THE COMPOSER WITHOUT BEING SENT.
*
* Two different things push files down this channel and they want different words. The composer
* used to build ONE sentence for both — "dropped when queued messages were merged into one: a
* message can carry at most 8" — which was true of the first and false of the second: nothing is
* merged when somebody removes a parked message, and no cap is hit. Telling them about a limit they
* never reached is worse than saying nothing, because it sends them looking for a limit to work
* around.
*
* `reduceQueue` reports the same `Attachment[]` either way, so the cause cannot be recovered from
* the files. It is read off the queue ACTION instead, by `conversation-view.tsx`, which is the one
* place that has both halves in hand.
*/
export type DroppedAttachmentCause =
/** Several parked messages became one turn, and the joined message overran the per-message cap. */
| "merged-over-cap"
/** A parked message was taken back out of the queue, and it was carrying these. */
| "queued-message-removed";
export type DroppedAttachments = {
cause: DroppedAttachmentCause;
attachments: readonly Attachment[];
};
/**
* WHAT A STAGED ATTACHMENT ACTUALLY IS, rather than what the browser called it when it was picked
* up. See the `images` memo for the whole account, and `attachmentModality` in `chat-messages.ts`
* for the rule itself — the send path and the parked tiles ask this same question the same way, and
* a second copy of the rule here would be a second thing to get wrong.
*
* A one-line function rather than an inline expression because BOTH halves of the strip call it and
* they are complements: `images` keeps what this calls an image and `files` keeps everything else,
* so the two must never be able to drift into disagreeing about one attachment.
*/
function stagedModality(attachment: Attachment) {
const { source } = attachment;
// Only a `url` source has been past the server, which sniffed the bytes. A `data` source's
// `mimeType` is `file.type`: the same claim, not a second opinion on it.
const corroborated =
source.type === "url" && source.mimeType ? source.mimeType : undefined;
return attachmentModality(attachment.type, corroborated);
}
const MAX_HEIGHT_PX = 220;
/**
* Tracks the compact `text-sm` line box so PromptArea stays vertically centered in one row.
*/
const COMPACT_MIN_HEIGHT_PX = 19;
const COMPACT_MAX_HEIGHT_PX = 96;
export type ComposerProps = {
className?: string;
/**
* Classes for the editor itself rather than the frame. `className` styles the box — border,
* background, width; the type inside it is PromptArea's, so changing it (a hero composer's
* `text-lg`) goes through here, where tailwind-merge lets it beat the built-in `text-sm`.
*/
editorClassName?: string;
compact?: boolean;
voiceCall?: { active: boolean; supported: boolean; onStart(): void };
/** Agents that `@` can address. Empty means the mention menu reports an empty channel. */
agents?: readonly AgentOption[];
commands?: readonly CommandOption[];
/**
* Receives the whole draft rather than a string, so a mention or a command reaches the caller as
* structured data instead of something it would have to re-parse out of the text.
*/
onSubmit?: (draft: ComposerDraft) => void | Promise<void>;
/**
* Park this message until the turn in flight is over, instead of refusing the keystroke.
*
* Its presence is what lets a person type at a Bot that is already working. Without it the
* composer goes on refusing mid-turn sends, which is still the right answer for a screen that has
* nowhere to put a parked message — the compose screen creates the channel on send and then
* navigates away, so anything parked there would be dropped on unmount, and a message that
* silently disappears is worse than a send button that visibly will not go.
*
* Called instead of `onSubmit`, not as well as it, and it does not return a promise: parking is
* a state change, and awaiting one would hold the composer's send lock for the length of somebody
* else's turn and block the next correction.
*/
onQueue?: (draft: ComposerDraft) => void;
/** Stop the Bot mid-answer; while pending, the send button becomes a stop button. */
onStop?: () => void;
/**
* The conversation cannot take another message at all, which is a property of the conversation
* rather than of the moment: a channel whose coworker was deleted. This is the only thing that
* stops a person typing.
*/
disabled?: boolean;
/**
* A turn is in flight. It gates sending, not writing: a channel is `pending` while it is still
* connecting and restoring its history, and the composer is on screen throughout.
*/
pending?: boolean;
/**
* Put the caret in the editor the first moment it can take one, and then leave it alone. For the
* screens where typing is the next thing a person does — choosing a coworker answers the "to"
* field, and the message is what remains.
*
* Once, not on every change: it used to re-claim the caret whenever the editor became interactive
* again, so a person who had clicked into something else — a search box, another channel's row —
* had the cursor yanked back the moment a turn finished. A send of their own still returns the
* caret, because that one they asked for.
*/
autoFocus?: boolean;
/**
* The channel a picked file is uploaded to, and the one switch for the whole attachment feature.
*
* WITH NO `channelId` THIS COMPOSER BEHAVES EXACTLY AS IT DID BEFORE ATTACHMENTS EXISTED, which
* is what keeps `/channel/new`, the home screen and the onboarding poster working untouched. No
* config reaches `useAttachments`, so it installs no paste listener at all; the form takes no
* drag handlers, no file input is rendered, and the `+` button goes on saying it has nothing to
* offer. That is the right answer rather than a degraded one for a screen with nowhere to put an
* upload: the compose screen creates its channel on send, so a file staged there would belong to
* a channel that does not exist yet.
*/
channelId?: string;
/**
* There is a run on the wire for Stop to reach.
*
* Not the same question as `pending`, and telling them apart is the whole reason this exists. A
* turn is in flight from the moment somebody presses send; the run it becomes does not exist
* until the caller has waited for whatever it has to wait for, which on a channel that is still
* joining is up to a second and a half. A Stop button drawn in that window aborts a controller
* nobody has made yet: the press is swallowed, the message goes anyway, and the one control the
* whole affordance leans on has quietly lied.
*
* Defaults to `pending`, which is the right answer for a caller with no gap between the two.
*/
stoppable?: boolean;
initialValue?: string;
/**
* Files a caller's queue left behind, and WHY, reported so they read as a refusal rather than
* vanishing.
*
* Two causes reach here and they are not interchangeable — see `DroppedAttachments` above.
* Joining several parked messages into one drained turn can overflow
* `MAX_ATTACHMENTS_PER_MESSAGE` in a way no per-draft check ever saw coming (see `reduceQueue`'s
* `droppedAttachments` in `queue.ts`), and removing a parked message takes whatever it was
* carrying with it. Either way those files are still staged server-side, so saying nothing is not
* neutral: it is a person finding out from a 409 on their next upload, with nothing connecting
* that refusal to the files that silently disappeared.
*
* A FRESH OBJECT EACH TIME SOMETHING IS DROPPED is what this relies on — see the effect below.
* The caller builds one per event, which it has to do anyway to say which cause it was.
*/
droppedAttachments?: DroppedAttachments;
/**
* HOW MANY ATTACHMENTS ARE SITTING IN THE CALLER'S QUEUE, BECAUSE THE SERVER IS STILL COUNTING
* THEM AND THIS COMPOSER CANNOT SEE THEM.
*
* Parking a message takes its chips off the strip — the queue owns them now — but nothing about
* the rows behind them changes: `attachedAt` is written only when the message is really sent, so
* they stay `attached_at IS NULL` in this composer's `uploadGroup` for the whole life of the
* in-flight turn, and the server's upload cap counts exactly that set. The strip is empty,
* `screenPickedFiles` is told `alreadyStaged: 0`, the pick is accepted, the upload round-trips,
* and the server answers 409 for a file the client had already said yes to. Park eight files
* during a turn — or three messages carrying three each — and the next one is refused.
*
* A per-draft cap that ignores the queue cannot agree with a per-group cap that does not, so the
* one number the client screens against has to include both halves.
*
* NOT THE CLOSED-TAB LOCKOUT, and worth saying so because the sentence is the same: parked files
* are drawn in the transcript, come back if the message is taken out of the queue, and their rows
* are stamped the moment the turn drains. The cost is a refusal that should have been instant and
* in our words arriving after a round trip in the server's.
*
* The count rather than the attachments, because that is all the screen needs and the queue's
* shape is the caller's business. `conversation-view.tsx` owns the queue and is the only thing
* that can sum this; a caller with no queue leaves it out and nothing changes.
*/
queuedAttachmentCount?: number;
};
/**
* A draft holding more files than one message may carry.
*
* A function rather than a comparison written twice, because the two readers must never disagree:
* the button that refuses the press, and `submitDraft`, which refuses the Enter key that never
* looks at the button. See `tooManyStaged` for how a strip gets over the cap at all.
*/
function overCap(draft: ComposerDraft): boolean {
return draft.attachments.length > MAX_ATTACHMENTS_PER_MESSAGE;
}
/** What the person is told when Send is held shut by the cap, and what to do about it. */
function tooManyStagedReason(count: number): string {
return (
`A message can take at most ${MAX_ATTACHMENTS_PER_MESSAGE} attachments. ` +
`Remove ${count - MAX_ATTACHMENTS_PER_MESSAGE} to send.`
);
}
/**
* One sentence per cause, and they say different things because different things happened.
*
* A merge names the cap, because that is the limit the person can work around — send fewer at once.
* A removal names the removal and nothing else: there is no limit to explain, and inventing one
* would send somebody hunting for a rule they never hit.
*/
const DROPPED_REASON: Record<DroppedAttachmentCause, string> = {
"merged-over-cap":
"dropped when your queued messages were merged. A message can take " +
`at most ${MAX_ATTACHMENTS_PER_MESSAGE} attachments.`,
"queued-message-removed": "removed with its queued message.",
};
/**
* WHAT A FILE DROPPED ON A COMPOSER THAT CANNOT TAKE IT IS TOLD, AND WHY IT IS TOLD ANYTHING.
*
* Catching the drop (see `refuseDragOver`/`refuseDrop` below) is what stops the browser from
* navigating the app away, and that alone would be a fix. It would also be a file that vanished:
* the person aimed a screenshot at the one box on the screen that takes screenshots, let go, and
* got nothing back — no chip, no error, no cursor change that outlasts the gesture. That is the
* exact failure `rejected` exists to end for every other door into this composer, and a drop is
* not a lesser door than the `+` button.
*
* TWO SENTENCES, BECAUSE THE TWO REFUSALS ARE NOT THE SAME REFUSAL. One is a "not yet" with a next
* step the person can take immediately; the other is a "not here, ever". Sharing one string
* between them would either promise a send that will never work or hide the send that will.
*
* NEITHER NAMES A CAUSE THIS COMPONENT CANNOT SEE. `disabled` is a plain boolean prop —
* `channel-chat.tsx` passes `!channel.active` and its own notice says the coworker was deleted,
* but that is the CALLER'S knowledge, and a composer that repeated it would be guessing on behalf
* of every future caller that disables it for some other reason. So this says only what is true of
* all of them: nothing can be sent from here, so nothing can be attached to it either.
*
* The filename is not repeated inside the reason — `RejectedFiles` renders `<name>: <reason>` —
* matching `DROPPED_REASON` above rather than `picked-files.ts`, whose strings quote the name a
* second time.
*/
const UNACCEPTED_DROP_REASON = {
"cannot-send": "not attached. This conversation can no longer take messages.",
"no-conversation":
"not attached. There is no conversation here yet. Send your message " +
"first, then attach files in the conversation it starts.",
} as const;
export function Composer({
className,
editorClassName,
compact = false,
voiceCall,
agents = [],
commands = PLACEHOLDER_COMMANDS,
onSubmit,
onQueue,
onStop,
disabled = false,
pending = false,
autoFocus = false,
channelId,
stoppable,
initialValue,
droppedAttachments,
// Nothing parked is the right answer for every caller without a queue, which is most of them.
queuedAttachmentCount = 0,
}: ComposerProps) {
const [value, setValue] = useState<Segment[]>(
initialValue ? [{ type: "text", text: initialValue }] : [],
);
const [isSubmitting, setIsSubmitting] = useState(false);
const submitInFlight = useRef(false);
const promptAreaRef = useRef<PromptAreaHandle>(null);
/**
* The composer's outer element, and the reason the hook's own `containerRef` is left on the
* floor.
*
* `useAttachments` scopes its `document` paste listener with exactly this test — is the event's
* target inside the element holding my ref — so an unheld ref is a listener that returns on
* every paste. That is the point. This composer deliberately does its own paste handling (see
* the listener below for why), and while ours claimed every paste carrying a file the SDK's
* never got a look in. It does now, on the pastes we decline, and it does not decline them: a
* spreadsheet cell was staged TWICE, once by us and once by it, and a Word paste that we
* correctly let through as text had its picture attached anyway. Holding the ref ourselves is
* what makes this composer the only thing in the app that decides what a paste means.
*/
const containerRef = useRef<HTMLDivElement>(null);
/** A send has completed and the caret is owed back, as soon as the editor will take it. */
const wantsFocus = useRef(false);
const sendDictatedDraft = useRef(false);
const dictation = useDictation(
(transcript, intent) => {
setValue((current) => appendDictation(current, transcript));
sendDictatedDraft.current = intent === "send";
wantsFocus.current = true;
},
disabled || voiceCall?.active === true,
);
/** `autoFocus` has been honoured once, and is not owed again for the life of this composer. */
const claimedAutoFocus = useRef(false);
/**
* EVERY REFUSAL THIS COMPOSER HAS EVER MADE, BECAUSE NOTHING ELSE REMEMBERS THEM.
*
* An `Attachment` has no error state and the hook has no retry: a failed upload removes the
* placeholder from the strip and calls `onUploadFailed` exactly once, so a refusal that is not
* kept here is a file that vanished from the composer with nothing said about it. Our own
* pre-check adds to the same list, so the two sources of "no" read as one list of reasons.
*/
const [rejected, setRejected] = useState<RejectedFile[]>([]);
const dismissRejections = useCallback(() => setRejected([]), []);
/**
* `newId()` rather than `crypto.randomUUID()`, for the reason `uploadGroup` below sets out at
* length: the function is ABSENT outside a secure context, so on a deployment served over plain
* `http://<address>` this throws rather than returning something worse.
*
* The throw would land in the worst possible place. This is the SDK's `onUploadFailed`, called
* from inside `processFiles` — so the report of a failed upload would itself fail, the file
* would leave the strip the way a failed upload always does, and the sentence explaining it
* would never arrive. Every upload refusal in the app comes through here.
*/
const recordRejection = useCallback((failure: UploadFailure) => {
setRejected((current) => [
...current,
{
id: newId(),
name: failure.file.name,
reason: failure.message,
},
]);
}, []);
/**
* THIS COMPOSER'S UPLOAD GROUP: one key, minted once, sent with every upload it makes.
*
* The per-message cap has two enforcers, and before this they counted different sets. The client
* counts what is on its own screen; the server counted every unsent row this person had in this
* channel. They agree only while nothing has been left behind — and a closed tab, a stopped run
* or a removed queued message leaves exactly that. The client would then accept a pick the server
* refused with a 409 naming files nobody could see, and eight orphans locked uploads in that
* channel until the sweeper's 24-hour window expired. Grouping the rows by the composer that
* staged them is what makes both sides count the same set.
*
* NOT A DRAFT ID. Nothing about the message is saved anywhere by this, and nothing survives a
* reload: a remount mints a new key and the rows the old one staged become somebody else's
* problem, which is to say the sweeper's.
*
* `newId()` rather than `crypto.randomUUID()`, which does not exist outside a secure context —
* on a deployment reached at plain `http://<address>` the call is not merely wrong, it throws,
* and the throw here would abort the whole screening pass rather than fail one upload. See
* `lib/new-id.ts`.
*
* Lazy `useState` rather than `useRef(newId())`, whose argument would be evaluated on every
* render to be thrown away — cheap, but it would also mean the id nobody keeps is minted
* hundreds of times per composer.
*/
const [uploadGroup] = useState(newId);
/**
* EVERY SERVER ROW THIS COMPOSER HAS CREATED AND NOT YET ACCOUNTED FOR.
*
* A row leaves this set exactly one of two ways: a message takes ownership of it
* (`releaseStagedRows`, on send and on queue), or the reconciler below finds it has no chip left
* and gives it back to the server. Anything still in here is a row whose fate is undecided.
*
* A ref rather than state: nothing on screen is drawn from it, and a set that re-rendered the
* composer on every upload would invalidate all four attachment memos for no visible reason.
*/
const uploadedRows = useRef<Set<string>>(new Set());
const recordUpload = useCallback((attachmentId: string) => {
uploadedRows.current.add(attachmentId);
}, []);
/**
* These rows belong to a message now, not to this composer, so it must stop offering to delete
* them. Called before the chips are taken off, on both paths where a draft carries its
* attachments away — the send that became a message, and the parked message the queue now owns.
*
* Getting this wrong in the other direction is the expensive one: leave a row in the set and the
* reconciler will notice the chip has gone and DELETE an attachment that has just been sent, or
* that a queued message is still waiting to send.
*/
const releaseStagedRows = useCallback((released: readonly Attachment[]) => {
for (const attachment of released) {
const rowId = stagedRowId(attachment);
if (rowId !== undefined) {
uploadedRows.current.delete(rowId);
}
}
}, []);
const attachmentsConfig = useMemo(
() =>
channelId
? attachmentsConfigFor(
channelId,
uploadGroup,
recordRejection,
recordUpload,
)
: undefined,
[channelId, uploadGroup, recordRejection, recordUpload],
);
/**
* The queue just left these behind, and they need the same rejection treatment a pick-time
* refusal gets — see `droppedAttachments` above for why staying quiet is not an option.
*
* Keyed on the object itself rather than on something derived from it, because the caller is
* expected to hand over a fresh one only when a new drop actually happened; an empty one on
* mount, or between drops, runs this once for nothing and then not again until the next real
* drop.
*/
useEffect(() => {
if (!droppedAttachments || droppedAttachments.attachments.length === 0) {
return;
}
const reason = DROPPED_REASON[droppedAttachments.cause];
setRejected((current) => [
...current,
...droppedAttachments.attachments.map((attachment) => ({
// `newId()` again, and this is the least survivable of the three sites: an effect body
// that throws propagates out of React's commit, so on a deployment served over plain
// `http://` a queue drop would answer by tearing down the tree that was about to explain
// it — a blank conversation instead of a list of the files it just lost.
id: newId(),
name: attachment.filename ?? "Attachment",
reason,
})),
]);
}, [droppedAttachments]);
/**
* Called unconditionally, with a config only when there is a channel to upload to. The hook
* reads no React context — it is state, refs and one `document` paste listener that it does not
* install while disabled — so an undefined config is a hook that does nothing, not a hook that
* throws.
*/
const {
attachments,
enabled: attachmentsEnabled,
fileInputRef,
processFiles,
handleDragOver,
handleDragLeave,
removeAttachment,
} = useAttachments({ config: attachmentsConfig });
/**
* THERE IS A CHANNEL TO UPLOAD TO **AND** THIS CONVERSATION CAN STILL TAKE A MESSAGE.
*
* `disabled` used to gate sending and nothing else, so every one of the three doors — the drop,
* the paste, and the `+` button with its input — went on accepting files for a channel whose
* coworker has been deleted. Each one becomes a row staged server-side that counts against that
* channel's cap and waits for the sweeper, attached to a message the screen has already said can
* never be sent, with nothing connecting the two.
*
* Every door reads this rather than `attachmentsEnabled`, and `stageFiles` re-asks it besides:
* `onImagePaste` is PromptArea's call and not ours, so the choke point has to answer for itself.
*/
const canAttach = attachmentsEnabled && !disabled;
/**
* THE ATTACHMENTS A SEND IN FLIGHT IS ALREADY CARRYING, HIDDEN FOR THE LENGTH OF THE RUN.
*
* `onSubmit` does not resolve until the whole run does, so between the press and the answer a
* screenshot was on screen twice — once in the transcript and once still in the strip — and
* `canSendDraft` unlocks on attachments alone, so the text box being empty did not disable
* anything: one more press queued the identical attachment ids into a second message. That
* duplicate is what this exists to close.
*
* THE OTHER WAY TO CLOSE IT, AND WHY NOT IT. Calling `consumeAttachments()` optimistically
* alongside `setValue([])` is three lines and loses the strip whenever a send fails. This file
* will not make that trade: a failed send already puts the words back, and files that vanished
* from the composer at the same moment would be exactly the thing it never does quietly — the
* whole `RejectedFiles` apparatus above exists because a file that disappears with nothing said
* about it is the worst outcome here, and these ones are still staged server-side, so nothing on
* screen would connect them to the 409 they later cause. So the send takes a snapshot of the ids
* instead, they are hidden while it runs, and the catch hands them straight back with the words.
*
* State rather than a ref, because `images`, `files` and `draft` are memos keyed on the
* attachments: a ref would not invalidate them, and the chips would sit there for the whole run,
* which is the bug itself.
*/
const [sending, setSending] = useState<readonly string[]>([]);
/**
* What is on the composer right now: everything staged, less whatever a send in flight already
* took. Every reader goes through this — the per-message cap, both halves of the strip, and the
* draft both buttons are enabled from — so there is no path left on which an attachment that has
* already been sent can be counted, drawn, or sent again.
*/
const staged = useMemo(
() => attachments.filter((attachment) => !sending.includes(attachment.id)),
[attachments, sending],
);
/**
* Take a chip off the strip. That is all this does, and the row it stood for is deliberately
* somebody else's problem — `reconcileStagedRows` below.
*
* IT USED TO DELETE THE ROW ITSELF, AND COULD ONLY EVER DO HALF THE JOB. It read the id off the
* attachment, so it worked for a `ready` chip and did nothing at all for one whose upload was
* still in flight — there is no id on that one yet. The comment said the in-flight case was the
* sweeper's and treated it as harmless. It is not: `uploadGroup` is minted once per composer and
* lives for the whole mount, so the row that lands a moment later is counted by the server
* against THIS composer, while the chip it belonged to is gone from the strip. The screen counts
* seven, the server counts eight, and the next pick comes back 409 naming a file nobody can see —
* verbatim the failure `uploadGroup` was introduced to remove, reached through a Remove button
* instead of through a closed tab.
*
* Splitting the answer across two functions is what left the gap, so there is one function now,
* and it is the one that can see both halves.
*/
const discardAttachment = useCallback(
// Unconditional: the person asked for the chip to be gone, and nothing here is allowed to make
// that wait on a round trip.
(id: string) => removeAttachment(id),
[removeAttachment],
);
/**
* GIVE BACK EVERY ROW THAT NO LONGER HAS A CHIP — THE ONE PLACE THAT DECIDES THIS.
*
* A row this composer uploaded is either on the strip, or owned by a message, or nobody's. The
* third is the leak, and it has two sources that used to be handled differently and one of them
* not at all: a `ready` chip removed by hand, and a chip removed while its upload was still in
* the air. Reconciling what was uploaded against what is drawn catches both without having to
* know which happened.
*
* WHY IT CANNOT BE DONE AT THE MOMENT OF THE REMOVAL, WHICH IS THE OBVIOUS PLACE. `onUpload` is
* handed a `File` and nothing else; the SDK mints the placeholder id itself and never says which
* placeholder a given call belongs to. So at the moment somebody removes an uploading chip there
* is no id to record, and when the upload lands there is no way to ask whether the chip it
* belonged to is the one that went. Absence is the only signal that survives that, and it is a
* complete one.
*
* WAITING FOR NOTHING TO BE UPLOADING IS THE WHOLE OF THE SAFETY. Between `onUpload` returning an
* id and the SDK writing it onto its placeholder there is a window in which the row is known and
* not yet drawn, and deleting there would destroy a live attachment. While that window is open
* the placeholder is still `uploading` in committed state, so this gate closes exactly over it.
* The gate is read off `attachments` rather than off the `staging` ref next to `stagedCount`
* deliberately: a ref is not a render, so a ref-gated pass could skip the last commit and never
* be woken again — a stale count self-corrects on the next commit, an un-deleted row does not.
*
* `attachments` and not `staged`: a send in flight only HIDES its attachments, and they are still
* the composer's until the send becomes a message.
*/
useEffect(() => {
if (uploadedRows.current.size === 0) {
return;
}
if (attachments.some((attachment) => attachment.status === "uploading")) {
return;
}
const drawn = new Set<string>();
for (const attachment of attachments) {
const rowId = stagedRowId(attachment);
if (rowId !== undefined) {
drawn.add(rowId);
}
}
for (const rowId of uploadedRows.current) {
if (drawn.has(rowId)) {
// Still on the strip. Left in the set on purpose: it may yet be removed, and this is the
// only thing watching for that.
continue;
}
uploadedRows.current.delete(rowId);
discardStagedAttachment(rowId);
}
}, [attachments]);
/**
* How many attachments the next screen must count, including any this tick has already accepted.
*
* `staged.length` is a number captured at render, and `stageFiles` is async, so two gestures in
* one tick — two drops in a row, or a drop landing on a paste — both read the same stale count
* and both accept a full cap's worth. Five files and five more went out as ten uploads against a
* cap of eight, and the server refused the surplus: a 409 the person had been given no chance to
* avoid, which is the exact failure this whole change exists to remove.
*
* A ref, because the correction has to be visible to the second caller in the SAME tick, and no
* state update is.
*/
const stagedCount = useRef(0);
/**
* How many accepted files are between `stageFiles` and their placeholders.
*
* This exists only to say when `stagedCount` may be resynced, and it is not optional: the hook
* adds placeholders ONE AT A TIME, so mid-flight `staged.length` is a number that is still
* climbing. Resyncing from it there would hand the reservation straight back — the first version
* of this did, and the second gesture screened against 1 instead of 5.
*/
const staging = useRef(0);
/*
* Every commit, and cheap: whenever nothing is in flight, the hook's own count is the truth, and
* that is how a removal, a send taking its attachments off, or a file the SDK refused after we
* accepted it all get back into the number. No dependency array on purpose — the condition that
* matters is a ref, which no dependency list can watch.
*/
useEffect(() => {
if (staging.current === 0) {
stagedCount.current = staged.length;
}
});
/**
* The one way a file gets from a person's hands into the upload queue.
*
* SCREENING HAPPENS HERE, BEFORE `processFiles`, AND THAT ORDER IS THE WHOLE POINT. The SDK
* enforces `accept` and `maxSize` itself and phrases its refusals for a machine — `File
* "logo.svg" is not accepted. Supported types: image/png,…` — where `screenPickedFiles` writes a
* sentence naming the file and the limit it hit. Anything this refuses never reaches the SDK, so
* a refused file produces exactly one reason, in our words.
*/
const stageFiles = useCallback(
async (picked: readonly File[]) => {
// The last gate, and the only one `onImagePaste` passes: PromptArea decides on its own when
// to hand an image over, so a door we do not own still arrives here.
if (disabled) {
return;
}
const screened = screenPickedFiles(picked, {
// What is on the composer, not what the hook is holding: an attachment riding on a send
// in flight belongs to that message's count, not to the one being built now.
//
// WHICH IS TRUE OF A SEND THAT LANDS AND NOT OF ONE THAT FAILS, and this number cannot
// tell them apart at the moment it is read — the send is still out. A failure hands the
// riding files back onto a strip that has filled up behind them, and the draft is then
// over the cap however carefully this counted. `tooManyStaged` is what catches that,
// because it asks about the strip as it actually is rather than predicting it.
//
// PLUS WHAT IS PARKED, which is on nobody's strip and is still counted by the server —
// see `queuedAttachmentCount`. Without the second half the client accepts a pick the
// server then refuses with a 409 the person was given no chance to avoid.
alreadyStaged: stagedCount.current + queuedAttachmentCount,
});
if (screened.rejected.length > 0) {
setRejected((current) => [...current, ...screened.rejected]);
}
if (screened.accepted.length === 0) {
return;
}
// Both bumps happen BEFORE the await, so a second gesture in this same tick screens against
// a number that already includes these.
stagedCount.current += screened.accepted.length;
staging.current += screened.accepted.length;
try {
await processFiles(screened.accepted.map(withMediaTypeOnly));
} finally {
staging.current -= screened.accepted.length;
}
},
[disabled, processFiles, queuedAttachmentCount],
);
/**
* The image half of a paste that our own listener let through.
*
* `PromptArea` has its own rule for a clipboard carrying BOTH text and an image: if the
* `text/html` is Microsoft Office markup it inserts the TEXT and ignores the image, because a
* copied Excel cell or Word block is text that happens to ship a picture of itself. Anything else
* it treats as an image, calls this, and RETURNS — having already called `preventDefault` and
* inserted nothing.
*
* WHICH SOURCES LAND WHERE, SAID PLAINLY, BECAUSE THE SECOND GROUP IS NOT COVERED. Word and Excel
* write Office markup, so their text is typed. Google Sheets and Numbers do not, so they take the
* second branch: this prop attaches their image and THEIR TEXT IS NOT TYPED. Having the prop is
* still strictly better than not having it — without it that same paste calls nothing at all, so
* there is no text AND no attachment, which is the failure our own listener was written to avoid
* — but it does not make the spreadsheet case right, and this does not claim it does. See
* `shouldClaimPaste` in `shared/attachments.ts` for the rule and for why it is being kept.
*
* Routing it into `stageFiles` means the file arrives by the same door as the picker and the
* drop, so it is screened, capped and refused in the same words.
*
* EVERY BRANCH BELOW HAS TO PASS IT, WHICH IS THE WHOLE OF THIS PROP'S CORRECTNESS. It went on
* the compact one alone for a while, and the full-size branch — the shape the home screen draws
* — swallowed exactly this paste in silence. `composer-paste.test.tsx` renders that branch for
* no other reason.
*/
const stagePastedImage = useCallback(
(file: File) => {
void stageFiles([file]);
},
[stageFiles],
);
/**
* THE THIRD DOOR, SHUT — AND SHUT AHEAD OF THE SDK'S OWN.
*
* `useAttachments` installs a bubble-phase `document` paste listener that pre-filters the
* clipboard with the same exact `file.type === filter` comparison `withMediaTypeOnly` exists to
* survive, and then calls `processFiles` directly. A pasted `text/plain;charset=utf-8` file —
* which is what a browser reports for some clipboard entries — fails that comparison, and the
* listener then returns having uploaded nothing, said nothing and called no `onUploadFailed`.
* Silent. Paste also skipped the per-message cap and `MAX_FILE_BYTES`, which our screen enforces
* and the SDK's does not.
*
* So this one listens in the CAPTURE phase, which runs before the hook's, and `stopPropagation`
* on a paste we claim means the hook's listener never runs at all. What we claim goes through
* `stageFiles`, the same path the `+` button and the drop already take, so screening, the cap and
* the wording of a refusal are identical whichever way the file arrived.
*
* `shouldClaimPaste` decides whether the paste is ours: text wins whenever the clipboard carries
* any, and a file is ours only when there is none. Copying a cell from a spreadsheet puts BOTH an
* image and text on the clipboard, and claiming that paste attached a screenshot of the cell and
* typed nothing.
*
* DECLINING IS NOT THE SAME AS THE TEXT BEING TYPED. What a declined paste does next is
* PromptArea's rule, and it types the text only when the `text/html` is Microsoft Office markup.
* So Word and Excel are handled; Google Sheets and Numbers are not — their image is attached
* through `stagePastedImage` below and their text is lost. That is a known defect being kept for
* now, and it is written out in full on `shouldClaimPaste` in `shared/attachments.ts`.
*/
useEffect(() => {
if (!canAttach) {
return;
}
const handlePaste = (event: ClipboardEvent) => {
// The hook's own containment gate, kept exactly: several composers can be mounted at once,
// and a paste into a search box is nobody's attachment.
const target = event.target as Node | null;
if (!target || !containerRef.current?.contains(target)) {
return;
}
const clipboard = event.clipboardData;
if (!clipboard) {
return;
}
const files = Array.from(clipboard.items)
.filter((item) => item.kind === "file")
.map((item) => item.getAsFile())
.filter((file): file is File => file !== null);
const claimed = shouldClaimPaste({
kinds: files.map((file) => classifyAttachment(file.type)),
plainText: clipboard.getData("text/plain"),
});
if (!claimed) {
return;
}
event.preventDefault();
event.stopPropagation();
void stageFiles(files);
};
document.addEventListener("paste", handlePaste, true);
return () => document.removeEventListener("paste", handlePaste, true);
}, [canAttach, stageFiles]);
const handleDrop = useCallback(
(event: DragEvent<HTMLDivElement>) => {
event.preventDefault();
/*
* The hook's `dragOver` flag, put back down.
*
* NOTHING DRAWS IT TODAY, AND THIS IS STILL NOT DEAD CODE. `useAttachments` keeps a
* `dragOver` boolean that its own chat components render a highlight from; this composer
* does not destructure it and no border or overlay anywhere in `app/src` changes while a
* file hovers. The comment that used to sit here said a missed drag-leave "would leave the
* composer looking like a file is still hovering over it", which was describing a highlight
* that does not exist — a reader chasing that sentence finds nothing.
*
* The call stays because the flag is the hook's, not ours: leaving it stuck at `true` after
* a drop would hand a trap to whoever wires the highlight up, and they would have no reason
* to suspect the drop path. It costs one function call per drop.
*/
handleDragLeave(event);
void stageFiles(Array.from(event.dataTransfer.files));
},
[handleDragLeave, stageFiles],
);
/**
* THE DROP THIS COMPOSER CANNOT ACCEPT, CAUGHT ANYWAY — BECAUSE "NOT A DROP TARGET" IS NOT THE
* SAME THING AS "IGNORES DROPS", AND THE DIFFERENCE IS THE WHOLE APP.
*
* An element becomes a drop target only when something calls `preventDefault` on its `dragover`.
* With no handler at all — which is what `dropZone` used to spread whenever `canAttach` was
* false — the composer is not a target, `drop` never fires on it, and the browser performs ITS
* default for a file dropped on a document: it NAVIGATES THE TOP-LEVEL DOCUMENT TO THAT FILE.
*
* The comment this replaces called those "drag handlers it would only ignore". Ignoring is the
* one thing that does not happen. The single-page app unloads and everything held in memory goes
* with it: the sentence being typed on `/channel/new`, and on a `disabled` channel the entire
* parked queue — whose own teardown effect in `conversation-view.tsx` never gets to run, because
* the document is being REPLACED rather than unmounted, so the rows behind those parked messages
* stay orphaned until the 24-hour sweep. The person sees their raw PNG on a blank page and
* presses Back.
*
* ALWAYS INSTALLED; ONLY THE ACCEPTANCE IS CONDITIONAL. The states that reach here are the three
* the `channelId` docblock names — `/channel/new`, the home screen, the onboarding poster — plus
* every channel whose composer is `disabled`.
*
* THE APP-WIDE GUARD NOW EXISTS, AND THIS IS STILL NOT REDUNDANT. `useUnclaimedDropGuard` in
* `routes/__root.tsx` refuses any drop nobody claimed, which covers the transcript, the sidebar,
* the page margin and the onboarding poster's `pointer-events-none` composer — every surface a
* leaf could never reach. It deliberately stands down the moment an event is already
* `defaultPrevented`, because that is the browser's own signal that something in the tree owns
* the drop. So the two do not fight, and they do different jobs: the root one can only refuse
* silently, since it has no idea what the person was aiming at. This one KNOWS, and names the
* file and the reason in `RejectedFiles`. Deleting it would turn a sentence into silence on the
* one surface people actually aim files at.
*/
const refuseDragOver = useCallback((event: DragEvent<HTMLDivElement>) => {
event.preventDefault();
/*
* `dropEffect = "none"` SO THE CURSOR TELLS THE TRUTH BEFORE THE PERSON LETS GO.
*
* `preventDefault` alone leaves the effect at its default, which draws the same copy-badge
* cursor the working composer draws — so the guard would advertise an acceptance it is about
* to refuse, and the refusal would then read as a bug rather than as an answer. "none" draws
* the no-entry cursor and changes nothing else: the element is still a drop target, `drop`
* still fires on it, and the browser still never gets the file.
*/
if (event.dataTransfer) {
event.dataTransfer.dropEffect = "none";
}
}, []);
const refuseDrop = useCallback(
(event: DragEvent<HTMLDivElement>) => {
// FIRST, AND UNCONDITIONALLY. Everything below this line is the explanation; this line is
// the fix, and no branch of the explanation may be able to skip it.
event.preventDefault();
// `?.` and `??` because a drag event can reach a handler with no `dataTransfer` — happy-dom
// builds one only when a test supplies it — and a throw here would be a page saved and a
// refusal never written down.
const files = Array.from(event.dataTransfer?.files ?? []);
if (files.length === 0) {
/*
* A dragged link, or a selection of text, or a drag from another app carrying no file.
* The default is still refused above — a dropped URL navigates just as a dropped file does
* — but there is nothing to name and nothing was attempted, so a refusal written here
* would be one invented for a gesture nobody made.
*/
return;
}
/*
* CHOSEN BY WHAT IS DEAD, NOT BY WHAT IS MISSING.
*
* This asked `attachmentsEnabled` — is there a channel — and got one of the four states
* wrong. A composer that is BOTH `disabled` and channel-less was told "there is no
* conversation here yet. Send this message first, then attach to the one it opens", while
* the Send button beside the sentence is shut and pressing it does nothing. Advice that
* cannot be followed is worse than none: it sends somebody to a control that is already
* refusing them, and they conclude the app is broken rather than that this conversation is
* over.
*
* `disabled` is the question actually being answered — CAN THIS PERSON DO THE THING THE
* SENTENCE WILL TELL THEM TO DO. It is also the only one of the two that can be true while
* the other is: `canAttach` is `attachmentsEnabled && !disabled`, so reaching here means at
* least one is against us, and `disabled` is the one that makes the next step impossible.
* The three states that were already right are unchanged: a live channel-less composer still
* gets the "not yet" sentence, and a disabled channel still gets "can no longer take
* messages".
*/
const reason =
UNACCEPTED_DROP_REASON[disabled ? "cannot-send" : "no-conversation"];
/*
* `setRejected` directly rather than through `recordRejection`, which takes the SDK's
* `UploadFailure` shape — a `file` plus a `message` — and would mean fabricating an upload
* failure for a file no upload was ever attempted for. One line per file, matching every
* other refusal on this composer: dropping two files on a dead channel is two files that did
* not arrive, and folding them into one line loses which.
*/
setRejected((current) => [
...current,
...files.map((file) => ({ id: newId(), name: file.name, reason })),
]);
},
[disabled],
);
const handlePickedFiles = useCallback(
(event: ChangeEvent<HTMLInputElement>) => {
const picked = Array.from(event.target.files ?? []);
// Emptied so that picking the same file again still fires a change event: a file refused by
// the screen above is a file somebody may well pick a second time by mistake, and an input
// still holding it would silently do nothing.
event.target.value = "";
void stageFiles(picked);
},
[stageFiles],
);
/**
* PromptArea already draws an attachment strip, so these map onto its props rather than adding a
* second one. An upload in flight has no preview to show — its placeholder source is an empty
* string until `onUpload` answers — which is what `loading` covers.
*
* SPLIT ON WHAT THE FILE IS, NOT ON WHAT THE BROWSER CALLED IT — the same correction the send
* path (`toAttachmentPart` in `channel-chat.tsx`) and the parked tiles (`parkedTiles` in
* `chat-transcript.tsx`) already made, through the same shared `attachmentModality`.
*
* `attachment.type` is the SDK's modality, and the SDK derives it from `file.type`: the
* browser's guess from a file extension, made before anything read a byte. A screenshot dragged
* out of an app that names it `application/octet-stream` was drawn here as a grey file card and
* then turned into a thumbnail the instant it was parked or sent — the same file, three
* surfaces, two answers, and the tile visibly changing shape at the moment of sending. The other
* direction is worse: a text file the browser calls `image/png` was handed to an `<img>` that
* can never render it, which is a broken-image icon where a filename should be.
*
* ONLY A `url` SOURCE'S `mimeType` IS EVIDENCE, which is why the narrowing below is not
* defensive noise. A `data` source's `mimeType` is `file.type` — the very claim being refused,
* wearing the name of an answer — and only a `url` source has been past the server, which sniffs
* the bytes. `attachmentModality` falls back to the declared type when there is nothing
* corroborated, so an attachment still uploading is drawn exactly as it used to be and settles
* onto the truth when the server answers. That settle is the one visible cost: a mislabelled
* screenshot spends its upload as a file card. The alternative is holding every tile back until
* the answer, which would make every ordinary attachment feel slower to spare a rare one a
* flicker.
*/
const images = useMemo(
() =>
staged
.filter((attachment) => stagedModality(attachment) === "image")
.map((attachment) => ({
id: attachment.id,
url: attachment.source.value,
alt: attachment.filename,
loading: attachment.status === "uploading",
})),
[staged],
);
/**
* NO `type` HERE, BECAUSE NOTHING HAS EVER READ ONE. This carried
* `type: attachment.source.mimeType`, `StagedFile` (`attachment-strip.tsx`) declares no such
* field, and `AttachmentStrip` draws the same `IconFile` for every file whatever its type. It
* survived because the array is a variable rather than a fresh object literal at the JSX site, so
* TypeScript's excess-property check — the thing that would have caught it — never ran.
*
* Deleted rather than adopted. Adding `type` to `StagedFile` and drawing a per-format label off
* it is a real improvement and a deliberately separate one: it is a design change to the tile,
* not the removal of a line that pretends to feed something.
*
* The complement of `images` above, and it has to be read as one: whatever is not an image is a
* card, so both halves must ask the same question of the same field or an attachment lands in
* both strips or in neither.
*/
const files = useMemo(
() =>
staged
.filter((attachment) => stagedModality(attachment) !== "image")
.map((attachment) => ({
id: attachment.id,
name: attachment.filename ?? "Attachment",
size: attachment.size,
loading: attachment.status === "uploading",
/*
* Warned, never refused. The server accepts the whole file and the
* model reads its first MAX_EXTRACTED_CHARACTERS; mayBeTruncatedForModel
* is exact in the safe direction (N bytes decode to at most N chars),
* so a file at or under the ceiling cannot be cut. Only text reaches
* the extraction path: images are excluded by the filter above, and an
* unnamed pick whose type is still unknown gets no warning until the
* server has sniffed it (then the strip re-renders off the url source).
*
* THE FILTER IS THE ONLY IMAGE TEST, DELIBERATELY. `attachment.type` is
* the browser's claim, fixed at pick time and never revised; the filter
* runs `stagedModality`, which prefers what the server sniffed. Testing
* both would not narrow this to text, it would only subtract: a file the
* browser called a PNG and the server read as text lands in this strip,
* goes down the extraction path, and is exactly the one that gets cut.
*/
mayTruncate:
attachment.status !== "uploading" &&
attachment.size !== undefined &&
mayBeTruncatedForModel(attachment.size),
})),
[staged],
);
const isBusy = pending || isSubmitting;
const triggers = useMemo(
() => buildTriggers({ agents, commands }),
[agents, commands],
);
const draft = useMemo(() => toDraft(value, staged), [staged, value]);
/**
* MORE FILES ON THIS STRIP THAN ONE MESSAGE MAY CARRY — a state the screening is supposed to make
* unreachable, and does not.
*
* HOW THE STRIP GETS HERE. `sending` hides an outgoing message's attachments from `staged`, and
* `stagedCount` resyncs off `staged`, so while a send is out the client-side count reads zero and
* a second full batch is accepted behind the first. That is deliberate and right for a send that
* lands: those files belong to the message that went, not to the one being built now. It is only
* wrong when the send FAILS, because the `finally` then hands the first batch back — onto a strip
* that has since filled up — and one draft is holding two messages' worth of files.
*
* WHY THE CAP AND NOT `canSendDraft`. That function asks about upload status and emptiness, which
* are facts about each attachment; this is a fact about the draft as a whole, and it belongs
* beside the other thing the composer knows and the draft model does not — see `stageFiles`,
* which screens against the same number.
*
* NOTHING IS DROPPED TO RESOLVE IT, and that is the whole reason this is a gate rather than a
* slice. Trimming the strip back to the cap would delete files somebody picked, on a path they
* did not ask for, with the rows behind them released behind their back — which is verbatim the
* failure every other release in this file exists to avoid. So every chip stays, every one is
* removable by hand, and Send says no with a sentence naming the limit until it is.
*/
const tooManyStaged = overCap(draft);
const handleChange = useCallback(
(next: Segment[]) => {
const { segments, actions } = applyCommandChips(
enforceSingleAgent(next),
commands,
);
setValue(segments);
// Run after the commit so an action that navigates or opens a panel is not fighting the
// editor's own state update for the same tick.
for (const action of actions) {
action();
}
},
[commands],
);
/**
* The single submit path for Enter, the send button, and the form.
*
* `submitInFlight` is a ref rather than `isSubmitting` because a second Enter can land before
* React has re-rendered with the new state, which would send the message twice.
*/
const submitDraft = useCallback(
async (segments: Segment[]) => {
// `canSendDraft` rather than `isEmpty`: a screenshot with no words is a message, and an
// upload still in flight is not one yet, whatever is typed alongside it.
//
// `overCap` is asked here as well as at the button, and not only there: Enter reaches this
// function through prompt-area's own `onSubmit`, which has never looked at `canSend`. A gate
// drawn on the button alone would refuse the press and accept the keystroke.
const submitted = toDraft(segments, staged);
if (
!canSendDraft(submitted) ||
overCap(submitted) ||
disabled ||
dictation.session.getSnapshot().phase !== "idle"
) {
return;
}
/*
* A TURN IS IN FLIGHT, AND THIS IS THE FORK THE WHOLE AFFORDANCE HANGS ON.
*
* With somewhere to park it the message goes there and the box empties, so the person sees
* their words land. Without, we are back to refusing, which is what every caller that does
* not queue still gets.
*
* It returns before `submitInFlight` and `isSubmitting` are touched on purpose. Those guard
* one send from starting twice; a send here is held open for the length of the whole run, so
* borrowing them for a parked message would let the first turn lock out every correction
* typed while it worked — the exact thing this exists to allow.
*/
if (isBusy) {
if (!onQueue) {
return;
}
setValue([]);
dismissRejections();
// Taken off the composer as the message is parked, so the strip empties with the words
// rather than leaving the files looking like they are still to be sent. Only these —
// `consumeAttachments()` takes every `ready` attachment, including ones a send already
// in flight is riding, and that send's own `finally` still needs them to hand back if it
// fails. `submitted.attachments` is `staged`, which already excludes those.
//
// Released BEFORE the chips go, and this order is not cosmetic: the parked message owns
// these rows now and will send them later, so the reconciler must be told before it sees
// the chips disappear — otherwise it reads a queued message's attachments as abandoned and
// deletes the rows out from under it.
releaseStagedRows(submitted.attachments);
for (const attachment of submitted.attachments) {
removeAttachment(attachment.id);
}
onQueue(submitted);
return;
}
if (submitInFlight.current || !onSubmit) {
return;
}
submitInFlight.current = true;
setIsSubmitting(true);
// Clear optimistically; restore if the send fails before becoming a message.
setValue([]);
/*
* The refusals go with them, and do NOT come back if the send fails. They are about files
* that never made it onto this message, so the words being restored has nothing to do with
* them; putting them back would be an old complaint reappearing next to a new attempt.
*/
dismissRejections();
// The strip is cleared optimistically too, but by hiding rather than by consuming: these
// ids leave the composer now, so nothing on screen can send them a second time, and the
// `finally` below is what decides whether they come back.
const riding = submitted.attachments.map((attachment) => attachment.id);
setSending(riding);
try {
await onSubmit(submitted);
// Only once the send has become a message, and only the ones that rode on it —
// `consumeAttachments()` would also swallow anything attached while the run was in
// flight, which belongs to the next message and has never been sent.
//
// Released first, for the reason the queue branch above gives: the message carries these
// rows now, and a reconciler that saw the chips go without being told would delete
// attachments that have just been sent.
releaseStagedRows(submitted.attachments);
for (const id of riding) {
removeAttachment(id);
}
} catch {
/*
* THE WORDS COME BACK IN FRONT OF WHATEVER ARRIVED WHILE THE SEND WAS OUT, NOT OVER IT.
*
* The editor is never disabled mid-turn, and that is deliberate — it is how a correction
* gets typed at a Bot that is already working. So by the time a send fails the box may well
* hold something newer than the message that failed. `setValue(segments)` wrote straight
* over it: the failed message came back and the sentence typed after it was gone, with
* nothing said about either. Both are somebody's words, so neither may be dropped; the
* restored ones go ahead of the newer ones and the person edits the join.
*/
setValue((current) => {
// An attachment-only message has no words to restore, and putting an empty segment list
// back would clear a box somebody has since typed into.
if (isSegmentsEmpty(segments)) {
return current;
}
if (isSegmentsEmpty(current)) {
return segments;
}
return mergeAdjacentTextSegments([
...segments,
text(" "),
...current,
]);
});
/*
* NOT RETHROWN, AND THE RETHROW THIS REPLACES REACHED NOTHING.
*
* `submitDraft` has exactly two callers: `handleFormSubmit`, which does
* `void submitDraft(value)`, and PromptArea's `onSubmit`, which calls it and ignores the
* promise. Neither awaits and neither catches, so every failed send became an unhandled
* rejection — and in this repository's test runner, a failure attributed to whichever test
* happened to be running when it surfaced, which is why two composer suites carry notes
* saying a failed send could not be driven from them at all.
*
* Nothing is hidden by stopping. The caller is the half that knows what went wrong and it
* already reports it: `conversation-view.tsx` shows a failed turn through its own notice,
* and its drain path catches this same rejection under a comment saying the composer's
* throw exists only so the composer can put the words back. Putting the words back is what
* this catch does, so there is nothing left for the throw to carry.
*/
} finally {
// Handed back to the composer either way: on success they are already gone from the
// hook's own state, and on failure this is what puts the chips back beside the restored
// words rather than leaving somebody to re-pick files that are still staged server-side.
setSending([]);
submitInFlight.current = false;
setIsSubmitting(false);
// Asked for here, performed in the effect below, which runs after the commit that clears
// `isSubmitting` and so after the render the caret would otherwise be placed against.
wantsFocus.current = true;
}
},
[
disabled,
dictation.session,
dismissRejections,
isBusy,
onQueue,
onSubmit,
releaseStagedRows,
removeAttachment,
staged,
],
);
// Submit after the transcript has been committed to the latest draft. The ref is consumed
// before invoking the normal send path, so rerenders and StrictMode cannot submit twice.
useEffect(() => {
if (!sendDictatedDraft.current) return;
sendDictatedDraft.current = false;
void submitDraft(value);
}, [value, submitDraft]);
const wasDictating = useRef(false);
/**
* Put the caret back the moment the composer can accept it again.
*
* Keyed off the editor becoming interactive rather than off the send resolving, so it survives
* whatever the parent does with `pending` in between — and it runs after the commit, which is the
* only point at which the element is enabled and focusable.
*
* Two different debts, and only one of them recurs. A finished send owes the caret back every
* time. `autoFocus` owes it exactly once, at the start: it used to be re-owed on every
* disabled/busy transition, so every completed turn stole the caret back from wherever the person
* had moved it, and a composer that had never been sent from would grab focus mid-conversation.
*/
useEffect(() => {
if (wasDictating.current && !dictation.busy) wantsFocus.current = true;
wasDictating.current = dictation.busy;
if (disabled || isBusy || dictation.busy) {
return;
}
const owed = wantsFocus.current || (autoFocus && !claimedAutoFocus.current);
if (!owed) {
return;
}
wantsFocus.current = false;
claimedAutoFocus.current = true;
promptAreaRef.current?.focus();
}, [autoFocus, disabled, isBusy, dictation.busy]);
const handleFormSubmit = (event: FormEvent<HTMLFormElement>) => {
event.preventDefault();
void submitDraft(value);
};
/**
* There is a turn in flight and somewhere to park what is being typed.
*
* Not the same question as "is anything typed" — an empty composer mid-turn can queue nothing,
* and the button it wants is Stop.
*/
const canQueue = Boolean(onQueue) && isBusy && !disabled;
/**
* There is a message here to send or to park.
*
* `canSendDraft` rather than a local "is anything typed": it is the half of this answer that
* knows about attachments — an image on its own is a message, and one still uploading is not
* one yet. Both buttons read it, so Send and Queue can never disagree about whether there is
* anything to do.
*/
const sendable = canSendDraft(draft) && !tooManyStaged;
/** Something to send, mid-turn, with a queue to put it in. */
const parking = canQueue && sendable;
const canSend =
!disabled && !dictation.busy && sendable && (!isBusy || canQueue);
const canSendRecording =
!disabled &&
!tooManyStaged &&
!draft.attachments.some(
(attachment) => attachment.status === "uploading",
) &&
(!isBusy || canQueue) &&
Boolean(onSubmit || onQueue);
/**
* Stop is available only once there is a run for it to reach, and it gives way to Send the moment
* there is something typed to park.
*
* `stoppable` rather than `pending`, because a turn is in flight before its run is, and a button
* that cannot do the thing it names is worse than no button at all.
*
* One button, so one of the two has to yield. Send wins because the correction is the thing that
* cannot wait: park it and the box empties, which brings Stop straight back — so stopping is
* never more than one press away, and the press before it is the one that saves the sentence.
* Showing both would be honest and would also put two round buttons in a row on a compact
* composer that has room for one.
*/
const canStop = Boolean(onStop) && (stoppable ?? pending) && !parking;
/**
* The same arrow either way, because it is the same gesture, but a screen reader is told which of
* the two it is about to do. "Send" on a button that will not send for another minute is a small
* lie told to exactly the people who cannot see the queue it lands in.
*/
const sendLabel = parking ? "Queue message" : "Send message";
const callAction =
draft.isEmpty && draft.attachments.length === 0 ? voiceCall : undefined;
const actionClassName = cn(
"rounded-full p-0",
compact ? "size-8 self-end" : "size-7",
);
const primaryAction = canStop ? (
<Button
aria-label="Stop the Bot"
className={actionClassName}
data-slot="composer-stop"
data-testid="composer-stop"
onClick={onStop}
size="icon"
type="button"
>
<IconPlayerStopFilled className="size-3" />
</Button>
) : callAction ? (
<Button
aria-label={callAction.active ? "Show voice call" : "Start voice call"}
title={
callAction.supported
? callAction.active
? "Show voice call"
: "Call this Bot"
: "Voice calls need a microphone and a secure (HTTPS) connection"
}
className={actionClassName}
disabled={disabled || dictation.busy || !callAction.supported}
onClick={callAction.onStart}
size="icon"
type="button"
>
<IconWaveform className="size-4" />
</Button>
) : (
<Button
aria-label={sendLabel}
className={actionClassName}
data-slot="composer-send"
disabled={!canSend}
size="icon"
type="submit"
>
<IconArrowUp className="size-3.5" />
</Button>
);
/**
* EVERY COMPOSER IS A DROP TARGET. What changes with `canAttach` is what happens to the file,
* never whether the browser gets to keep it — see `refuseDragOver` above for what an
* uninstalled `dragover` handler actually does to this app.
*
* SPREAD ON THE CONTAINER, NOT ON THE FORM, AND THE DIFFERENCE IS A REAL GAP THAT WAS OPEN. The
* refusal strip renders ABOVE the form — `RejectedFiles` is a sibling, moved there so the reasons
* sit next to the drop that caused them rather than below the box — so with the handlers on the
* form, a file let go over a refusal was let go over nothing. The most likely second drop in the
* whole app lands exactly there: somebody drops two files, reads why the first was refused, and
* aims the retry at the sentence they are reading.
*
* The container is also the element `containerRef` is on, which is the boundary our own paste
* listener already uses to decide whether a paste is ours. One element now answers both
* questions, so "inside this composer" means the same thing for a file that arrives by clipboard
* and for one that arrives by hand.
*
* No `onDragLeave` on the refusing branch, and that is not an omission: `handleDragLeave` only
* puts the hook's `dragOver` flag back down, and the branch that never raises it has nothing to
* put down. (Nothing renders that flag today — see `handleDrop` above, which says why the call
* is kept anyway.)
*/
const dropZone = canAttach
? {
onDragLeave: handleDragLeave,
onDragOver: handleDragOver,
onDrop: handleDrop,
}
: {
onDragOver: refuseDragOver,
onDrop: refuseDrop,
};
/**
* Rendered only with a channel behind it: without one there is nothing to upload to, and a file
* dialog that leads nowhere is worse than no button.
*
* `FILE_PICKER_ACCEPT` RATHER THAN `attachmentsConfig?.accept`, WHICH THESE TWO NO LONGER SHARE.
* The config's `accept` is a GATE the SDK enforces on every file we hand it, and it is a wildcard
* now for the reason set out on `attachmentsConfigFor` — a second, stricter, machine-worded gate
* behind `screenPickedFiles` refused the very files that screen exists to pass. A dialog filter is
* a HINT: it greys files out, refuses nothing, and drag and paste never meet it. Spending one
* string on both meant the honest widening of the gate would have widened the hint to "any file",
* which helps nobody. Two names, two jobs.
*/
const filePicker = attachmentsEnabled ? (
<input
accept={FILE_PICKER_ACCEPT}
className="sr-only"
// The input the `+` button clicks, shut along with it: a `click()` on a disabled input opens
// no dialog, so the door is closed even to a caller that reaches past the button for the ref.
disabled={disabled}
multiple
onChange={handlePickedFiles}
ref={fileInputRef}
type="file"
/>
) : null;
/**
* WHY SEND IS SHUT WITH A FULL STRIP IN FRONT OF IT — drawn wherever the refusals are, because it
* is the same kind of sentence and answers the same question.
*
* NOT DISMISSABLE, unlike `RejectedFiles`. A refusal is news about a file that is already gone,
* so it is read once and cleared; this is a live description of the strip, and it goes away by
* removing a chip rather than by being acknowledged. A dismiss would leave a dead Send button
* with nothing on screen explaining it.
*
* `role="status"` and not `alert`: nothing happened at this instant — the person did not just do
* something refusable — and interrupting a screen reader mid-sentence to describe a button's
* state is not what an alert is for.
*/
const tooManyStagedNotice = tooManyStaged ? (
<p className="pb-2 text-sm text-muted-foreground" role="status">
{tooManyStagedReason(draft.attachments.length)}
</p>
) : null;
if (compact) {
return (
/*
* THE WRAPPER EXISTS TO HOLD `containerRef`, AND HOLDING IT IS NOT OPTIONAL. The ref is the
* boundary our own `document` paste listener asks about — it claims a paste only when the
* event's target is inside this element — so a branch that never lands the ref has paste
* dead entirely rather than merely unstyled: every paste into it reads as somebody else's.
* The ref is typed for a `div`, which is why it cannot simply go on the form.
*
* IT IS ALSO A COLUMN NOW, so the refusals can sit ABOVE the composer. Below, they pushed the
* box the person is reading down the screen as each one arrived, and on the compact composer
* that box is already pinned to the bottom of the pane — so the reasons appeared in the gap
* under it, furthest from the drop that caused them.
*/
<div className="flex flex-col" ref={containerRef} {...dropZone}>
<RejectedFiles onDismiss={dismissRejections} rejected={rejected} />
{tooManyStagedNotice}
<form
aria-busy={isBusy}
data-slot="composer"
className={cn(
/*
* `py-3` IS LOAD-BEARING ONCE THE TEXT WRAPS. On one line `min-h-14` and the controls
* row's own `items-center` fake the vertical padding, so it read as correct for as long
* as nobody typed a paragraph. Past that the box grows to fit its content exactly and
* the glyphs sit against the border.
*
* It goes on the form rather than on the editor because the editor scrolls internally
* at COMPACT_MAX_HEIGHT_PX: padding inside that box would scroll away with the text, so
* the first visible line would still touch the top edge on a long message.
*/
/*
* A COLUMN, SO THE ATTACHMENT STRIP CAN HAVE THE FULL WIDTH. It used to be one row —
* attach button, editor, send — with the strip inside the editor's column, which
* started it 42px in from the frame's left edge with nothing under it. The strip is
* its own row across the top now, and the three controls keep their row below it.
*/
"flex min-h-14 flex-col rounded-2xl border border-border bg-card px-3 py-3 focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50",
className,
)}
onSubmit={handleFormSubmit}
>
<DictationSurface dictation={dictation} canSend={canSendRecording}>
{filePicker}
<AttachmentStrip
files={files}
images={images}
onRemove={discardAttachment}
/>
{/*
* `self-end` ON THE THREE CONTROLS, AND IT COSTS NOTHING ON ONE LINE. The row is
* `items-center`, which is right while everything in it is a single line high. A long
* message grows the editor to `COMPACT_MAX_HEIGHT_PX`, and centred buttons then float to
* the middle of that block rather than sitting on the line the person is typing. Empty,
* the row is exactly a button tall, so centred and bottom are the same pixel.
*/}
<div className="flex items-center gap-3">
{attachmentsEnabled ? (
<Button
aria-label="Attach a file"
className="self-end"
data-slot="composer-attach"
// The button stays, and stays labelled: a conversation that cannot take another
// message has not lost the ability to attach, it has lost the message. Swapping it
// for the "unavailable" placeholder would say the wrong thing about why.
disabled={disabled}
onClick={() => fileInputRef.current?.click()}
size="icon"
type="button"
variant="ghost"
>
<IconPlus className="size-5" />
</Button>
) : (
<Button
aria-label="More message options unavailable"
className="self-end disabled:opacity-100"
disabled
size="icon"
type="button"
variant="ghost"
>
<IconPlus className="size-5" />
</Button>
)}
{/* The slot is ours: `PromptArea` passes no attribute through to its own box. */}
<div className="min-w-0 flex-1" data-slot="composer-input">
<PromptArea
aria-label="Message"
className={cn(
"w-full border-0 bg-transparent p-0 text-sm shadow-none",
editorClassName,
)}
disabled={disabled}
maxHeight={COMPACT_MAX_HEIGHT_PX}
minHeight={COMPACT_MIN_HEIGHT_PX}
onChange={handleChange}
onImagePaste={canAttach ? stagePastedImage : undefined}
onSubmit={submitDraft}
placeholder="Ask anything"
ref={promptAreaRef}
triggers={triggers}
value={value}
/>
</div>
<DictationButton
dictation={dictation}
disabled={disabled || voiceCall?.active === true}
/>
{primaryAction}
</div>
</DictationSurface>
</form>
</div>
);
}
return (
// The same `containerRef`, on the wrapper this branch already had: the paste listener is scoped
// to whatever holds the ref, so a branch without it can be pasted into and nothing happens.
<div
className={cn("flex w-xl flex-col", className)}
ref={containerRef}
{...dropZone}
>
<RejectedFiles onDismiss={dismissRejections} rejected={rejected} />
{tooManyStagedNotice}
<form
aria-busy={isBusy}
className="overflow-hidden rounded-2xl border border-border bg-card"
data-slot="composer"
onSubmit={handleFormSubmit}
>
<DictationSurface
dictation={dictation}
canSend={canSendRecording}
className="p-3"
>
{filePicker}
<div className="grow pb-2">
<AttachmentStrip
files={files}
images={images}
onRemove={discardAttachment}
/>
<div data-slot="composer-input">
<PromptArea
aria-label="Message"
autoGrow
className={cn(
"w-full border-0 bg-transparent p-0 text-sm shadow-none",
editorClassName,
)}
disabled={disabled}
maxHeight={MAX_HEIGHT_PX}
onChange={handleChange}
onImagePaste={canAttach ? stagePastedImage : undefined}
onSubmit={submitDraft}
placeholder="Ask anything"
ref={promptAreaRef}
triggers={triggers}
value={value}
/>
</div>
</div>
<div className="flex items-center justify-between">
{attachmentsEnabled ? (
<Button
aria-label="Attach a file"
className="size-7 rounded-full p-0"
data-slot="composer-attach"
disabled={disabled}
onClick={() => fileInputRef.current?.click()}
type="button"
variant="ghost"
>
<IconPlus className="size-4" />
</Button>
) : (
<div />
)}
<div className="flex items-center gap-1">
<DictationButton
dictation={dictation}
disabled={disabled || voiceCall?.active === true}
/>
{primaryAction}
</div>
</div>
</DictationSurface>
</form>
</div>
);
}
/**
* GIVE BACK THE STAGED ROW A REMOVED CHIP STOOD FOR — THE ONLY CALLER THIS ENDPOINT HAS.
*
* `removeAttachment` only filters client state, so until this existed, attach-then-change-your-mind
* left the row staged with `attachedAt IS NULL` for good. The upload handler counts exactly those
* rows per person per channel and refuses the ninth with "You already have 8 attachments waiting to
* send in this channel." — naming files that are on nobody's screen, with no way back.
*
* BEST-EFFORT, AND DELIBERATELY UNINSPECTED. The chip is gone from the strip before this is called,
* because that is what the person asked for; making that wait on a round trip, or reporting what
* comes back, would put an error in front of somebody for a request they never made. There are two
* such answers — 404 for a non-uploader, 409 for an attachment already sent — and neither is
* actionable. `cull-staged-attachments.ts` is the backstop for whatever this misses.
*/
function discardStagedAttachment(attachmentId: string): void {
void fetch(attachmentUrl(attachmentId), {
method: "DELETE",
credentials: "include",
}).catch(() => undefined);
}
/**
* THE SECOND DOOR, SHUT.
*
* `processFiles` re-checks `accept` itself with an exact, CASE-SENSITIVE `file.type === filter`
* comparison, while `classifyAttachment` — the rule the server also applies — normalises first.
* Left alone, the two gates disagree, and a text file this composer accepted would be refused a
* second time in the SDK's own machine wording.
*
* BOTH HALVES OF THE NORMALISATION, WHICH IS WHY THIS GOES THROUGH `mediaTypeOf` RATHER THAN DOING
* ITS OWN SPLIT. It used to drop the parameter and leave the case, which closed the
* `text/plain;charset=utf-8` half of the gap and left the other half open: a type differing from
* the accept list only in case came back from the split unchanged, so this function decided nothing
* needed doing and handed the SDK a file it was about to refuse. That case cannot be reproduced
* with `new File(...)`, which lower-cases `type` per the Blob spec — but this function's whole
* purpose is the files this app did not build.
*
* The new `File` is a handle onto the same bytes, not a copy of them.
*/
function withMediaTypeOnly(file: File): File {
const mediaType = mediaTypeOf(file.type);
if (mediaType === file.type) {
return file;
}
return new File([file], file.name, {
lastModified: file.lastModified,
type: mediaType,
});
}