@wix/himalaya-cli 0.1029.0 → 0.1031.0

package/templates/retail-store-owner/tier5-src/_shared/aria-chat.ts

@@ -29,8 +29,11 @@ import {
   ARIA_ORIGIN,
   abortAssistantMessageGeneration,
   ariaAssistantConfig,
+  attachmentsOf,
   conversationIdOf,
   createConversation,
+  createFileUpload,
+  genieUploadRef,
   functionCallsOf,
   getConversationMessages,
   getConversations,
@@ -39,11 +42,26 @@ import {
   sendFunctionCallResults,
   sendMessage,
   triggerAssistantMessage,
+  uploadTargetUrl,
   userMessageIdOf,
+  type Attachment,
   type ConversationMessage,
   type ConversationSummary,
   type SendMessageResponse,
 } from "@himalaya/wix-genie-chat";
+import {
+  ARIA_MAX_ATTACHMENTS,
+  ARIA_MAX_IMAGE_BYTES,
+  attachmentLine,
+  chipIn,
+  imageFileName,
+  normalizeMime,
+  parseDataUri,
+  refusalFor,
+  sendBlocker,
+  type AriaAttachmentChip,
+  type AriaAttachmentOutcome,
+} from "./aria-attachments.js";
 import { runClientToolExchange, type AriaClientTools } from "./aria-client-tools.js";
 import { proseOfParts, scanEnvelopes, stripHidden } from "./aria-widgets.js";
 import { isWebUrl, stripMarkdown } from "./aria-widget-model.js";
@@ -91,6 +109,11 @@ export interface AriaBubble {
   link1Label: string; link1Url: string; link1Hidden: boolean;
   link2Label: string; link2Url: string; link2Hidden: boolean;
   link3Label: string; link3Url: string; link3Hidden: boolean;
+  /** The files attached to this turn, as one line ("📎 a.jpg, b.png"), and its
+   *  collapse flag. Present on EVERY bubble for the same reason the link slots
+   *  are: a row missing the field does not substitute. */
+  attachText: string;
+  attachHidden: boolean;
 }
 
 /** An empty-state suggestion card: emoji + title + hint, and the text that is
@@ -127,6 +150,10 @@ export interface AriaChatState {
   /** Text of the optimistic user bubble awaiting reconciliation with the server
    *  transcript. Empty when nothing is in flight. */
   _pending: string;
+  /** The file names the in-flight message was sent with, so the optimistic
+   *  bubble keeps its attachment line across every tick until the server's own
+   *  copy of the turn replaces it. */
+  _pendingAttach: string[];
   /** Server USER-turn COUNT at the moment the in-flight message was sent. The
    *  optimistic bubble is dropped once the server holds more than this.
    *
@@ -185,6 +212,17 @@ export interface AriaChatState {
    *  every time the transcript is, which is what makes "one active widget"
    *  true by construction rather than by remembering to clear it. */
   widget: WidgetView;
+  /** The photos waiting in the composer to go with the next message.
+   *
+   *  A PROJECTION, not a field the reducers maintain: the worker holds the chips
+   *  in one place and every action's result is stamped with them on the way out
+   *  (`gated`). An upload finishes on its own clock, so its outcome arrives while
+   *  other actions are mid-await holding older snapshots; a field each reducer
+   *  spread along would let any of those snapshots put a finished upload back to
+   *  "Uploading…", or drop a photo picked during a send. */
+  attachments: AriaAttachmentChip[];
+  /** Collapses the composer's attachment strip while it is empty. */
+  attachmentsHidden: boolean;
   /** Transient host directives — a poll cadence to install, and a navigation to
    *  perform. The runtime strips both before storing the state, so they are
    *  never persisted and never re-fire when the state is spread. */
@@ -246,13 +284,53 @@ export interface AriaChatLabels {
    *  all — it carries no Wix app binding to sign the chat-service call with.
    *  See `isWixAccountUnreachable`, and note what it is NOT: a signed-out user. */
   unavailable?: Resolvable<string>;
+  /** Attachment copy — see `AriaChatOptions.attachments`. Chip states: */
+  attachUploading?: Resolvable<string>;
+  attachFailed?: Resolvable<string>;
+  /** Refusals, shown in the neutral status line. Nothing went wrong, so none of
+   *  them is red; each one says what to do instead. */
+  attachTooMany?: (max: number) => string;
+  attachUnsupported?: Resolvable<string>;
+  attachTooLarge?: (maxMb: number) => string;
+  /** Send refused while a photo is still uploading, or failed to. */
+  attachWaitUploading?: Resolvable<string>;
+  attachWaitFailed?: Resolvable<string>;
+  /** Send refused with photos and no words. The service requires message text
+   *  on every turn, so a photo alone is not a sendable message. */
+  attachNeedsText?: Resolvable<string>;
   /** Shown when a client-tool exchange broke down (see `clientTools`) and the
    *  turn cannot finish. The underlying reason is a protocol fault the owner can
    *  do nothing about, so it is not what they are shown. */
   toolFailed?: Resolvable<string>;
 }
 
+/** What the composer needs from the device to attach a photo. Supplied by the
+ *  app's adapter, because both are capabilities the SCREEN has to declare — the
+ *  shared core imports neither, so a consumer without attachments (the clone)
+ *  keeps a declared-capability list with no camera and no upload in it.
+ *
+ *  Both ports must REJECT (or resolve not-ok) on failure. A port that swallows
+ *  an error and resolves as if it had worked would put a photo on the message
+ *  that the service never received. */
+export interface AriaAttachmentPorts {
+  /** Let the owner pick (or take) one photo. Resolves the image as a `data:`
+   *  URI, or null when they cancelled. */
+  pick(source: "library" | "camera"): Promise<{ dataUri: string; name?: string; mimeType?: string } | null>;
+  /** PUT `base64` to a pre-signed url with `contentType`, carrying NO user
+   *  credentials — the url authorizes itself. */
+  put(url: string, base64: string, contentType: string): Promise<{ ok: boolean; status: number }>;
+  /** Hand an upload's outcome back to the service as a NEW action
+   *  (`attachmentSettled`). A fresh dispatch rather than a return value, because
+   *  the upload outlives the action that started it — which must return at once
+   *  so the chip paints while the bytes are still moving. */
+  settled(outcome: AriaAttachmentOutcome): void;
+}
+
 export interface AriaChatOptions {
+  /** Photo attachments in the composer. Omit it and the attach actions are
+   *  inert — which is also what the descriptor does, since it paints no attach
+   *  control unless the app passes the matching actions. */
+  attachments?: AriaAttachmentPorts;
   /** Mount the generic card for an unrecognised kind in this `WorkerSubtree`
    *  slot.
    *
@@ -328,7 +406,7 @@ export interface AriaChatOptions {
  *  its new BOOLEAN there on iOS and Android, and the native marshaller merges
  *  args over params — so anything reading it must cope with a non-string.
  *  `optionValue` is the key a caller should use when it means the option. */
-export type AriaActionArg = string | { message?: string; text?: string; value?: unknown; optionValue?: string; id?: string; url?: string; intent?: string } | undefined;
+export type AriaActionArg = string | { message?: string; text?: string; value?: unknown; optionValue?: string; id?: string; url?: string; intent?: string; source?: string; ok?: unknown; ref?: string } | undefined;
 
 /** The first of these fields that is actually a non-empty string.
  *
@@ -580,9 +658,24 @@ export function withSpoken(bubbles: AriaBubble[]): AriaBubble[] {
     : bubbles.map((b) => (typeof b.spoken === "string" ? b : { ...b, spoken: spokenOf(b.who, b.content) }));
 }
 
-/** A greeting or optimistic bubble: no links, all slots defaulted. */
-export function plainBubble(id: string, role: string, who: string, content: string): AriaBubble {
-  return { id, role, who, content, notUser: role !== "USER", notAria: role === "USER", spoken: spokenOf(who, content), ...linkFieldsOf("", role) };
+/** A bubble's words and its attachment line, with its collapse flag.
+ *
+ *  A turn that is ONLY attachments carries the line as its content instead of
+ *  beside it: a screen that draws the owner's words in a padded bubble would
+ *  otherwise paint an empty bubble above the file names, and the row's
+ *  `spoken` label, built from the content, would announce the author and
+ *  nothing else. */
+function withAttachments(content: string, names: readonly string[]): { content: string; attachText: string; attachHidden: boolean } {
+  const attachText = attachmentLine(names);
+  if (attachText && !content.trim()) return { content: attachText, attachText: "", attachHidden: true };
+  return { content, attachText, attachHidden: !attachText };
+}
+
+/** A greeting or optimistic bubble: no links, all slots defaulted. `attached`
+ *  names the files an optimistic USER bubble is being sent with. */
+export function plainBubble(id: string, role: string, who: string, content: string, attached: readonly string[] = []): AriaBubble {
+  const a = withAttachments(content, attached);
+  return { id, role, who, notUser: role !== "USER", notAria: role === "USER", spoken: spokenOf(who, a.content), ...linkFieldsOf("", role), ...a };
 }
 
 /** Server transcript → bubbles. USER text is literal; ASSISTANT replies are
@@ -619,8 +712,16 @@ export function toBubbles(
       // can keep exactly the same text and still render differently (a held
       // back envelope is released), so text alone would serve the stale bubble.
       const writing = role !== "USER" && stillWriting(m);
-      const build = () => bubbleOf(id, role, who, raw, writing);
-      const b = memo ? memo.row(id, raw, `${role}\u0000${who}\u0000${writing ? "w" : ""}`, build) : build();
+      // The OWNER's attachments only. An assistant row carrying the field is
+      // not something the service is known to send, and naming files on it
+      // would claim Aria sent them.
+      const attached = role === "USER" ? attachmentsOf(m).map((a) => a.fileName) : [];
+      const build = () => bubbleOf(id, role, who, raw, writing, attached);
+      // Attachments are part of the key: they are not in the text, so a row
+      // keyed on text alone could serve a bubble naming the wrong files.
+      const b = memo
+        ? memo.row(id, raw, `${role}\u0000${who}\u0000${writing ? "w" : ""}\u0000${attached.join("\u0001")}`, build)
+        : build();
       if (b) out.push(b);
     }
   } finally {
@@ -643,7 +744,9 @@ export function assistantProse(raw: string, closed = true): string {
 export type BubbleMemo = RowMemo<AriaBubble | null>;
 export const createBubbleMemo = (): BubbleMemo => createRowMemo<AriaBubble | null>();
 
-function bubbleOf(id: string, role: string, who: string, raw: string, writing: boolean): AriaBubble | null {
+function bubbleOf(
+  id: string, role: string, who: string, raw: string, writing: boolean, attached: readonly string[] = [],
+): AriaBubble | null {
   // Only assistant turns carry envelopes; a user's own text is literal, and
   // scanning it would let an owner who typed `<<…>>` erase their own message.
   // HIDDEN spans go first: the service marks text as transcript-only that
@@ -655,16 +758,20 @@ function bubbleOf(id: string, role: string, who: string, raw: string, writing: b
   // painted as raw JSON until the row finishes.
   const prose = role === "USER" ? raw : assistantProse(raw, !writing);
   const content = role === "USER" ? prose : stripMarkdown(prose);
-  if (!content || !content.trim()) return null;
+  // A turn that is only attachments still happened, and dropping it would hide
+  // what the owner sent: `withAttachments` makes the file line its content.
+  // Empty prose AND no attachments is the placeholder row.
+  const a = withAttachments(content ?? "", attached);
+  if (!a.content.trim()) return null;
   return {
     id,
     role,
     who,
-    content,
     notUser: role !== "USER",
     notAria: role === "USER",
-    spoken: spokenOf(who, content),
+    spoken: spokenOf(who, a.content),
     ...linkFieldsOf(prose, role),
+    ...a,
   };
 }
 
@@ -715,13 +822,14 @@ export function argText(arg: AriaActionArg): string {
  *  vanish mid-turn. */
 export function reconcile(
   server: AriaBubble[], pending: string, pendingAfter: number, youName = "You", pendingId = "",
+  pendingAttached: readonly string[] = [],
 ): { messages: AriaBubble[]; pending: string } {
   if (!pending) return { messages: server, pending: "" };
   if (countRole(server, "USER") > pendingAfter) return { messages: server, pending: "" };
   // `pendingId` is empty only for state persisted before ids were minted; a
   // fixed fallback still keeps that one row stable across ticks.
   const id = pendingId || `${LOCAL_ID_PREFIX}pending`;
-  return { messages: [...server, plainBubble(id, "USER", youName, pending)], pending };
+  return { messages: [...server, plainBubble(id, "USER", youName, pending, pendingAttached)], pending };
 }
 
 /** How many turns of one role the transcript holds. Counted over BUBBLES rather
@@ -1054,6 +1162,19 @@ export interface AriaChatCore {
   widgetPick(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
   /** Answer one QUESTIONNAIRE question. */
   widgetAnswer(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Pick (or take) a photo and start uploading it. Returns as soon as the chip
+   *  exists — the upload reports back through `attachmentSettled`. The source is
+   *  the arg (`"camera"`, or `{ source: "camera" }`); anything else is the
+   *  library. */
+  attach(s: AriaChatState, arg?: AriaActionArg): Promise<AriaChatState>;
+  /** An upload's outcome, dispatched by the upload itself. A chip that has
+   *  since been removed or sent is not resurrected. */
+  attachmentSettled(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Drop one chip. The upload, if still running, is left to finish — there is
+   *  no cancel on the transfer — and its outcome is then ignored. */
+  removeAttachment(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Re-send a failed chip's bytes from the copy it already holds. */
+  retryAttachment(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
 }
 
 const POLL_ID = "aria-turn";
@@ -1089,6 +1210,28 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const unavailableText = () => res(
     o.labels?.unavailable ?? `${assistant()} can't reach your Wix account from here.`,
   );
+  const attachUploadingText = () => res(o.labels?.attachUploading ?? "Uploading…");
+  const attachFailedText = () => res(o.labels?.attachFailed ?? "Couldn't upload");
+  const chipLabels = () => ({ uploading: attachUploadingText(), failed: attachFailedText() });
+  const refusalText = (why: "type" | "size" | "count"): string =>
+    why === "count"
+      ? o.labels?.attachTooMany?.(ARIA_MAX_ATTACHMENTS) ?? `You can attach up to ${ARIA_MAX_ATTACHMENTS} photos.`
+      : why === "size"
+        ? o.labels?.attachTooLarge?.(ARIA_MAX_IMAGE_BYTES / (1024 * 1024))
+          ?? `That photo is too large to attach (up to ${ARIA_MAX_IMAGE_BYTES / (1024 * 1024)} MB).`
+        : res(o.labels?.attachUnsupported ?? "That file type can't be attached.");
+  const waitUploadingText = () => res(o.labels?.attachWaitUploading ?? "Wait for your photo to finish uploading.");
+  const waitFailedText = () => res(o.labels?.attachWaitFailed ?? "Retry or remove the photo that didn't upload.");
+  const needsTextText = () => res(o.labels?.attachNeedsText ?? "Add a message to send with your photo.");
+  /** Clear the status line if what it says is an attachment notice, and only
+   *  then. Every notice is advice about the composer's photos, so once the owner
+   *  acts on them it is stale — but the same line also carries "Aria is
+   *  typing…", which a photo edit must never erase. */
+  const withoutNotice = <T extends { statusText: string }>(s: T): T => {
+    const notices = [waitUploadingText(), waitFailedText(), needsTextText(),
+      refusalText("type"), refusalText("size"), refusalText("count")];
+    return s.statusText && notices.includes(s.statusText) ? { ...s, statusText: "" } : s;
+  };
   const toolFailedText = () => res(o.labels?.toolFailed ?? `${assistant()} couldn't finish that. Try again.`);
   const promptList = () => res(o.prompts);
   const siteOf = o.siteId ?? (() => "");
@@ -1098,10 +1241,98 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
 
   const initialState: AriaChatState = {
     status: "loading", statusText: "", error: "", input: "", copyNote: "", replyActionsHidden: true,
-    messages: [], prompts: [], _convId: "", _siteId: "", _pending: "",
+    messages: [], prompts: [], _convId: "", _siteId: "", _pending: "", _pendingAttach: [],
     _pendingAfter: 0, _pendingId: "", _replyAfter: 0, _srvUsers: 0, _srvAssistants: 0,
     _abortId: "", _turnId: "", stopHidden: true, ok: false,
     widget: NO_WIDGET,
+    attachments: [], attachmentsHidden: true,
+  };
+
+  /** The composer's photos — the ONE copy. See `AriaChatState.attachments` for
+   *  why the state's field is only ever a projection of this. */
+  let chips: AriaAttachmentChip[] = [];
+  /** Whether `chips` has been seeded from a rehydrated state yet. A cold start
+   *  hands the first action a PERSISTED state whose chips this worker has never
+   *  seen; the latch starts empty and would otherwise wipe them. */
+  let chipsSeeded = false;
+  /** Mints chip ids. Never derived from the file: two photos named
+   *  `IMG_0001.jpg` are two chips. */
+  let chipSeq = 0;
+  /** Each chip's full image as a `data:` URI, keyed by chip id: the bytes an
+   *  upload, or a retry, sends. Kept HERE and not in the chip, because every chip
+   *  is projected into the service state, which rides every web frame, and the
+   *  contained web runtime refuses a frame over 4 MiB. With up to 10 photos of up
+   *  to 8 MB each, the chips alone would exceed that, and the action would fail
+   *  before anything rendered. Pruned to the live chips in `gated`. */
+  const chipBytes = new Map<string, string>();
+  /** A picked image this small doubles as its own chip thumbnail; a larger one
+   *  shows the chip without a preview. Ten of these stay well under a frame. */
+  const THUMB_INLINE_MAX = 200_000;
+
+  const seedChips = (s: AriaChatState): void => {
+    if (chipsSeeded) return;
+    chipsSeeded = true;
+    const persisted = Array.isArray(s.attachments) ? s.attachments : [];
+    // An upload does not survive the process that ran it, so a chip persisted
+    // mid-upload would say "Uploading…" forever. It still holds its bytes, so it
+    // comes back as FAILED — with the retry control — rather than being dropped.
+    chips = persisted
+      .filter((c) => c && typeof c.id === "string")
+      .map((c) => (c.state === "uploading" ? chipIn(c, "failed", chipLabels()) : c));
+    for (const c of chips) {
+      const n = Number(/^att-(\d+)$/.exec(c.id)?.[1] ?? 0);
+      if (n > chipSeq) chipSeq = n;
+      // A rehydrated chip's bytes are whatever it kept inline. A large photo kept
+      // none, so its retry fails honestly rather than sending nothing.
+      if (c.thumbUrl && !chipBytes.has(c.id)) chipBytes.set(c.id, c.thumbUrl);
+    }
+  };
+
+  /** Is Send refused while photos are pending, and what does the owner see?
+   *  Shared by a typed send and a suggested-prompt tap, so neither can send past
+   *  a photo that is still uploading or failed, or drop the photos off a turn. */
+  const attachmentRefusal = (s: AriaChatState, content: string): AriaChatState | null => {
+    if (!chips.length) return null;
+    const blocker = sendBlocker(chips);
+    if (blocker === "uploading") return { ...s, statusText: waitUploadingText(), error: "" };
+    if (blocker === "failed") return { ...s, statusText: waitFailedText(), error: "" };
+    if (!content) return { ...s, statusText: needsTextText(), error: "" };
+    return null;
+  };
+
+  /** Keep a "wait for your photo" notice true to the chips as they are NOW. An
+   *  upload that FAILED while Send was held on "Wait for your photo to finish
+   *  uploading" must say to retry or remove it instead, and one that landed,
+   *  with nothing else pending, clears it. Any other status line (the typing
+   *  line above all) is left alone. */
+  const refreshWaitNotice = (s: AriaChatState): AriaChatState => {
+    const waiting = [waitUploadingText(), waitFailedText()];
+    if (!s.statusText || !waiting.includes(s.statusText)) return s;
+    const blocker = sendBlocker(chips);
+    const next = blocker === "uploading" ? waitUploadingText() : blocker === "failed" ? waitFailedText() : "";
+    return next === s.statusText ? s : { ...s, statusText: next };
+  };
+
+  /** Send one chip's bytes: mint the upload, PUT the bytes, report back. Detached
+   *  on purpose — see `AriaAttachmentPorts.settled`. Any failure, at either
+   *  step, reports `ok: false`; nothing is retried behind the owner's back. */
+  const startUpload = (chip: AriaAttachmentChip): void => {
+    const ports = o.attachments;
+    if (!ports) return;
+    const run = async (): Promise<AriaAttachmentOutcome> => {
+      const parsed = parseDataUri(chipBytes.get(chip.id) ?? chip.thumbUrl);
+      if (!parsed) return { id: chip.id, ok: false };
+      const minted = await createFileUpload(chip.name, chip.mimeType);
+      const id = (minted?.upload?.id ?? "").trim();
+      const target = uploadTargetUrl(minted?.upload?.uploadUrl ?? "", chip.name);
+      if (!id || !target) return { id: chip.id, ok: false };
+      const sent = await ports.put(target, parsed.base64, chip.mimeType);
+      return sent?.ok ? { id: chip.id, ok: true, ref: genieUploadRef(id) } : { id: chip.id, ok: false };
+    };
+    run().then(
+      (outcome) => ports.settled(outcome),
+      () => ports.settled({ id: chip.id, ok: false }),
+    );
   };
 
   /** One create at a time, per site.
@@ -1545,12 +1776,17 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const withDraft = (next: AriaChatState, since: number): AriaChatState =>
     draftSeq === since || draft === next.input ? next : { ...next, input: draft };
 
-  async function send(s: AriaChatState, content: string): Promise<AriaChatState> {
+  async function send(s: AriaChatState, content: string, attached: readonly AriaAttachmentChip[] = []): Promise<AriaChatState> {
     // A new turn is a turn boundary: any tick still parked on the PREVIOUS
     // turn's transcript read must stand down rather than write its snapshot over
     // this one. Bump before the first await so an in-flight tick is already stale
     // by the time it resolves.
     turnSeq += 1;
+    // Only chips whose bytes have LANDED travel; `submit` refuses to get here
+    // with any other kind, and this filter is the second lock on that door.
+    const riding = attached.filter((c) => c.state === "ready" && !!c.ref);
+    const attachments: Attachment[] = riding.map((c) => ({ fileName: c.name, mimeType: c.mimeType, url: c.ref }));
+    const attachedNames = riding.map((c) => c.name);
     // Optimistic first: the owner's message and the typing line are part of the
     // state this action RETURNS, so on the `_poll` path they paint immediately.
     // Its id is the LOCAL SEND ID, minted here and carried as `_pendingId`, the
@@ -1572,7 +1808,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       localId = minted.id;
     }
     const optimistic: AriaBubble[] = [
-      ...s.messages.filter((b) => b.id !== localId), plainBubble(localId, "USER", you(), content),
+      ...s.messages.filter((b) => b.id !== localId), plainBubble(localId, "USER", you(), content, attachedNames),
     ];
     const base: AriaChatState = {
       // `copyNote: ""` — a Copy confirmation belongs to the moment, and a new
@@ -1584,7 +1820,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // on a stale turn id would look for an answer that already exists. Both
       // are replaced the moment this send knows its own id.
       _abortId: "", _turnId: "",
-      statusText: typingText(), messages: optimistic, _pending: content, _pendingId: localId,
+      statusText: typingText(), messages: optimistic, _pending: content, _pendingId: localId, _pendingAttach: attachedNames,
       // Mark the turn against the LAST COUNTS WE SAW, not against our own
       // message list — the greeting is a local bubble the server never had, so
       // counting `messages` would mark the turn one assistant reply ahead and
@@ -1683,9 +1919,21 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         abortId = stalled.userMessageId;
         answer = await triggerAssistantMessage(convId, stalled.userMessageId, { origin });
       } else {
-        answer = await sendMessage(convId, content, { origin });
+        answer = await sendMessage(convId, content, {
+          origin,
+          // Omitted rather than `[]` when there are none, so a plain text turn
+          // is byte-for-byte what it was before attachments existed.
+          ...(attachments.length ? { attachments } : {}),
+        });
         abortId = userMessageIdOf(answer);
       }
+      // The turn is stored WITH its photos, so they leave the composer — by id,
+      // against the live latch, because a photo picked while this send was in
+      // the air is not part of it and must stay.
+      if (riding.length) {
+        const gone = new Set(riding.map((c) => c.id));
+        chips = chips.filter((c) => !gone.has(c.id));
+      }
       // A SECOND boundary bump, and the load-bearing one. The bump at entry only
       // retires a tick that was already parked when the owner tapped Send. A tick
       // dispatched DURING the two round trips above read the post-bump epoch, so
@@ -1844,9 +2092,19 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     // `_pending` rather than `turnInFlight` — see `regenerate` for why `status`
     // is not trusted to have been cleared.
     const replyActionsHidden = !(lastReply(s) && !s._pending);
-    const out = s.stopHidden === hidden && s.replyActionsHidden === replyActionsHidden
+    const actioned = s.stopHidden === hidden && s.replyActionsHidden === replyActionsHidden
       ? s
       : { ...s, stopHidden: hidden, replyActionsHidden };
+    // The attachment projection rides the same exit, for the same reason: one
+    // place that every action's result passes through, so no reducer can hand
+    // back a stale copy of the chips. Seeded first, so the very first action of
+    // a cold start stamps the PERSISTED chips rather than an empty latch.
+    seedChips(actioned);
+    for (const id of [...chipBytes.keys()]) if (!chips.some((c) => c.id === id)) chipBytes.delete(id);
+    const attachmentsHidden = chips.length === 0;
+    const out = actioned.attachments === chips && actioned.attachmentsHidden === attachmentsHidden
+      ? actioned
+      : { ...actioned, attachments: chips, attachmentsHidden };
     // Every state the runtime commits passes through here (an `undefined`
     // result commits nothing and skips it), so this is the newest committed
     // state — what `copyMessage` puts its note on when other actions landed
@@ -1858,6 +2116,21 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     return out;
   };
 
+  /** Which chip an action names. Accepts the bare id and the object form, as
+   *  every other action here does. */
+  const chipIdOf = (arg?: AriaActionArg): string =>
+    typeof arg === "string" ? arg.trim() : firstString(arg?.id, arg?.optionValue, arg?.value);
+
+  /** Replace one chip in the latch. Returns false when it no longer exists —
+   *  removed, sent, or discarded by ➕ — which every caller treats as "nothing to
+   *  do" rather than bringing it back. */
+  const replaceChip = (id: string, next: (c: AriaAttachmentChip) => AriaAttachmentChip): boolean => {
+    const at = chips.findIndex((c) => c.id === id);
+    if (at < 0) return false;
+    chips = [...chips.slice(0, at), next(chips[at]), ...chips.slice(at + 1)];
+    return true;
+  };
+
   /** Ask the service how an async job is getting on.
    *
    *  Folded into the existing `tick` rather than armed as a SECOND `_poll`, and
@@ -1973,7 +2246,12 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     initialState,
 
     load: async (s) => {
+      seedChips(s);
       const site = siteOf();
+      // An upload is minted under the business whose signed instance asked for
+      // it, exactly as a conversation is. Photos picked for one business must not
+      // ride a message to another, so a switch drops them with the conversation.
+      if (s._siteId && s._siteId !== site) chips = [];
       // Every branch below that puts a DIFFERENT conversation on screen abandons
       // whatever turn was in flight — a business switch mid-turn does exactly
       // that — so it re-arms the ladder slow, as `newChat` does. Otherwise the
@@ -2062,9 +2340,14 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
 
     submit: async (s, arg) => {
       const content = argText(arg) || (s.input ?? "").trim();
+      // Read from the latch, never from `s`: see `AriaChatState.attachments`.
+      // Each refusal leaves the draft AND the photos exactly as they were — the
+      // owner fixes the one thing named and taps Send again.
+      const refused = attachmentRefusal(s, content);
+      if (refused) return refused;
       if (!content) return { ...s, statusText: "" };
       if (duplicate(s, content)) return s;
-      return send(s, content);
+      return send(s, content, chips);
     },
 
     // A suggested-prompt chip submits its own text through the SAME path a typed
@@ -2074,8 +2357,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     submitPrompt: async (s, arg) => {
       const msg = argText(arg);
       if (!msg) return s;
+      // Staged photos go with the prompt, under the same rules as Send: a chip
+      // that bypassed them would send the words and strand the photos in the
+      // composer, or send past one that has not finished uploading.
+      const refused = attachmentRefusal(s, msg);
+      if (refused) return refused;
       if (duplicate(s, msg)) return s;
-      return send(s, msg);
+      return send(s, msg, chips);
     },
 
     newChat: async (s) => {
@@ -2083,6 +2371,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // A fresh conversation is a turn boundary too: a tick parked on the OLD
       // conversation's transcript must not reconcile it over the new greeting.
       turnSeq += 1;
+      // ➕ discards the draft (`input: ""` below), and the photos are part of the
+      // draft. An upload still running settles into nothing: its chip is gone.
+      chipsSeeded = true;
+      chips = [];
       // ➕ can land mid-turn, and it abandons that turn: `status` goes back to
       // `ready`, so `tick`'s `wasFast` is false from here on and the FAST
       // ladder the send armed would never be slowed again. A worker cannot
@@ -2151,7 +2443,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // reply go unnoticed and pinned the ladder fast forever. Safe to return
         // `s` here: the guard above proved this tick is still current.
         if (!raw.length) return s;
-        const { messages, pending } = reconcile(server, s._pending, s._pendingAfter, you(), s._pendingId);
+        const { messages, pending } = reconcile(server, s._pending, s._pendingAfter, you(), s._pendingId, s._pendingAttach ?? []);
         // …but still never PAINT nothing over something. `messages` is only
         // adopted when it has content: a transcript that renders empty leaves
         // the screen as it was (the greeting, or the last good turn) while the
@@ -2371,6 +2663,95 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       return s;
     },
 
+    attach: async (s, arg) => {
+      const ports = o.attachments;
+      if (!ports) return s;
+      seedChips(s);
+      // Refused BEFORE the picker opens when there is no room: presenting a
+      // picker whose result will be thrown away wastes the owner's time.
+      if (chips.length >= ARIA_MAX_ATTACHMENTS) return { ...s, statusText: refusalText("count"), error: "" };
+      const raw = typeof arg === "string" ? arg : firstString(arg?.source, arg?.value);
+      const source = raw.trim().toLowerCase() === "camera" ? "camera" : "library";
+      // The picker is open for as long as the owner takes, and a poll, a reply or
+      // another action can commit a NEWER state meanwhile. Returning `{ ...s }`
+      // afterwards would put this pre-picker snapshot back over it: an older
+      // transcript, a `_pending` already answered, a reply that just landed
+      // hidden again. So the result is built on the newest committed state, the
+      // same way `copyMessage` puts its note there (see `gated`).
+      const at = commits;
+      const latest = (): AriaChatState => (commits !== at && committed ? committed : s);
+      let picked: Awaited<ReturnType<AriaAttachmentPorts["pick"]>>;
+      try {
+        picked = await ports.pick(source);
+      } catch {
+        // A picker that could not open is not the owner's fault and there is no
+        // file to talk about; say nothing rather than something misleading.
+        return latest();
+      }
+      if (!picked || !picked.dataUri) return latest();   // cancelled
+      const parsed = parseDataUri(picked.dataUri);
+      const mimeType = normalizeMime(picked.mimeType || parsed?.mimeType || "");
+      // Re-checked after the await: other picks may have landed meanwhile.
+      const refused = refusalFor(parsed, mimeType, chips.length);
+      if (refused) return { ...latest(), statusText: refusalText(refused), error: "" };
+      chipSeq += 1;
+      const id = `att-${chipSeq}`;
+      chipBytes.set(id, picked.dataUri);
+      const chip = chipIn({
+        id,
+        name: imageFileName(mimeType, chipSeq, picked.name),
+        mimeType,
+        // Only a small image rides the state as its own thumbnail; see `chipBytes`.
+        thumbUrl: picked.dataUri.length <= THUMB_INLINE_MAX ? picked.dataUri : "",
+      }, "uploading", chipLabels());
+      chips = [...chips, chip];
+      startUpload(chip);
+      // Clear a refusal left over from an earlier pick: this one worked. The
+      // typing line is not touched, so picking mid-turn does not hide it.
+      return { ...withoutNotice(latest()), error: "" };
+    },
+
+    attachmentSettled: (s, arg) => {
+      const id = chipIdOf(arg);
+      if (!id) return s;
+      const ok = typeof arg === "object" && !!arg && (arg.ok === true || arg.ok === "true");
+      const ref = typeof arg === "object" && arg ? (arg.ref ?? "").trim() : "";
+      // Only an UPLOADING chip can settle. A retry re-mints the chip's id (see
+      // `retryAttachment`), so a late answer from an earlier attempt names an id
+      // that no longer exists and cannot decide the attempt now running.
+      const current = chips.find((c) => c.id === id);
+      if (!current || current.state !== "uploading") return s;
+      replaceChip(id, (c) => chipIn(c, ok && ref ? "ready" : "failed", chipLabels(), ref));
+      // A "wait for your photo" notice follows the chips: a failure turns
+      // "…finish uploading" into "retry or remove…", and a success clears it
+      // once nothing else is pending.
+      return refreshWaitNotice(s);
+    },
+
+    removeAttachment: (s, arg) => {
+      const id = chipIdOf(arg);
+      if (!id || !chips.some((c) => c.id === id)) return s;
+      chips = chips.filter((c) => c.id !== id);
+      return refreshWaitNotice(withoutNotice(s));
+    },
+
+    retryAttachment: (s, arg) => {
+      const id = chipIdOf(arg);
+      const current = chips.find((c) => c.id === id);
+      if (!current || current.state !== "failed") return s;
+      // A NEW id for the new attempt, in the same place in the strip. Keeping the
+      // old one would let the first attempt's outcome, if it is still in the air,
+      // settle this one.
+      chipSeq += 1;
+      const again = chipIn({ ...current, id: `att-${chipSeq}` }, "uploading", chipLabels());
+      // The bytes follow the chip to its new id; the old entry is pruned in `gated`.
+      const bytes = chipBytes.get(id);
+      if (bytes) chipBytes.set(again.id, bytes);
+      replaceChip(id, () => again);
+      startUpload(again);
+      return withoutNotice(s);
+    },
+
     // Abandon the reply being generated. Three things happen, and only the first
     // is a network call:
     //
@@ -2533,6 +2914,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     widgetRespond: (s, arg) => impl.widgetRespond(s, arg).then(gated),
     widgetPrimary: (s) => impl.widgetPrimary(s).then(gated),
     widgetSecondary: (s) => impl.widgetSecondary(s).then(gated),
+    attach: (s, arg) => impl.attach(s, arg).then(gated),
+    attachmentSettled: (s, arg) => gated(impl.attachmentSettled(s, arg)),
+    removeAttachment: (s, arg) => gated(impl.removeAttachment(s, arg)),
+    retryAttachment: (s, arg) => gated(impl.retryAttachment(s, arg)),
   };
 }