@stigmer/react 3.12.3 → 3.12.5

package/src/attachment/useAttachments.ts

@@ -12,6 +12,7 @@ import {
   uniquifyFilename,
   validateAttachmentSize,
 } from "./attachment-utils.js";
+import { prepareImageForVision } from "./prepare-image.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -20,11 +21,16 @@ import {
 /**
  * Lifecycle phase of a single attachment managed by {@link useAttachments}.
  *
+ * - `preparing` — client-side image preparation is running (see
+ *   {@link AddFilesOptions.prepareImages}); the entry exists so the UI can
+ *   show the file from the instant it was added, but no bytes have been
+ *   sent yet. Only entries added with `prepareImages` ever visit this
+ *   phase — everything else starts at `uploading`.
  * - `uploading` — bytes are being sent to the server
  * - `ready` — upload succeeded, `storageKey` is available
  * - `error` — upload failed, `error` describes the failure
  */
-export type AttachmentPhase = "uploading" | "ready" | "error";
+export type AttachmentPhase = "preparing" | "uploading" | "ready" | "error";
 
 /**
  * State for a single file being managed by the hook.
@@ -50,7 +56,12 @@ export type AttachmentPhase = "uploading" | "ready" | "error";
 export interface AttachmentEntry {
   /** Unique client-side identifier for this attachment. */
   readonly id: string;
-  /** The original `File` object selected by the user. */
+  /**
+   * The `File` object backing this attachment. For entries added with
+   * {@link AddFilesOptions.prepareImages} this starts as the user's
+   * original file and swaps to the prepared file (possibly smaller, with
+   * a matching extension/MIME change) when the `preparing` phase ends.
+   */
   readonly file: File;
   /** Current upload lifecycle phase. */
   readonly phase: AttachmentPhase;
@@ -71,25 +82,59 @@ export interface UseAttachmentsOptions {
   readonly onValidationError?: (message: string) => void;
 }
 
+/** Per-call options for {@link UseAttachmentsReturn.addFiles}. */
+export interface AddFilesOptions {
+  /**
+   * Bound image files to provider vision resolution before upload (via
+   * {@link prepareImageForVision}) — the paste-to-attach treatment
+   * (stigmer/stigmer#284). Each file's entry appears immediately in the
+   * `preparing` phase, so a large screenshot shows a chip the instant it
+   * is pasted instead of after the 150-350 ms decode/downscale/re-encode
+   * (stigmer/stigmer#369). Non-image files pass through preparation
+   * untouched.
+   *
+   * Meant for pasted content only: a picked or dragged file may be the
+   * subject of the task ("read the EXIF"), and silently re-encoding it
+   * would be a regression — see prepare-image.ts for the doctrine.
+   *
+   * With this flag, size validation runs against the PREPARED bytes (the
+   * bytes that actually upload), so an oversized paste that downscales
+   * under the limit is accepted — identical to preparing before calling
+   * `addFiles`, which is what this option replaces. A file still
+   * oversized after preparation is removed and reported via
+   * `onValidationError`.
+   */
+  readonly prepareImages?: boolean;
+}
+
 /** Return value of {@link useAttachments}. */
 export interface UseAttachmentsReturn {
-  /** Current attachment entries (uploading, ready, or errored). */
+  /** Current attachment entries (preparing, uploading, ready, or errored). */
   readonly entries: readonly AttachmentEntry[];
-  /** True when at least one entry is in the `"uploading"` phase. */
+  /**
+   * True while any entry has work in flight (`preparing` or
+   * `uploading`). This is the submit gate: `toAttachmentInputs()` carries
+   * only `ready` entries, so a send while this is true would silently
+   * drop the file the user just added.
+   */
   readonly isUploading: boolean;
+  /** True when at least one entry is in the `"preparing"` phase. */
+  readonly isPreparing: boolean;
   /** Number of entries that are ready for submission. */
   readonly readyCount: number;
-  /** True when there are entries and all are ready (none uploading or errored). */
+  /** True when there are entries and all are ready (none preparing, uploading, or errored). */
   readonly allReady: boolean;
   /** True when there is at least one entry (in any phase). */
   readonly hasEntries: boolean;
   /**
    * Add one or more files. Each file is validated and uploaded
    * immediately. Invalid files (e.g., too large) are rejected via
-   * `onValidationError` and not added.
+   * `onValidationError` and not added. With
+   * {@link AddFilesOptions.prepareImages}, images are bounded to vision
+   * resolution first — entries appear at once in the `preparing` phase.
    */
-  readonly addFiles: (files: FileList | File[]) => void;
-  /** Remove an entry by its stable ID. Aborts in-flight uploads. */
+  readonly addFiles: (files: FileList | File[], addOptions?: AddFilesOptions) => void;
+  /** Remove an entry by its stable ID. Aborts in-flight preparation and uploads. */
   readonly removeEntry: (id: string) => void;
   /** Retry a failed upload. */
   readonly retryEntry: (id: string) => void;
@@ -220,13 +265,92 @@ export function useAttachments(
     [stigmer],
   );
 
+  // The `preparing` half of the lifecycle (AddFilesOptions.prepareImages):
+  // runs prepareImageForVision on the raw file, then hands the result to
+  // the normal validate → uniquify → upload sequence. The entry already
+  // exists (created by addFiles in the `preparing` phase), so this
+  // transitions it rather than creating it.
+  const prepareEntry = useCallback(
+    async (id: string, rawFile: File) => {
+      // Registered under the same id the upload path uses, so removeEntry
+      // and clear() cancel a preparation exactly like an upload. The
+      // signal is only ever read, never passed down — prepareImageForVision
+      // never throws and cannot be interrupted; cancellation means
+      // discarding its result.
+      const controller = new AbortController();
+      abortControllers.current.set(id, controller);
+
+      const prepared = await prepareImageForVision(rawFile);
+      if (controller.signal.aborted) return;
+      // Hand-off point: from here the upload path owns the map slot
+      // (uploadFile registers its own controller under this id).
+      abortControllers.current.delete(id);
+
+      // Deferred validation — deliberately on the PREPARED bytes, the
+      // bytes that actually upload: a 12 MB screenshot that downscales
+      // under the limit must pass, exactly as it did when callers
+      // prepared before calling addFiles. Rejection removes the chip the
+      // user has been watching, so the toast is the explanation.
+      const sizeError = validateAttachmentSize(prepared);
+      if (sizeError) {
+        setEntries((prev) => prev.filter((e) => e.id !== id));
+        options?.onValidationError?.(sizeError);
+        return;
+      }
+
+      // Preparation may rename (extension follows the re-encode format),
+      // so uniquify now, against every OTHER entry's settled name —
+      // same downstream-breakage rule as the un-prepared path.
+      const takenNames = new Set(
+        entriesRef.current.filter((e) => e.id !== id).map((e) => e.file.name),
+      );
+      const uniqueName = uniquifyFilename(prepared.name, takenNames);
+      const file =
+        uniqueName === prepared.name
+          ? prepared
+          : new File([prepared], uniqueName, {
+              type: prepared.type,
+              lastModified: prepared.lastModified,
+            });
+      const contentType = detectContentType(file);
+
+      setEntries((prev) =>
+        prev.map((e) =>
+          e.id === id
+            ? { ...e, file, contentType, phase: "uploading" as const }
+            : e,
+        ),
+      );
+      uploadFile(id, file, contentType);
+    },
+    [options, uploadFile],
+  );
+
   const addFiles = useCallback(
-    (files: FileList | File[]) => {
+    (files: FileList | File[], addOptions?: AddFilesOptions) => {
       const fileArray = Array.from(files);
       const validEntries: AttachmentEntry[] = [];
       const takenNames = new Set(entriesRef.current.map((e) => e.file.name));
 
       for (const rawFile of fileArray) {
+        if (addOptions?.prepareImages) {
+          // The entry must exist THIS tick — the whole point of the
+          // preparing phase is feedback during the decode/downscale gap.
+          // Size validation and name uniquification move to prepareEntry:
+          // both depend on the prepared file (final bytes, final name).
+          const id = generateId();
+          validEntries.push({
+            id,
+            file: rawFile,
+            phase: "preparing",
+            contentType: detectContentType(rawFile),
+            storageKey: null,
+            error: null,
+          });
+          void prepareEntry(id, rawFile);
+          continue;
+        }
+
         const sizeError = validateAttachmentSize(rawFile);
         if (sizeError) {
           options?.onValidationError?.(sizeError);
@@ -266,7 +390,7 @@ export function useAttachments(
         setEntries((prev) => [...prev, ...validEntries]);
       }
     },
-    [options, uploadFile],
+    [options, uploadFile, prepareEntry],
   );
 
   const removeEntry = useCallback((id: string) => {
@@ -317,7 +441,14 @@ export function useAttachments(
       }));
   }, [entries]);
 
-  const isUploading = entries.some((e) => e.phase === "uploading");
+  const isPreparing = entries.some((e) => e.phase === "preparing");
+  // `preparing` counts as uploading-in-the-gate sense: both phases mean
+  // "this file will be lost if the message sends now" (see the
+  // isUploading doc). Hosts that gate submit on isUploading inherit the
+  // preparing gate without a code change.
+  const isUploading = entries.some(
+    (e) => e.phase === "preparing" || e.phase === "uploading",
+  );
   const readyCount = entries.filter((e) => e.phase === "ready").length;
   const hasEntries = entries.length > 0;
   const allReady = hasEntries && readyCount === entries.length;
@@ -325,6 +456,7 @@ export function useAttachments(
   return {
     entries,
     isUploading,
+    isPreparing,
     readyCount,
     allReady,
     hasEntries,

package/src/channel/ChannelConversationsDialog.tsx

@@ -5,6 +5,7 @@ import { timestampDate } from "@bufbuild/protobuf/wkt";
 import { MessageSquare, User, X } from "lucide-react";
 import { cn } from "@stigmer/theme";
 import { DialogShell } from "../internal/DialogShell.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
 import { getUserMessage } from "@stigmer/sdk";
 import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
@@ -153,7 +154,7 @@ function ChannelConversationsDialogBody({
             description="When someone messages this channel, the sessions serving them appear here."
           />
         ) : (
-          <ul className="stg:space-y-1">
+          <ul className={cn(UNSTYLED_LIST, "stg:space-y-1")}>
             {sessions.map((session) => (
               <ConversationRow
                 key={session.metadata?.id}

package/src/channel/ChannelTemplatesDialog.tsx

@@ -4,6 +4,7 @@ import { useCallback, useId, type ReactNode } from "react";
 import { ExternalLink, LayoutTemplate, X } from "lucide-react";
 import { cn } from "@stigmer/theme";
 import { DialogShell } from "../internal/DialogShell.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
 import { getUserMessage } from "@stigmer/sdk";
 import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import type { ChannelTemplate } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
@@ -297,7 +298,7 @@ function ChannelTemplatesList({
         </p>
         <WhatsAppManagerLink label="Manage in WhatsApp Manager" />
       </div>
-      <ul className="stg:space-y-2">
+      <ul className={cn(UNSTYLED_LIST, "stg:space-y-2")}>
         {templates.map((template) => (
           <TemplateRow
             key={`${template.name}\u0000${template.language}`}

package/src/channel/ConnectSlackDialog.tsx

@@ -3,6 +3,7 @@
 import { useCallback, useId, useMemo, useState } from "react";
 import { cn } from "@stigmer/theme";
 import { DialogShell } from "../internal/DialogShell.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
 import { getErrorReason, type ResourceRef } from "@stigmer/sdk";
 import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
@@ -527,7 +528,7 @@ function FlowProgress({
 
   return (
     <div className="stg:space-y-3" aria-live="polite">
-      <ul className="stg:space-y-2">
+      <ul className={cn(UNSTYLED_LIST, "stg:space-y-2")}>
         {FLOW_STEPS.map((step, i) => {
           const isActive = i === activeIndex;
           const isDone = activeIndex > i;

package/src/channel/connect/ServingAppSection.tsx

@@ -2,6 +2,7 @@
 
 import type { ReactNode } from "react";
 import { cn } from "@stigmer/theme";
+import { UNSTYLED_FIELDSET } from "../../internal/element-resets.js";
 import type { ResourceRef } from "@stigmer/sdk";
 import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
 
@@ -67,7 +68,7 @@ export function ServingAppSection({
   }
 
   return (
-    <fieldset>
+    <fieldset className={UNSTYLED_FIELDSET}>
       <legend className="stg:mb-1.5 stg:block stg:text-xs stg:font-medium stg:text-foreground">
         Connect as
       </legend>

package/src/channel-app/CreateChannelAppForm.tsx

@@ -2,6 +2,7 @@
 
 import { type FormEvent, useCallback, useId, useMemo, useState } from "react";
 import { cn } from "@stigmer/theme";
+import { UNSTYLED_FIELDSET } from "../internal/element-resets.js";
 import { getUserMessage } from "@stigmer/sdk";
 import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
 import {
@@ -286,7 +287,7 @@ function ProviderPicker({
 }) {
   const groupName = useId();
   return (
-    <fieldset>
+    <fieldset className={UNSTYLED_FIELDSET}>
       <legend className="stg:mb-1.5 stg:block stg:text-xs stg:font-medium stg:text-foreground">
         Provider
       </legend>

package/src/composer/SessionComposer.tsx

@@ -31,7 +31,6 @@ import type { UseGitHubConnectionReturn } from "../github/useGitHubConnection.js
 import { useAttachments } from "../attachment/useAttachments.js";
 import { AttachmentChipList } from "../attachment/AttachmentChipList.js";
 import { extractClipboardFiles } from "../attachment/clipboard.js";
-import { prepareImageForVision } from "../attachment/prepare-image.js";
 import { useFileReferences } from "../file-reference/useFileReferences.js";
 import { FileReferenceChipList } from "../file-reference/FileReferenceChipList.js";
 import { FILE_REF_MIME } from "../internal/file-tree/index.js";
@@ -855,11 +854,17 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
   const visionNotice = useMemo(() => {
     if (!enableAttachments || attachments.entries.length === 0) return null;
     const preflight = assessVisionPreflight(
-      attachments.entries.map((e) => ({
-        name: e.file.name,
-        sizeBytes: e.file.size,
-        contentType: e.contentType,
-      })),
+      attachments.entries
+        // A `preparing` entry still carries pre-downscale bytes — judging
+        // those would flash a false "too large" that vanishes when
+        // preparation lands. Same tri-state discipline as the module
+        // itself: silent while the real size is unknown.
+        .filter((e) => e.phase !== "preparing")
+        .map((e) => ({
+          name: e.file.name,
+          sizeBytes: e.file.size,
+          contentType: e.contentType,
+        })),
       { model: effective.model, limits: visionLimits },
     );
     return visionPreflightMessage(preflight, {
@@ -963,12 +968,11 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
       e.preventDefault();
 
       // Pasted images (and only pasted — see prepare-image.ts) are bounded
-      // to provider resolution before upload. prepareImageForVision never
-      // throws; every failure path yields the original file.
+      // to provider resolution before upload. The hook owns the whole
+      // pipeline: chips appear immediately in the `preparing` phase
+      // (stigmer/stigmer#369), then upload.
       const addFiles = attachments.addFiles;
-      void Promise.all(files.map(prepareImageForVision)).then((prepared) => {
-        addFiles(prepared);
-      });
+      addFiles(files, { prepareImages: true });
     },
     [enableAttachments, isDisabled, attachments.addFiles],
   );
@@ -1376,11 +1380,12 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
   // ---------------------------------------------------------------------------
 
   const mcpBlocked = showMcp && !mcpSetup.allReady;
-  // Send waits for in-flight uploads: toAttachmentInputs() carries only
+  // Send waits for in-flight work: toAttachmentInputs() carries only
   // "ready" entries, so a send racing an upload would silently drop the
   // file the user just pasted — the worst failure for "what's wrong in
   // this screenshot?". Errored entries never gate (their chip offers
-  // retry/remove); only the uploading phase blocks.
+  // retry/remove); isUploading covers both the preparing and uploading
+  // phases (see its doc — same drop class).
   const uploadsBlocked = enableAttachments && attachments.isUploading;
   const canSend = composer.canSubmit && !mcpBlocked && !uploadsBlocked;
 
@@ -1758,7 +1763,11 @@ const SessionComposerInner = forwardRef<SessionComposerHandle, SessionComposerPr
             className="stg:mx-3 stg:mb-2 stg:flex stg:items-center stg:gap-2 stg:rounded-md stg:bg-muted stg:px-2.5 stg:py-1.5 stg:text-xs stg:text-muted-foreground"
           >
             <ChipSpinner />
-            <span>Waiting for attachments to finish uploading…</span>
+            <span>
+              {attachments.isPreparing
+                ? "Waiting for attachments to finish preparing…"
+                : "Waiting for attachments to finish uploading…"}
+            </span>
           </div>
         )}
 

package/src/conversation/ConversationComposer.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useId, useState } from "react";
-import { Send, TriangleAlert } from "lucide-react";
+import { LayoutTemplate, Send, TriangleAlert } from "lucide-react";
 import { cn } from "@stigmer/theme";
 import { getUserMessage } from "@stigmer/sdk";
 import { ChannelSendOutcome } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
@@ -9,13 +9,29 @@ import type { SendChannelMessageOutput } from "@stigmer/protos/ai/stigmer/agenti
 import { Button } from "../button/Button.js";
 import { SpinnerIcon } from "../internal/SpinnerIcon.js";
 import { useComposer } from "../composer/useComposer.js";
+import type { ConversationReplyPayload } from "./useConversationParticipation.js";
 
 /** Props for {@link ConversationComposer}. */
 export interface ConversationComposerProps {
-  /** Send a staff reply (from `useConversationParticipation().reply`). */
-  readonly onSend: (text: string) => Promise<SendChannelMessageOutput>;
+  /**
+   * Send a staff reply (from `useConversationParticipation().reply`).
+   * The composer's own textarea always submits the `text` lane; hosts
+   * wiring a template picker send the `template` lane through the same
+   * seam — one command, one busy state, one outcome contract.
+   */
+  readonly onSend: (payload: ConversationReplyPayload) => Promise<SendChannelMessageOutput>;
   /** `true` while a reply is in flight. */
   readonly isSending: boolean;
+  /**
+   * Opens the host's template picker. When present, a persistent
+   * template affordance renders beside Send — templates are the one
+   * lane WhatsApp offers for a closed window, so the surface must
+   * offer the door, not just the advisory's warning (hosts should
+   * point at the button in the advisory copy; the advisory itself
+   * stays interaction-free — it is the input's description, F-18).
+   * Omit on channels whose provider has no template registry.
+   */
+  readonly onOpenTemplatePicker?: () => void;
   /**
    * Why replying is unavailable, when it is — rendered in place of the
    * input (a senderless provider, or a conversation the customer has
@@ -52,6 +68,7 @@ export interface ConversationComposerProps {
 export function ConversationComposer({
   onSend,
   isSending,
+  onOpenTemplatePicker,
   disabledReason,
   advisory,
   className,
@@ -66,7 +83,7 @@ export function ConversationComposer({
   const composer = useComposer({
     onSubmit: (message) => {
       setNotice(null);
-      onSend(message).then(
+      onSend({ kind: "text", body: message }).then(
         (output) => {
           if (output.outcome === ChannelSendOutcome.refused) {
             // The words never left; keep them so the user can adjust.
@@ -110,6 +127,12 @@ export function ConversationComposer({
           className="stg:mb-2 stg:flex stg:items-start stg:gap-1.5 stg:rounded-md stg:bg-status-degraded-subtle stg:px-2.5 stg:py-1.5 stg:text-xs stg:text-status-degraded"
         >
           <TriangleAlert aria-hidden="true" className="stg:mt-0.5 stg:size-3.5 stg:shrink-0" />
+          {/* Interactive content is deliberately NOT allowed in here:
+              this element is the input's aria-describedby target with
+              zero tab stops (F-18). The way forward the advisory names
+              (the template lane) lives on the persistent template
+              button beside Send — hosts point at it in the advisory
+              COPY, never with an embedded control. */}
           <span className="stg:min-w-0">{advisory}</span>
         </p>
       )}
@@ -137,6 +160,17 @@ export function ConversationComposer({
             "stg:focus-visible:outline-none stg:focus-visible:ring-2 stg:focus-visible:ring-ring",
           )}
         />
+        {onOpenTemplatePicker && (
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={onOpenTemplatePicker}
+            disabled={isSending}
+            aria-label="Send a template reply"
+          >
+            <LayoutTemplate aria-hidden="true" className="stg:size-4" />
+          </Button>
+        )}
         <Button
           variant="primary"
           size="sm"

package/src/conversation/ConversationListPane.tsx

@@ -4,6 +4,7 @@ import { memo, useCallback, useId, useRef } from "react";
 import { timestampDate } from "@bufbuild/protobuf/wkt";
 import { MessageSquare, TriangleAlert, User } from "lucide-react";
 import { cn } from "@stigmer/theme";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
 import { getUserMessage } from "@stigmer/sdk";
 import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
 import {
@@ -193,11 +194,7 @@ export function ConversationListPane({
             {/* One context-only provider arms every row's attention
                 tooltip (the WorkspaceSidebar recents-list precedent). */}
             <TooltipProvider>
-              {/* The SDK's own list reset (the MemberKeysPanel
-                  convention): hosts without a global preflight would
-                  otherwise render inbox rows with UA bullets and
-                  indent. */}
-              <ul className="stg:m-0 stg:list-none stg:space-y-0.5 stg:p-0">
+              <ul className={cn(UNSTYLED_LIST, "stg:space-y-0.5")}>
                 {conversations.map((conversation) => (
                   <ConversationRow
                     key={`${conversation.agentChannelId}:${conversation.conversationKey}`}