From 4b437d0906db05403b8f343d2f65a5247255f689 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 18 Jun 2026 20:11:34 -0700
Subject: [PATCH 01/34] wip: PromptField styling

---
 .../@react-spectrum/ai/src/PromptField.tsx    |  71 +--
 .../ai/src/PromptFieldContainer.tsx           | 234 ++++++++++
 .../@react-spectrum/ai/src/tokens.macro.ts    |  58 +++
 .../@react-spectrum/ai/src/tokens.merged.json | 441 ++++++++++++++++++
 .../ai/stories/PromptField.stories.tsx        |   3 +-
 5 files changed, 754 insertions(+), 53 deletions(-)
 create mode 100644 packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
 create mode 100644 packages/@react-spectrum/ai/src/tokens.macro.ts
 create mode 100644 packages/@react-spectrum/ai/src/tokens.merged.json

diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index 7614bcae7d3..1c15abdcb0a 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -14,7 +14,6 @@ import {ActionButton} from '@react-spectrum/s2/ActionButton';
 import Attach from '@react-spectrum/s2/icons/Attach';
 import {Attachment, AttachmentList, AttachmentListProps} from './AttachmentList';
 import {Autocomplete} from 'react-aria-components/Autocomplete';
-import {baseColor, css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {Button} from '@react-spectrum/s2/Button';
 import {CenterBaseline} from '@react-spectrum/s2/CenterBaseline';
 import {
@@ -27,7 +26,7 @@ import {
   useRef,
   useState
 } from 'react';
-// eslint-disable-next-line
+import {css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
   Direction,
   Position,
@@ -35,18 +34,15 @@ import {
   TokenSegment,
   TokenSegmentList
 } from './TokenSegmentList';
-import {getEventTarget} from 'react-aria/private/utils/shadowdom/DOMFunctions';
-import {Group} from 'react-aria-components/Group';
-import {IconContext, mergeStyles} from '@react-spectrum/s2';
+import {IconContext} from '@react-spectrum/s2';
 import {Image, Text} from '@react-spectrum/s2/Card';
 import {isFileDropItem, useDrop} from 'react-aria-components/useDrop';
-import {isFocusable} from 'react-aria/private/utils/isFocusable';
 import {Link} from '@react-spectrum/s2/Link';
 import {Menu, MenuItem, MenuItemProps, MenuTrigger} from '@react-spectrum/s2/Menu';
-// eslint-disable-next-line
 import Plus from '@react-spectrum/s2/icons/Add';
 import {Popover, PopoverProps} from '@react-spectrum/s2/Popover';
 import {positionToDOMRange, Token, TokenField, TokenProps} from './TokenField';
+import {PromptFieldContainer} from './PromptFieldContainer';
 import {PromptFocusContext} from './Chat';
 import Send from '@react-spectrum/s2/icons/ArrowUpSend';
 import Stop from '@react-spectrum/s2/icons/StopProcessing';
@@ -67,6 +63,7 @@ export interface PromptFieldProps {
   onAddAttachments?: (attachments: PromptFieldAttachment[]) => void;
   onRemoveAttachments?: (attachments: PromptFieldAttachment[]) => void;
   styles?: StyleString;
+  variant?: 'balanced' | 'prominent' | 'subtle';
 }
 
 interface PromptFieldState {
@@ -141,7 +138,8 @@ export function PromptField(props: PromptFieldProps) {
     onStop,
     styles,
     onAddAttachments,
-    onRemoveAttachments
+    onRemoveAttachments,
+    variant = 'balanced'
   } = props;
   let [prompt, setPrompt] = useState<TokenSegmentList>(new AutoLinkingSegmentList([]));
   let [attachments, setAttachments] = useState<PromptFieldAttachment[]>([]);
@@ -149,7 +147,7 @@ export function PromptField(props: PromptFieldProps) {
   // Not using RAC DropZone because it adds its own focusable button,
   // and we want to avoid an extra tab. We support pasting files directly into the input.
   let inputRef = useRef<HTMLDivElement>(null);
-  let {dropProps, isDropTarget} = useDrop({
+  let {dropProps} = useDrop({
     ref: inputRef,
     hasDropButton: true,
     isDisabled: !acceptedAttachmentTypes,
@@ -202,47 +200,15 @@ export function PromptField(props: PromptFieldProps) {
         onRemoveAttachments
       }}>
       <div {...focusWithinProps}>
-        <Group
+        <PromptFieldContainer
           {...dropProps}
           role="group"
-          className={renderProps =>
-            mergeStyles(
-              style({
-                display: 'flex',
-                flexDirection: 'column',
-                gap: 16,
-                padding: 16,
-                boxShadow: 'emphasized',
-                backgroundColor: {
-                  default: 'elevated',
-                  isDropTarget: 'blue-200'
-                },
-                borderRadius: 'lg',
-                borderWidth: 2,
-                borderStyle: 'solid',
-                borderColor: {
-                  default: 'transparent',
-                  isDropTarget: 'blue-800'
-                },
-                cursor: 'text'
-              })({...renderProps, isDropTarget}),
-              styles
-            )
-          }
-          onPointerDown={e => {
-            // If not clicking on something focusable within the prompt field, focus the input.
-            let target = getEventTarget(e) as Element | null;
-            while (target && target !== e.currentTarget && !isFocusable(target)) {
-              target = target.parentElement;
-            }
-
-            if (target === e.currentTarget) {
-              e.preventDefault();
-              inputRef.current?.focus();
-            }
-          }}>
+          variant={variant}
+          isGenerating={isGenerating ?? false}
+          styles={styles}
+          inputRef={inputRef}>
           {children}
-        </Group>
+        </PromptFieldContainer>
         <p className={style({font: 'ui-sm', textAlign: 'center'})}>
           Responses are generated using AI, and may be inaccurate. Check before using.{' '}
           <Link
@@ -373,21 +339,21 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
             : undefined
         }
         onSubmit={onSubmit}
-        className={renderProps =>
+        className={
           css('&:empty::before { content: attr(data-placeholder); }') +
           style({
             font: 'body',
             color: {
-              default: baseColor('neutral'),
+              default: 'gray-800',
               ':empty': {
-                default: 'gray-600',
+                default: 'transparent-overlay-600',
                 forcedColors: 'GrayText'
               }
             },
             width: 'full',
             outlineStyle: 'none',
             cursor: 'text'
-          })(renderProps)
+          })
         }>
         {children || (segment => <PromptToken>{segment.text}</PromptToken>)}
       </TokenField>
@@ -519,6 +485,7 @@ export function PromptFieldSubmitButton(props: PromptFieldSubmitButtonProps) {
   return (
     <Button
       variant="primary"
+      staticColor="auto"
       // TODO: should it be possible to submit a prompt with only attachments?
       isDisabled={prompt.segments.length === 0 && !isGenerating}
       aria-label={isGenerating ? 'Stop' : 'Send'}
@@ -536,7 +503,7 @@ export function InsertMenuButton(props: InsertMenuItemProps) {
   let {children} = props;
   return (
     <MenuTrigger>
-      <ActionButton isQuiet aria-label="Add">
+      <ActionButton isQuiet staticColor="auto" aria-label="Add">
         <Plus />
       </ActionButton>
       <Menu>{children}</Menu>
diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
new file mode 100644
index 00000000000..f3bd525b18e
--- /dev/null
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -0,0 +1,234 @@
+import {color, css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {defineProperties, stops, token} from './tokens.macro' with {type: 'macro'};
+import {getEventTarget} from 'react-aria/private/utils/shadowdom/DOMFunctions';
+import {Group, GroupProps} from 'react-aria-components/Group';
+import {isFocusable} from 'react-aria/private/utils/isFocusable';
+import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
+
+const STATE_TRANSITION = '700ms cubic-bezier(0.32, 0.72, 0, 1)';
+
+defineProperties(`
+  @property --con-hue-opacity {
+    syntax: '<percentage>';
+    initial-value: 0%;
+    inherits: false;
+  }
+
+  @property --con-bg-stop-1 {
+    syntax: '<color>';
+    initial-value: #0000;
+    inherits: false;
+  }
+
+  @property --con-bg-stop-2 {
+    syntax: '<color>';
+    initial-value: #0000;
+    inherits: false;  
+  }
+
+  @property --con-bg-stop-3 {
+    syntax: '<color>';
+    initial-value: #0000;
+    inherits: false;
+  }
+
+  @property --con-bg-stop-4 {
+    syntax: '<color>';
+    initial-value: #0000;
+    inherits: false;
+  }
+`);
+
+const containerBackground = css(`
+  transition: --con-hue-opacity ${STATE_TRANSITION}, --con-bg-stop-1 ${STATE_TRANSITION}, --con-bg-stop-2 ${STATE_TRANSITION}, --con-bg-stop-3 ${STATE_TRANSITION}, --con-bg-stop-4 ${STATE_TRANSITION}, box-shadow ${STATE_TRANSITION};
+  
+  background:
+    linear-gradient(
+      to bottom,
+      light-dark(rgb(255 255 255 / 40%), rgb(0 0 0 / 40%)), 37%,
+      light-dark(rgb(255 255 255 / 12%), rgb(0 0 0 / 12%)) 83%
+    ),
+    radial-gradient(
+      50% 50% at -20% 100%,
+      rgb(from ${token('container.gradient.con-hue.generating.stop-3')} r g b / var(--con-hue-opacity)),
+      transparent
+    ),
+    radial-gradient(
+      70% 60% at 5% 80%,
+      rgb(from ${token('container.gradient.con-hue.generating.stop-2')} r g b / var(--con-hue-opacity)),
+      transparent
+    ),
+    radial-gradient(
+      70% 50% at 40% 80%,
+      rgb(from ${token('container.gradient.con-hue.generating.stop-1')} r g b / var(--con-hue-opacity)),
+      transparent
+    ),
+    radial-gradient(
+      circle at right bottom,
+      var(--con-bg-stop-1) 0%,
+      var(--con-bg-stop-2) 35%,
+      var(--con-bg-stop-3) 82%,
+      var(--con-bg-stop-4) 100%
+    );
+
+  --border-color: ${token(`container.border.default`)};
+  --inset-shadow-color: ${color('transparent-white-50')};
+  --drop-shadow-color: ${color('fuchsia-900/5')};
+  --outer-border-color: ${token('outer-border.gradient.ob-border.stop-1')};
+  
+  box-shadow:
+    inset 0 0 0 1px var(--border-color),
+    inset 0 6px 15px 0 var(--inset-shadow-color),
+    inset 0 -5px 21.6px 0 ${color('transparent-white-50')},
+    inset 0 24px 32px 0 ${color('transparent-white-50')},
+    0 -3px 10px 1px var(--drop-shadow-color),
+    0 0 0 6px var(--outer-border-color),
+    0 6px 16px -6px var(--outer-border-hue);
+
+  &[data-variant=balanced] {
+    --outer-border-hue: light-dark(
+      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-balanced.light')}%),
+      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-balanced.dark')}%)
+    );
+  }
+  
+  &[data-variant=prominent] {
+    --outer-border-hue: rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-prominent')}%);
+  }
+
+  &[data-variant=subtle] {
+    --outer-border-hue: light-dark(
+      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-subtle.light')}%),
+      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-subtle.dark')}%)
+    );
+  }
+
+  &[data-state=idle] {
+    &[data-variant=balanced] {
+      ${stops('idle', 'default', 'balanced')}
+
+      &[data-hovered] {
+        ${stops('idle', 'hover', 'balanced')}
+      }
+    }
+
+    &[data-variant=prominent] {
+      ${stops('idle', 'default', 'prominent')}
+
+      &[data-hovered] {
+        ${stops('idle', 'hover', 'prominent')}
+      }
+    }
+
+    &[data-variant=subtle] {
+      --con-hue-opacity: 0%;
+      --con-bg-stop-1: light-dark(white, ${color('gray-75')});
+      --con-bg-stop-2: light-dark(white, ${color('gray-75')});
+      --con-bg-stop-3: light-dark(white, ${color('gray-75')});
+      --con-bg-stop-4: light-dark(white, ${color('gray-75')});
+
+      &[data-hovered] {
+        ${stops('idle', 'hover', 'subtle')}
+      }
+    }
+
+    &[data-focus-within][data-focus-within] {
+      --con-hue-opacity: 0%;
+      --con-bg-stop-1: light-dark(white, ${color('gray-75')});
+      --con-bg-stop-2: light-dark(white, ${color('gray-75')});
+      --con-bg-stop-3: light-dark(white, ${color('gray-75')});
+      --con-bg-stop-4: light-dark(white, ${color('gray-75')});
+
+      --border-color: ${token(`container.border.focus`)};
+      --inset-shadow-color: transparent;
+      --drop-shadow-color: transparent;
+      --outer-border-color: ${token('outer-border.gradient.ob-border.focus.stop-1')};
+      --outer-border-hue: transparent;
+    }
+  }
+
+  &[data-state=generating] {
+    box-shadow:
+      inset 0 0 0 1px var(--border-color),
+      inset 0 6px 15px 0 var(--inset-shadow-color),
+      inset 0 -32px 100px -50px ${token('container.color.inner-shadow.generating')},
+      inset 0 -5px 21.6px 0 ${color('transparent-white-50')},
+      inset 0 24px 32px 0 ${color('transparent-white-50')},
+      0 -3px 10px 1px var(--drop-shadow-color),
+      0 6px 16px -6px var(--outer-border-hue),
+      0 6px 83px rgb(from ${token('outer-border.gradient.ob-spread-shadow.generating.stop-3')} r g b / ${token('outer-border.opacity.spread-bg-balanced')}%),
+      0 0 0 6px var(--outer-border-color);
+
+    &[data-variant=balanced] {
+      ${stops('generating', 'default', 'balanced')}
+
+      &[data-hovered] {
+        ${stops('generating', 'hover', 'balanced')}
+      }
+    }
+
+    &[data-variant=prominent] {
+      ${stops('generating', 'default', 'prominent')}
+
+      &[data-hovered] {
+        ${stops('generating', 'hover', 'prominent')}
+      }
+    }
+
+    &[data-variant=subtle] {
+      ${stops('generating', 'default', 'subtle')}
+
+      &[data-hovered] {
+        ${stops('generating', 'hover', 'subtle')}
+      }
+    }
+  }
+`);
+
+interface PropFieldContainerProps extends GroupProps {
+  variant: 'balanced' | 'prominent' | 'subtle';
+  isGenerating: boolean;
+  styles?: StyleString;
+  inputRef: React.RefObject<HTMLDivElement | null>;
+}
+
+export function PromptFieldContainer(props: PropFieldContainerProps) {
+  let {variant, isGenerating, styles, inputRef, ...otherProps} = props;
+  return (
+    <Group
+      {...otherProps}
+      role="group"
+      data-variant={variant}
+      data-state={isGenerating ? 'generating' : 'idle'}
+      className={
+        (props.className || '') +
+        ' ' +
+        containerBackground +
+        mergeStyles(
+          style({
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 16,
+            padding: 16,
+            cursor: 'text',
+            borderRadius: '[24px]'
+          }),
+          styles
+        )
+      }
+      onPointerDown={e => {
+        // If not clicking on something focusable within the prompt field, focus the input.
+        let target = getEventTarget(e) as Element | null;
+        while (target && target !== e.currentTarget && !isFocusable(target)) {
+          target = target.parentElement;
+        }
+
+        if (target === e.currentTarget) {
+          e.preventDefault();
+          inputRef.current?.focus();
+        }
+      }}>
+      {props.children}
+    </Group>
+  );
+}
diff --git a/packages/@react-spectrum/ai/src/tokens.macro.ts b/packages/@react-spectrum/ai/src/tokens.macro.ts
new file mode 100644
index 00000000000..6c6d839c5b2
--- /dev/null
+++ b/packages/@react-spectrum/ai/src/tokens.macro.ts
@@ -0,0 +1,58 @@
+import {color} from '@react-spectrum/s2/style';
+import tokens from './tokens.merged.json';
+
+export function token(name: string) {
+  let token = name.split('.').reduce((acc, curr) => {
+    let res = acc[curr];
+    if (res == null) {
+      throw new Error(`Token ${name} not found`);
+    }
+    return res;
+  }, tokens) as any;
+  if (token?.light && token.dark) {
+    return `light-dark(${token.light}, ${token.dark})`;
+  } else if (token?.light) {
+    return token.light;
+  } else if (token?.dark) {
+    return token.dark;
+  } else {
+    return token.value ?? token;
+  }
+}
+
+export function alphaToGrayscale(name: string) {
+  let token = name.split('.').reduce((acc, curr) => acc[curr], tokens) as any;
+  let match = token.match(/^rgba\((.+?),\s*(.+?),\s*(.+?),\s*(.+?)\)$/);
+  if (match && match[1] === match[2] && match[2] === match[3]) {
+    return [`rgb(${match[1]}, ${match[2]}, ${match[3]})`, Number(match[4]) * 100];
+  } else {
+    return token;
+  }
+}
+
+export function mix(gray: string, stop: string, opacity: string) {
+  let stopColor = token(stop);
+  let stopOpacity = token(opacity);
+  return `color-mix(in srgb, ${gray}, ${stopColor} ${stopOpacity}%)`;
+}
+
+export function stop(gray: string, stop: string, opacity: string) {
+  return `light-dark(${mix('white', stop + '.light', opacity + '.light')}, ${mix(color('gray-75'), stop + '.dark', opacity + '.dark')})`;
+}
+
+export function defineProperties(css: string) {
+  this.addAsset({
+    type: 'css',
+    content: css
+  });
+}
+
+export function stops(generating: string, state: string, variant: string) {
+  return `
+    --con-hue-opacity: ${token(`container.opacity.con-hue.${generating}.${state}-${variant}`)}%;
+    --con-bg-stop-1: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-1`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+    --con-bg-stop-2: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-2`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+    --con-bg-stop-3: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-3`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+    --con-bg-stop-4: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-4`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+  `;
+}
diff --git a/packages/@react-spectrum/ai/src/tokens.merged.json b/packages/@react-spectrum/ai/src/tokens.merged.json
new file mode 100644
index 00000000000..8573375c5c1
--- /dev/null
+++ b/packages/@react-spectrum/ai/src/tokens.merged.json
@@ -0,0 +1,441 @@
+{
+  "send-button": {
+    "bg": {
+      "default": {
+        "light": "rgba(0, 0, 0, 0.85)",
+        "dark": "rgba(255, 255, 255, 0.85)"
+      },
+      "disabled": {
+        "light": "rgba(0, 0, 0, 0.05)",
+        "dark": "rgba(255, 255, 255, 0.05)"
+      }
+    },
+    "icon": {
+      "default": {
+        "light": "rgba(255, 255, 255, 1)",
+        "dark": "rgba(0, 0, 0, 1)"
+      },
+      "disabled": {
+        "light": "rgba(0, 0, 0, 0.15)",
+        "dark": "rgba(255, 255, 255, 0.15)"
+      }
+    }
+  },
+  "content": {
+    "default": {
+      "light": "rgba(0, 0, 0, 0.56)",
+      "dark": "rgba(255, 255, 255, 0.51)"
+    },
+    "focus": {
+      "light": "rgba(41, 41, 41, 1)",
+      "dark": "rgba(41, 41, 41, 1)"
+    }
+  },
+  "container": {
+    "bg": {
+      "default": {
+        "light": "rgba(255, 255, 255, 0.85)",
+        "dark": "rgba(255, 255, 255, 0.05)"
+      },
+      "focus": {
+        "light": "rgba(255, 255, 255, 0.85)",
+        "dark": "rgba(255, 255, 255, 0.02)"
+      }
+    },
+    "opacity": {
+      "con-overlay": {
+        "idle": {
+          "default-balanced": {
+            "value": 40
+          },
+          "default-prominent": {
+            "value": 60
+          },
+          "default-subtle": {
+            "value": 40
+          },
+          "hover-balanced": {
+            "light": 50,
+            "dark": 40
+          },
+          "hover-prominent": {
+            "light": 75,
+            "dark": 60
+          },
+          "hover-subtle": {
+            "light": 50,
+            "dark": 40
+          }
+        },
+        "generating": {
+          "default-balanced": {
+            "light": 50,
+            "dark": 40
+          },
+          "default-subtle": {
+            "light": 60,
+            "dark": 40
+          },
+          "default-prominent": {
+            "light": 50,
+            "dark": 40
+          },
+          "focus": {
+            "light": 40,
+            "dark": 50
+          },
+          "inner-shadow": {
+            "value": 100
+          }
+        }
+      },
+      "con-hue": {
+        "generating": {
+          "default-balanced": {
+            "value": 50
+          },
+          "default-prominent": {
+            "value": 75
+          },
+          "default-subtle": {
+            "value": 20
+          },
+          "hover-balanced": {
+            "value": 100
+          },
+          "hover-prominent": {
+            "value": 100
+          },
+          "hover-subtle": {
+            "value": 75
+          }
+        },
+        "idle": {
+          "default-balanced": {
+            "value": 12.5
+          },
+          "default-prominent": {
+            "value": 75
+          },
+          "default-subtle": {
+            "value": 40
+          },
+          "hover-balanced": {
+            "value": 20
+          },
+          "hover-prominent": {
+            "value": 100
+          },
+          "hover-subtle": {
+            "value": 12.5
+          }
+        }
+      },
+      "gradient-bg": {
+        "generating": {
+          "default-balanced": {
+            "value": 30
+          },
+          "default-prominent": {
+            "value": 50
+          },
+          "default-subtle": {
+            "value": 30
+          },
+          "hover-balanced": {
+            "light": 40,
+            "dark": 50
+          },
+          "hover-prominent": {
+            "value": 75
+          },
+          "hover-subtle": {
+            "value": 40
+          }
+        },
+        "idle": {
+          "default-balanced": {
+            "value": 30
+          },
+          "default-prominent": {
+            "value": 40
+          },
+          "default-subtle": {
+            "value": 20
+          },
+          "hover-balanced": {
+            "light": 30,
+            "dark": 40
+          },
+          "hover-subtle": {
+            "value": 30
+          },
+          "hover-prominent": {
+            "value": 50
+          }
+        }
+      },
+      "con-bg": {
+        "generating": {
+          "default-balanced": {
+            "light": 50,
+            "dark": 50
+          },
+          "default-subtle": {
+            "light": 20,
+            "dark": 20
+          },
+          "default-prominent": {
+            "light": 100,
+            "dark": 75
+          },
+          "hover-balanced": {
+            "light": 75,
+            "dark": 75
+          },
+          "hover-subtle": {
+            "light": 20,
+            "dark": 20
+          },
+          "hover-prominent": {
+            "light": 100,
+            "dark": 100
+          }
+        },
+        "idle": {
+          "default-balanced": {
+            "light": 12.5,
+            "dark": 20
+          },
+          "default-prominent": {
+            "light": 30,
+            "dark": 20
+          },
+          "default-subtle": {
+            "light": 12.5,
+            "dark": 20
+          },
+          "hover-balanced": {
+            "light": 30,
+            "dark": 40
+          },
+          "hover-prominent": {
+            "light": 30,
+            "dark": 40
+          },
+          "hover-subtle": {
+            "light": 30,
+            "dark": 40
+          }
+        }
+      },
+      "con-bg-inner-shadow": {
+        "generating": {
+          "default": {
+            "value": 50
+          }
+        },
+        "idle": {
+          "default": {
+            "value": 50
+          }
+        }
+      }
+    },
+    "border": {
+      "default": {
+        "light": "rgba(236, 105, 255, 0.1)",
+        "dark": "rgba(255, 255, 255, 0.05)"
+      },
+      "focus": {
+        "light": "rgba(0, 0, 0, 0.05)",
+        "dark": "rgba(255, 255, 255, 0.05)"
+      }
+    },
+    "gradient": {
+      "con-bg": {
+        "idle": {
+          "stop-1": {
+            "light": "rgb(235, 238, 255)",
+            "dark": "rgb(0, 0, 0)"
+          },
+          "stop-2": {
+            "light": "rgb(250, 211, 255)",
+            "dark": "rgb(30, 0, 93)"
+          },
+          "stop-3": {
+            "light": "rgb(255, 235, 232)",
+            "dark": "rgb(50, 0, 61)"
+          },
+          "stop-4": {
+            "light": "rgb(255, 236, 207)",
+            "dark": "rgb(54, 10, 3)"
+          }
+        },
+        "generating": {
+          "stop-1": {
+            "light": "rgb(216, 222, 255)",
+            "dark": "rgb(0, 0, 0)"
+          },
+          "stop-2": {
+            "light": "rgb(253, 233, 255)",
+            "dark": "rgb(35, 0, 110)"
+          },
+          "stop-3": {
+            "light": "rgb(255, 236, 207)",
+            "dark": "rgb(68, 13, 5)"
+          },
+          "stop-4": {
+            "light": "rgb(247, 181, 255)",
+            "dark": "rgb(102, 9, 120)"
+          }
+        }
+      },
+      "con-hue": {
+        "generating": {
+          "stop-1": {
+            "light": "rgb(253, 233, 255)",
+            "dark": "rgb(64, 0, 122)"
+          },
+          "stop-2": {
+            "light": "rgb(254, 246, 255)",
+            "dark": "rgb(127, 23, 146)"
+          },
+          "stop-3": {
+            "light": "rgb(255, 232, 240)",
+            "dark": "rgb(181, 19, 76)"
+          }
+        }
+      }
+    },
+    "color": {
+      "inner-shadow": {
+        "generating": {
+          "light": "rgb(254, 246, 255)",
+          "dark": "rgb(127, 23, 146)"
+        }
+      }
+    }
+  },
+  "outer-border": {
+    "gradient": {
+      "ob-spread-shadow": {
+        "generating": {
+          "stop-1": {
+            "light": "rgb(253, 233, 255)",
+            "dark": "rgb(30, 0, 93)"
+          },
+          "stop-2": {
+            "light": "rgb(250, 211, 255)",
+            "dark": "rgb(61, 0, 74)"
+          },
+          "stop-3": {
+            "light": "rgb(255, 185, 208)",
+            "dark": "rgb(74, 0, 27)"
+          }
+        }
+      },
+      "ob-border": {
+        "stop-1": {
+          "light": "rgb(255, 255, 255)",
+          "dark": "rgba(255, 255, 255, 0.02)"
+        },
+        "stop-2": {
+          "light": "rgba(255, 255, 255, 0.51)",
+          "dark": "rgba(255, 255, 255, 0.03)"
+        },
+        "focus": {
+          "stop-1": {
+            "light": "rgba(255, 255, 255, 0.51)",
+            "dark": "rgba(133, 133, 133, 0.04)"
+          },
+          "stop-2": {
+            "light": "rgba(255, 255, 255, 0.51)",
+            "dark": "rgba(133, 133, 133, 0.05)"
+          }
+        }
+      },
+      "ob-hue": {
+        "stop-1": {
+          "light": "rgba(236, 105, 255, 0.6)",
+          "dark": null
+        },
+        "stop-2": {
+          "light": "rgba(255, 81, 61, 0.5)",
+          "dark": null
+        },
+        "stop-3": {
+          "light": "rgba(255, 162, 19, 0.4)",
+          "dark": null
+        }
+      }
+    },
+    "color": {
+      "drop-shadow": {
+        "ob-border": {
+          "default": {
+            "light": "rgba(236, 105, 255, 0.1)",
+            "dark": "rgba(213, 73, 235, 0)"
+          },
+          "subtle": {
+            "light": "rgba(0, 0, 0, 0.05)",
+            "dark": "rgba(0, 0, 0, 0.1)"
+          },
+          "focus": {
+            "light": "rgba(0, 0, 0, 0.05)",
+            "dark": "rgba(0, 0, 0, 0.03)"
+          }
+        }
+      }
+    },
+    "opacity": {
+      "spread-bg-balanced": {
+        "value": 50
+      },
+      "spread-bg-prominent": {
+        "value": 50
+      },
+      "spread-bg-subtle": {
+        "value": 30
+      },
+      "spread-gradient": {
+        "value": 50
+      },
+      "border-gradient": {
+        "value": 100
+      },
+      "border-generating": {
+        "value": 30
+      },
+      "ob-hue-balanced": {
+        "light": 30,
+        "dark": 0
+      },
+      "ob-hue-subtle": {
+        "light": 20,
+        "dark": 0
+      },
+      "ob-hue-prominent": {
+        "value": 40
+      }
+    }
+  },
+  "outline-glow": {
+    "gradient": {
+      "generating": {
+        "stop-1": {
+          "light": "rgb(254, 246, 255)",
+          "dark": "rgb(50, 0, 61)"
+        },
+        "stop-2": {
+          "light": "rgb(253, 233, 255)",
+          "dark": "rgb(61, 0, 74)"
+        },
+        "stop-3": {
+          "light": "rgb(247, 181, 255)",
+          "dark": "rgb(102, 9, 120)"
+        }
+      }
+    }
+  }
+}
diff --git a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
index 4c838a12e1f..5db564e3d4e 100644
--- a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
@@ -170,7 +170,7 @@ interface UploadState {
   progress?: number;
 }
 
-export const Everything = () => {
+export const Everything = args => {
   let [attachmentState, setAttachmentState] = useState<Map<string, UploadState>>(new Map());
 
   let mockUpload = async (id: string) => {
@@ -194,6 +194,7 @@ export const Everything = () => {
 
   return (
     <PromptField
+      {...args}
       acceptedAttachmentTypes={['image/*']}
       onAddAttachments={attachments => {
         setAttachmentState(prev => {

From 4152303dbf056b87818d1104157b5a44f6db05e4 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 18 Jun 2026 20:17:36 -0700
Subject: [PATCH 02/34] fix tests

---
 packages/@react-spectrum/ai/src/tokens.macro.ts | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/tokens.macro.ts b/packages/@react-spectrum/ai/src/tokens.macro.ts
index 6c6d839c5b2..ca7e6d839b7 100644
--- a/packages/@react-spectrum/ai/src/tokens.macro.ts
+++ b/packages/@react-spectrum/ai/src/tokens.macro.ts
@@ -40,11 +40,13 @@ export function stop(gray: string, stop: string, opacity: string) {
   return `light-dark(${mix('white', stop + '.light', opacity + '.light')}, ${mix(color('gray-75'), stop + '.dark', opacity + '.dark')})`;
 }
 
-export function defineProperties(css: string) {
-  this.addAsset({
-    type: 'css',
-    content: css
-  });
+export function defineProperties(this: any, css: string) {
+  if (this && typeof this.addAsset === 'function') {
+    this.addAsset({
+      type: 'css',
+      content: css
+    });
+  }
 }
 
 export function stops(generating: string, state: string, variant: string) {

From ff6e872cb11c6db0fd0c485b63752d1279dedd5e Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 19 Jun 2026 09:35:36 -0700
Subject: [PATCH 03/34] fix: use os.tmpdir() for docgen socket when project
 path is too long

macOS limits Unix domain socket paths to 104 characters. Deep paths (e.g.
git worktrees inside .claude/worktrees/) push the project-relative socket
path over that limit, causing EINVAL on server.listen(). Fall back to
os.tmpdir() when the path would exceed the limit.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../react-docgen-typescript.ts                   | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts b/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts
index ba7bd5b5f80..cf5e293b1a5 100644
--- a/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts
+++ b/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts
@@ -1,3 +1,4 @@
+import os from 'os';
 import path from 'path';
 import ts from 'typescript';
 import {ComponentDoc, Parser} from 'react-docgen-typescript';
@@ -9,10 +10,19 @@ export function getCacheDir(options: PluginOptions) {
   return path.join(options.projectRoot, 'node_modules', '.cache', 'docgen');
 }
 
+// macOS limits Unix socket paths to 104 characters. Use os.tmpdir() for the
+// socket when the project-relative path would exceed that.
+const UNIX_SOCKET_MAX = 104;
+
 function getSocketPath(options: PluginOptions) {
-  return process.platform === 'win32'
-    ? path.join('\\\\?\\pipe', getCacheDir(options), options.instanceId)
-    : path.join(getCacheDir(options), options.instanceId);
+  if (process.platform === 'win32') {
+    return path.join('\\\\?\\pipe', getCacheDir(options), options.instanceId);
+  }
+  let sock = path.join(getCacheDir(options), options.instanceId);
+  if (sock.length > UNIX_SOCKET_MAX) {
+    sock = path.join(os.tmpdir(), 'parcel-docgen-' + options.instanceId);
+  }
+  return sock;
 }
 
 // TypeScript is single threaded, but Parcel is multi-threaded.

From 2403e410e2a9029146403d77187c6f55155caff1 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 19 Jun 2026 16:55:52 -0700
Subject: [PATCH 04/34] light mode styles

---
 .../ai/src/PromptFieldContainer.tsx           | 179 +++++++++++-------
 .../@react-spectrum/ai/src/tokens.macro.ts    |  50 +++--
 .../@react-spectrum/ai/src/tokens.merged.json |   6 +-
 3 files changed, 152 insertions(+), 83 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
index f3bd525b18e..b0fe75625cf 100644
--- a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -1,5 +1,10 @@
 import {color, css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
-import {defineProperties, stops, token} from './tokens.macro' with {type: 'macro'};
+import {
+  defineProperties,
+  outerBorderStops,
+  stops,
+  token
+} from './tokens.macro' with {type: 'macro'};
 import {getEventTarget} from 'react-aria/private/utils/shadowdom/DOMFunctions';
 import {Group, GroupProps} from 'react-aria-components/Group';
 import {isFocusable} from 'react-aria/private/utils/isFocusable';
@@ -14,25 +19,25 @@ defineProperties(`
     inherits: false;
   }
 
-  @property --con-bg-stop-1 {
+  @property --bg-stop-1 {
     syntax: '<color>';
     initial-value: #0000;
     inherits: false;
   }
 
-  @property --con-bg-stop-2 {
+  @property --bg-stop-2 {
     syntax: '<color>';
     initial-value: #0000;
     inherits: false;  
   }
 
-  @property --con-bg-stop-3 {
+  @property --bg-stop-3 {
     syntax: '<color>';
     initial-value: #0000;
     inherits: false;
   }
 
-  @property --con-bg-stop-4 {
+  @property --bg-stop-4 {
     syntax: '<color>';
     initial-value: #0000;
     inherits: false;
@@ -40,13 +45,13 @@ defineProperties(`
 `);
 
 const containerBackground = css(`
-  transition: --con-hue-opacity ${STATE_TRANSITION}, --con-bg-stop-1 ${STATE_TRANSITION}, --con-bg-stop-2 ${STATE_TRANSITION}, --con-bg-stop-3 ${STATE_TRANSITION}, --con-bg-stop-4 ${STATE_TRANSITION}, box-shadow ${STATE_TRANSITION};
+  transition: --con-hue-opacity ${STATE_TRANSITION}, --bg-stop-1 ${STATE_TRANSITION}, --bg-stop-2 ${STATE_TRANSITION}, --bg-stop-3 ${STATE_TRANSITION}, --bg-stop-4 ${STATE_TRANSITION}, box-shadow ${STATE_TRANSITION};
   
   background:
     linear-gradient(
       to bottom,
-      light-dark(rgb(255 255 255 / 40%), rgb(0 0 0 / 40%)), 37%,
-      light-dark(rgb(255 255 255 / 12%), rgb(0 0 0 / 12%)) 83%
+      light-dark(rgb(255 255 255 / 75%), rgb(0 0 0 / 40%)) 0% 37%,
+      light-dark(rgb(255 255 255 / 15%), rgb(0 0 0 / 12%)) 83% 100%
     ),
     radial-gradient(
       50% 50% at -20% 100%,
@@ -65,43 +70,23 @@ const containerBackground = css(`
     ),
     radial-gradient(
       circle at right bottom,
-      var(--con-bg-stop-1) 0%,
-      var(--con-bg-stop-2) 35%,
-      var(--con-bg-stop-3) 82%,
-      var(--con-bg-stop-4) 100%
+      var(--bg-stop-1) 0%,
+      var(--bg-stop-2) 35%,
+      var(--bg-stop-3) 82%,
+      var(--bg-stop-4) 100%
     );
 
   --border-color: ${token(`container.border.default`)};
   --inset-shadow-color: ${color('transparent-white-50')};
   --drop-shadow-color: ${color('fuchsia-900/5')};
-  --outer-border-color: ${token('outer-border.gradient.ob-border.stop-1')};
-  
+
   box-shadow:
     inset 0 0 0 1px var(--border-color),
     inset 0 6px 15px 0 var(--inset-shadow-color),
+    inset 0 0 0 0 transparent, /* placeholder for generating state so transition is smooth */
     inset 0 -5px 21.6px 0 ${color('transparent-white-50')},
     inset 0 24px 32px 0 ${color('transparent-white-50')},
-    0 -3px 10px 1px var(--drop-shadow-color),
-    0 0 0 6px var(--outer-border-color),
-    0 6px 16px -6px var(--outer-border-hue);
-
-  &[data-variant=balanced] {
-    --outer-border-hue: light-dark(
-      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-balanced.light')}%),
-      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-balanced.dark')}%)
-    );
-  }
-  
-  &[data-variant=prominent] {
-    --outer-border-hue: rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-prominent')}%);
-  }
-
-  &[data-variant=subtle] {
-    --outer-border-hue: light-dark(
-      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-subtle.light')}%),
-      rgb(from ${token('outer-border.gradient.ob-hue.stop-1')} r g b / ${token('outer-border.opacity.ob-hue-subtle.dark')}%)
-    );
-  }
+    0 -3px 10px 1px var(--drop-shadow-color);
 
   &[data-state=idle] {
     &[data-variant=balanced] {
@@ -122,28 +107,27 @@ const containerBackground = css(`
 
     &[data-variant=subtle] {
       --con-hue-opacity: 0%;
-      --con-bg-stop-1: light-dark(white, ${color('gray-75')});
-      --con-bg-stop-2: light-dark(white, ${color('gray-75')});
-      --con-bg-stop-3: light-dark(white, ${color('gray-75')});
-      --con-bg-stop-4: light-dark(white, ${color('gray-75')});
+      --bg-stop-1: light-dark(white, ${color('gray-75')});
+      --bg-stop-2: light-dark(white, ${color('gray-75')});
+      --bg-stop-3: light-dark(white, ${color('gray-75')});
+      --bg-stop-4: light-dark(white, ${color('gray-75')});
+      --border-color: ${token(`container.border.focus`)};
 
       &[data-hovered] {
         ${stops('idle', 'hover', 'subtle')}
+        --border-color: ${token(`container.border.default`)};
       }
     }
 
     &[data-focus-within][data-focus-within] {
       --con-hue-opacity: 0%;
-      --con-bg-stop-1: light-dark(white, ${color('gray-75')});
-      --con-bg-stop-2: light-dark(white, ${color('gray-75')});
-      --con-bg-stop-3: light-dark(white, ${color('gray-75')});
-      --con-bg-stop-4: light-dark(white, ${color('gray-75')});
-
+      --bg-stop-1: light-dark(white, ${color('gray-75')});
+      --bg-stop-2: light-dark(white, ${color('gray-75')});
+      --bg-stop-3: light-dark(white, ${color('gray-75')});
+      --bg-stop-4: light-dark(white, ${color('gray-75')});
       --border-color: ${token(`container.border.focus`)};
       --inset-shadow-color: transparent;
       --drop-shadow-color: transparent;
-      --outer-border-color: ${token('outer-border.gradient.ob-border.focus.stop-1')};
-      --outer-border-hue: transparent;
     }
   }
 
@@ -155,11 +139,10 @@ const containerBackground = css(`
       inset 0 -5px 21.6px 0 ${color('transparent-white-50')},
       inset 0 24px 32px 0 ${color('transparent-white-50')},
       0 -3px 10px 1px var(--drop-shadow-color),
-      0 6px 16px -6px var(--outer-border-hue),
-      0 6px 83px rgb(from ${token('outer-border.gradient.ob-spread-shadow.generating.stop-3')} r g b / ${token('outer-border.opacity.spread-bg-balanced')}%),
-      0 0 0 6px var(--outer-border-color);
+      0 6px 83px rgb(from ${token('outer-border.gradient.ob-spread-shadow.generating.stop-3')} r g b / var(--spread-shadow-opacity));
 
     &[data-variant=balanced] {
+      --spread-shadow-opacity: ${token('outer-border.opacity.spread-bg-balanced')}%;
       ${stops('generating', 'default', 'balanced')}
 
       &[data-hovered] {
@@ -168,6 +151,7 @@ const containerBackground = css(`
     }
 
     &[data-variant=prominent] {
+      --spread-shadow-opacity: ${token('outer-border.opacity.spread-bg-prominent')}%;
       ${stops('generating', 'default', 'prominent')}
 
       &[data-hovered] {
@@ -176,6 +160,7 @@ const containerBackground = css(`
     }
 
     &[data-variant=subtle] {
+      --spread-shadow-opacity: ${token('outer-border.opacity.spread-bg-subtle')}%;
       ${stops('generating', 'default', 'subtle')}
 
       &[data-hovered] {
@@ -185,6 +170,59 @@ const containerBackground = css(`
   }
 `);
 
+const outerBorder = css(`
+  --outer-drop-shadow-color: ${token('outer-border.color.drop-shadow.ob-border.default')};
+
+  padding: 6px;
+  border-radius: calc(24px + 6px);
+  transition: --bg-stop-1 ${STATE_TRANSITION}, --bg-stop-2 ${STATE_TRANSITION}, --bg-stop-3 ${STATE_TRANSITION}, box-shadow ${STATE_TRANSITION};
+  background: linear-gradient(
+    to right,
+    var(--bg-stop-1) 0%,
+    var(--bg-stop-2) 37%,
+    var(--bg-stop-3) 77%
+  );
+
+  box-shadow:
+    0 2px 4px var(--outer-drop-shadow-color),
+    0 6px 16px -10px var(--outer-border-hue);
+
+  &[data-variant=balanced] {
+    ${outerBorderStops('balanced')}
+  }
+  
+  &[data-variant=prominent] {
+    ${outerBorderStops('prominent')}
+
+    &[data-state=idle][data-focus-within] {
+      --bg-stop-1: ${token('outer-border.gradient.ob-border.stop-1')};
+      --bg-stop-2: ${token('outer-border.gradient.ob-border.stop-1')};
+      --bg-stop-3: ${token('outer-border.gradient.ob-border.stop-1')};
+    }
+  }
+
+  &[data-variant=subtle] {
+    --outer-drop-shadow-color: ${token('outer-border.color.drop-shadow.ob-border.subtle')};
+    --outer-border-hue: transparent;
+    --bg-stop-1: ${token('outer-border.gradient.ob-border.stop-1')};
+    --bg-stop-2: ${token('outer-border.gradient.ob-border.stop-1')};
+    --bg-stop-3: ${token('outer-border.gradient.ob-border.stop-1')};
+
+    &[data-hovered] {
+      --outer-drop-shadow-color: ${token('outer-border.color.drop-shadow.ob-border.default')};
+      ${outerBorderStops('subtle')}
+    }
+  }
+
+  &[data-state=idle][data-focus-within] {
+    --bg-stop-1: ${token('outer-border.gradient.ob-border.stop-1')};
+    --bg-stop-2: ${token('outer-border.gradient.ob-border.stop-1')};
+    --bg-stop-3: ${token('outer-border.gradient.ob-border.stop-1')};
+    --outer-border-hue: transparent;
+    --outer-drop-shadow-color: ${token('outer-border.color.drop-shadow.ob-border.focus')};
+  }
+`);
+
 interface PropFieldContainerProps extends GroupProps {
   variant: 'balanced' | 'prominent' | 'subtle';
   isGenerating: boolean;
@@ -200,22 +238,7 @@ export function PromptFieldContainer(props: PropFieldContainerProps) {
       role="group"
       data-variant={variant}
       data-state={isGenerating ? 'generating' : 'idle'}
-      className={
-        (props.className || '') +
-        ' ' +
-        containerBackground +
-        mergeStyles(
-          style({
-            display: 'flex',
-            flexDirection: 'column',
-            gap: 16,
-            padding: 16,
-            cursor: 'text',
-            borderRadius: '[24px]'
-          }),
-          styles
-        )
-      }
+      className={outerBorder}
       onPointerDown={e => {
         // If not clicking on something focusable within the prompt field, focus the input.
         let target = getEventTarget(e) as Element | null;
@@ -228,7 +251,31 @@ export function PromptFieldContainer(props: PropFieldContainerProps) {
           inputRef.current?.focus();
         }
       }}>
-      {props.children}
+      {({isHovered, isFocusWithin}) => (
+        <div
+          data-hovered={isHovered || undefined}
+          data-focus-within={isFocusWithin || undefined}
+          data-variant={variant}
+          data-state={isGenerating ? 'generating' : 'idle'}
+          className={
+            (props.className || '') +
+            ' ' +
+            containerBackground +
+            mergeStyles(
+              style({
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 16,
+                padding: 16,
+                cursor: 'text',
+                borderRadius: '[24px]'
+              }),
+              styles
+            )
+          }>
+          {props.children}
+        </div>
+      )}
     </Group>
   );
 }
diff --git a/packages/@react-spectrum/ai/src/tokens.macro.ts b/packages/@react-spectrum/ai/src/tokens.macro.ts
index ca7e6d839b7..dce27ced150 100644
--- a/packages/@react-spectrum/ai/src/tokens.macro.ts
+++ b/packages/@react-spectrum/ai/src/tokens.macro.ts
@@ -20,16 +20,6 @@ export function token(name: string) {
   }
 }
 
-export function alphaToGrayscale(name: string) {
-  let token = name.split('.').reduce((acc, curr) => acc[curr], tokens) as any;
-  let match = token.match(/^rgba\((.+?),\s*(.+?),\s*(.+?),\s*(.+?)\)$/);
-  if (match && match[1] === match[2] && match[2] === match[3]) {
-    return [`rgb(${match[1]}, ${match[2]}, ${match[3]})`, Number(match[4]) * 100];
-  } else {
-    return token;
-  }
-}
-
 export function mix(gray: string, stop: string, opacity: string) {
   let stopColor = token(stop);
   let stopOpacity = token(opacity);
@@ -52,9 +42,41 @@ export function defineProperties(this: any, css: string) {
 export function stops(generating: string, state: string, variant: string) {
   return `
     --con-hue-opacity: ${token(`container.opacity.con-hue.${generating}.${state}-${variant}`)}%;
-    --con-bg-stop-1: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-1`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
-    --con-bg-stop-2: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-2`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
-    --con-bg-stop-3: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-3`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
-    --con-bg-stop-4: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-4`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+    --bg-stop-1: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-1`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+    --bg-stop-2: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-2`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+    --bg-stop-3: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-3`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
+    --bg-stop-4: ${stop('container.bg.default', `container.gradient.con-bg.${generating}.stop-4`, `container.opacity.con-bg.${generating}.${state}-${variant}`)};
   `;
 }
+
+export function outerBorderStops(variant: string) {
+  let border = token('outer-border.gradient.ob-border.stop-1');
+  return `
+    --outer-border-hue: light-dark(
+      ${outerBorderStop(2, variant, 'light', 1)},
+      ${outerBorderStop(2, variant, 'dark', 1)}
+    );
+    --bg-stop-1: light-dark(
+      ${outerBorderStop(1, variant, 'light')},
+      ${variant === 'prominent' ? outerBorderStop(1, variant, 'dark') : border}
+    );
+    --bg-stop-2: light-dark(
+      ${outerBorderStop(2, variant, 'light')},
+      ${variant === 'prominent' ? outerBorderStop(2, variant, 'dark') : border}
+    );
+    --bg-stop-3: light-dark(
+      ${outerBorderStop(3, variant, 'light')},
+      ${variant === 'prominent' ? outerBorderStop(3, variant, 'dark') : border}
+    );
+  `;
+}
+
+function outerBorderStop(stop: number, variant: string, colorScheme: string, div = 10) {
+  let opacity = token(
+    `outer-border.opacity.ob-hue-${variant}.${variant === 'prominent' ? 'value' : colorScheme}`
+  );
+  if (colorScheme === 'light') {
+    opacity = opacity / div;
+  }
+  return `rgb(from ${token(`outer-border.gradient.ob-hue.stop-${stop}.${colorScheme}`)} r g b / ${opacity}%)`;
+}
diff --git a/packages/@react-spectrum/ai/src/tokens.merged.json b/packages/@react-spectrum/ai/src/tokens.merged.json
index 8573375c5c1..0b4c61302a0 100644
--- a/packages/@react-spectrum/ai/src/tokens.merged.json
+++ b/packages/@react-spectrum/ai/src/tokens.merged.json
@@ -358,15 +358,15 @@
       "ob-hue": {
         "stop-1": {
           "light": "rgba(236, 105, 255, 0.6)",
-          "dark": null
+          "dark": "rgb(50, 0, 61)"
         },
         "stop-2": {
           "light": "rgba(255, 81, 61, 0.5)",
-          "dark": null
+          "dark": "rgb(30, 0, 93)"
         },
         "stop-3": {
           "light": "rgba(255, 162, 19, 0.4)",
-          "dark": null
+          "dark": "rgb(30, 0, 93)"
         }
       }
     },

From 20cbb3b887f5bd6a2e52beed5c6d41707ebfd4fe Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 19 Jun 2026 17:03:54 -0700
Subject: [PATCH 05/34] tsc

---
 packages/@react-spectrum/ai/src/PromptFieldContainer.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
index b0fe75625cf..31c2cd545dc 100644
--- a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -223,7 +223,8 @@ const outerBorder = css(`
   }
 `);
 
-interface PropFieldContainerProps extends GroupProps {
+interface PropFieldContainerProps extends Omit<GroupProps, 'children'> {
+  children: React.ReactNode;
   variant: 'balanced' | 'prominent' | 'subtle';
   isGenerating: boolean;
   styles?: StyleString;

From 3f49db46dcf3e18c0b921ecd64c10cefbdab3c8f Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 19 Jun 2026 22:41:05 -0700
Subject: [PATCH 06/34] wip: loader animation

---
 .../@react-spectrum/ai/src/PromptField.tsx    | 142 +--
 .../@react-spectrum/ai/src/loader/data.ts     | 841 ++++++++++++++++++
 .../@react-spectrum/ai/src/loader/react.tsx   | 259 ++++++
 .../@react-spectrum/ai/src/loader/runtime.ts  | 137 +++
 4 files changed, 1316 insertions(+), 63 deletions(-)
 create mode 100644 packages/@react-spectrum/ai/src/loader/data.ts
 create mode 100644 packages/@react-spectrum/ai/src/loader/react.tsx
 create mode 100644 packages/@react-spectrum/ai/src/loader/runtime.ts

diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index 1c15abdcb0a..a1dc8ca36ab 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -47,6 +47,7 @@ import {PromptFocusContext} from './Chat';
 import Send from '@react-spectrum/s2/icons/ArrowUpSend';
 import Stop from '@react-spectrum/s2/icons/StopProcessing';
 import {useFocusWithin} from 'react-aria/useFocusWithin';
+import {PixelLoader} from './loader/react';
 
 export interface PromptFieldAttachment {
   id: string;
@@ -274,7 +275,8 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
     setAttachments,
     onAddAttachments,
     inputRef,
-    onSubmit
+    onSubmit,
+    isGenerating
   } = useContext(PromptFieldContext);
   let [isFocused, setFocused] = useState(false);
 
@@ -298,71 +300,85 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
   }, [filterValue, renderCompletions]);
 
   return (
-    <Autocomplete>
-      <TokenField
-        value={prompt}
-        onChange={setPrompt}
-        multiline
-        aria-label="Prompt"
-        data-placeholder="Ready to get started? Ask a question, share an idea, or add a task."
-        ref={inputRef}
-        onFocus={e => {
-          if (e.isTrusted) {
-            setFocused(true);
-          }
-        }}
-        onBlur={e => {
-          if (e.isTrusted) {
-            setFocused(false);
-          }
-        }}
-        onPaste={
-          acceptedAttachmentTypes
-            ? e => {
-                let clipboardData = e.clipboardData as DataTransfer;
-                let attachments: PromptFieldAttachment[] = [];
-                for (let item of clipboardData.items) {
-                  if (matchMimeType(item.type, acceptedAttachmentTypes)) {
-                    let file = item.getAsFile()!;
-                    attachments.push({
-                      id: crypto.randomUUID(),
-                      file,
-                      image: file.type.startsWith('image/') ? URL.createObjectURL(file) : ''
-                    });
+    <div
+      className={style({
+        display: 'flex',
+        gap: 12,
+        alignItems: 'baseline',
+        color: 'body',
+        paddingStart: 4,
+        width: 'full'
+      })}>
+      <CenterBaseline>
+        <PixelLoader size={24} playing={isGenerating} preset="exp" />
+      </CenterBaseline>
+      <Autocomplete>
+        <TokenField
+          value={prompt}
+          onChange={setPrompt}
+          multiline
+          aria-label="Prompt"
+          data-placeholder="Ready to get started? Ask a question, share an idea, or add a task."
+          ref={inputRef}
+          onFocus={e => {
+            if (e.isTrusted) {
+              setFocused(true);
+            }
+          }}
+          onBlur={e => {
+            if (e.isTrusted) {
+              setFocused(false);
+            }
+          }}
+          onPaste={
+            acceptedAttachmentTypes
+              ? e => {
+                  let clipboardData = e.clipboardData as DataTransfer;
+                  let attachments: PromptFieldAttachment[] = [];
+                  for (let item of clipboardData.items) {
+                    if (matchMimeType(item.type, acceptedAttachmentTypes)) {
+                      let file = item.getAsFile()!;
+                      attachments.push({
+                        id: crypto.randomUUID(),
+                        file,
+                        image: file.type.startsWith('image/') ? URL.createObjectURL(file) : ''
+                      });
+                    }
+                  }
+                  if (attachments.length > 0) {
+                    onAddAttachments?.(attachments);
+                    setAttachments(prev => [...prev, ...attachments]);
                   }
                 }
-                if (attachments.length > 0) {
-                  onAddAttachments?.(attachments);
-                  setAttachments(prev => [...prev, ...attachments]);
+              : undefined
+          }
+          onSubmit={onSubmit}
+          className={
+            css('&:empty::before { content: attr(data-placeholder); }') +
+            style({
+              flexGrow: 1,
+              font: 'body',
+              color: {
+                default: 'gray-800',
+                ':empty': {
+                  default: 'transparent-overlay-600',
+                  forcedColors: 'GrayText'
                 }
-              }
-            : undefined
-        }
-        onSubmit={onSubmit}
-        className={
-          css('&:empty::before { content: attr(data-placeholder); }') +
-          style({
-            font: 'body',
-            color: {
-              default: 'gray-800',
-              ':empty': {
-                default: 'transparent-overlay-600',
-                forcedColors: 'GrayText'
-              }
-            },
-            width: 'full',
-            outlineStyle: 'none',
-            cursor: 'text'
-          })
-        }>
-        {children || (segment => <PromptToken>{segment.text}</PromptToken>)}
-      </TokenField>
-      <PromptTokenFieldPopover
-        filterAnchor={filterAnchor}
-        items={useDeferredValue(items)}
-        isFocused={isFocused}
-      />
-    </Autocomplete>
+              },
+              width: 'full',
+              outlineStyle: 'none',
+              cursor: 'text'
+            })
+          }>
+          {children || (segment => <PromptToken>{segment.text}</PromptToken>)}
+        </TokenField>
+        <PromptTokenFieldPopover
+          filterAnchor={filterAnchor}
+          items={useDeferredValue(items)}
+          isFocused={isFocused}
+        />
+      </Autocomplete>
+    </div>
   );
 }
 
diff --git a/packages/@react-spectrum/ai/src/loader/data.ts b/packages/@react-spectrum/ai/src/loader/data.ts
new file mode 100644
index 00000000000..8a4f41e2b31
--- /dev/null
+++ b/packages/@react-spectrum/ai/src/loader/data.ts
@@ -0,0 +1,841 @@
+// Loader cell-position data, ported from
+// experiments/pixel-fall-animation/index.html.
+//
+// Each cell:
+//   { cx, cy, outer, stagger, exitStart, fadeIn, fadeOut }
+// Coordinates are in the source Lottie's 1000×1000 canvas.
+
+// ─────────────────────────────────────────────────────────────
+// ai-logo: original 12-cell diamond layout with hand-tuned timings.
+// ─────────────────────────────────────────────────────────────
+export const aiLogoCells = [
+  {cx: 500, cy: 800, outer: true, stagger: 0, exitStart: 47, fadeIn: [1, 4], fadeOut: [47, 59]},
+  {cx: 300, cy: 700, outer: true, stagger: 2, exitStart: 48, fadeIn: [4, 7], fadeOut: [48, 60]},
+  {cx: 700, cy: 700, outer: true, stagger: 4, exitStart: 49, fadeIn: [6, 9], fadeOut: [49, 61]},
+  {cx: 400, cy: 600, outer: false, stagger: 6, exitStart: 50, fadeIn: [9, 12], fadeOut: [50, 62]},
+  {cx: 600, cy: 600, outer: false, stagger: 8, exitStart: 51, fadeIn: [13, 16], fadeOut: [51, 63]},
+  {cx: 200, cy: 500, outer: true, stagger: 10, exitStart: 52, fadeIn: [14, 17], fadeOut: [52, 64]},
+  {cx: 800, cy: 500, outer: true, stagger: 14, exitStart: 54, fadeIn: [18, 21], fadeOut: [54, 66]},
+  {cx: 400, cy: 400, outer: false, stagger: 16, exitStart: 55, fadeIn: [21, 24], fadeOut: [55, 67]},
+  {cx: 600, cy: 400, outer: false, stagger: 18, exitStart: 56, fadeIn: [23, 26], fadeOut: [56, 68]},
+  {cx: 300, cy: 300, outer: true, stagger: 20, exitStart: 57, fadeIn: [26, 29], fadeOut: [57, 69]},
+  {cx: 700, cy: 300, outer: true, stagger: 22, exitStart: 58, fadeIn: [27, 30], fadeOut: [58, 70]},
+  {cx: 500, cy: 200, outer: true, stagger: 24, exitStart: 59, fadeIn: [31, 34], fadeOut: [59, 71]}
+];
+
+// ─────────────────────────────────────────────────────────────
+// POSITIONS — each entry is a list of [col, row] cell coords on a
+// 7×7 grid. Bottom-up, left-to-right within row → stagger order.
+// ─────────────────────────────────────────────────────────────
+export const POSITIONS = {
+  brush: [
+    [0, 6],
+    [1, 6],
+    [2, 6],
+    [1, 5],
+    [3, 5],
+    [2, 4],
+    [3, 4],
+    [3, 3],
+    [4, 3],
+    [4, 2],
+    [5, 2],
+    [5, 1],
+    [6, 1],
+    [6, 0]
+  ],
+  eye: [
+    [2, 4],
+    [3, 4],
+    [4, 4],
+    [1, 3],
+    [3, 3],
+    [5, 3],
+    [0, 2],
+    [2, 2],
+    [3, 2],
+    [4, 2],
+    [6, 2],
+    [1, 1],
+    [2, 1],
+    [3, 1],
+    [5, 1],
+    [2, 0],
+    [3, 0],
+    [4, 0]
+  ],
+  hourglass: [
+    [0, 6],
+    [1, 6],
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [5, 6],
+    [6, 6],
+    [1, 5],
+    [2, 5],
+    [3, 5],
+    [4, 5],
+    [5, 5],
+    [1, 4],
+    [2, 4],
+    [4, 4],
+    [5, 4],
+    [2, 3],
+    [3, 3],
+    [4, 3],
+    [1, 2],
+    [2, 2],
+    [3, 2],
+    [4, 2],
+    [5, 2],
+    [1, 1],
+    [5, 1],
+    [0, 0],
+    [1, 0],
+    [2, 0],
+    [3, 0],
+    [4, 0],
+    [5, 0],
+    [6, 0]
+  ],
+  mag: [
+    [6, 6],
+    [5, 5],
+    [1, 4],
+    [2, 4],
+    [3, 4],
+    [0, 3],
+    [4, 3],
+    [0, 2],
+    [4, 2],
+    [0, 1],
+    [4, 1],
+    [1, 0],
+    [2, 0],
+    [3, 0]
+  ],
+  crop: [
+    [5, 6],
+    [1, 5],
+    [2, 5],
+    [3, 5],
+    [4, 5],
+    [5, 5],
+    [6, 5],
+    [1, 4],
+    [1, 3],
+    [5, 3],
+    [1, 2],
+    [5, 2],
+    [0, 1],
+    [1, 1],
+    [3, 1],
+    [4, 1],
+    [5, 1],
+    [1, 0]
+  ],
+  flower: [
+    [3, 6],
+    [3, 5],
+    [2, 4],
+    [4, 4],
+    [2, 3],
+    [5, 3],
+    [1, 2],
+    [4, 2],
+    [6, 2],
+    [0, 1],
+    [2, 1],
+    [5, 1],
+    [1, 0]
+  ],
+  image: [
+    [0, 6],
+    [1, 6],
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [5, 6],
+    [6, 6],
+    [0, 5],
+    [1, 5],
+    [2, 5],
+    [3, 5],
+    [4, 5],
+    [5, 5],
+    [6, 5],
+    [0, 4],
+    [1, 4],
+    [2, 4],
+    [3, 4],
+    [5, 4],
+    [6, 4],
+    [0, 3],
+    [2, 3],
+    [6, 3],
+    [0, 2],
+    [4, 2],
+    [6, 2],
+    [0, 1],
+    [6, 1],
+    [0, 0],
+    [1, 0],
+    [2, 0],
+    [3, 0],
+    [4, 0],
+    [5, 0],
+    [6, 0]
+  ],
+  lasso: [
+    [1, 6],
+    [2, 5],
+    [1, 4],
+    [2, 4],
+    [0, 3],
+    [3, 3],
+    [4, 3],
+    [5, 3],
+    [0, 2],
+    [6, 2],
+    [1, 1],
+    [6, 1],
+    [2, 0],
+    [3, 0],
+    [4, 0],
+    [5, 0]
+  ],
+  page: [
+    [0, 6],
+    [1, 6],
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [5, 6],
+    [6, 6],
+    [0, 5],
+    [6, 5],
+    [0, 4],
+    [6, 4],
+    [0, 3],
+    [3, 3],
+    [4, 3],
+    [5, 3],
+    [6, 3],
+    [0, 2],
+    [3, 2],
+    [6, 2],
+    [0, 1],
+    [3, 1],
+    [5, 1],
+    [0, 0],
+    [1, 0],
+    [2, 0],
+    [3, 0],
+    [4, 0]
+  ],
+  wand: [
+    [6, 6],
+    [5, 5],
+    [0, 4],
+    [4, 4],
+    [2, 3],
+    [1, 2],
+    [3, 2],
+    [2, 1],
+    [0, 0],
+    [4, 0]
+  ],
+  bargraph: [
+    [0, 6],
+    [2, 6],
+    [4, 6],
+    [6, 6],
+    [2, 5],
+    [4, 5],
+    [6, 5],
+    [0, 4],
+    [2, 4],
+    [4, 4],
+    [6, 4],
+    [1, 3],
+    [6, 3],
+    [2, 2],
+    [4, 2],
+    [6, 2],
+    [3, 1],
+    [5, 1],
+    [6, 0]
+  ],
+  trefoil: [
+    [0, 6],
+    [1, 6],
+    [1, 5],
+    [2, 4],
+    [3, 4],
+    [5, 4],
+    [6, 4],
+    [2, 3],
+    [4, 3],
+    [3, 2],
+    [3, 1],
+    [3, 0]
+  ],
+  dial: [
+    [0, 4],
+    [6, 4],
+    [0, 3],
+    [3, 3],
+    [6, 3],
+    [0, 2],
+    [4, 2],
+    [6, 2],
+    [1, 1],
+    [5, 1],
+    [2, 0],
+    [3, 0]
+  ],
+  folder: [
+    [0, 5],
+    [1, 5],
+    [2, 5],
+    [3, 5],
+    [4, 5],
+    [5, 5],
+    [6, 5],
+    [0, 4],
+    [6, 4],
+    [0, 3],
+    [6, 3],
+    [0, 2],
+    [6, 2],
+    [0, 1],
+    [3, 1],
+    [4, 1],
+    [5, 1],
+    [6, 1],
+    [1, 0],
+    [2, 0]
+  ],
+  arrow: [
+    [0, 4],
+    [1, 3],
+    [3, 3],
+    [2, 2],
+    [4, 2],
+    [6, 2],
+    [5, 1],
+    [6, 1],
+    [4, 0],
+    [5, 0],
+    [6, 0]
+  ],
+  cloud: [
+    [0, 4],
+    [1, 4],
+    [2, 4],
+    [3, 4],
+    [4, 4],
+    [5, 4],
+    [6, 4],
+    [0, 3],
+    [6, 3],
+    [1, 2],
+    [5, 2],
+    [1, 1],
+    [2, 1],
+    [5, 1],
+    [3, 0],
+    [4, 0]
+  ],
+  comment: [
+    [1, 6],
+    [1, 5],
+    [2, 5],
+    [1, 4],
+    [3, 4],
+    [4, 4],
+    [5, 4],
+    [0, 3],
+    [6, 3],
+    [0, 2],
+    [6, 2],
+    [0, 1],
+    [6, 1],
+    [1, 0],
+    [2, 0],
+    [3, 0],
+    [4, 0],
+    [5, 0]
+  ],
+  filter: [
+    [2, 6],
+    [3, 6],
+    [2, 5],
+    [4, 5],
+    [2, 4],
+    [4, 4],
+    [2, 3],
+    [4, 3],
+    [1, 2],
+    [5, 2],
+    [0, 1],
+    [6, 1],
+    [0, 0],
+    [1, 0],
+    [2, 0],
+    [3, 0],
+    [4, 0],
+    [5, 0],
+    [6, 0]
+  ],
+  microphone: [
+    [1, 6],
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [2, 5],
+    [3, 5],
+    [1, 4],
+    [4, 4],
+    [0, 3],
+    [1, 3],
+    [4, 3],
+    [5, 3],
+    [1, 2],
+    [4, 2],
+    [1, 1],
+    [4, 1],
+    [2, 0],
+    [3, 0]
+  ],
+  pencil: [
+    [0, 6],
+    [1, 6],
+    [2, 6],
+    [0, 5],
+    [1, 5],
+    [3, 5],
+    [0, 4],
+    [4, 4],
+    [1, 3],
+    [5, 3],
+    [2, 2],
+    [4, 2],
+    [6, 2],
+    [3, 1],
+    [6, 1],
+    [4, 0],
+    [5, 0]
+  ],
+  potion: [
+    [1, 6],
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [5, 6],
+    [0, 5],
+    [6, 5],
+    [0, 4],
+    [2, 4],
+    [6, 4],
+    [1, 3],
+    [3, 3],
+    [5, 3],
+    [2, 2],
+    [4, 2],
+    [2, 1],
+    [4, 1],
+    [1, 0],
+    [2, 0],
+    [3, 0],
+    [4, 0],
+    [5, 0]
+  ],
+  slider: [
+    [4, 5],
+    [0, 4],
+    [1, 4],
+    [2, 4],
+    [3, 4],
+    [5, 4],
+    [6, 4],
+    [4, 3],
+    [2, 2],
+    [0, 1],
+    [1, 1],
+    [3, 1],
+    [4, 1],
+    [5, 1],
+    [6, 1],
+    [2, 0]
+  ],
+  timeline: [
+    [3, 6],
+    [0, 5],
+    [1, 5],
+    [3, 5],
+    [4, 5],
+    [5, 5],
+    [6, 5],
+    [0, 4],
+    [1, 4],
+    [3, 4],
+    [4, 4],
+    [5, 4],
+    [6, 4],
+    [3, 3],
+    [2, 2],
+    [4, 2],
+    [1, 1],
+    [5, 1],
+    [1, 0],
+    [2, 0],
+    [3, 0],
+    [4, 0],
+    [5, 0]
+  ],
+  eyedrop: [
+    [0, 6],
+    [1, 6],
+    [0, 5],
+    [2, 5],
+    [1, 4],
+    [3, 4],
+    [2, 3],
+    [4, 3],
+    [6, 3],
+    [3, 2],
+    [4, 2],
+    [5, 2],
+    [4, 1],
+    [5, 1],
+    [6, 1],
+    [3, 0],
+    [5, 0],
+    [6, 0]
+  ],
+  'adobe-a': [
+    [0, 6],
+    [1, 6],
+    [2, 6],
+    [3, 6],
+    [5, 6],
+    [6, 6],
+    [1, 5],
+    [2, 5],
+    [5, 5],
+    [1, 4],
+    [2, 4],
+    [4, 4],
+    [5, 4],
+    [1, 3],
+    [2, 3],
+    [4, 3],
+    [5, 3],
+    [2, 2],
+    [3, 2],
+    [4, 2],
+    [2, 1],
+    [3, 1],
+    [4, 1]
+  ],
+  'adobe-d': [
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [5, 6],
+    [1, 5],
+    [2, 5],
+    [4, 5],
+    [5, 5],
+    [1, 4],
+    [2, 4],
+    [4, 4],
+    [5, 4],
+    [1, 3],
+    [2, 3],
+    [4, 3],
+    [5, 3],
+    [2, 2],
+    [3, 2],
+    [4, 2],
+    [5, 2],
+    [4, 1],
+    [5, 1]
+  ],
+  'adobe-o': [
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [1, 5],
+    [2, 5],
+    [4, 5],
+    [5, 5],
+    [1, 4],
+    [2, 4],
+    [4, 4],
+    [5, 4],
+    [1, 3],
+    [2, 3],
+    [4, 3],
+    [5, 3],
+    [2, 2],
+    [3, 2],
+    [4, 2]
+  ],
+  'adobe-b': [
+    [1, 6],
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [1, 5],
+    [2, 5],
+    [4, 5],
+    [5, 5],
+    [1, 4],
+    [2, 4],
+    [4, 4],
+    [5, 4],
+    [1, 3],
+    [2, 3],
+    [4, 3],
+    [5, 3],
+    [1, 2],
+    [2, 2],
+    [3, 2],
+    [4, 2],
+    [1, 1],
+    [2, 1]
+  ],
+  'adobe-e': [
+    [2, 6],
+    [3, 6],
+    [4, 6],
+    [1, 5],
+    [2, 5],
+    [1, 4],
+    [2, 4],
+    [3, 4],
+    [4, 4],
+    [5, 4],
+    [1, 3],
+    [2, 3],
+    [4, 3],
+    [5, 3],
+    [2, 2],
+    [3, 2],
+    [4, 2]
+  ]
+};
+
+// ─────────────────────────────────────────────────────────────
+// buildCells — turn a positions list into a cells array with
+// per-cell timing (stagger, exitStart, fadeIn, fadeOut).
+//
+// stagger modes:
+//   'individual' — brush style. Each cell gets i * interval.
+//   'grouped' (default) — eye style. Cells stagger within a row,
+//     with 1-cell overlap between consecutive rows (cleaner reads).
+//   'by-row' — all cells in a row share one stagger value.
+// ─────────────────────────────────────────────────────────────
+export function buildCells(positions, options = {}) {
+  const {staggerInterval = 2, rowOffset = 0, stagger: staggerMode = 'grouped'} = options;
+  let staggers;
+  if (staggerMode === 'by-row') {
+    const rowsBottomUp = [...new Set(positions.map(p => p[1]))].sort((a, b) => b - a);
+    const rowStagger = Object.fromEntries(rowsBottomUp.map((r, i) => [r, i * staggerInterval]));
+    staggers = positions.map(([, row]) => rowStagger[row]);
+  } else if (staggerMode === 'grouped') {
+    const rowGroups = new Map();
+    positions.forEach(([, row], i) => {
+      if (!rowGroups.has(row)) rowGroups.set(row, []);
+      rowGroups.get(row).push(i);
+    });
+    const rowsBottomUp = [...rowGroups.keys()].sort((a, b) => b - a);
+    staggers = new Array(positions.length);
+    let rowStart = 0;
+    for (const row of rowsBottomUp) {
+      const indices = rowGroups.get(row);
+      indices.forEach((idx, j) => {
+        staggers[idx] = rowStart + j * staggerInterval;
+      });
+      rowStart += Math.max(0, indices.length - 1) * staggerInterval;
+    }
+  } else if (staggerMode === 'individual') {
+    staggers = positions.map((_, i) => i * staggerInterval);
+  } else {
+    throw new Error(
+      `Unknown stagger mode: ${staggerMode}. Use 'individual', 'grouped', or 'by-row'.`
+    );
+  }
+  const maxStagger = Math.max(1, ...staggers);
+  return positions.map(([col, row], i) => {
+    const stagger = staggers[i];
+    const exitStart = 47 + (stagger / maxStagger) * 12;
+    return {
+      cx: 200 + col * 100,
+      cy: 200 + (row + rowOffset) * 100,
+      outer: false,
+      stagger,
+      exitStart,
+      fadeIn: [stagger + 1, stagger + 4],
+      fadeOut: [exitStart, exitStart + 12]
+    };
+  });
+}
+
+// ─────────────────────────────────────────────────────────────
+// cellSets — { name: Cell[] } for every shipped icon.
+// ─────────────────────────────────────────────────────────────
+export const cellSets = {
+  'ai-logo': aiLogoCells,
+  brush: buildCells(POSITIONS.brush, {staggerInterval: 2, stagger: 'grouped'}),
+  eye: buildCells(POSITIONS.eye, {staggerInterval: 2, stagger: 'grouped', rowOffset: 1}),
+  hourglass: buildCells(POSITIONS.hourglass, {staggerInterval: 1, stagger: 'grouped'}),
+  mag: buildCells(POSITIONS.mag, {staggerInterval: 2, stagger: 'grouped'}),
+  crop: buildCells(POSITIONS.crop, {staggerInterval: 2, stagger: 'grouped'}),
+  flower: buildCells(POSITIONS.flower, {staggerInterval: 2, stagger: 'grouped'}),
+  image: buildCells(POSITIONS.image, {staggerInterval: 1, stagger: 'grouped'}),
+  lasso: buildCells(POSITIONS.lasso, {staggerInterval: 2, stagger: 'grouped'}),
+  page: buildCells(POSITIONS.page, {staggerInterval: 1, stagger: 'grouped'}),
+  wand: buildCells(POSITIONS.wand, {staggerInterval: 2, stagger: 'grouped'}),
+  bargraph: buildCells(POSITIONS.bargraph, {staggerInterval: 2, stagger: 'grouped'}),
+  trefoil: buildCells(POSITIONS.trefoil, {staggerInterval: 2, stagger: 'grouped'}),
+  dial: buildCells(POSITIONS.dial, {staggerInterval: 2, stagger: 'grouped', rowOffset: 1}),
+  folder: buildCells(POSITIONS.folder, {staggerInterval: 1, stagger: 'grouped', rowOffset: 1}),
+  arrow: buildCells(POSITIONS.arrow, {staggerInterval: 2, stagger: 'grouped', rowOffset: 2}),
+  cloud: buildCells(POSITIONS.cloud, {staggerInterval: 1, stagger: 'grouped', rowOffset: 1}),
+  comment: buildCells(POSITIONS.comment, {staggerInterval: 1, stagger: 'grouped'}),
+  filter: buildCells(POSITIONS.filter, {staggerInterval: 1, stagger: 'grouped'}),
+  microphone: buildCells(POSITIONS.microphone, {staggerInterval: 1, stagger: 'grouped'}),
+  pencil: buildCells(POSITIONS.pencil, {staggerInterval: 2, stagger: 'grouped'}),
+  potion: buildCells(POSITIONS.potion, {staggerInterval: 1, stagger: 'grouped'}),
+  slider: buildCells(POSITIONS.slider, {staggerInterval: 1, stagger: 'grouped', rowOffset: 1}),
+  timeline: buildCells(POSITIONS.timeline, {staggerInterval: 1, stagger: 'grouped'}),
+  eyedrop: buildCells(POSITIONS.eyedrop, {staggerInterval: 1, stagger: 'grouped'}),
+  'adobe-a': buildCells(POSITIONS['adobe-a'], {staggerInterval: 2, stagger: 'grouped'}),
+  'adobe-d': buildCells(POSITIONS['adobe-d'], {staggerInterval: 2, stagger: 'grouped'}),
+  'adobe-o': buildCells(POSITIONS['adobe-o'], {
+    staggerInterval: 2,
+    stagger: 'grouped',
+    rowOffset: -1
+  }),
+  'adobe-b': buildCells(POSITIONS['adobe-b'], {staggerInterval: 2, stagger: 'grouped'}),
+  'adobe-e': buildCells(POSITIONS['adobe-e'], {
+    staggerInterval: 2,
+    stagger: 'grouped',
+    rowOffset: -1
+  })
+};
+
+// ─────────────────────────────────────────────────────────────
+// LOADER_PRESETS — named sequences of icons (loops through them).
+// ─────────────────────────────────────────────────────────────
+export const LOADER_PRESETS = {
+  cc: {
+    label: 'CC Loader',
+    icons: [
+      'ai-logo',
+      'brush',
+      'wand',
+      'crop',
+      'eye',
+      'hourglass',
+      'adobe-a',
+      'adobe-d',
+      'adobe-o',
+      'adobe-b',
+      'adobe-e',
+      'eyedrop'
+    ]
+  },
+  dc: {
+    label: 'DC Loader',
+    icons: [
+      'ai-logo',
+      'page',
+      'trefoil',
+      'image',
+      'cloud',
+      'mag',
+      'adobe-a',
+      'adobe-d',
+      'adobe-o',
+      'adobe-b',
+      'adobe-e',
+      'pencil'
+    ]
+  },
+  exp: {
+    label: 'EXP Loader',
+    icons: [
+      'ai-logo',
+      'bargraph',
+      'dial',
+      'filter',
+      'slider',
+      'folder',
+      'adobe-a',
+      'adobe-d',
+      'adobe-o',
+      'adobe-b',
+      'adobe-e',
+      'arrow'
+    ]
+  },
+  analyze: {
+    label: 'Analyze Image',
+    icons: ['flower', 'image', 'brush', 'eye', 'eyedrop', 'wand', 'lasso', 'crop']
+  },
+  mega: {
+    label: 'Mega Loader',
+    icons: [
+      'ai-logo',
+      'brush',
+      'wand',
+      'crop',
+      'eye',
+      'hourglass',
+      'page',
+      'trefoil',
+      'image',
+      'eyedrop',
+      'mag',
+      'bargraph',
+      'dial',
+      'folder',
+      'flower',
+      'lasso',
+      'adobe-a',
+      'adobe-d',
+      'adobe-o',
+      'adobe-b',
+      'adobe-e',
+      'arrow',
+      'cloud',
+      'comment',
+      'filter',
+      'microphone',
+      'pencil',
+      'potion',
+      'slider',
+      'timeline'
+    ]
+  }
+};
+
+// ─────────────────────────────────────────────────────────────
+// ICON_LABELS — display-name overrides for icons whose key
+// doesn't read nicely (e.g. microphone → "mic", ai-logo → "ai logo").
+// ─────────────────────────────────────────────────────────────
+export const ICON_LABELS = {
+  'ai-logo': 'ai logo',
+  microphone: 'mic'
+};
+
+// ─────────────────────────────────────────────────────────────
+// Public icon name list — handy for consumers building pickers.
+// ─────────────────────────────────────────────────────────────
+export const ICON_NAMES = Object.keys(cellSets);
+export const PRESET_NAMES = Object.keys(LOADER_PRESETS);
diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
new file mode 100644
index 00000000000..bbc0e162dfa
--- /dev/null
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -0,0 +1,259 @@
+// React pixel-fall loader. Renders plain HTML divs and lets the browser
+// drive the animation natively via generated CSS @keyframes — no
+// requestAnimationFrame loop, and no SVG. Cells animate only `transform`
+// and `opacity`, with exactly ONE `replace` animation per property per
+// cell, so Chrome composites both on the GPU (off the main thread) for
+// near-zero idle CPU. (An earlier shared-keyframe variant using
+// `animation-composition: add` and stacked opacity animations was ~2x
+// the CPU because additive/stacked animations fall back to the main
+// thread — composited residency matters far more than keyframe count.)
+//
+// The curve math in runtime.ts is the single source of truth: the
+// keyframe values/easings below are emitted from it, and the paused
+// "poster" frame is rendered from the same samplers, so playing and
+// paused states match exactly.
+//
+// Multi-icon sequences (presets) play one icon per 2.4s cycle and
+// advance via a single timer — only the current icon's cells are in the
+// DOM. A single-icon loader stays a pure infinite CSS loop with no JS.
+
+import * as React from 'react';
+import {cellSets, LOADER_PRESETS} from './data.js';
+import {
+  EASE,
+  FPS,
+  getOpacity,
+  getY,
+  POSTER_FRAME,
+  TOTAL_FRAMES,
+  Y_EXIT,
+  Y_OVERSHOOT,
+  Y_START
+} from './runtime.js';
+
+const DURATION_MS = (TOTAL_FRAMES / FPS) * 1000;
+
+// The animation lives in a fixed VIEWBOX-sized coordinate space (matching
+// the source Lottie's 1000×1000 canvas) that is scaled down to the
+// rendered `size`. Cells are absolutely positioned in this space, so all
+// the translateY offsets below are in these units — identical to the old
+// SVG viewBox math, just on HTML elements the compositor can accelerate.
+const VIEWBOX = 1000;
+const CELL = 100;
+
+// ─────────────────────────────────────────────────────────────
+// CSS @keyframes generation. Each piecewise segment of the runtime
+// curves becomes one keyframe stop whose `animation-timing-function`
+// is the matching cubic-bezier — CSS interpolates it identically to
+// `getY`/`getOpacity`.
+// ─────────────────────────────────────────────────────────────
+
+function pct(frame) {
+  // Frame → keyframe offset percentage, trimmed of noise.
+  return `${+((frame / TOTAL_FRAMES) * 100).toFixed(4)}%`;
+}
+
+function cb(coeffs) {
+  return `cubic-bezier(${coeffs.join(',')})`;
+}
+
+// stops: ordered [{f, decl, ease}]. `decl` is the CSS declarations for
+// that stop; `ease` (optional) is the timing function for the segment
+// starting at it. Stops sharing a frame are de-duped (first wins).
+type Stop = {f: number; decl: string; ease?: readonly number[] | null};
+
+function emitKeyframes(name: string, stops: Stop[]) {
+  let body = '';
+  let lastPct: string | null = null;
+  for (const s of stops) {
+    const p = pct(s.f);
+    if (p === lastPct) continue;
+    lastPct = p;
+    const ease = s.ease ? `animation-timing-function:${cb(s.ease)};` : '';
+    body += `${p}{${s.decl}${ease}}`;
+  }
+  return `@keyframes ${name}{${body}}`;
+}
+
+const ty = v => `transform:translateY(${v}px);`;
+const op = v => `opacity:${v};`;
+
+function cellYKeyframes(name, c) {
+  const s = c.stagger;
+  const e = c.exitStart;
+  const stops: Stop[] = [{f: 0, decl: ty(Y_START), ease: s > 0 ? null : EASE.drop}];
+  if (s > 0) {
+    stops.push({f: s, decl: ty(Y_START), ease: EASE.drop});
+  }
+  stops.push({f: s + 10, decl: ty(Y_OVERSHOOT), ease: EASE.recover});
+  stops.push({f: s + 13, decl: ty(0)}); // settled — hold until exit
+  stops.push({f: e, decl: ty(0), ease: EASE.exit});
+  stops.push({f: e + 12, decl: ty(Y_EXIT)});
+  stops.push({f: TOTAL_FRAMES, decl: ty(Y_EXIT)}); // hold offscreen until wrap
+  return emitKeyframes(name, stops);
+}
+
+function cellOpacityKeyframes(name, c) {
+  const [fi0, fi1] = c.fadeIn;
+  const [fo0, fo1] = c.fadeOut;
+  return emitKeyframes(name, [
+    {f: 0, decl: op(0)},
+    {f: fi0, decl: op(0), ease: EASE.fade},
+    {f: fi1, decl: op(1)},
+    {f: fo0, decl: op(1), ease: EASE.fade},
+    {f: fo1, decl: op(0)},
+    {f: TOTAL_FRAMES, decl: op(0)}
+  ]);
+}
+
+const cssCache = new Map();
+function keyframesFor(iconName, cells) {
+  let css = cssCache.get(iconName);
+  if (!css) {
+    css = cells
+      .map(
+        (c, i) =>
+          cellYKeyframes(`pl-${iconName}-${i}-y`, c) +
+          cellOpacityKeyframes(`pl-${iconName}-${i}-o`, c)
+      )
+      .join('');
+    cssCache.set(iconName, css);
+  }
+  return css;
+}
+
+// Resolve a sequence of icon names from the icon-selection props, in
+// precedence order: explicit `icons` list, single `icon`, then `preset`.
+// Falls back to the ai-logo. Unknown names are dropped.
+function resolveSequence({preset, icon, icons}): string[] {
+  if (icons && icons.length) {
+    const names = icons.filter(n => cellSets[n]);
+    if (names.length) return names;
+  }
+  if (icon && cellSets[icon]) return [icon];
+  if (preset && LOADER_PRESETS[preset]) {
+    const names = LOADER_PRESETS[preset].icons.filter(n => cellSets[n]);
+    if (names.length) return names;
+  }
+  return ['ai-logo'];
+}
+
+// ─────────────────────────────────────────────────────────────
+// Component. Only `size` and `playing` are load-bearing for the
+// PromptField usage; `icon`/`icons`/`preset`, `speed`, `color`,
+// `className`, and `style` are supported because they're free. When not
+// playing, the loader renders a single static poster frame (no
+// animation).
+// ─────────────────────────────────────────────────────────────
+export function PixelLoader(props) {
+  const {
+    size = 64,
+    playing = true,
+    preset,
+    icon,
+    icons,
+    speed = 1,
+    color = 'currentColor',
+    className,
+    style,
+    ...rest
+  } = props;
+
+  // The icon sequence (1+ names). A single-icon sequence loops forever
+  // in pure CSS; a multi-icon sequence advances one icon per cycle via
+  // the timer below, so only the current icon's cells are ever in the DOM.
+  const sequence = resolveSequence({preset, icon, icons});
+  const isSequence = sequence.length > 1;
+  const duration = DURATION_MS / (speed || 1);
+
+  // `tick` increments once per cycle; the current icon is `tick % len`.
+  // It's also the remount key, so each swap restarts the animation cleanly.
+  const [tick, setTick] = React.useState(0);
+  const seqKey = sequence.join(',');
+
+  // Restart the sequence from the first icon whenever the sequence changes.
+  React.useEffect(() => {
+    setTick(0);
+  }, [seqKey]);
+
+  // Advance the sequence one icon per cycle while playing. Single-icon
+  // loaders never start a timer — they're a pure infinite CSS loop.
+  React.useEffect(() => {
+    if (!playing || !isSequence) {
+      return undefined;
+    }
+    const id = setInterval(() => setTick(t => t + 1), duration);
+    return () => clearInterval(id);
+  }, [playing, isSequence, duration, seqKey]);
+
+  const iconName = sequence[isSequence ? tick % sequence.length : 0];
+  const cells = cellSets[iconName];
+  const css = keyframesFor(iconName, cells);
+  // Sequences play each icon once and hold its faded-out final frame
+  // (`forwards`) until the next remount; a single icon loops forever.
+  const iteration = isSequence ? '1 forwards' : 'infinite';
+
+  // Map the VIEWBOX coordinate space down to the rendered size.
+  const px = typeof size === 'number' ? size : parseFloat(size);
+  const scaleFactor = px / VIEWBOX;
+
+  return (
+    <div
+      aria-hidden="true"
+      className={className}
+      style={{
+        display: 'inline-block',
+        width: size,
+        height: size,
+        lineHeight: 0,
+        // Cells fly far outside the box (off-top on entry, off-bottom on
+        // exit) — clip them, like the SVG viewBox did.
+        overflow: 'hidden',
+        position: 'relative',
+        ...style
+      }}
+      {...rest}>
+      {playing ? <style>{css}</style> : null}
+      {/* VIEWBOX → size scale, mapping the 1000-unit coordinate space to `size`.
+          Keyed by `tick` so each sequence swap remounts and restarts cleanly. */}
+      <div
+        style={{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          width: VIEWBOX,
+          height: VIEWBOX,
+          transformOrigin: '0 0',
+          transform: `scale(${scaleFactor})`
+        }}>
+        {cells.map((c, i) => {
+          const cellStyle = playing
+            ? {
+                animation:
+                  `pl-${iconName}-${i}-y ${duration}ms linear ${iteration}, ` +
+                  `pl-${iconName}-${i}-o ${duration}ms linear ${iteration}`,
+                willChange: 'transform, opacity'
+              }
+            : {
+                transform: `translateY(${getY(POSTER_FRAME - c.stagger, c.exitStart - c.stagger)}px)`,
+                opacity: getOpacity(POSTER_FRAME, c)
+              };
+          return (
+            <div
+              key={i}
+              style={{
+                position: 'absolute',
+                left: c.cx - CELL / 2,
+                top: c.cy - CELL / 2,
+                width: CELL,
+                height: CELL,
+                backgroundColor: color,
+                ...cellStyle
+              }}
+            />
+          );
+        })}
+      </div>
+    </div>
+  );
+}
diff --git a/packages/@react-spectrum/ai/src/loader/runtime.ts b/packages/@react-spectrum/ai/src/loader/runtime.ts
new file mode 100644
index 00000000000..c1cb9325cec
--- /dev/null
+++ b/packages/@react-spectrum/ai/src/loader/runtime.ts
@@ -0,0 +1,137 @@
+// Pure animation model for the pixel-fall loader, ported from the
+// standalone HTML export in experiments/pixel-fall-animation/index.html.
+//
+// These curves are the single source of truth for both the CSS
+// @keyframes generated in react.tsx (the playing animation) and the
+// static poster-frame render (the paused state). The animation itself
+// is driven natively by the browser via CSS animations — there is no
+// rAF loop. Visual parity with the playground is the load-bearing test.
+
+// ─────────────────────────────────────────────────────────────
+// Cubic-bezier easing — P0=(0,0), P3=(1,1); returns y for x ∈ [0,1].
+// ─────────────────────────────────────────────────────────────
+export function cubicBezier(p1x, p1y, p2x, p2y) {
+  const sampleX = t => 3 * (1 - t) * (1 - t) * t * p1x + 3 * (1 - t) * t * t * p2x + t * t * t;
+  const sampleY = t => 3 * (1 - t) * (1 - t) * t * p1y + 3 * (1 - t) * t * t * p2y + t * t * t;
+  const sampleDX = t =>
+    3 * (1 - t) * (1 - t) * p1x + 6 * (1 - t) * t * (p2x - p1x) + 3 * t * t * (1 - p2x);
+  function solve(x) {
+    let t = x;
+    for (let i = 0; i < 8; i++) {
+      const cx = sampleX(t) - x;
+      if (Math.abs(cx) < 1e-6) return t;
+      const dx = sampleDX(t);
+      if (Math.abs(dx) < 1e-6) break;
+      t -= cx / dx;
+    }
+    let lo = 0;
+    let hi = 1;
+    while (hi - lo > 1e-6) {
+      const m = (lo + hi) / 2;
+      if (sampleX(m) < x) lo = m;
+      else hi = m;
+    }
+    return (lo + hi) / 2;
+  }
+  return x => sampleY(solve(Math.max(0, Math.min(1, x))));
+}
+
+// Easing control points — shared by the JS samplers below and the
+// `cubic-bezier(...)` strings emitted into CSS, so the two can never
+// drift. Native CSS solves these the same way `cubicBezier` does, so
+// the playing animation matches the poster frame exactly.
+export const EASE = {
+  drop: [0.333, 0, 0.667, 1],
+  recover: [0.333, 0, 0.833, 1],
+  exit: [0.563, 0, 0.906, 0.757],
+  scaleUp: [0.333, 0, 0.378, 0.765],
+  scaleDown: [0.253, -0.027, 0.97, 0.045],
+  fade: [0.167, 0.167, 0.833, 0.833]
+} as const;
+
+export const easeDrop = cubicBezier(...EASE.drop);
+export const easeRecover = cubicBezier(...EASE.recover);
+export const easeExit = cubicBezier(...EASE.exit);
+export const easeScaleUp = cubicBezier(...EASE.scaleUp);
+export const easeScaleDown = cubicBezier(...EASE.scaleDown);
+export const easeFade = cubicBezier(...EASE.fade);
+
+// ─────────────────────────────────────────────────────────────
+// Timing constants — one full cycle is 72 frames at 30fps (2.4s).
+// ─────────────────────────────────────────────────────────────
+export const TOTAL_FRAMES = 72;
+export const FPS = 30;
+
+// ─────────────────────────────────────────────────────────────
+// Per-cell vertical offset from settled position (data3.json kfs).
+// ─────────────────────────────────────────────────────────────
+export const Y_START = -876.156;
+export const Y_OVERSHOOT = 18;
+export const Y_EXIT = 1015;
+
+export function getY(localT, exitLocal) {
+  if (localT < 0) return Y_START;
+  if (localT < 10) return Y_START + (Y_OVERSHOOT - Y_START) * easeDrop(localT / 10);
+  if (localT < 13) return Y_OVERSHOOT + (0 - Y_OVERSHOOT) * easeRecover((localT - 10) / 3);
+  if (localT < exitLocal) return 0;
+  if (localT < exitLocal + 12) return Y_EXIT * easeExit((localT - exitLocal) / 12);
+  return Y_EXIT;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Global scale curve — cells bloom from a slightly smaller starting
+// scale up to their natural footprint (1.0) at POSTER_FRAME, hold
+// there for a few frames, then descend toward the exit pose.
+//
+// Shape:
+//   compT ∈ [0, 38)   — grow 0.92 → 1.0   (anticipation then bloom)
+//   compT ∈ [38, 44)  — plateau at 1.0     (POSTER_FRAME = 42 sits here)
+//   compT ∈ [44, 83)  — descend 1.0 → 0.74991
+//   compT ≥ 83        — frozen at 0.74991
+//
+// Growing into 1.0 (instead of overshooting above and snapping back
+// down) keeps the curve C0-continuous across the plateau boundary and
+// avoids the visible scale pop that the earlier overshoot-then-snap
+// shape caused. `getGlobalScale(POSTER_FRAME) === 1.0` exactly, so the
+// paused poster render is literally a single frame of the playing
+// animation — no special-cased override needed.
+// ─────────────────────────────────────────────────────────────
+export const SCALE_START = 0.92;
+export const SCALE_END = 74.991 / 100;
+export const PLATEAU_START = 38;
+export const PLATEAU_END = 44;
+
+export function getGlobalScale(compT) {
+  if (compT < 0) return SCALE_START;
+  if (compT < PLATEAU_START) {
+    return SCALE_START + (1 - SCALE_START) * easeScaleUp(compT / PLATEAU_START);
+  }
+  if (compT < PLATEAU_END) return 1;
+  if (compT < 83) {
+    const t = (compT - PLATEAU_END) / (83 - PLATEAU_END);
+    return 1 + (SCALE_END - 1) * easeScaleDown(t);
+  }
+  return SCALE_END;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Per-cell opacity from data3.json (4 keyframes per cell).
+// ─────────────────────────────────────────────────────────────
+export function getOpacity(compT, cell) {
+  const [fi0, fi1] = cell.fadeIn;
+  const [fo0, fo1] = cell.fadeOut;
+  if (compT < fi0) return 0;
+  if (compT < fi1) return easeFade((compT - fi0) / (fi1 - fi0));
+  if (compT < fo0) return 1;
+  if (compT < fo1) return 1 - easeFade((compT - fo0) / (fo1 - fo0));
+  return 0;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Poster frame — the rest-pose compFrame for the paused render. Sits
+// inside the plateau region of `getGlobalScale`, so the curve
+// naturally evaluates to 1.0 here and the paused render is just a
+// literal single frame of the playing animation — no scale pop when
+// toggling `playing`.
+// ─────────────────────────────────────────────────────────────
+export const POSTER_FRAME = 42;

From e2b4422873b995402e1b32f393564756d0f5cda2 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Mon, 22 Jun 2026 15:44:57 -0700
Subject: [PATCH 07/34] Make PixelLoader tree shakeable

---
 .../@react-spectrum/ai/src/PromptField.tsx    |    8 +-
 .../@react-spectrum/ai/src/loader/data.ts     | 1606 +++++++++--------
 .../@react-spectrum/ai/src/loader/react.tsx   |  100 +-
 .../ai/stories/PromptField.stories.tsx        |   31 +-
 4 files changed, 927 insertions(+), 818 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index a1dc8ca36ab..fc397077415 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -15,6 +15,7 @@ import Attach from '@react-spectrum/s2/icons/Attach';
 import {Attachment, AttachmentList, AttachmentListProps} from './AttachmentList';
 import {Autocomplete} from 'react-aria-components/Autocomplete';
 import {Button} from '@react-spectrum/s2/Button';
+import {Cell} from './loader/data';
 import {CenterBaseline} from '@react-spectrum/s2/CenterBaseline';
 import {
   createContext,
@@ -39,6 +40,7 @@ import {Image, Text} from '@react-spectrum/s2/Card';
 import {isFileDropItem, useDrop} from 'react-aria-components/useDrop';
 import {Link} from '@react-spectrum/s2/Link';
 import {Menu, MenuItem, MenuItemProps, MenuTrigger} from '@react-spectrum/s2/Menu';
+import {PixelLoader} from './loader/react';
 import Plus from '@react-spectrum/s2/icons/Add';
 import {Popover, PopoverProps} from '@react-spectrum/s2/Popover';
 import {positionToDOMRange, Token, TokenField, TokenProps} from './TokenField';
@@ -47,7 +49,6 @@ import {PromptFocusContext} from './Chat';
 import Send from '@react-spectrum/s2/icons/ArrowUpSend';
 import Stop from '@react-spectrum/s2/icons/StopProcessing';
 import {useFocusWithin} from 'react-aria/useFocusWithin';
-import {PixelLoader} from './loader/react';
 
 export interface PromptFieldAttachment {
   id: string;
@@ -264,10 +265,11 @@ export interface PromptTokenFieldProps {
     filterValue: string
   ) => React.ReactNode[] | null | Promise<React.ReactNode[] | null>;
   children?: (segment: TokenSegment) => React.ReactElement;
+  pixelLoader?: Cell[] | Cell[][];
 }
 
 export function PromptTokenField(props: PromptTokenFieldProps) {
-  let {completionTrigger, renderCompletions, children} = props;
+  let {completionTrigger, renderCompletions, children, pixelLoader} = props;
   let {
     prompt,
     setPrompt,
@@ -310,7 +312,7 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
         width: 'full'
       })}>
       <CenterBaseline>
-        <PixelLoader size={24} playing={isGenerating} preset="exp" />
+        <PixelLoader size={24} playing={isGenerating} icon={pixelLoader} />
       </CenterBaseline>
       <Autocomplete>
         <TokenField
diff --git a/packages/@react-spectrum/ai/src/loader/data.ts b/packages/@react-spectrum/ai/src/loader/data.ts
index 8a4f41e2b31..0a22ee1a9b4 100644
--- a/packages/@react-spectrum/ai/src/loader/data.ts
+++ b/packages/@react-spectrum/ai/src/loader/data.ts
@@ -1,14 +1,36 @@
 // Loader cell-position data, ported from
 // experiments/pixel-fall-animation/index.html.
 //
-// Each cell:
-//   { cx, cy, outer, stagger, exitStart, fadeIn, fadeOut }
+// Each icon is an independently-exported `Cell[]` so unused icons tree-
+// shake away; a preset is a `Cell[][]` (a sequence of icons). Import only
+// what you render: `import {brush} from '...'` then `<PixelLoader icon={brush} />`,
+// or a preset `import {cc} from '...'` then `<PixelLoader icon={cc} />`.
+//
 // Coordinates are in the source Lottie's 1000×1000 canvas.
 
+export interface Cell {
+  cx: number;
+  cy: number;
+  // Retained from the source data; no longer affects rendering.
+  outer: boolean;
+  stagger: number;
+  exitStart: number;
+  fadeIn: number[];
+  fadeOut: number[];
+}
+
+type StaggerMode = 'individual' | 'grouped' | 'by-row';
+
+interface BuildOptions {
+  staggerInterval?: number;
+  rowOffset?: number;
+  stagger?: StaggerMode;
+}
+
 // ─────────────────────────────────────────────────────────────
 // ai-logo: original 12-cell diamond layout with hand-tuned timings.
 // ─────────────────────────────────────────────────────────────
-export const aiLogoCells = [
+export const aiLogo: Cell[] = [
   {cx: 500, cy: 800, outer: true, stagger: 0, exitStart: 47, fadeIn: [1, 4], fadeOut: [47, 59]},
   {cx: 300, cy: 700, outer: true, stagger: 2, exitStart: 48, fadeIn: [4, 7], fadeOut: [48, 60]},
   {cx: 700, cy: 700, outer: true, stagger: 4, exitStart: 49, fadeIn: [6, 9], fadeOut: [49, 61]},
@@ -24,614 +46,612 @@ export const aiLogoCells = [
 ];
 
 // ─────────────────────────────────────────────────────────────
-// POSITIONS — each entry is a list of [col, row] cell coords on a
-// 7×7 grid. Bottom-up, left-to-right within row → stagger order.
+// POSITIONS — [col, row] grid coords per icon, exported individually.
 // ─────────────────────────────────────────────────────────────
-export const POSITIONS = {
-  brush: [
-    [0, 6],
-    [1, 6],
-    [2, 6],
-    [1, 5],
-    [3, 5],
-    [2, 4],
-    [3, 4],
-    [3, 3],
-    [4, 3],
-    [4, 2],
-    [5, 2],
-    [5, 1],
-    [6, 1],
-    [6, 0]
-  ],
-  eye: [
-    [2, 4],
-    [3, 4],
-    [4, 4],
-    [1, 3],
-    [3, 3],
-    [5, 3],
-    [0, 2],
-    [2, 2],
-    [3, 2],
-    [4, 2],
-    [6, 2],
-    [1, 1],
-    [2, 1],
-    [3, 1],
-    [5, 1],
-    [2, 0],
-    [3, 0],
-    [4, 0]
-  ],
-  hourglass: [
-    [0, 6],
-    [1, 6],
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [5, 6],
-    [6, 6],
-    [1, 5],
-    [2, 5],
-    [3, 5],
-    [4, 5],
-    [5, 5],
-    [1, 4],
-    [2, 4],
-    [4, 4],
-    [5, 4],
-    [2, 3],
-    [3, 3],
-    [4, 3],
-    [1, 2],
-    [2, 2],
-    [3, 2],
-    [4, 2],
-    [5, 2],
-    [1, 1],
-    [5, 1],
-    [0, 0],
-    [1, 0],
-    [2, 0],
-    [3, 0],
-    [4, 0],
-    [5, 0],
-    [6, 0]
-  ],
-  mag: [
-    [6, 6],
-    [5, 5],
-    [1, 4],
-    [2, 4],
-    [3, 4],
-    [0, 3],
-    [4, 3],
-    [0, 2],
-    [4, 2],
-    [0, 1],
-    [4, 1],
-    [1, 0],
-    [2, 0],
-    [3, 0]
-  ],
-  crop: [
-    [5, 6],
-    [1, 5],
-    [2, 5],
-    [3, 5],
-    [4, 5],
-    [5, 5],
-    [6, 5],
-    [1, 4],
-    [1, 3],
-    [5, 3],
-    [1, 2],
-    [5, 2],
-    [0, 1],
-    [1, 1],
-    [3, 1],
-    [4, 1],
-    [5, 1],
-    [1, 0]
-  ],
-  flower: [
-    [3, 6],
-    [3, 5],
-    [2, 4],
-    [4, 4],
-    [2, 3],
-    [5, 3],
-    [1, 2],
-    [4, 2],
-    [6, 2],
-    [0, 1],
-    [2, 1],
-    [5, 1],
-    [1, 0]
-  ],
-  image: [
-    [0, 6],
-    [1, 6],
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [5, 6],
-    [6, 6],
-    [0, 5],
-    [1, 5],
-    [2, 5],
-    [3, 5],
-    [4, 5],
-    [5, 5],
-    [6, 5],
-    [0, 4],
-    [1, 4],
-    [2, 4],
-    [3, 4],
-    [5, 4],
-    [6, 4],
-    [0, 3],
-    [2, 3],
-    [6, 3],
-    [0, 2],
-    [4, 2],
-    [6, 2],
-    [0, 1],
-    [6, 1],
-    [0, 0],
-    [1, 0],
-    [2, 0],
-    [3, 0],
-    [4, 0],
-    [5, 0],
-    [6, 0]
-  ],
-  lasso: [
-    [1, 6],
-    [2, 5],
-    [1, 4],
-    [2, 4],
-    [0, 3],
-    [3, 3],
-    [4, 3],
-    [5, 3],
-    [0, 2],
-    [6, 2],
-    [1, 1],
-    [6, 1],
-    [2, 0],
-    [3, 0],
-    [4, 0],
-    [5, 0]
-  ],
-  page: [
-    [0, 6],
-    [1, 6],
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [5, 6],
-    [6, 6],
-    [0, 5],
-    [6, 5],
-    [0, 4],
-    [6, 4],
-    [0, 3],
-    [3, 3],
-    [4, 3],
-    [5, 3],
-    [6, 3],
-    [0, 2],
-    [3, 2],
-    [6, 2],
-    [0, 1],
-    [3, 1],
-    [5, 1],
-    [0, 0],
-    [1, 0],
-    [2, 0],
-    [3, 0],
-    [4, 0]
-  ],
-  wand: [
-    [6, 6],
-    [5, 5],
-    [0, 4],
-    [4, 4],
-    [2, 3],
-    [1, 2],
-    [3, 2],
-    [2, 1],
-    [0, 0],
-    [4, 0]
-  ],
-  bargraph: [
-    [0, 6],
-    [2, 6],
-    [4, 6],
-    [6, 6],
-    [2, 5],
-    [4, 5],
-    [6, 5],
-    [0, 4],
-    [2, 4],
-    [4, 4],
-    [6, 4],
-    [1, 3],
-    [6, 3],
-    [2, 2],
-    [4, 2],
-    [6, 2],
-    [3, 1],
-    [5, 1],
-    [6, 0]
-  ],
-  trefoil: [
-    [0, 6],
-    [1, 6],
-    [1, 5],
-    [2, 4],
-    [3, 4],
-    [5, 4],
-    [6, 4],
-    [2, 3],
-    [4, 3],
-    [3, 2],
-    [3, 1],
-    [3, 0]
-  ],
-  dial: [
-    [0, 4],
-    [6, 4],
-    [0, 3],
-    [3, 3],
-    [6, 3],
-    [0, 2],
-    [4, 2],
-    [6, 2],
-    [1, 1],
-    [5, 1],
-    [2, 0],
-    [3, 0]
-  ],
-  folder: [
-    [0, 5],
-    [1, 5],
-    [2, 5],
-    [3, 5],
-    [4, 5],
-    [5, 5],
-    [6, 5],
-    [0, 4],
-    [6, 4],
-    [0, 3],
-    [6, 3],
-    [0, 2],
-    [6, 2],
-    [0, 1],
-    [3, 1],
-    [4, 1],
-    [5, 1],
-    [6, 1],
-    [1, 0],
-    [2, 0]
-  ],
-  arrow: [
-    [0, 4],
-    [1, 3],
-    [3, 3],
-    [2, 2],
-    [4, 2],
-    [6, 2],
-    [5, 1],
-    [6, 1],
-    [4, 0],
-    [5, 0],
-    [6, 0]
-  ],
-  cloud: [
-    [0, 4],
-    [1, 4],
-    [2, 4],
-    [3, 4],
-    [4, 4],
-    [5, 4],
-    [6, 4],
-    [0, 3],
-    [6, 3],
-    [1, 2],
-    [5, 2],
-    [1, 1],
-    [2, 1],
-    [5, 1],
-    [3, 0],
-    [4, 0]
-  ],
-  comment: [
-    [1, 6],
-    [1, 5],
-    [2, 5],
-    [1, 4],
-    [3, 4],
-    [4, 4],
-    [5, 4],
-    [0, 3],
-    [6, 3],
-    [0, 2],
-    [6, 2],
-    [0, 1],
-    [6, 1],
-    [1, 0],
-    [2, 0],
-    [3, 0],
-    [4, 0],
-    [5, 0]
-  ],
-  filter: [
-    [2, 6],
-    [3, 6],
-    [2, 5],
-    [4, 5],
-    [2, 4],
-    [4, 4],
-    [2, 3],
-    [4, 3],
-    [1, 2],
-    [5, 2],
-    [0, 1],
-    [6, 1],
-    [0, 0],
-    [1, 0],
-    [2, 0],
-    [3, 0],
-    [4, 0],
-    [5, 0],
-    [6, 0]
-  ],
-  microphone: [
-    [1, 6],
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [2, 5],
-    [3, 5],
-    [1, 4],
-    [4, 4],
-    [0, 3],
-    [1, 3],
-    [4, 3],
-    [5, 3],
-    [1, 2],
-    [4, 2],
-    [1, 1],
-    [4, 1],
-    [2, 0],
-    [3, 0]
-  ],
-  pencil: [
-    [0, 6],
-    [1, 6],
-    [2, 6],
-    [0, 5],
-    [1, 5],
-    [3, 5],
-    [0, 4],
-    [4, 4],
-    [1, 3],
-    [5, 3],
-    [2, 2],
-    [4, 2],
-    [6, 2],
-    [3, 1],
-    [6, 1],
-    [4, 0],
-    [5, 0]
-  ],
-  potion: [
-    [1, 6],
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [5, 6],
-    [0, 5],
-    [6, 5],
-    [0, 4],
-    [2, 4],
-    [6, 4],
-    [1, 3],
-    [3, 3],
-    [5, 3],
-    [2, 2],
-    [4, 2],
-    [2, 1],
-    [4, 1],
-    [1, 0],
-    [2, 0],
-    [3, 0],
-    [4, 0],
-    [5, 0]
-  ],
-  slider: [
-    [4, 5],
-    [0, 4],
-    [1, 4],
-    [2, 4],
-    [3, 4],
-    [5, 4],
-    [6, 4],
-    [4, 3],
-    [2, 2],
-    [0, 1],
-    [1, 1],
-    [3, 1],
-    [4, 1],
-    [5, 1],
-    [6, 1],
-    [2, 0]
-  ],
-  timeline: [
-    [3, 6],
-    [0, 5],
-    [1, 5],
-    [3, 5],
-    [4, 5],
-    [5, 5],
-    [6, 5],
-    [0, 4],
-    [1, 4],
-    [3, 4],
-    [4, 4],
-    [5, 4],
-    [6, 4],
-    [3, 3],
-    [2, 2],
-    [4, 2],
-    [1, 1],
-    [5, 1],
-    [1, 0],
-    [2, 0],
-    [3, 0],
-    [4, 0],
-    [5, 0]
-  ],
-  eyedrop: [
-    [0, 6],
-    [1, 6],
-    [0, 5],
-    [2, 5],
-    [1, 4],
-    [3, 4],
-    [2, 3],
-    [4, 3],
-    [6, 3],
-    [3, 2],
-    [4, 2],
-    [5, 2],
-    [4, 1],
-    [5, 1],
-    [6, 1],
-    [3, 0],
-    [5, 0],
-    [6, 0]
-  ],
-  'adobe-a': [
-    [0, 6],
-    [1, 6],
-    [2, 6],
-    [3, 6],
-    [5, 6],
-    [6, 6],
-    [1, 5],
-    [2, 5],
-    [5, 5],
-    [1, 4],
-    [2, 4],
-    [4, 4],
-    [5, 4],
-    [1, 3],
-    [2, 3],
-    [4, 3],
-    [5, 3],
-    [2, 2],
-    [3, 2],
-    [4, 2],
-    [2, 1],
-    [3, 1],
-    [4, 1]
-  ],
-  'adobe-d': [
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [5, 6],
-    [1, 5],
-    [2, 5],
-    [4, 5],
-    [5, 5],
-    [1, 4],
-    [2, 4],
-    [4, 4],
-    [5, 4],
-    [1, 3],
-    [2, 3],
-    [4, 3],
-    [5, 3],
-    [2, 2],
-    [3, 2],
-    [4, 2],
-    [5, 2],
-    [4, 1],
-    [5, 1]
-  ],
-  'adobe-o': [
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [1, 5],
-    [2, 5],
-    [4, 5],
-    [5, 5],
-    [1, 4],
-    [2, 4],
-    [4, 4],
-    [5, 4],
-    [1, 3],
-    [2, 3],
-    [4, 3],
-    [5, 3],
-    [2, 2],
-    [3, 2],
-    [4, 2]
-  ],
-  'adobe-b': [
-    [1, 6],
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [1, 5],
-    [2, 5],
-    [4, 5],
-    [5, 5],
-    [1, 4],
-    [2, 4],
-    [4, 4],
-    [5, 4],
-    [1, 3],
-    [2, 3],
-    [4, 3],
-    [5, 3],
-    [1, 2],
-    [2, 2],
-    [3, 2],
-    [4, 2],
-    [1, 1],
-    [2, 1]
-  ],
-  'adobe-e': [
-    [2, 6],
-    [3, 6],
-    [4, 6],
-    [1, 5],
-    [2, 5],
-    [1, 4],
-    [2, 4],
-    [3, 4],
-    [4, 4],
-    [5, 4],
-    [1, 3],
-    [2, 3],
-    [4, 3],
-    [5, 3],
-    [2, 2],
-    [3, 2],
-    [4, 2]
-  ]
-};
+const brushPositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [2, 6],
+  [1, 5],
+  [3, 5],
+  [2, 4],
+  [3, 4],
+  [3, 3],
+  [4, 3],
+  [4, 2],
+  [5, 2],
+  [5, 1],
+  [6, 1],
+  [6, 0]
+];
+const eyePositions: number[][] = [
+  [2, 4],
+  [3, 4],
+  [4, 4],
+  [1, 3],
+  [3, 3],
+  [5, 3],
+  [0, 2],
+  [2, 2],
+  [3, 2],
+  [4, 2],
+  [6, 2],
+  [1, 1],
+  [2, 1],
+  [3, 1],
+  [5, 1],
+  [2, 0],
+  [3, 0],
+  [4, 0]
+];
+const hourglassPositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [5, 6],
+  [6, 6],
+  [1, 5],
+  [2, 5],
+  [3, 5],
+  [4, 5],
+  [5, 5],
+  [1, 4],
+  [2, 4],
+  [4, 4],
+  [5, 4],
+  [2, 3],
+  [3, 3],
+  [4, 3],
+  [1, 2],
+  [2, 2],
+  [3, 2],
+  [4, 2],
+  [5, 2],
+  [1, 1],
+  [5, 1],
+  [0, 0],
+  [1, 0],
+  [2, 0],
+  [3, 0],
+  [4, 0],
+  [5, 0],
+  [6, 0]
+];
+const magPositions: number[][] = [
+  [6, 6],
+  [5, 5],
+  [1, 4],
+  [2, 4],
+  [3, 4],
+  [0, 3],
+  [4, 3],
+  [0, 2],
+  [4, 2],
+  [0, 1],
+  [4, 1],
+  [1, 0],
+  [2, 0],
+  [3, 0]
+];
+const cropPositions: number[][] = [
+  [5, 6],
+  [1, 5],
+  [2, 5],
+  [3, 5],
+  [4, 5],
+  [5, 5],
+  [6, 5],
+  [1, 4],
+  [1, 3],
+  [5, 3],
+  [1, 2],
+  [5, 2],
+  [0, 1],
+  [1, 1],
+  [3, 1],
+  [4, 1],
+  [5, 1],
+  [1, 0]
+];
+const flowerPositions: number[][] = [
+  [3, 6],
+  [3, 5],
+  [2, 4],
+  [4, 4],
+  [2, 3],
+  [5, 3],
+  [1, 2],
+  [4, 2],
+  [6, 2],
+  [0, 1],
+  [2, 1],
+  [5, 1],
+  [1, 0]
+];
+const imagePositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [5, 6],
+  [6, 6],
+  [0, 5],
+  [1, 5],
+  [2, 5],
+  [3, 5],
+  [4, 5],
+  [5, 5],
+  [6, 5],
+  [0, 4],
+  [1, 4],
+  [2, 4],
+  [3, 4],
+  [5, 4],
+  [6, 4],
+  [0, 3],
+  [2, 3],
+  [6, 3],
+  [0, 2],
+  [4, 2],
+  [6, 2],
+  [0, 1],
+  [6, 1],
+  [0, 0],
+  [1, 0],
+  [2, 0],
+  [3, 0],
+  [4, 0],
+  [5, 0],
+  [6, 0]
+];
+const lassoPositions: number[][] = [
+  [1, 6],
+  [2, 5],
+  [1, 4],
+  [2, 4],
+  [0, 3],
+  [3, 3],
+  [4, 3],
+  [5, 3],
+  [0, 2],
+  [6, 2],
+  [1, 1],
+  [6, 1],
+  [2, 0],
+  [3, 0],
+  [4, 0],
+  [5, 0]
+];
+const pagePositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [5, 6],
+  [6, 6],
+  [0, 5],
+  [6, 5],
+  [0, 4],
+  [6, 4],
+  [0, 3],
+  [3, 3],
+  [4, 3],
+  [5, 3],
+  [6, 3],
+  [0, 2],
+  [3, 2],
+  [6, 2],
+  [0, 1],
+  [3, 1],
+  [5, 1],
+  [0, 0],
+  [1, 0],
+  [2, 0],
+  [3, 0],
+  [4, 0]
+];
+const wandPositions: number[][] = [
+  [6, 6],
+  [5, 5],
+  [0, 4],
+  [4, 4],
+  [2, 3],
+  [1, 2],
+  [3, 2],
+  [2, 1],
+  [0, 0],
+  [4, 0]
+];
+const bargraphPositions: number[][] = [
+  [0, 6],
+  [2, 6],
+  [4, 6],
+  [6, 6],
+  [2, 5],
+  [4, 5],
+  [6, 5],
+  [0, 4],
+  [2, 4],
+  [4, 4],
+  [6, 4],
+  [1, 3],
+  [6, 3],
+  [2, 2],
+  [4, 2],
+  [6, 2],
+  [3, 1],
+  [5, 1],
+  [6, 0]
+];
+const trefoilPositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [1, 5],
+  [2, 4],
+  [3, 4],
+  [5, 4],
+  [6, 4],
+  [2, 3],
+  [4, 3],
+  [3, 2],
+  [3, 1],
+  [3, 0]
+];
+const dialPositions: number[][] = [
+  [0, 4],
+  [6, 4],
+  [0, 3],
+  [3, 3],
+  [6, 3],
+  [0, 2],
+  [4, 2],
+  [6, 2],
+  [1, 1],
+  [5, 1],
+  [2, 0],
+  [3, 0]
+];
+const folderPositions: number[][] = [
+  [0, 5],
+  [1, 5],
+  [2, 5],
+  [3, 5],
+  [4, 5],
+  [5, 5],
+  [6, 5],
+  [0, 4],
+  [6, 4],
+  [0, 3],
+  [6, 3],
+  [0, 2],
+  [6, 2],
+  [0, 1],
+  [3, 1],
+  [4, 1],
+  [5, 1],
+  [6, 1],
+  [1, 0],
+  [2, 0]
+];
+const arrowPositions: number[][] = [
+  [0, 4],
+  [1, 3],
+  [3, 3],
+  [2, 2],
+  [4, 2],
+  [6, 2],
+  [5, 1],
+  [6, 1],
+  [4, 0],
+  [5, 0],
+  [6, 0]
+];
+const cloudPositions: number[][] = [
+  [0, 4],
+  [1, 4],
+  [2, 4],
+  [3, 4],
+  [4, 4],
+  [5, 4],
+  [6, 4],
+  [0, 3],
+  [6, 3],
+  [1, 2],
+  [5, 2],
+  [1, 1],
+  [2, 1],
+  [5, 1],
+  [3, 0],
+  [4, 0]
+];
+const commentPositions: number[][] = [
+  [1, 6],
+  [1, 5],
+  [2, 5],
+  [1, 4],
+  [3, 4],
+  [4, 4],
+  [5, 4],
+  [0, 3],
+  [6, 3],
+  [0, 2],
+  [6, 2],
+  [0, 1],
+  [6, 1],
+  [1, 0],
+  [2, 0],
+  [3, 0],
+  [4, 0],
+  [5, 0]
+];
+const filterPositions: number[][] = [
+  [2, 6],
+  [3, 6],
+  [2, 5],
+  [4, 5],
+  [2, 4],
+  [4, 4],
+  [2, 3],
+  [4, 3],
+  [1, 2],
+  [5, 2],
+  [0, 1],
+  [6, 1],
+  [0, 0],
+  [1, 0],
+  [2, 0],
+  [3, 0],
+  [4, 0],
+  [5, 0],
+  [6, 0]
+];
+const microphonePositions: number[][] = [
+  [1, 6],
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [2, 5],
+  [3, 5],
+  [1, 4],
+  [4, 4],
+  [0, 3],
+  [1, 3],
+  [4, 3],
+  [5, 3],
+  [1, 2],
+  [4, 2],
+  [1, 1],
+  [4, 1],
+  [2, 0],
+  [3, 0]
+];
+const pencilPositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [2, 6],
+  [0, 5],
+  [1, 5],
+  [3, 5],
+  [0, 4],
+  [4, 4],
+  [1, 3],
+  [5, 3],
+  [2, 2],
+  [4, 2],
+  [6, 2],
+  [3, 1],
+  [6, 1],
+  [4, 0],
+  [5, 0]
+];
+const potionPositions: number[][] = [
+  [1, 6],
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [5, 6],
+  [0, 5],
+  [6, 5],
+  [0, 4],
+  [2, 4],
+  [6, 4],
+  [1, 3],
+  [3, 3],
+  [5, 3],
+  [2, 2],
+  [4, 2],
+  [2, 1],
+  [4, 1],
+  [1, 0],
+  [2, 0],
+  [3, 0],
+  [4, 0],
+  [5, 0]
+];
+const sliderPositions: number[][] = [
+  [4, 5],
+  [0, 4],
+  [1, 4],
+  [2, 4],
+  [3, 4],
+  [5, 4],
+  [6, 4],
+  [4, 3],
+  [2, 2],
+  [0, 1],
+  [1, 1],
+  [3, 1],
+  [4, 1],
+  [5, 1],
+  [6, 1],
+  [2, 0]
+];
+const timelinePositions: number[][] = [
+  [3, 6],
+  [0, 5],
+  [1, 5],
+  [3, 5],
+  [4, 5],
+  [5, 5],
+  [6, 5],
+  [0, 4],
+  [1, 4],
+  [3, 4],
+  [4, 4],
+  [5, 4],
+  [6, 4],
+  [3, 3],
+  [2, 2],
+  [4, 2],
+  [1, 1],
+  [5, 1],
+  [1, 0],
+  [2, 0],
+  [3, 0],
+  [4, 0],
+  [5, 0]
+];
+const eyedropPositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [0, 5],
+  [2, 5],
+  [1, 4],
+  [3, 4],
+  [2, 3],
+  [4, 3],
+  [6, 3],
+  [3, 2],
+  [4, 2],
+  [5, 2],
+  [4, 1],
+  [5, 1],
+  [6, 1],
+  [3, 0],
+  [5, 0],
+  [6, 0]
+];
+const adobeAPositions: number[][] = [
+  [0, 6],
+  [1, 6],
+  [2, 6],
+  [3, 6],
+  [5, 6],
+  [6, 6],
+  [1, 5],
+  [2, 5],
+  [5, 5],
+  [1, 4],
+  [2, 4],
+  [4, 4],
+  [5, 4],
+  [1, 3],
+  [2, 3],
+  [4, 3],
+  [5, 3],
+  [2, 2],
+  [3, 2],
+  [4, 2],
+  [2, 1],
+  [3, 1],
+  [4, 1]
+];
+const adobeDPositions: number[][] = [
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [5, 6],
+  [1, 5],
+  [2, 5],
+  [4, 5],
+  [5, 5],
+  [1, 4],
+  [2, 4],
+  [4, 4],
+  [5, 4],
+  [1, 3],
+  [2, 3],
+  [4, 3],
+  [5, 3],
+  [2, 2],
+  [3, 2],
+  [4, 2],
+  [5, 2],
+  [4, 1],
+  [5, 1]
+];
+const adobeOPositions: number[][] = [
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [1, 5],
+  [2, 5],
+  [4, 5],
+  [5, 5],
+  [1, 4],
+  [2, 4],
+  [4, 4],
+  [5, 4],
+  [1, 3],
+  [2, 3],
+  [4, 3],
+  [5, 3],
+  [2, 2],
+  [3, 2],
+  [4, 2]
+];
+const adobeBPositions: number[][] = [
+  [1, 6],
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [1, 5],
+  [2, 5],
+  [4, 5],
+  [5, 5],
+  [1, 4],
+  [2, 4],
+  [4, 4],
+  [5, 4],
+  [1, 3],
+  [2, 3],
+  [4, 3],
+  [5, 3],
+  [1, 2],
+  [2, 2],
+  [3, 2],
+  [4, 2],
+  [1, 1],
+  [2, 1]
+];
+const adobeEPositions: number[][] = [
+  [2, 6],
+  [3, 6],
+  [4, 6],
+  [1, 5],
+  [2, 5],
+  [1, 4],
+  [2, 4],
+  [3, 4],
+  [4, 4],
+  [5, 4],
+  [1, 3],
+  [2, 3],
+  [4, 3],
+  [5, 3],
+  [2, 2],
+  [3, 2],
+  [4, 2]
+];
 
 // ─────────────────────────────────────────────────────────────
-// buildCells — turn a positions list into a cells array with
-// per-cell timing (stagger, exitStart, fadeIn, fadeOut).
+// buildCells — turn a positions list ([col, row] coords on a 7×7 grid,
+// bottom-up/left-to-right within a row → stagger order) into a cells
+// array with per-cell timing (stagger, exitStart, fadeIn, fadeOut).
 //
 // stagger modes:
 //   'individual' — brush style. Each cell gets i * interval.
@@ -639,24 +659,27 @@ export const POSITIONS = {
 //     with 1-cell overlap between consecutive rows (cleaner reads).
 //   'by-row' — all cells in a row share one stagger value.
 // ─────────────────────────────────────────────────────────────
-export function buildCells(positions, options = {}) {
+export function buildCells(positions: number[][], options: BuildOptions = {}): Cell[] {
   const {staggerInterval = 2, rowOffset = 0, stagger: staggerMode = 'grouped'} = options;
-  let staggers;
+  let staggers: number[];
   if (staggerMode === 'by-row') {
     const rowsBottomUp = [...new Set(positions.map(p => p[1]))].sort((a, b) => b - a);
-    const rowStagger = Object.fromEntries(rowsBottomUp.map((r, i) => [r, i * staggerInterval]));
-    staggers = positions.map(([, row]) => rowStagger[row]);
+    const rowStagger = new Map<number, number>();
+    rowsBottomUp.forEach((r, i) => rowStagger.set(r, i * staggerInterval));
+    staggers = positions.map(([, row]) => rowStagger.get(row)!);
   } else if (staggerMode === 'grouped') {
-    const rowGroups = new Map();
+    const rowGroups = new Map<number, number[]>();
     positions.forEach(([, row], i) => {
-      if (!rowGroups.has(row)) rowGroups.set(row, []);
-      rowGroups.get(row).push(i);
+      if (!rowGroups.has(row)) {
+        rowGroups.set(row, []);
+      }
+      rowGroups.get(row)!.push(i);
     });
     const rowsBottomUp = [...rowGroups.keys()].sort((a, b) => b - a);
     staggers = new Array(positions.length);
     let rowStart = 0;
     for (const row of rowsBottomUp) {
-      const indices = rowGroups.get(row);
+      const indices = rowGroups.get(row)!;
       indices.forEach((idx, j) => {
         staggers[idx] = rowStart + j * staggerInterval;
       });
@@ -686,156 +709,213 @@ export function buildCells(positions, options = {}) {
 }
 
 // ─────────────────────────────────────────────────────────────
-// cellSets — { name: Cell[] } for every shipped icon.
+// Icons — each an independently tree-shakeable `Cell[]`.
 // ─────────────────────────────────────────────────────────────
-export const cellSets = {
-  'ai-logo': aiLogoCells,
-  brush: buildCells(POSITIONS.brush, {staggerInterval: 2, stagger: 'grouped'}),
-  eye: buildCells(POSITIONS.eye, {staggerInterval: 2, stagger: 'grouped', rowOffset: 1}),
-  hourglass: buildCells(POSITIONS.hourglass, {staggerInterval: 1, stagger: 'grouped'}),
-  mag: buildCells(POSITIONS.mag, {staggerInterval: 2, stagger: 'grouped'}),
-  crop: buildCells(POSITIONS.crop, {staggerInterval: 2, stagger: 'grouped'}),
-  flower: buildCells(POSITIONS.flower, {staggerInterval: 2, stagger: 'grouped'}),
-  image: buildCells(POSITIONS.image, {staggerInterval: 1, stagger: 'grouped'}),
-  lasso: buildCells(POSITIONS.lasso, {staggerInterval: 2, stagger: 'grouped'}),
-  page: buildCells(POSITIONS.page, {staggerInterval: 1, stagger: 'grouped'}),
-  wand: buildCells(POSITIONS.wand, {staggerInterval: 2, stagger: 'grouped'}),
-  bargraph: buildCells(POSITIONS.bargraph, {staggerInterval: 2, stagger: 'grouped'}),
-  trefoil: buildCells(POSITIONS.trefoil, {staggerInterval: 2, stagger: 'grouped'}),
-  dial: buildCells(POSITIONS.dial, {staggerInterval: 2, stagger: 'grouped', rowOffset: 1}),
-  folder: buildCells(POSITIONS.folder, {staggerInterval: 1, stagger: 'grouped', rowOffset: 1}),
-  arrow: buildCells(POSITIONS.arrow, {staggerInterval: 2, stagger: 'grouped', rowOffset: 2}),
-  cloud: buildCells(POSITIONS.cloud, {staggerInterval: 1, stagger: 'grouped', rowOffset: 1}),
-  comment: buildCells(POSITIONS.comment, {staggerInterval: 1, stagger: 'grouped'}),
-  filter: buildCells(POSITIONS.filter, {staggerInterval: 1, stagger: 'grouped'}),
-  microphone: buildCells(POSITIONS.microphone, {staggerInterval: 1, stagger: 'grouped'}),
-  pencil: buildCells(POSITIONS.pencil, {staggerInterval: 2, stagger: 'grouped'}),
-  potion: buildCells(POSITIONS.potion, {staggerInterval: 1, stagger: 'grouped'}),
-  slider: buildCells(POSITIONS.slider, {staggerInterval: 1, stagger: 'grouped', rowOffset: 1}),
-  timeline: buildCells(POSITIONS.timeline, {staggerInterval: 1, stagger: 'grouped'}),
-  eyedrop: buildCells(POSITIONS.eyedrop, {staggerInterval: 1, stagger: 'grouped'}),
-  'adobe-a': buildCells(POSITIONS['adobe-a'], {staggerInterval: 2, stagger: 'grouped'}),
-  'adobe-d': buildCells(POSITIONS['adobe-d'], {staggerInterval: 2, stagger: 'grouped'}),
-  'adobe-o': buildCells(POSITIONS['adobe-o'], {
-    staggerInterval: 2,
-    stagger: 'grouped',
-    rowOffset: -1
-  }),
-  'adobe-b': buildCells(POSITIONS['adobe-b'], {staggerInterval: 2, stagger: 'grouped'}),
-  'adobe-e': buildCells(POSITIONS['adobe-e'], {
-    staggerInterval: 2,
-    stagger: 'grouped',
-    rowOffset: -1
-  })
-};
+export const brush = /* @__PURE__ */ buildCells(brushPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const eye = /* @__PURE__ */ buildCells(eyePositions, {
+  staggerInterval: 2,
+  stagger: 'grouped',
+  rowOffset: 1
+});
+export const hourglass = /* @__PURE__ */ buildCells(hourglassPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const mag = /* @__PURE__ */ buildCells(magPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const crop = /* @__PURE__ */ buildCells(cropPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const flower = /* @__PURE__ */ buildCells(flowerPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const image = /* @__PURE__ */ buildCells(imagePositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const lasso = /* @__PURE__ */ buildCells(lassoPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const page = /* @__PURE__ */ buildCells(pagePositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const wand = /* @__PURE__ */ buildCells(wandPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const bargraph = /* @__PURE__ */ buildCells(bargraphPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const trefoil = /* @__PURE__ */ buildCells(trefoilPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const dial = /* @__PURE__ */ buildCells(dialPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped',
+  rowOffset: 1
+});
+export const folder = /* @__PURE__ */ buildCells(folderPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped',
+  rowOffset: 1
+});
+export const arrow = /* @__PURE__ */ buildCells(arrowPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped',
+  rowOffset: 2
+});
+export const cloud = /* @__PURE__ */ buildCells(cloudPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped',
+  rowOffset: 1
+});
+export const comment = /* @__PURE__ */ buildCells(commentPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const filter = /* @__PURE__ */ buildCells(filterPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const microphone = /* @__PURE__ */ buildCells(microphonePositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const pencil = /* @__PURE__ */ buildCells(pencilPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const potion = /* @__PURE__ */ buildCells(potionPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const slider = /* @__PURE__ */ buildCells(sliderPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped',
+  rowOffset: 1
+});
+export const timeline = /* @__PURE__ */ buildCells(timelinePositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const eyedrop = /* @__PURE__ */ buildCells(eyedropPositions, {
+  staggerInterval: 1,
+  stagger: 'grouped'
+});
+export const adobeA = /* @__PURE__ */ buildCells(adobeAPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const adobeD = /* @__PURE__ */ buildCells(adobeDPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const adobeO = /* @__PURE__ */ buildCells(adobeOPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped',
+  rowOffset: -1
+});
+export const adobeB = /* @__PURE__ */ buildCells(adobeBPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped'
+});
+export const adobeE = /* @__PURE__ */ buildCells(adobeEPositions, {
+  staggerInterval: 2,
+  stagger: 'grouped',
+  rowOffset: -1
+});
 
 // ─────────────────────────────────────────────────────────────
-// LOADER_PRESETS — named sequences of icons (loops through them).
+// Presets — sequences (`Cell[][]`) that loop through their icons.
+// Importing a preset pulls in only the icons it references.
 // ─────────────────────────────────────────────────────────────
-export const LOADER_PRESETS = {
-  cc: {
-    label: 'CC Loader',
-    icons: [
-      'ai-logo',
-      'brush',
-      'wand',
-      'crop',
-      'eye',
-      'hourglass',
-      'adobe-a',
-      'adobe-d',
-      'adobe-o',
-      'adobe-b',
-      'adobe-e',
-      'eyedrop'
-    ]
-  },
-  dc: {
-    label: 'DC Loader',
-    icons: [
-      'ai-logo',
-      'page',
-      'trefoil',
-      'image',
-      'cloud',
-      'mag',
-      'adobe-a',
-      'adobe-d',
-      'adobe-o',
-      'adobe-b',
-      'adobe-e',
-      'pencil'
-    ]
-  },
-  exp: {
-    label: 'EXP Loader',
-    icons: [
-      'ai-logo',
-      'bargraph',
-      'dial',
-      'filter',
-      'slider',
-      'folder',
-      'adobe-a',
-      'adobe-d',
-      'adobe-o',
-      'adobe-b',
-      'adobe-e',
-      'arrow'
-    ]
-  },
-  analyze: {
-    label: 'Analyze Image',
-    icons: ['flower', 'image', 'brush', 'eye', 'eyedrop', 'wand', 'lasso', 'crop']
-  },
-  mega: {
-    label: 'Mega Loader',
-    icons: [
-      'ai-logo',
-      'brush',
-      'wand',
-      'crop',
-      'eye',
-      'hourglass',
-      'page',
-      'trefoil',
-      'image',
-      'eyedrop',
-      'mag',
-      'bargraph',
-      'dial',
-      'folder',
-      'flower',
-      'lasso',
-      'adobe-a',
-      'adobe-d',
-      'adobe-o',
-      'adobe-b',
-      'adobe-e',
-      'arrow',
-      'cloud',
-      'comment',
-      'filter',
-      'microphone',
-      'pencil',
-      'potion',
-      'slider',
-      'timeline'
-    ]
-  }
-};
+export const cc: Cell[][] = [
+  aiLogo,
+  brush,
+  wand,
+  crop,
+  eye,
+  hourglass,
+  adobeA,
+  adobeD,
+  adobeO,
+  adobeB,
+  adobeE,
+  eyedrop
+];
 
-// ─────────────────────────────────────────────────────────────
-// ICON_LABELS — display-name overrides for icons whose key
-// doesn't read nicely (e.g. microphone → "mic", ai-logo → "ai logo").
-// ─────────────────────────────────────────────────────────────
-export const ICON_LABELS = {
-  'ai-logo': 'ai logo',
-  microphone: 'mic'
-};
+export const dc: Cell[][] = [
+  aiLogo,
+  page,
+  trefoil,
+  image,
+  cloud,
+  mag,
+  adobeA,
+  adobeD,
+  adobeO,
+  adobeB,
+  adobeE,
+  pencil
+];
 
-// ─────────────────────────────────────────────────────────────
-// Public icon name list — handy for consumers building pickers.
-// ─────────────────────────────────────────────────────────────
-export const ICON_NAMES = Object.keys(cellSets);
-export const PRESET_NAMES = Object.keys(LOADER_PRESETS);
+export const exp: Cell[][] = [
+  aiLogo,
+  bargraph,
+  dial,
+  filter,
+  slider,
+  folder,
+  adobeA,
+  adobeD,
+  adobeO,
+  adobeB,
+  adobeE,
+  arrow
+];
+
+export const analyze: Cell[][] = [flower, image, brush, eye, eyedrop, wand, lasso, crop];
+
+export const mega: Cell[][] = [
+  aiLogo,
+  brush,
+  wand,
+  crop,
+  eye,
+  hourglass,
+  page,
+  trefoil,
+  image,
+  eyedrop,
+  mag,
+  bargraph,
+  dial,
+  folder,
+  flower,
+  lasso,
+  adobeA,
+  adobeD,
+  adobeO,
+  adobeB,
+  adobeE,
+  arrow,
+  cloud,
+  comment,
+  filter,
+  microphone,
+  pencil,
+  potion,
+  slider,
+  timeline
+];
diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
index bbc0e162dfa..3baf22f9c5c 100644
--- a/packages/@react-spectrum/ai/src/loader/react.tsx
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -17,8 +17,7 @@
 // advance via a single timer — only the current icon's cells are in the
 // DOM. A single-icon loader stays a pure infinite CSS loop with no JS.
 
-import * as React from 'react';
-import {cellSets, LOADER_PRESETS} from './data.js';
+import {aiLogo, type Cell} from './data.js';
 import {
   EASE,
   FPS,
@@ -30,6 +29,7 @@ import {
   Y_OVERSHOOT,
   Y_START
 } from './runtime.js';
+import * as React from 'react';
 
 const DURATION_MS = (TOTAL_FRAMES / FPS) * 1000;
 
@@ -106,52 +106,56 @@ function cellOpacityKeyframes(name, c) {
   ]);
 }
 
-const cssCache = new Map();
-function keyframesFor(iconName, cells) {
-  let css = cssCache.get(iconName);
-  if (!css) {
+// Stable per-icon id, keyed by the cell-array reference (icons are
+// module-level consts, so the reference is stable). Used to namespace
+// each icon's @keyframes and to cache its generated CSS.
+let nextIconId = 0;
+const iconIds = new WeakMap<object, string>();
+function iconId(cells: object): string {
+  let id = iconIds.get(cells);
+  if (id === undefined) {
+    id = `pl${nextIconId++}`;
+    iconIds.set(cells, id);
+  }
+  return id;
+}
+
+const cssCache = new WeakMap<object, string>();
+function keyframesFor(cells: Cell[]): string {
+  let css = cssCache.get(cells);
+  if (css === undefined) {
+    const id = iconId(cells);
     css = cells
-      .map(
-        (c, i) =>
-          cellYKeyframes(`pl-${iconName}-${i}-y`, c) +
-          cellOpacityKeyframes(`pl-${iconName}-${i}-o`, c)
-      )
+      .map((c, i) => cellYKeyframes(`${id}-${i}-y`, c) + cellOpacityKeyframes(`${id}-${i}-o`, c))
       .join('');
-    cssCache.set(iconName, css);
+    cssCache.set(cells, css);
   }
   return css;
 }
 
-// Resolve a sequence of icon names from the icon-selection props, in
-// precedence order: explicit `icons` list, single `icon`, then `preset`.
-// Falls back to the ai-logo. Unknown names are dropped.
-function resolveSequence({preset, icon, icons}): string[] {
-  if (icons && icons.length) {
-    const names = icons.filter(n => cellSets[n]);
-    if (names.length) return names;
-  }
-  if (icon && cellSets[icon]) return [icon];
-  if (preset && LOADER_PRESETS[preset]) {
-    const names = LOADER_PRESETS[preset].icons.filter(n => cellSets[n]);
-    if (names.length) return names;
-  }
-  return ['ai-logo'];
+interface PixelLoaderProps {
+  size?: number;
+  playing?: boolean;
+  icon?: Cell[] | Cell[][];
+  speed?: number;
+  color?: string;
+  className?: string;
+  style?: React.CSSProperties;
 }
 
 // ─────────────────────────────────────────────────────────────
 // Component. Only `size` and `playing` are load-bearing for the
-// PromptField usage; `icon`/`icons`/`preset`, `speed`, `color`,
+// PromptField usage. `icon` takes a single icon (`Cell[]`) or a
+// sequence (`Cell[][]`) imported from ./data; `speed`, `color`,
 // `className`, and `style` are supported because they're free. When not
 // playing, the loader renders a single static poster frame (no
 // animation).
 // ─────────────────────────────────────────────────────────────
-export function PixelLoader(props) {
+export function PixelLoader(props: PixelLoaderProps) {
   const {
     size = 64,
     playing = true,
-    preset,
-    icon,
-    icons,
+    icon = aiLogo,
     speed = 1,
     color = 'currentColor',
     className,
@@ -159,22 +163,26 @@ export function PixelLoader(props) {
     ...rest
   } = props;
 
-  // The icon sequence (1+ names). A single-icon sequence loops forever
-  // in pure CSS; a multi-icon sequence advances one icon per cycle via
-  // the timer below, so only the current icon's cells are ever in the DOM.
-  const sequence = resolveSequence({preset, icon, icons});
+  // Normalize to a sequence. A `Cell[][]` (first element is itself an
+  // array) is already a sequence; a flat `Cell[]` is wrapped. A single-
+  // icon sequence loops forever in pure CSS; a multi-icon sequence
+  // advances one icon per cycle via the timer below, so only the current
+  // icon's cells are ever in the DOM.
+  const sequence = React.useMemo(
+    () => (Array.isArray(icon[0]) ? icon : [icon]) as Cell[][],
+    [icon]
+  );
   const isSequence = sequence.length > 1;
   const duration = DURATION_MS / (speed || 1);
 
   // `tick` increments once per cycle; the current icon is `tick % len`.
   // It's also the remount key, so each swap restarts the animation cleanly.
   const [tick, setTick] = React.useState(0);
-  const seqKey = sequence.join(',');
 
-  // Restart the sequence from the first icon whenever the sequence changes.
+  // Restart from the first icon whenever the sequence changes.
   React.useEffect(() => {
     setTick(0);
-  }, [seqKey]);
+  }, [sequence]);
 
   // Advance the sequence one icon per cycle while playing. Single-icon
   // loaders never start a timer — they're a pure infinite CSS loop.
@@ -184,11 +192,11 @@ export function PixelLoader(props) {
     }
     const id = setInterval(() => setTick(t => t + 1), duration);
     return () => clearInterval(id);
-  }, [playing, isSequence, duration, seqKey]);
+  }, [playing, isSequence, duration, sequence]);
 
-  const iconName = sequence[isSequence ? tick % sequence.length : 0];
-  const cells = cellSets[iconName];
-  const css = keyframesFor(iconName, cells);
+  const cells = sequence[isSequence ? tick % sequence.length : 0];
+  const animId = iconId(cells);
+  const css = keyframesFor(cells);
   // Sequences play each icon once and hold its faded-out final frame
   // (`forwards`) until the next remount; a single icon loops forever.
   const iteration = isSequence ? '1 forwards' : 'infinite';
@@ -206,9 +214,7 @@ export function PixelLoader(props) {
         width: size,
         height: size,
         lineHeight: 0,
-        // Cells fly far outside the box (off-top on entry, off-bottom on
-        // exit) — clip them, like the SVG viewBox did.
-        overflow: 'hidden',
+        overflow: 'clip',
         position: 'relative',
         ...style
       }}
@@ -230,8 +236,8 @@ export function PixelLoader(props) {
           const cellStyle = playing
             ? {
                 animation:
-                  `pl-${iconName}-${i}-y ${duration}ms linear ${iteration}, ` +
-                  `pl-${iconName}-${i}-o ${duration}ms linear ${iteration}`,
+                  `${animId}-${i}-y ${duration}ms linear ${iteration}, ` +
+                  `${animId}-${i}-o ${duration}ms linear ${iteration}`,
                 willChange: 'transform, opacity'
               }
             : {
diff --git a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
index 5db564e3d4e..16c8ab28877 100644
--- a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
@@ -35,6 +35,7 @@ import {
   Text
 } from '@react-spectrum/s2/Menu';
 import Data from '@react-spectrum/s2/icons/Data';
+import * as data from '../src/loader/data';
 import {iconStyle, style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {Image} from '@react-spectrum/s2/Image';
 import LinkIcon from '@react-spectrum/s2/icons/Link';
@@ -55,13 +56,30 @@ const meta: Meta<typeof PromptField> = {
   tags: ['autodocs'],
   argTypes: {
     ...categorizeArgTypes('Events', events),
-    children: {table: {disable: true}}
+    children: {table: {disable: true}},
+    brand: {
+      control: 'color',
+      description:
+        'Sets the --brand custom property to retheme the PromptField. Only the hue is used; lightness and chroma come from the design tokens.',
+      table: {category: 'Theming'}
+    },
+    pixelLoader: {
+      control: 'select',
+      options: Object.keys(data),
+      description: 'Sets the icon to use for the pixel loader.',
+      table: {category: 'Theming'}
+    }
   },
-  args: {...getActionArgs(events)},
+  args: {brand: 'rgb(236, 105, 255)', pixelLoader: 'aiLogo', ...getActionArgs(events)},
   title: 'AI/PromptField',
   decorators: [
-    Story => (
-      <div style={{width: '800px'}}>
+    (Story, {args}) => (
+      <div
+        style={{
+          width: '800px',
+          // @ts-ignore
+          '--brand': args.brand
+        }}>
         <Story />
       </div>
     )
@@ -227,7 +245,10 @@ export const Everything = args => {
           );
         }}
       </PromptFieldAttachmentList>
-      <PromptTokenField completionTrigger={/(?<=^|\s)[@/]/} renderCompletions={renderCompletions}>
+      <PromptTokenField
+        completionTrigger={/(?<=^|\s)[@/]/}
+        renderCompletions={renderCompletions}
+        pixelLoader={data[args.pixelLoader]}>
         {segment => (
           <PromptToken>
             {icons[segment.value?.type]}

From f5dda5ce080a0460011ecb8945aafec11055de21 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Mon, 22 Jun 2026 15:45:21 -0700
Subject: [PATCH 08/34] Implement brand color theming

---
 .../ai/src/PromptFieldContainer.tsx           | 16 +++-
 .../@react-spectrum/ai/src/tokens.macro.ts    | 94 ++++++++++++++++++-
 .../ai/stories/PromptField.stories.tsx        |  2 +
 3 files changed, 106 insertions(+), 6 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
index 31c2cd545dc..b63a11481ef 100644
--- a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -1,10 +1,12 @@
-import {color, css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
+  brand,
+  defaultBrand,
   defineProperties,
   outerBorderStops,
   stops,
   token
 } from './tokens.macro' with {type: 'macro'};
+import {color, css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {getEventTarget} from 'react-aria/private/utils/shadowdom/DOMFunctions';
 import {Group, GroupProps} from 'react-aria-components/Group';
 import {isFocusable} from 'react-aria/private/utils/isFocusable';
@@ -12,7 +14,17 @@ import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
 
 const STATE_TRANSITION = '700ms cubic-bezier(0.32, 0.72, 0, 1)';
 
+/* The brand color drives the hue of the entire component. Override --brand on
+   the PromptField (or any ancestor) to retheme it — all gradients, shadows, and
+   borders are derived from this hue via OKLCH relative colors in tokens.macro.
+   The default is the fuchsia primary, rgb(236, 105, 255). */
 defineProperties(`
+  @property --brand {
+    syntax: '<color>';
+    initial-value: ${defaultBrand()};
+    inherits: true;
+  }
+
   @property --con-hue-opacity {
     syntax: '<percentage>';
     initial-value: 0%;
@@ -78,7 +90,7 @@ const containerBackground = css(`
 
   --border-color: ${token(`container.border.default`)};
   --inset-shadow-color: ${color('transparent-white-50')};
-  --drop-shadow-color: ${color('fuchsia-900/5')};
+  --drop-shadow-color: light-dark(${brand(0.5826, 0.2265, -0.4, 0.05)}, ${brand(0.6617, 0.2508, -0.5, 0.05)});
 
   box-shadow:
     inset 0 0 0 1px var(--border-color),
diff --git a/packages/@react-spectrum/ai/src/tokens.macro.ts b/packages/@react-spectrum/ai/src/tokens.macro.ts
index dce27ced150..43fe81fa6f3 100644
--- a/packages/@react-spectrum/ai/src/tokens.macro.ts
+++ b/packages/@react-spectrum/ai/src/tokens.macro.ts
@@ -1,6 +1,92 @@
 import {color} from '@react-spectrum/s2/style';
 import tokens from './tokens.merged.json';
 
+// Colors below this OKLCH chroma are treated as neutral (white/black/gray) and
+// left untouched — rotating their hue would tint a surface that's meant to be gray.
+const NEUTRAL_CHROMA = 0.015;
+
+function srgbToLinear(c: number) {
+  c /= 255;
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+function rgbToOklch(r: number, g: number, b: number): [number, number, number] {
+  let lr = srgbToLinear(r),
+    lg = srgbToLinear(g),
+    lb = srgbToLinear(b);
+  let l = 0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb;
+  let m = 0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb;
+  let s = 0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb;
+  let l_ = Math.cbrt(l),
+    m_ = Math.cbrt(m),
+    s_ = Math.cbrt(s);
+  let L = 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_;
+  let A = 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_;
+  let B = 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_;
+  let C = Math.sqrt(A * A + B * B);
+  let H = (Math.atan2(B, A) * 180) / Math.PI;
+  if (H < 0) {
+    H += 360;
+  }
+  return [L, C, H];
+}
+
+function parseRgb(value: string): [number, number, number] {
+  let match = value.match(/rgba?\(([^)]+)\)/);
+  if (!match) {
+    throw new Error(`Expected an rgb color, got: ${value}`);
+  }
+  let [r, g, b] = match[1].split(',').map(x => parseFloat(x.trim()));
+  return [r, g, b];
+}
+
+// The brand anchor: the fuchsia primary that the rest of the palette fans out
+// from, taken from the most saturated brand-colored token (the outer border hue).
+// Every hue-bearing token stores its hue as an offset from this anchor, so the
+// whole palette can be rotated to a new brand color by overriding the --brand
+// custom property.
+const BRAND_REF = rgbToOklch(
+  ...parseRgb(tokens['outer-border'].gradient['ob-hue']['stop-1'].light)
+);
+const BRAND_REF_HUE = BRAND_REF[2];
+
+// The default --brand color, derived from the same anchor token so the default
+// theme renders identically to the source design tokens.
+export function defaultBrand() {
+  let [L, C, H] = BRAND_REF;
+  return `oklch(${Math.round(L * 1e4) / 1e4} ${Math.round(C * 1e4) / 1e4} ${Math.round(H * 10) / 10})`;
+}
+
+// Builds a CSS relative color derived from --brand: it keeps the given lightness
+// and chroma but takes the hue from the brand color (offset by hueOffset degrees).
+// This preserves each token's role while letting the brand drive the overall hue.
+export function brand(l: number, c: number, hueOffset: number, alpha = 1) {
+  let hue = hueOffset === 0 ? 'h' : `calc(h + ${hueOffset})`;
+  let a = alpha < 1 ? ` / ${alpha}` : '';
+  return `oklch(from var(--brand) ${l} ${c} ${hue}${a})`;
+}
+
+// Converts a single token color value to a brand-relative color, unless it's a
+// neutral (kept as-is) or not a color at all (e.g. an opacity number, kept as-is).
+function convertColor(value: any) {
+  if (typeof value !== 'string') {
+    return value;
+  }
+  let match = value.match(/rgba?\(([^)]+)\)/);
+  if (!match) {
+    return value;
+  }
+  let parts = match[1].split(',').map(x => parseFloat(x.trim()));
+  let [r, g, b] = parts;
+  let alpha = parts[3] ?? 1;
+  let [L, C, H] = rgbToOklch(r, g, b);
+  if (C < NEUTRAL_CHROMA) {
+    return value;
+  }
+  let offset = Math.round((H - BRAND_REF_HUE) * 10) / 10;
+  return brand(Math.round(L * 1e4) / 1e4, Math.round(C * 1e4) / 1e4, offset, alpha);
+}
+
 export function token(name: string) {
   let token = name.split('.').reduce((acc, curr) => {
     let res = acc[curr];
@@ -10,13 +96,13 @@ export function token(name: string) {
     return res;
   }, tokens) as any;
   if (token?.light && token.dark) {
-    return `light-dark(${token.light}, ${token.dark})`;
+    return `light-dark(${convertColor(token.light)}, ${convertColor(token.dark)})`;
   } else if (token?.light) {
-    return token.light;
+    return convertColor(token.light);
   } else if (token?.dark) {
-    return token.dark;
+    return convertColor(token.dark);
   } else {
-    return token.value ?? token;
+    return convertColor(token.value ?? token);
   }
 }
 
diff --git a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
index 16c8ab28877..f6fbe389af7 100644
--- a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
@@ -77,6 +77,8 @@ const meta: Meta<typeof PromptField> = {
       <div
         style={{
           width: '800px',
+          maxWidth: '90vw',
+          margin: '0 auto',
           // @ts-ignore
           '--brand': args.brand
         }}>

From 2a94c16db4edc5d874f65417eddc902117913519 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Mon, 22 Jun 2026 16:08:46 -0700
Subject: [PATCH 09/34] simplify poster frame

---
 .../@react-spectrum/ai/src/loader/react.tsx   |  89 ++++++------
 .../@react-spectrum/ai/src/loader/runtime.ts  | 137 ------------------
 2 files changed, 46 insertions(+), 180 deletions(-)
 delete mode 100644 packages/@react-spectrum/ai/src/loader/runtime.ts

diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
index 3baf22f9c5c..ae49ec752fd 100644
--- a/packages/@react-spectrum/ai/src/loader/react.tsx
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -8,31 +8,39 @@
 // the CPU because additive/stacked animations fall back to the main
 // thread — composited residency matters far more than keyframe count.)
 //
-// The curve math in runtime.ts is the single source of truth: the
-// keyframe values/easings below are emitted from it, and the paused
-// "poster" frame is rendered from the same samplers, so playing and
-// paused states match exactly.
+// The easing control points and Y offsets are the single
+// source of truth — the keyframes below are emitted from them. When not
+// playing, cells render with no animation: settled (translateY 0) and
+// opaque, i.e. the fully-assembled poster pose.
 //
 // Multi-icon sequences (presets) play one icon per 2.4s cycle and
 // advance via a single timer — only the current icon's cells are in the
 // DOM. A single-icon loader stays a pure infinite CSS loop with no JS.
 
-import {aiLogo, type Cell} from './data.js';
-import {
-  EASE,
-  FPS,
-  getOpacity,
-  getY,
-  POSTER_FRAME,
-  TOTAL_FRAMES,
-  Y_EXIT,
-  Y_OVERSHOOT,
-  Y_START
-} from './runtime.js';
+import {aiLogo, type Cell} from './data';
 import * as React from 'react';
 
+// Easing control points, formatted into `cubic-bezier(...)` in the
+// generated keyframes. `fade` is intentionally linear — its control
+// points lie on y=x.
+const EASE = {
+  drop: [0.333, 0, 0.667, 1],
+  recover: [0.333, 0, 0.833, 1],
+  exit: [0.563, 0, 0.906, 0.757],
+  fade: [0.167, 0.167, 0.833, 0.833]
+};
+
+// One full cycle is 72 frames at 30fps (2.4s).
+const TOTAL_FRAMES = 72;
+const FPS = 30;
 const DURATION_MS = (TOTAL_FRAMES / FPS) * 1000;
 
+// Per-cell vertical offsets in the 1000-unit VIEWBOX space: start off
+// the top, overshoot just past the settled position, exit off the bottom.
+const Y_START = -876.156;
+const Y_OVERSHOOT = 18;
+const Y_EXIT = 1015;
+
 // The animation lives in a fixed VIEWBOX-sized coordinate space (matching
 // the source Lottie's 1000×1000 canvas) that is scaled down to the
 // rendered `size`. Cells are absolutely positioned in this space, so all
@@ -42,10 +50,10 @@ const VIEWBOX = 1000;
 const CELL = 100;
 
 // ─────────────────────────────────────────────────────────────
-// CSS @keyframes generation. Each piecewise segment of the runtime
-// curves becomes one keyframe stop whose `animation-timing-function`
-// is the matching cubic-bezier — CSS interpolates it identically to
-// `getY`/`getOpacity`.
+// CSS @keyframes generation. Each piecewise segment of the motion
+// becomes one keyframe stop whose `animation-timing-function` is the
+// matching cubic-bezier (from EASE), so the browser interpolates the
+// drop/recover/exit/fade curves natively.
 // ─────────────────────────────────────────────────────────────
 
 function pct(frame) {
@@ -232,33 +240,28 @@ export function PixelLoader(props: PixelLoaderProps) {
           transformOrigin: '0 0',
           transform: `scale(${scaleFactor})`
         }}>
-        {cells.map((c, i) => {
-          const cellStyle = playing
-            ? {
+        {cells.map((c, i) => (
+          // When not playing, cells render with no animation — at their
+          // settled position (left/top) and fully opaque, i.e. the
+          // fully-assembled poster pose.
+          <div
+            key={i}
+            style={{
+              position: 'absolute',
+              left: c.cx - CELL / 2,
+              top: c.cy - CELL / 2,
+              width: CELL,
+              height: CELL,
+              backgroundColor: color,
+              ...(playing && {
                 animation:
                   `${animId}-${i}-y ${duration}ms linear ${iteration}, ` +
                   `${animId}-${i}-o ${duration}ms linear ${iteration}`,
                 willChange: 'transform, opacity'
-              }
-            : {
-                transform: `translateY(${getY(POSTER_FRAME - c.stagger, c.exitStart - c.stagger)}px)`,
-                opacity: getOpacity(POSTER_FRAME, c)
-              };
-          return (
-            <div
-              key={i}
-              style={{
-                position: 'absolute',
-                left: c.cx - CELL / 2,
-                top: c.cy - CELL / 2,
-                width: CELL,
-                height: CELL,
-                backgroundColor: color,
-                ...cellStyle
-              }}
-            />
-          );
-        })}
+              })
+            }}
+          />
+        ))}
       </div>
     </div>
   );
diff --git a/packages/@react-spectrum/ai/src/loader/runtime.ts b/packages/@react-spectrum/ai/src/loader/runtime.ts
deleted file mode 100644
index c1cb9325cec..00000000000
--- a/packages/@react-spectrum/ai/src/loader/runtime.ts
+++ /dev/null
@@ -1,137 +0,0 @@
-// Pure animation model for the pixel-fall loader, ported from the
-// standalone HTML export in experiments/pixel-fall-animation/index.html.
-//
-// These curves are the single source of truth for both the CSS
-// @keyframes generated in react.tsx (the playing animation) and the
-// static poster-frame render (the paused state). The animation itself
-// is driven natively by the browser via CSS animations — there is no
-// rAF loop. Visual parity with the playground is the load-bearing test.
-
-// ─────────────────────────────────────────────────────────────
-// Cubic-bezier easing — P0=(0,0), P3=(1,1); returns y for x ∈ [0,1].
-// ─────────────────────────────────────────────────────────────
-export function cubicBezier(p1x, p1y, p2x, p2y) {
-  const sampleX = t => 3 * (1 - t) * (1 - t) * t * p1x + 3 * (1 - t) * t * t * p2x + t * t * t;
-  const sampleY = t => 3 * (1 - t) * (1 - t) * t * p1y + 3 * (1 - t) * t * t * p2y + t * t * t;
-  const sampleDX = t =>
-    3 * (1 - t) * (1 - t) * p1x + 6 * (1 - t) * t * (p2x - p1x) + 3 * t * t * (1 - p2x);
-  function solve(x) {
-    let t = x;
-    for (let i = 0; i < 8; i++) {
-      const cx = sampleX(t) - x;
-      if (Math.abs(cx) < 1e-6) return t;
-      const dx = sampleDX(t);
-      if (Math.abs(dx) < 1e-6) break;
-      t -= cx / dx;
-    }
-    let lo = 0;
-    let hi = 1;
-    while (hi - lo > 1e-6) {
-      const m = (lo + hi) / 2;
-      if (sampleX(m) < x) lo = m;
-      else hi = m;
-    }
-    return (lo + hi) / 2;
-  }
-  return x => sampleY(solve(Math.max(0, Math.min(1, x))));
-}
-
-// Easing control points — shared by the JS samplers below and the
-// `cubic-bezier(...)` strings emitted into CSS, so the two can never
-// drift. Native CSS solves these the same way `cubicBezier` does, so
-// the playing animation matches the poster frame exactly.
-export const EASE = {
-  drop: [0.333, 0, 0.667, 1],
-  recover: [0.333, 0, 0.833, 1],
-  exit: [0.563, 0, 0.906, 0.757],
-  scaleUp: [0.333, 0, 0.378, 0.765],
-  scaleDown: [0.253, -0.027, 0.97, 0.045],
-  fade: [0.167, 0.167, 0.833, 0.833]
-} as const;
-
-export const easeDrop = cubicBezier(...EASE.drop);
-export const easeRecover = cubicBezier(...EASE.recover);
-export const easeExit = cubicBezier(...EASE.exit);
-export const easeScaleUp = cubicBezier(...EASE.scaleUp);
-export const easeScaleDown = cubicBezier(...EASE.scaleDown);
-export const easeFade = cubicBezier(...EASE.fade);
-
-// ─────────────────────────────────────────────────────────────
-// Timing constants — one full cycle is 72 frames at 30fps (2.4s).
-// ─────────────────────────────────────────────────────────────
-export const TOTAL_FRAMES = 72;
-export const FPS = 30;
-
-// ─────────────────────────────────────────────────────────────
-// Per-cell vertical offset from settled position (data3.json kfs).
-// ─────────────────────────────────────────────────────────────
-export const Y_START = -876.156;
-export const Y_OVERSHOOT = 18;
-export const Y_EXIT = 1015;
-
-export function getY(localT, exitLocal) {
-  if (localT < 0) return Y_START;
-  if (localT < 10) return Y_START + (Y_OVERSHOOT - Y_START) * easeDrop(localT / 10);
-  if (localT < 13) return Y_OVERSHOOT + (0 - Y_OVERSHOOT) * easeRecover((localT - 10) / 3);
-  if (localT < exitLocal) return 0;
-  if (localT < exitLocal + 12) return Y_EXIT * easeExit((localT - exitLocal) / 12);
-  return Y_EXIT;
-}
-
-// ─────────────────────────────────────────────────────────────
-// Global scale curve — cells bloom from a slightly smaller starting
-// scale up to their natural footprint (1.0) at POSTER_FRAME, hold
-// there for a few frames, then descend toward the exit pose.
-//
-// Shape:
-//   compT ∈ [0, 38)   — grow 0.92 → 1.0   (anticipation then bloom)
-//   compT ∈ [38, 44)  — plateau at 1.0     (POSTER_FRAME = 42 sits here)
-//   compT ∈ [44, 83)  — descend 1.0 → 0.74991
-//   compT ≥ 83        — frozen at 0.74991
-//
-// Growing into 1.0 (instead of overshooting above and snapping back
-// down) keeps the curve C0-continuous across the plateau boundary and
-// avoids the visible scale pop that the earlier overshoot-then-snap
-// shape caused. `getGlobalScale(POSTER_FRAME) === 1.0` exactly, so the
-// paused poster render is literally a single frame of the playing
-// animation — no special-cased override needed.
-// ─────────────────────────────────────────────────────────────
-export const SCALE_START = 0.92;
-export const SCALE_END = 74.991 / 100;
-export const PLATEAU_START = 38;
-export const PLATEAU_END = 44;
-
-export function getGlobalScale(compT) {
-  if (compT < 0) return SCALE_START;
-  if (compT < PLATEAU_START) {
-    return SCALE_START + (1 - SCALE_START) * easeScaleUp(compT / PLATEAU_START);
-  }
-  if (compT < PLATEAU_END) return 1;
-  if (compT < 83) {
-    const t = (compT - PLATEAU_END) / (83 - PLATEAU_END);
-    return 1 + (SCALE_END - 1) * easeScaleDown(t);
-  }
-  return SCALE_END;
-}
-
-// ─────────────────────────────────────────────────────────────
-// Per-cell opacity from data3.json (4 keyframes per cell).
-// ─────────────────────────────────────────────────────────────
-export function getOpacity(compT, cell) {
-  const [fi0, fi1] = cell.fadeIn;
-  const [fo0, fo1] = cell.fadeOut;
-  if (compT < fi0) return 0;
-  if (compT < fi1) return easeFade((compT - fi0) / (fi1 - fi0));
-  if (compT < fo0) return 1;
-  if (compT < fo1) return 1 - easeFade((compT - fo0) / (fo1 - fo0));
-  return 0;
-}
-
-// ─────────────────────────────────────────────────────────────
-// Poster frame — the rest-pose compFrame for the paused render. Sits
-// inside the plateau region of `getGlobalScale`, so the curve
-// naturally evaluates to 1.0 here and the paused render is just a
-// literal single frame of the playing animation — no scale pop when
-// toggling `playing`.
-// ─────────────────────────────────────────────────────────────
-export const POSTER_FRAME = 42;

From 97c411f39e3e19b669f5ce61f2051d6ba18d9558 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 13:24:36 -0700
Subject: [PATCH 10/34] update token styling

---
 .../@react-spectrum/ai/src/PromptField.tsx     | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index fc397077415..231522bf1d1 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -27,7 +27,7 @@ import {
   useRef,
   useState
 } from 'react';
-import {css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {color, css, space, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
   Direction,
   Position,
@@ -446,18 +446,24 @@ export function PromptToken(props: PromptTokenProps) {
     <Token
       {...props}
       className={style({
+        font: 'ui',
         backgroundColor: {
-          default: 'blue-300',
+          default: 'transparent-overlay-1000/10',
           isSelected: 'blue-800',
           '::selection': 'transparent'
         },
         color: {
-          default: 'blue-1000',
+          default: 'body',
           isSelected: 'white'
         },
-        borderRadius: 'sm',
-        paddingX: 4,
-        paddingY: 2,
+        outlineStyle: 'solid',
+        outlineWidth: 1,
+        outlineColor: 'transparent-overlay-1000/10',
+        outlineOffset: -1,
+        borderRadius: 'pill',
+        boxShadow: `[inset 0 24px 32px 0 ${color('transparent-white-50')}, 0 8px 32px 0 ${color('transparent-black-50')}]`,
+        paddingX: 8,
+        paddingY: 4,
         lineHeight: '[1em]',
         cursor: 'default',
         '--iconPrimary': {

From 9221bb7b6d1dadbf33003f4b94add9291e59fc3c Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 13:34:08 -0700
Subject: [PATCH 11/34] Fix focus state to only handle trusted events

---
 .../@react-spectrum/ai/src/PromptField.tsx    |  2 +-
 .../ai/src/PromptFieldContainer.tsx           | 24 +++++++++++++++----
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index 231522bf1d1..ac36b899923 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -17,6 +17,7 @@ import {Autocomplete} from 'react-aria-components/Autocomplete';
 import {Button} from '@react-spectrum/s2/Button';
 import {Cell} from './loader/data';
 import {CenterBaseline} from '@react-spectrum/s2/CenterBaseline';
+import {color, css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
   createContext,
   createRef,
@@ -27,7 +28,6 @@ import {
   useRef,
   useState
 } from 'react';
-import {color, css, space, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
   Direction,
   Position,
diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
index b63a11481ef..c5114c04a81 100644
--- a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -11,6 +11,7 @@ import {getEventTarget} from 'react-aria/private/utils/shadowdom/DOMFunctions';
 import {Group, GroupProps} from 'react-aria-components/Group';
 import {isFocusable} from 'react-aria/private/utils/isFocusable';
 import {mergeStyles} from '@react-spectrum/s2/mergeStyles';
+import {useState} from 'react';
 
 const STATE_TRANSITION = '700ms cubic-bezier(0.32, 0.72, 0, 1)';
 
@@ -131,7 +132,7 @@ const containerBackground = css(`
       }
     }
 
-    &[data-focus-within][data-focus-within] {
+    &[data-focused][data-focused] {
       --con-hue-opacity: 0%;
       --bg-stop-1: light-dark(white, ${color('gray-75')});
       --bg-stop-2: light-dark(white, ${color('gray-75')});
@@ -206,7 +207,7 @@ const outerBorder = css(`
   &[data-variant=prominent] {
     ${outerBorderStops('prominent')}
 
-    &[data-state=idle][data-focus-within] {
+    &[data-state=idle][data-focused] {
       --bg-stop-1: ${token('outer-border.gradient.ob-border.stop-1')};
       --bg-stop-2: ${token('outer-border.gradient.ob-border.stop-1')};
       --bg-stop-3: ${token('outer-border.gradient.ob-border.stop-1')};
@@ -226,7 +227,7 @@ const outerBorder = css(`
     }
   }
 
-  &[data-state=idle][data-focus-within] {
+  &[data-state=idle][data-focused] {
     --bg-stop-1: ${token('outer-border.gradient.ob-border.stop-1')};
     --bg-stop-2: ${token('outer-border.gradient.ob-border.stop-1')};
     --bg-stop-3: ${token('outer-border.gradient.ob-border.stop-1')};
@@ -245,13 +246,26 @@ interface PropFieldContainerProps extends Omit<GroupProps, 'children'> {
 
 export function PromptFieldContainer(props: PropFieldContainerProps) {
   let {variant, isGenerating, styles, inputRef, ...otherProps} = props;
+  let [isFocused, setFocused] = useState(false);
+
   return (
     <Group
       {...otherProps}
       role="group"
       data-variant={variant}
       data-state={isGenerating ? 'generating' : 'idle'}
+      data-focused={isFocused || undefined}
       className={outerBorder}
+      onFocus={e => {
+        if (e.isTrusted) {
+          setFocused(true);
+        }
+      }}
+      onBlur={e => {
+        if (e.isTrusted) {
+          setFocused(false);
+        }
+      }}
       onPointerDown={e => {
         // If not clicking on something focusable within the prompt field, focus the input.
         let target = getEventTarget(e) as Element | null;
@@ -264,10 +278,10 @@ export function PromptFieldContainer(props: PropFieldContainerProps) {
           inputRef.current?.focus();
         }
       }}>
-      {({isHovered, isFocusWithin}) => (
+      {({isHovered}) => (
         <div
           data-hovered={isHovered || undefined}
-          data-focus-within={isFocusWithin || undefined}
+          data-focused={isFocused || undefined}
           data-variant={variant}
           data-state={isGenerating ? 'generating' : 'idle'}
           className={

From 1430046381eacdb06026f91d71af5be6e940faca Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 16:15:47 -0700
Subject: [PATCH 12/34] fix TokenField shift selection

---
 .../@react-spectrum/ai/src/TokenField.tsx     | 79 ++++++++++++-------
 .../ai/test/TokenField.browser.test.tsx       | 79 +++++++++++++++++++
 .../ai/test/utils/tokenFieldBrowserUtils.tsx  | 20 +++++
 3 files changed, 151 insertions(+), 27 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index df659987a46..b1b7d2588a8 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -345,23 +345,40 @@ export const TokenField = forwardRef(function TokenField(
 
   // Firefox does not allow placing the cursor between adjacent tokens, so navigate manually.
   let moveSelection = (segmenter: Intl.Segmenter, direction: Direction, extend = false) => {
-    let selection = getSelection(ref.current!);
-    if (!selection) {
+    let selection = window.getSelection();
+    if (!selection || selection.rangeCount === 0) {
       return false;
     }
-    let originalPos = direction === Direction.Backward ? selection[0] : selection[1];
-    let pos =
-      extend || isCollapsed(selection[0], selection[1])
-        ? state.findBoundaryWithSegmenter(originalPos, segmenter, direction)
-        : originalPos;
+
+    // If the selection is directionless, swap the focus and anchor according to the direction.
+    // For example if you double click a word and then shift select.
+    let {focusNode, focusOffset, anchorNode, anchorOffset} = selection;
+    if (
+      extend &&
+      selection.direction === 'none' &&
+      direction !== getSelectionDirection(selection)
+    ) {
+      [focusNode, focusOffset, anchorNode, anchorOffset] = [
+        anchorNode,
+        anchorOffset,
+        focusNode,
+        focusOffset
+      ];
+    }
+
+    // Extend or move the selection.
+    let originalPos = getPosition(ref.current!, focusNode, focusOffset);
+    let pos = state.findBoundaryWithSegmenter(originalPos, segmenter, direction);
     if (pos) {
-      let [start, end] =
-        direction === Direction.Backward
-          ? [pos, extend ? selection[1] : pos]
-          : [extend ? selection[0] : pos, pos];
-      setSelection(ref.current!, start, end, true);
+      let [node, offset] = getDOMOffset(ref.current!, pos);
+      if (extend) {
+        selection.setBaseAndExtent(anchorNode, anchorOffset, node, offset);
+      } else {
+        selection.collapse(node, offset);
+      }
       return true;
     }
+
     return false;
   };
 
@@ -642,25 +659,37 @@ export function positionToDOMRange(root: Element, pos: Position): Range {
 
 function createDOMRange(root: Element, start: Position, end: Position): Range {
   let range = document.createRange();
-  let child = root.childNodes[start.index];
+  let [startChild, startOffset] = getDOMOffset(root, start);
+  let [endChild, endOffset] = getDOMOffset(root, end);
+  range.setStart(startChild, startOffset);
+  range.setEnd(endChild, endOffset);
+  return range;
+}
+
+function getDOMOffset(root: Element, pos: Position): [Node, number] {
+  let child = root.childNodes[pos.index];
   if (!child) {
-    range.setStart(root, Math.min(root.childNodes.length, start.index));
+    return [root, Math.min(root.childNodes.length, pos.index)];
   } else if (child.nodeType === Node.ELEMENT_NODE) {
     // Place the cursor in one of the zero width space nodes.
-    range.setStart(child, start.offset > 0 ? 2 : 0);
+    return [child, pos.offset > 0 ? 2 : 0];
   } else {
     // Place the cursor in the text node.
-    range.setStart(child, start.offset);
+    return [child, pos.offset];
   }
-  child = root.childNodes[end.index];
-  if (!child) {
-    range.setEnd(root, Math.min(root.childNodes.length, end.index));
-  } else if (child.nodeType === Node.ELEMENT_NODE) {
-    range.setEnd(child, end.offset > 0 ? 2 : 0);
+}
+
+function getSelectionDirection(selection: Selection): Direction | null {
+  let {focusNode, anchorNode, focusOffset, anchorOffset} = selection;
+  if (focusNode == null || anchorNode == null) {
+    return null;
+  } else if (focusNode === anchorNode) {
+    return focusOffset > anchorOffset ? Direction.Forward : Direction.Backward;
   } else {
-    range.setEnd(child, end.offset);
+    return anchorNode.compareDocumentPosition(focusNode) & Node.DOCUMENT_POSITION_FOLLOWING
+      ? Direction.Forward
+      : Direction.Backward;
   }
-  return range;
 }
 
 function useSelectionChange(ref: React.RefObject<Element | null>, handler: () => void) {
@@ -681,7 +710,3 @@ function useSelectionChange(ref: React.RefObject<Element | null>, handler: () =>
     }
   });
 }
-
-function isCollapsed(pos1: Position, pos2: Position) {
-  return pos1.index === pos2.index && pos1.offset === pos2.offset;
-}
diff --git a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
index 59418fd84b6..b75d83bb6b9 100644
--- a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
@@ -18,6 +18,7 @@
 import {
   abTokCd,
   adjacentTokensSample,
+  dblClickAt,
   expectCaret,
   focusField,
   getFieldSelection,
@@ -285,6 +286,84 @@ describeOrSkip('TokenField browser interactions', () => {
       await expect(tokenEl.getAttribute('data-selected')).toBe('true');
     });
 
+    it('extends selection to the left with Shift+ArrowLeft', async () => {
+      let list = segments(text('abcde'));
+      let {textbox} = await renderControlledTokenField(list);
+      await navigateCaret(textbox, list, {index: 0, offset: 3});
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 1}, {index: 0, offset: 3});
+    });
+
+    it('moves selection back to the right with Shift+ArrowRight without extending past the anchor', async () => {
+      let list = segments(text('abcde'));
+      let {textbox} = await renderControlledTokenField(list);
+      await navigateCaret(textbox, list, {index: 0, offset: 3});
+      // Extend left to select "bc".
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 1}, {index: 0, offset: 3});
+      // Shift+ArrowRight shrinks the selection from the left rather than extending it to the right.
+      await userEvent.keyboard('{Shift>}{ArrowRight}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 2}, {index: 0, offset: 3});
+    });
+
+    it('extends back to the left after moving right with Shift+ArrowLeft', async () => {
+      let list = segments(text('abcde'));
+      let {textbox} = await renderControlledTokenField(list);
+      await navigateCaret(textbox, list, {index: 0, offset: 3});
+      // Extend left, move back right, then extend left again. The anchor stays fixed at offset 3.
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 1}, {index: 0, offset: 3});
+      await userEvent.keyboard('{Shift>}{ArrowRight}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 2}, {index: 0, offset: 3});
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 1}, {index: 0, offset: 3});
+    });
+
+    it('keeps direction when shrinking a selection across a token', async () => {
+      let {textbox} = await renderControlledTokenField(abTokCd);
+      let tokenEl = textbox.getByText('TOK').element();
+      // Caret after the token (start of "cd"). Extend left across the token to select it.
+      await navigateCaretFromEnd(textbox, abTokCd, {index: 2, offset: 0});
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 2}, {index: 2, offset: 0});
+      await expect.poll(() => tokenEl.getAttribute('data-selected')).toBe('true');
+      // Shift+ArrowRight shrinks back across the token rather than extending to the right.
+      await userEvent.keyboard('{Shift>}{ArrowRight}{/Shift}');
+      await waitForSelection(textbox, {index: 2, offset: 0}, {index: 2, offset: 0});
+      await expect.poll(() => tokenEl.getAttribute('data-selected')).toBe(null);
+    });
+
+    it('extends a double-clicked word to the left with Shift+ArrowLeft', async () => {
+      // Double clicking a word creates a directionless selection. Shift+ArrowLeft should
+      // extend it to the left rather than shrinking it from the right.
+      let list = segments(text('aaaa bbbb cccc'));
+      let {textbox} = await renderControlledTokenField(list);
+      let el = textbox.element();
+      await focusField(textbox);
+      await dblClickAt(textbox, el.childNodes[0], 6); // inside "bbbb"
+      let sel = getFieldSelection(el)!;
+      let [start, end] = sel;
+      // The double click should have selected a whole word away from the field boundaries.
+      expect(start.offset).toBeGreaterThan(0);
+      expect(end.offset).toBeGreaterThan(start.offset);
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: start.index, offset: start.offset - 1}, end);
+    });
+
+    it('extends a double-clicked word to the right with Shift+ArrowRight', async () => {
+      let list = segments(text('aaaa bbbb cccc'));
+      let {textbox} = await renderControlledTokenField(list);
+      let el = textbox.element();
+      await focusField(textbox);
+      await dblClickAt(textbox, el.childNodes[0], 6); // inside "bbbb"
+      let sel = getFieldSelection(el)!;
+      let [start, end] = sel;
+      expect(end.offset).toBeGreaterThan(start.offset);
+      expect(end.offset).toBeLessThan(14);
+      await userEvent.keyboard('{Shift>}{ArrowRight}{/Shift}');
+      await waitForSelection(textbox, start, {index: end.index, offset: end.offset + 1});
+    });
+
     it('extends selection backward by word with word selection shortcut', async () => {
       let list = segments(text('hello world'));
       let {textbox} = await renderControlledTokenField(list);
diff --git a/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx b/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx
index e28548a57ca..3e8d3f44866 100644
--- a/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx
+++ b/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx
@@ -97,6 +97,26 @@ export function setFieldSelection(textboxEl: Element, start: Position, end: Posi
   setSelection(textboxEl, start, end);
 }
 
+/**
+ * Double clicks on the character at the given offset within a DOM node, selecting the word
+ * under the cursor. Used to create a real (directionless) word selection, since selecting
+ * programmatically via addRange sets a direction in some browsers.
+ */
+export async function dblClickAt(textbox: Locator, node: Node, offset: number): Promise<void> {
+  let el = textbox.element();
+  let range = document.createRange();
+  range.setStart(node, offset);
+  range.setEnd(node, offset + 1);
+  let elRect = el.getBoundingClientRect();
+  let charRect = range.getBoundingClientRect();
+  await userEvent.dblClick(textbox, {
+    position: {
+      x: charRect.left - elRect.left + charRect.width / 2,
+      y: charRect.top - elRect.top + charRect.height / 2
+    }
+  });
+}
+
 export async function navigateCaret(textbox: Locator, list: TokenSegmentList, target: Position) {
   await focusField(textbox);
   await userEvent.keyboard('{Home}');

From 461b81a9227da5f2ba648e99b17eba6e39b63f99 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 18:39:16 -0700
Subject: [PATCH 13/34] use native browser selection modification to handle rtl

---
 .../@react-spectrum/ai/src/TokenField.tsx     | 104 ++++++------
 .../ai/test/TokenField.browser.test.tsx       | 155 +++++++++++++++++-
 2 files changed, 204 insertions(+), 55 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index b1b7d2588a8..6fee2f3d406 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -343,43 +343,37 @@ export const TokenField = forwardRef(function TokenField(
     }
   });
 
-  // Firefox does not allow placing the cursor between adjacent tokens, so navigate manually.
-  let moveSelection = (segmenter: Intl.Segmenter, direction: Direction, extend = false) => {
+  let moveSelection = (
+    direction: 'left' | 'right',
+    granularity: 'character' | 'word',
+    extend = false
+  ) => {
     let selection = window.getSelection();
-    if (!selection || selection.rangeCount === 0) {
+    if (!selection || selection.rangeCount === 0 || !selection.focusNode || !selection.anchorNode) {
       return false;
     }
 
-    // If the selection is directionless, swap the focus and anchor according to the direction.
-    // For example if you double click a word and then shift select.
-    let {focusNode, focusOffset, anchorNode, anchorOffset} = selection;
-    if (
-      extend &&
-      selection.direction === 'none' &&
-      direction !== getSelectionDirection(selection)
-    ) {
-      [focusNode, focusOffset, anchorNode, anchorOffset] = [
-        anchorNode,
-        anchorOffset,
-        focusNode,
-        focusOffset
-      ];
+    // Pressing an arrow with a non-empty selection collapses it to the corresponding edge.
+    // The browser handles this natively.
+    if (!extend && !selection.isCollapsed) {
+      return false;
     }
 
-    // Extend or move the selection.
-    let originalPos = getPosition(ref.current!, focusNode, focusOffset);
-    let pos = state.findBoundaryWithSegmenter(originalPos, segmenter, direction);
-    if (pos) {
-      let [node, offset] = getDOMOffset(ref.current!, pos);
-      if (extend) {
-        selection.setBaseAndExtent(anchorNode, anchorOffset, node, offset);
-      } else {
-        selection.collapse(node, offset);
+    // Move the caret using the browser's native caret movement (Selection.modify) so that
+    // bidirectional text is handled correctly. Repeat until the position actually changes
+    // to account for the zero width spaces around tokens.
+    let pos = getPosition(ref.current!, selection.focusNode, selection.focusOffset);
+    while (true) {
+      let {focusNode, focusOffset} = selection;
+      selection.modify(extend ? 'extend' : 'move', direction, granularity);
+      if (selection.focusNode === focusNode && selection.focusOffset === focusOffset) {
+        return false;
+      }
+      let newPos = getPosition(ref.current!, selection.focusNode, selection.focusOffset);
+      if (!isSamePosition(pos, newPos)) {
+        return true;
       }
-      return true;
     }
-
-    return false;
   };
 
   let mod = isMac() ? 'Meta' : 'Control';
@@ -392,28 +386,28 @@ export const TokenField = forwardRef(function TokenField(
       apply(state => state.redo());
     },
     ArrowLeft: () => {
-      return moveSelection(graphemeSegmenter, Direction.Backward);
+      return moveSelection('left', 'character');
     },
     [`${wordModKey}+ArrowLeft`]: () => {
-      return moveSelection(wordSegmenter, Direction.Backward);
+      return moveSelection('left', 'word');
     },
     'Shift+ArrowLeft': () => {
-      return moveSelection(graphemeSegmenter, Direction.Backward, true);
+      return moveSelection('left', 'character', true);
     },
     [`Shift+${wordModKey}+ArrowLeft`]: () => {
-      return moveSelection(wordSegmenter, Direction.Backward, true);
+      return moveSelection('left', 'word', true);
     },
     ArrowRight: () => {
-      return moveSelection(graphemeSegmenter, Direction.Forward);
+      return moveSelection('right', 'character');
     },
     [`${wordModKey}+ArrowRight`]: () => {
-      return moveSelection(wordSegmenter, Direction.Forward);
+      return moveSelection('right', 'word');
     },
     'Shift+ArrowRight': () => {
-      return moveSelection(graphemeSegmenter, Direction.Forward, true);
+      return moveSelection('right', 'character', true);
     },
     [`Shift+${wordModKey}+ArrowRight`]: () => {
-      return moveSelection(wordSegmenter, Direction.Forward, true);
+      return moveSelection('right', 'word', true);
     },
     Home: () => {
       // Browsers do not behave consistently when there are tokens.
@@ -620,18 +614,29 @@ function getPosition(container: Element, node: Node, offset: number): Position {
   let index = indexOfNode(node);
   if (node.nodeType === Node.ELEMENT_NODE) {
     let tokenNode = node.childNodes[1];
+    let atEnd: boolean;
     if (originalNode === tokenNode) {
       // Cursor is inside the token.
-      offset = offset > 0 ? (tokenNode?.textContent?.length ?? 0) : 0;
+      atEnd = offset > 0;
     } else if (originalNode === node) {
       // Cursor is inside the wrapper element.
-      offset = offset <= 1 ? 0 : (tokenNode?.textContent?.length ?? 0);
+      atEnd = offset > 1;
     } else {
       // Cursor is on one of the zero width spaces.
-      offset =
-        originalNode === tokenNode.previousSibling ? 0 : (tokenNode?.textContent?.length ?? 0);
+      atEnd = originalNode !== tokenNode.previousSibling;
+    }
+
+    offset = atEnd ? (tokenNode?.textContent?.length ?? 0) : 0;
+
+    // Several positions are equivalent due to the zero width spaces around tokens.
+    // Normalize offset to the end of the preceding text node, or the beginning of the following node.
+    if (offset === 0 && node.previousSibling?.nodeType === Node.TEXT_NODE) {
+      index--;
+      offset = node.previousSibling?.textContent?.length ?? 0;
+    } else if (atEnd && node.nextSibling) {
+      index++;
+      offset = 0;
     }
-    return {index, offset};
   }
   return {index, offset};
 }
@@ -672,24 +677,15 @@ function getDOMOffset(root: Element, pos: Position): [Node, number] {
     return [root, Math.min(root.childNodes.length, pos.index)];
   } else if (child.nodeType === Node.ELEMENT_NODE) {
     // Place the cursor in one of the zero width space nodes.
-    return [child, pos.offset > 0 ? 2 : 0];
+    return [child, 0];
   } else {
     // Place the cursor in the text node.
     return [child, pos.offset];
   }
 }
 
-function getSelectionDirection(selection: Selection): Direction | null {
-  let {focusNode, anchorNode, focusOffset, anchorOffset} = selection;
-  if (focusNode == null || anchorNode == null) {
-    return null;
-  } else if (focusNode === anchorNode) {
-    return focusOffset > anchorOffset ? Direction.Forward : Direction.Backward;
-  } else {
-    return anchorNode.compareDocumentPosition(focusNode) & Node.DOCUMENT_POSITION_FOLLOWING
-      ? Direction.Forward
-      : Direction.Backward;
-  }
+function isSamePosition(a: Position, b: Position): boolean {
+  return a.index === b.index && a.offset === b.offset;
 }
 
 function useSelectionChange(ref: React.RefObject<Element | null>, handler: () => void) {
diff --git a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
index b75d83bb6b9..7c29fc49a62 100644
--- a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
@@ -28,6 +28,7 @@ import {
   renderControlledTokenField,
   segments,
   selectRange,
+  setFieldSelection,
   text,
   token,
   waitForCaret,
@@ -127,6 +128,17 @@ describeOrSkip('TokenField browser interactions', () => {
       await waitForSelection(textbox, {index: 0, offset: 0});
     });
 
+    it('moves over an emoji as a single grapheme', async () => {
+      let list = segments(text('a😀b'));
+      let {textbox} = await renderControlledTokenField(list);
+      await navigateCaret(textbox, list, {index: 0, offset: 1});
+      // ArrowRight steps over the whole emoji (2 code units), not into the middle of it.
+      await userEvent.keyboard('{ArrowRight}');
+      await waitForSelection(textbox, {index: 0, offset: 3});
+      await userEvent.keyboard('{ArrowLeft}');
+      await waitForSelection(textbox, {index: 0, offset: 1});
+    });
+
     it('moves to field start with Home on single line', async () => {
       let list = segments(text('hello'));
       let {textbox} = await renderControlledTokenField(list);
@@ -212,6 +224,127 @@ describeOrSkip('TokenField browser interactions', () => {
     });
   });
 
+  describe('rtl caret movement', () => {
+    // In RTL text the visual arrow keys map to the opposite logical direction: ArrowLeft moves
+    // the caret forward through the text and ArrowRight moves it backward.
+    it('moves the caret in the visual direction in RTL text', async () => {
+      let list = segments(text('אבגד'));
+      let {textbox} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      setFieldSelection(el, {index: 0, offset: 2}, {index: 0, offset: 2});
+      await userEvent.keyboard('{ArrowLeft}');
+      await waitForSelection(textbox, {index: 0, offset: 3});
+      setFieldSelection(el, {index: 0, offset: 2}, {index: 0, offset: 2});
+      await userEvent.keyboard('{ArrowRight}');
+      await waitForSelection(textbox, {index: 0, offset: 1});
+    });
+
+    it('skips over a token in the visual direction in RTL text', async () => {
+      let list = segments(text('אב'), token('ך'), text('גד'));
+      let {textbox} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      // ArrowLeft (visual left = logical forward) crosses the token to the following text.
+      setFieldSelection(el, {index: 0, offset: 2}, {index: 0, offset: 2});
+      await userEvent.keyboard('{ArrowLeft}');
+      await waitForSelection(textbox, {index: 2, offset: 0});
+      // ArrowRight (visual right = logical backward) crosses back over the token.
+      await userEvent.keyboard('{ArrowRight}');
+      await waitForSelection(textbox, {index: 0, offset: 2});
+    });
+
+    it('extends the selection in the visual direction in RTL text', async () => {
+      let list = segments(text('אבגד'));
+      let {textbox} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      setFieldSelection(el, {index: 0, offset: 2}, {index: 0, offset: 2});
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 2}, {index: 0, offset: 4});
+    });
+
+    it('extends the selection across a token in RTL text', async () => {
+      let list = segments(text('אב'), token('ך'), text('גד'));
+      let {textbox} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      setFieldSelection(el, {index: 0, offset: 2}, {index: 0, offset: 2});
+      await userEvent.keyboard('{Shift>}{ArrowLeft}{/Shift}');
+      await waitForSelection(textbox, {index: 0, offset: 2}, {index: 2, offset: 0});
+    });
+
+    it('moves the caret by word in the visual direction in RTL text', async () => {
+      // "שלום עולם" = two words separated by a space (offsets 0-4 and 5-9).
+      let list = segments(text('שלום עולם'));
+      let {textbox} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      let mod = wordNavModKey();
+      // Word + ArrowLeft (visual left = logical forward) moves to the end of the first word.
+      setFieldSelection(el, {index: 0, offset: 0}, {index: 0, offset: 0});
+      await userEvent.keyboard(`{${mod}>}{ArrowLeft}{/${mod}}`);
+      await waitForSelection(textbox, {index: 0, offset: 4});
+      // Word + ArrowRight (visual right = logical backward) moves to the start of the last word.
+      setFieldSelection(el, {index: 0, offset: 9}, {index: 0, offset: 9});
+      await userEvent.keyboard(`{${mod}>}{ArrowRight}{/${mod}}`);
+      await waitForSelection(textbox, {index: 0, offset: 5});
+    });
+
+    it('moves to the line boundaries with Home and End in RTL text', async () => {
+      let list = segments(text('שלום עולם'));
+      let {textbox} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      setFieldSelection(el, {index: 0, offset: 4}, {index: 0, offset: 4});
+      await userEvent.keyboard('{Home}');
+      await waitForSelection(textbox, {index: 0, offset: 0});
+      await userEvent.keyboard('{End}');
+      await waitForSelection(textbox, {index: 0, offset: 9});
+    });
+  });
+
+  describe('bidirectional text', () => {
+    it('deletes the previous character with Backspace in RTL text', async () => {
+      let list = segments(text('שלום'));
+      let {textbox, getValue} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      setFieldSelection(el, {index: 0, offset: 4}, {index: 0, offset: 4});
+      await userEvent.keyboard('{Backspace}');
+      await waitForFieldText(getValue, 'שלו');
+    });
+
+    it('crosses a token atomically in mixed RTL and LTR text', async () => {
+      // RTL text, an LTR token, then RTL text.
+      let list = segments(text('שלום'), token('ABC'), text('עולם'));
+      let {textbox} = await renderControlledTokenField(list, {dir: 'rtl'} as any);
+      let el = textbox.element();
+      await focusField(textbox);
+      // From the boundary before the token, ArrowLeft (logical forward) jumps the whole token.
+      setFieldSelection(el, {index: 0, offset: 4}, {index: 0, offset: 4});
+      await userEvent.keyboard('{ArrowLeft}');
+      await waitForSelection(textbox, {index: 2, offset: 0});
+      // ArrowRight (logical backward) crosses back over the token.
+      await userEvent.keyboard('{ArrowRight}');
+      await waitForSelection(textbox, {index: 0, offset: 4});
+    });
+
+    it('moves through and back across mixed bidirectional text', async () => {
+      // "ab" (LTR) + "גד" (RTL) + "ef" (LTR). The visual path differs across browsers, but the
+      // caret must traverse the whole field and a round trip must return to the start.
+      let list = segments(text('abגדef'));
+      let {textbox} = await renderControlledTokenField(list);
+      await focusField(textbox);
+      await userEvent.keyboard('{Home}');
+      await waitForSelection(textbox, {index: 0, offset: 0});
+      await userEvent.keyboard('{ArrowRight>6}');
+      await waitForSelection(textbox, {index: 0, offset: 6});
+      await userEvent.keyboard('{ArrowLeft>6}');
+      await waitForSelection(textbox, {index: 0, offset: 0});
+    });
+  });
+
   describe('selection', () => {
     it('selects token atomically when extending selection across it', async () => {
       let {textbox} = await renderControlledTokenField(abTokCd);
@@ -333,7 +466,27 @@ describeOrSkip('TokenField browser interactions', () => {
       await expect.poll(() => tokenEl.getAttribute('data-selected')).toBe(null);
     });
 
+    it('collapses the selection to the right edge with ArrowRight', async () => {
+      let {textbox} = await renderControlledTokenField(abTokCd);
+      await selectRange(textbox, abTokCd, {index: 0, offset: 1}, {index: 2, offset: 1});
+      // A plain arrow collapses to the edge without moving the caret past it.
+      await userEvent.keyboard('{ArrowRight}');
+      await waitForSelection(textbox, {index: 2, offset: 1});
+    });
+
+    it('collapses the selection to the left edge with ArrowLeft', async () => {
+      let {textbox} = await renderControlledTokenField(abTokCd);
+      await selectRange(textbox, abTokCd, {index: 0, offset: 1}, {index: 2, offset: 1});
+      await userEvent.keyboard('{ArrowLeft}');
+      await waitForSelection(textbox, {index: 0, offset: 1});
+    });
+
     it('extends a double-clicked word to the left with Shift+ArrowLeft', async () => {
+      if (isFirefox()) {
+        // Firefox does not treat double clicks as directionless.
+        return;
+      }
+
       // Double clicking a word creates a directionless selection. Shift+ArrowLeft should
       // extend it to the left rather than shrinking it from the right.
       let list = segments(text('aaaa bbbb cccc'));
@@ -445,7 +598,7 @@ describeOrSkip('TokenField browser interactions', () => {
     it('replaces token when typing after clicking token', async () => {
       let {textbox, getValue} = await renderControlledTokenField(abTokCd);
       await userEvent.click(textbox.getByText('TOK'));
-      await waitForSelection(textbox, {index: 1, offset: 0}, {index: 1, offset: 3});
+      await waitForSelection(textbox, {index: 0, offset: 2}, {index: 2, offset: 0});
       await userEvent.keyboard('NEW');
       await waitForFieldText(getValue, 'abNEWcd');
     });

From c8a40c3bc1bb9755cebf01823e6934159100c697 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 20:14:01 -0700
Subject: [PATCH 14/34] Implement disabled/readonly

---
 .../@react-spectrum/ai/src/TokenField.tsx     |  5 ++++-
 .../ai/test/TokenField.browser.test.tsx       | 20 +++++++++++++++++++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index 6fee2f3d406..2739f69f7bf 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -437,6 +437,7 @@ export const TokenField = forwardRef(function TokenField(
   };
 
   let {keyboardProps} = useKeyboard({
+    isDisabled: isDisabled || isReadOnly,
     onKeyDown: e => {
       // mini version of useKeyboard shortcuts until it is merged.
       let modifiers = ['Shift', 'Control', 'Alt', 'Meta'] satisfies React.ModifierKey[];
@@ -485,12 +486,14 @@ export const TokenField = forwardRef(function TokenField(
       )}
       ref={mergeRefs(ref, autocompleteRef as any)}
       role="textbox"
-      contentEditable="true"
+      contentEditable={!isDisabled && !isReadOnly}
       suppressContentEditableWarning
       aria-multiline={multiline}
       aria-label={ariaLabel}
       aria-labelledby={ariaLabelledBy}
       aria-describedby={ariaDescribedBy}
+      aria-readonly={isReadOnly || undefined}
+      aria-disabled={isDisabled || undefined}
       data-focused={isFocused || undefined}
       data-focus-visible={isFocusVisible || undefined}
       data-disabled={isDisabled || undefined}
diff --git a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
index 7c29fc49a62..a16686677c8 100644
--- a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
@@ -64,6 +64,26 @@ describeOrSkip('TokenField browser interactions', () => {
       await expect.element(screen.getByRole('textbox', {name: 'Message'})).toBeInTheDocument();
       await expect.element(screen.getByText('TOK')).toBeInTheDocument();
     });
+
+    it('does not allow editing when read only', async () => {
+      let {textbox, getValue} = await renderControlledTokenField(abTokCd, {isReadOnly: true});
+      let el = textbox.element();
+      expect(el.getAttribute('contenteditable')).toBe('false');
+      expect(el.getAttribute('aria-readonly')).toBe('true');
+      await focusField(textbox);
+      await userEvent.keyboard('x');
+      let mod = modKey();
+      await userEvent.keyboard(`{${mod}>}z{/${mod}}`);
+      expect(getValue().toString()).toBe('abTOKcd');
+    });
+
+    it('is not editable or focusable when disabled', async () => {
+      let {textbox} = await renderControlledTokenField(abTokCd, {isDisabled: true});
+      let el = textbox.element();
+      expect(el.getAttribute('contenteditable')).toBe('false');
+      expect(el.getAttribute('aria-disabled')).toBe('true');
+      expect(el.getAttribute('tabindex')).toBeNull();
+    });
   });
 
   describe('caret movement', () => {

From 54403a6d1456322542fe43e1bccc811307a75d52 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 20:32:04 -0700
Subject: [PATCH 15/34] fix bug

---
 .../@react-spectrum/ai/src/TokenField.tsx     |  8 ++++----
 .../ai/test/TokenField.browser.test.tsx       | 19 +++++++++++++++++++
 2 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index 2739f69f7bf..bdfee36bc47 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -644,7 +644,7 @@ function getPosition(container: Element, node: Node, offset: number): Position {
   return {index, offset};
 }
 
-let isProgrammaticSelectionChange = false;
+let isProgrammaticSelectionChange = Symbol('isProgrammaticSelectionChange');
 
 // TODO: do we want to export these?
 export function setCursor(root: Element, pos: Position, fireEvent = false) {
@@ -655,7 +655,7 @@ export function setSelection(root: Element, start: Position, end: Position, fire
   let selection = window.getSelection();
   if (selection) {
     let range = createDOMRange(root, start, end);
-    isProgrammaticSelectionChange = !fireEvent;
+    root[isProgrammaticSelectionChange] = !fireEvent;
     selection.removeAllRanges();
     selection.addRange(range);
   }
@@ -693,8 +693,8 @@ function isSamePosition(a: Position, b: Position): boolean {
 
 function useSelectionChange(ref: React.RefObject<Element | null>, handler: () => void) {
   useEvent(useRef(document), 'selectionchange', () => {
-    if (isProgrammaticSelectionChange) {
-      isProgrammaticSelectionChange = false;
+    if (ref.current && ref.current[isProgrammaticSelectionChange]) {
+      ref.current[isProgrammaticSelectionChange] = false;
       return;
     }
 
diff --git a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
index a16686677c8..82c236623ce 100644
--- a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
@@ -822,6 +822,25 @@ describeOrSkip('TokenField browser interactions', () => {
       await waitForFieldText(getValue, '');
     });
 
+    it('coalesces consecutive typing in a second field instance', async () => {
+      // Reproduces a bug where two instances of a TokenField share state.
+      let tick = () => new Promise(resolve => setTimeout(resolve, 30));
+      await renderControlledTokenField(segments(text('')));
+      let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+      await focusField(textbox);
+      await userEvent.keyboard('x');
+      await tick();
+      await userEvent.keyboard('y');
+      await tick();
+      await userEvent.keyboard('z');
+      await tick();
+      await waitForFieldText(getValue, 'xyz');
+      let mod = modKey();
+      await userEvent.keyboard(`{${mod}>}z{/${mod}}`);
+      await tick();
+      expect(getValue().toString()).toBe('');
+    });
+
     it('redoes after undo', async () => {
       let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
       await focusField(textbox);

From e23381ab84560b502d6cd70d4689b21a635a7e9b Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 20:43:29 -0700
Subject: [PATCH 16/34] harden json parsing

---
 .../@react-spectrum/ai/src/TokenField.tsx     | 38 +++++++++++++++---
 .../ai/test/TokenField.browser.test.tsx       | 40 ++++++++++++++++++-
 2 files changed, 72 insertions(+), 6 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index bdfee36bc47..3e3bf2cd3e4 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -137,8 +137,11 @@ export const TokenField = forwardRef(function TokenField(
           data = transferredData.current;
           transferredData.current = null;
         } else if (e.dataTransfer) {
-          if (e.dataTransfer.types.includes(CLIPBOARD_MIME_TYPE)) {
-            data = JSON.parse(e.dataTransfer.getData(CLIPBOARD_MIME_TYPE));
+          let parsed = e.dataTransfer.types.includes(CLIPBOARD_MIME_TYPE)
+            ? parseSegments(e.dataTransfer.getData(CLIPBOARD_MIME_TYPE))
+            : null;
+          if (parsed) {
+            data = parsed;
           } else if (e.dataTransfer.types.includes('text/plain')) {
             data[0].text = e.dataTransfer.getData('text/plain');
           }
@@ -278,7 +281,7 @@ export const TokenField = forwardRef(function TokenField(
   useEvent(ref, 'paste', e => {
     // Safari doesn't pass the custom clipboard data type to beforeinput dataTransfer so we handle it here.
     if (e.clipboardData && e.clipboardData.types.includes(CLIPBOARD_MIME_TYPE)) {
-      transferredData.current = JSON.parse(e.clipboardData.getData(CLIPBOARD_MIME_TYPE));
+      transferredData.current = parseSegments(e.clipboardData.getData(CLIPBOARD_MIME_TYPE));
     }
   });
 
@@ -297,7 +300,7 @@ export const TokenField = forwardRef(function TokenField(
     }
 
     if (e.dataTransfer && e.dataTransfer.types.includes(CLIPBOARD_MIME_TYPE)) {
-      transferredData.current = JSON.parse(e.dataTransfer.getData(CLIPBOARD_MIME_TYPE));
+      transferredData.current = parseSegments(e.dataTransfer.getData(CLIPBOARD_MIME_TYPE));
     }
   });
 
@@ -313,7 +316,7 @@ export const TokenField = forwardRef(function TokenField(
         if (segment?.type === 'token') {
           announce(segment.text, 'assertive');
         }
-      } else if (start.offset === state.segments[start.index].text.length) {
+      } else if (start.offset === state.segments[start.index]?.text.length) {
         let segment = state.segments[start.index + 1];
         if (segment?.type === 'token') {
           announce(segment.text, 'assertive');
@@ -691,6 +694,31 @@ function isSamePosition(a: Position, b: Position): boolean {
   return a.index === b.index && a.offset === b.offset;
 }
 
+// Parse and validate segments from clipboard/drag data. Returns null if the data is not valid
+// JSON or does not match the expected shape, so malformed or untrusted data is ignored rather
+// than throwing or being inserted into the field.
+function parseSegments(json: string): TokenFieldSegment[] | null {
+  try {
+    let data = JSON.parse(json);
+    if (Array.isArray(data) && data.length > 0 && data.every(isValidSegment)) {
+      return data;
+    }
+  } catch {
+    // Ignore invalid clipboard data.
+  }
+  return null;
+}
+
+function isValidSegment(segment: unknown): segment is TokenFieldSegment {
+  return (
+    typeof segment === 'object' &&
+    segment != null &&
+    ((segment as TokenFieldSegment).type === 'text' ||
+      (segment as TokenFieldSegment).type === 'token') &&
+    typeof (segment as TokenFieldSegment).text === 'string'
+  );
+}
+
 function useSelectionChange(ref: React.RefObject<Element | null>, handler: () => void) {
   useEvent(useRef(document), 'selectionchange', () => {
     if (ref.current && ref.current[isProgrammaticSelectionChange]) {
diff --git a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
index 82c236623ce..e4fd3111cbf 100644
--- a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
@@ -37,12 +37,12 @@ import {
   wordDeleteModKey,
   wordNavModKey
 } from './utils/tokenFieldBrowserUtils';
+import {CLIPBOARD_MIME_TYPE, Token, TokenField} from '../src/TokenField';
 import {commands, userEvent} from 'vitest/browser';
 import {describe, expect, it} from 'vitest';
 import {isFirefox, isWebKit} from 'react-aria/private/utils/platform';
 import React from 'react';
 import {render} from 'vitest-browser-react';
-import {Token, TokenField} from '../src/TokenField';
 
 declare module 'vitest/browser' {
   interface BrowserCommands {
@@ -799,6 +799,44 @@ describeOrSkip('TokenField browser interactions', () => {
         await commands.unlockClipboard();
       }
     });
+
+    it('ignores malformed data under the custom clipboard type without crashing', async () => {
+      let {textbox, getValue} = await renderControlledTokenField(segments(text('hi')));
+      let el = textbox.element();
+      await focusField(textbox);
+      // Simulate another app placing invalid JSON under our custom clipboard type. The field must
+      // not throw (it previously called JSON.parse unguarded) and its value must be unchanged.
+      let dt = new DataTransfer();
+      dt.setData(CLIPBOARD_MIME_TYPE, '{ not valid json');
+      el.dispatchEvent(
+        new ClipboardEvent('paste', {clipboardData: dt, bubbles: true, cancelable: true})
+      );
+      expect(getValue().toString()).toBe('hi');
+    });
+
+    it('ignores valid JSON with invalid segments under the custom clipboard type', async () => {
+      let {textbox, getValue} = await renderControlledTokenField(segments(text('hi')));
+      let el = textbox.element();
+      await focusField(textbox);
+      // Valid JSON that does not match the segment shape must be rejected by validation rather
+      // than trusted and inserted. Covers the non-array and per-segment validation branches.
+      for (let payload of [
+        '{"type":"text","text":"x"}', // not an array
+        '[]', // empty array
+        '[{"type":"evil","text":"x"}]', // invalid segment type
+        '[{"type":"text"}]', // missing text
+        '[{"type":"token","text":42}]', // non-string text
+        '["plain string"]', // not an object
+        '[null]' // null entry
+      ]) {
+        let dt = new DataTransfer();
+        dt.setData(CLIPBOARD_MIME_TYPE, payload);
+        el.dispatchEvent(
+          new ClipboardEvent('paste', {clipboardData: dt, bubbles: true, cancelable: true})
+        );
+      }
+      expect(getValue().toString()).toBe('hi');
+    });
   });
 
   describe('undo and redo', () => {

From 5259b8d3965dbe21f3449ee1b798b151c64ba55f Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 21:05:46 -0700
Subject: [PATCH 17/34] Only move the caret when the field is focused

---
 .../@react-spectrum/ai/src/TokenField.tsx     | 10 +++++-
 .../ai/test/TokenField.browser.test.tsx       | 34 +++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index 3e3bf2cd3e4..39d8cf94e2c 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -21,6 +21,8 @@ import {
 import {FieldInputContext} from 'react-aria-components/Autocomplete';
 import {filterDOMProps} from 'react-aria/filterDOMProps';
 import {FocusableProps} from '@react-types/shared';
+import {getActiveElement} from 'react-aria/private/utils/shadowdom/DOMFunctions';
+import {getOwnerDocument} from 'react-aria/private/utils/domHelpers';
 import {isMac} from 'react-aria/private/utils/platform';
 import {mergeProps} from 'react-aria/mergeProps';
 import {mergeRefs} from 'react-aria/mergeRefs';
@@ -110,7 +112,13 @@ export const TokenField = forwardRef(function TokenField(
 
   let caretPosition = useRef<Position | null>(null);
   useLayoutEffect(() => {
-    if (ref.current && state.caretPosition && state.caretPosition !== caretPosition.current) {
+    // Only move the caret when the field is already focused.
+    if (
+      ref.current &&
+      state.caretPosition &&
+      state.caretPosition !== caretPosition.current &&
+      ref.current === getActiveElement(getOwnerDocument(ref.current))
+    ) {
       setCursor(ref.current, state.caretPosition);
       caretPosition.current = state.caretPosition;
     }
diff --git a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
index e4fd3111cbf..96a2bddcc24 100644
--- a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
@@ -86,6 +86,38 @@ describeOrSkip('TokenField browser interactions', () => {
     });
   });
 
+  describe('focus management', () => {
+    function FocusHarness() {
+      let [value, setValue] = React.useState(() => segments(text('hello')));
+      return (
+        <>
+          <input
+            aria-label="Other field"
+            onChange={e => setValue(segments(text(e.target.value)))} />
+          <TokenField aria-label="Focus test" value={value} onChange={setValue}>
+            {segment => <Token>{segment.text}</Token>}
+          </TokenField>
+        </>
+      );
+    }
+
+    it('does not focus the field on mount', async () => {
+      let screen = await render(<FocusHarness />);
+      await expect.element(screen.getByRole('textbox', {name: 'Focus test'})).not.toHaveFocus();
+    });
+
+    it('does not steal focus when the value changes while another element is focused', async () => {
+      let screen = await render(<FocusHarness />);
+      let other = screen.getByRole('textbox', {name: 'Other field'});
+      await userEvent.click(other);
+      await expect.element(other).toHaveFocus();
+      // Typing into the other input updates the TokenField value; focus must stay on the input.
+      await userEvent.type(other, 'x');
+      await expect.element(other).toHaveFocus();
+      await expect.element(screen.getByRole('textbox', {name: 'Focus test'})).not.toHaveFocus();
+    });
+  });
+
   describe('caret movement', () => {
     it('skips over token with ArrowRight from end of preceding text', async () => {
       let {textbox} = await renderControlledTokenField(abTokCd);
@@ -603,6 +635,7 @@ describeOrSkip('TokenField browser interactions', () => {
 
     it('inserts at clicked position in text', async () => {
       let {textbox, getValue} = await renderControlledTokenField(segments(text('hello')));
+      await focusField(textbox);
       let el = textbox.element();
       let textNode = Array.from(el.childNodes).find(n => n.nodeType === Node.TEXT_NODE) as Text;
       let range = document.createRange();
@@ -617,6 +650,7 @@ describeOrSkip('TokenField browser interactions', () => {
 
     it('replaces token when typing after clicking token', async () => {
       let {textbox, getValue} = await renderControlledTokenField(abTokCd);
+      await focusField(textbox);
       await userEvent.click(textbox.getByText('TOK'));
       await waitForSelection(textbox, {index: 0, offset: 2}, {index: 2, offset: 0});
       await userEvent.keyboard('NEW');

From 53dd33ee69f786b08b72f5fce056dffe7a99b713 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 21:24:50 -0700
Subject: [PATCH 18/34] fix tagfield story

---
 packages/@react-spectrum/ai/src/TokenField.tsx             | 2 +-
 packages/@react-spectrum/ai/stories/TokenField.stories.tsx | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index 39d8cf94e2c..c07e921a967 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -691,7 +691,7 @@ function getDOMOffset(root: Element, pos: Position): [Node, number] {
     return [root, Math.min(root.childNodes.length, pos.index)];
   } else if (child.nodeType === Node.ELEMENT_NODE) {
     // Place the cursor in one of the zero width space nodes.
-    return [child, 0];
+    return [child, pos.offset > 0 ? 2 : 0];
   } else {
     // Place the cursor in the text node.
     return [child, pos.offset];
diff --git a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
index 53398386050..05aed208d82 100644
--- a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
@@ -265,6 +265,7 @@ class TagFieldSegmentList extends TokenSegmentList {
 export const TagField: TokenFieldStory = () => {
   return (
     <TokenField
+      multiline
       defaultValue={
         new TagFieldSegmentList([
           {type: 'token', text: 'Architecture'},

From 858aa1e2c821a4b7e0c2ffcad1da22587c434490 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 23 Jun 2026 21:30:17 -0700
Subject: [PATCH 19/34] test multiline behavior

---
 .../@react-spectrum/ai/src/TokenField.tsx     |  6 ++
 .../ai/test/TokenField.browser.test.tsx       | 60 ++++++++++++++++++-
 2 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index c07e921a967..e21f71fc309 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -160,6 +160,12 @@ export const TokenField = forwardRef(function TokenField(
           dropPosition.current = null;
         }
 
+        if (!multiline) {
+          for (let segment of data) {
+            segment.text = segment.text.replace(/[\r\n]+/g, ' ');
+          }
+        }
+
         apply(tokens =>
           tokens.replaceRangeWithSegments(
             start,
diff --git a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
index 96a2bddcc24..aadb106326e 100644
--- a/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.browser.test.tsx
@@ -93,7 +93,8 @@ describeOrSkip('TokenField browser interactions', () => {
         <>
           <input
             aria-label="Other field"
-            onChange={e => setValue(segments(text(e.target.value)))} />
+            onChange={e => setValue(segments(text(e.target.value)))}
+          />
           <TokenField aria-label="Focus test" value={value} onChange={setValue}>
             {segment => <Token>{segment.text}</Token>}
           </TokenField>
@@ -765,6 +766,63 @@ describeOrSkip('TokenField browser interactions', () => {
     });
   });
 
+  describe('multiline', () => {
+    it('does not insert a newline on Enter in a single-line field', async () => {
+      let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+      await focusField(textbox);
+      await userEvent.type(textbox, 'ab');
+      await userEvent.keyboard('{Enter}');
+      await userEvent.type(textbox, 'c');
+      await waitForFieldText(getValue, 'abc');
+    });
+
+    it('inserts a newline on Enter in a multiline field', async () => {
+      let {textbox, getValue} = await renderControlledTokenField(segments(text('')), {
+        multiline: true
+      });
+      await focusField(textbox);
+      await userEvent.type(textbox, 'ab');
+      await userEvent.keyboard('{Enter}');
+      await userEvent.type(textbox, 'c');
+      await waitForFieldText(getValue, 'ab\nc');
+    });
+
+    it('removes newlines from pasted text in a single-line field', async () => {
+      // Put multiline text on the clipboard by copying it from a source field.
+      let source = await renderControlledTokenField(segments(text('a\nb')), {multiline: true});
+      let target = await renderControlledTokenField(segments(text('')));
+      let mod = modKey();
+      await commands.lockClipboard();
+      try {
+        await focusField(source.textbox);
+        await userEvent.keyboard(`{${mod}>}a{/${mod}}`);
+        await userEvent.copy();
+        await focusField(target.textbox);
+        await userEvent.paste();
+        await waitForFieldText(target.getValue, 'a b');
+      } finally {
+        await commands.unlockClipboard();
+      }
+    });
+
+    it('keeps newlines from pasted text in a multiline field', async () => {
+      let source = await renderControlledTokenField(segments(text('a\nb')), {multiline: true});
+      let target = await renderControlledTokenField(segments(text('')), {multiline: true});
+      let mod = modKey();
+      await commands.lockClipboard();
+      try {
+        await focusField(source.textbox);
+        await userEvent.keyboard(`{${mod}>}a{/${mod}}`);
+        await userEvent.copy();
+        await focusField(target.textbox);
+        await userEvent.paste();
+        await waitForFieldText(target.getValue, 'a\nb');
+      } finally {
+        await commands.unlockClipboard();
+      }
+    });
+  });
+
   describe('clipboard', () => {
     it('pastes plain text at caret', async () => {
       let list = segments(text('ab'));

From f660093dd8356a89990c798600dfe83364bb216c Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Wed, 24 Jun 2026 11:18:36 -0700
Subject: [PATCH 20/34] simplify and improve combobox tagfield example

---
 .../@react-spectrum/ai/src/TokenField.tsx     |   8 +-
 .../ai/stories/TokenField.stories.tsx         | 163 +++++++-----------
 .../react-aria-components/src/ComboBox.tsx    |  19 +-
 packages/react-aria-components/src/utils.tsx  |  25 ++-
 .../src/interactions/createEventHandler.ts    |   2 +-
 5 files changed, 108 insertions(+), 109 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index e21f71fc309..16dacf32ecc 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -502,13 +502,13 @@ export const TokenField = forwardRef(function TokenField(
         {onPaste: props.onPaste}
       )}
       ref={mergeRefs(ref, autocompleteRef as any)}
-      role="textbox"
+      role={autocompleteProps.role || 'textbox'}
       contentEditable={!isDisabled && !isReadOnly}
       suppressContentEditableWarning
       aria-multiline={multiline}
-      aria-label={ariaLabel}
-      aria-labelledby={ariaLabelledBy}
-      aria-describedby={ariaDescribedBy}
+      aria-label={ariaLabel ?? autocompleteProps['aria-label']}
+      aria-labelledby={ariaLabelledBy ?? autocompleteProps['aria-labelledby']}
+      aria-describedby={ariaDescribedBy ?? autocompleteProps['aria-describedby']}
       aria-readonly={isReadOnly || undefined}
       aria-disabled={isDisabled || undefined}
       data-focused={isFocused || undefined}
diff --git a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
index 05aed208d82..5e01b561e39 100644
--- a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
@@ -12,21 +12,19 @@
 
 import {categorizeArgTypes, getActionArgs} from '../../s2/stories/utils';
 import {Meta, StoryFn} from '@storybook/react';
-import React, {useContext, useMemo, useRef, useState} from 'react';
+import React, {useMemo, useRef, useState} from 'react';
 import './styles.global.css';
 import {Autocomplete} from 'react-aria-components/Autocomplete';
 import {ChevronDown} from 'lucide-react';
-import {Collection, ComboBox, ComboBoxStateContext} from 'react-aria-components';
+import {Collection, ComboBox} from 'react-aria-components';
 import {ComboBoxItem, ComboBoxListBox} from 'vanilla-starter/ComboBox';
 import {Direction, type TokenFieldSegment, TokenSegmentList} from '../src/TokenSegmentList';
 import {FieldButton, Label} from 'vanilla-starter/Form';
 import {Header, Menu, MenuItem, MenuSection} from 'vanilla-starter/Menu';
-import {InputContext} from 'react-aria-components/Input';
 import {Popover} from 'vanilla-starter/Popover';
 import {positionToDOMRange, Token, TokenField} from '../src/TokenField';
 import 'vanilla-starter/TagGroup.css';
 import {Text} from 'react-aria-components/Text';
-import {useSlottedContext} from 'react-aria-components/slots';
 
 const events = ['onChange', 'onPaste', 'onSubmit', 'onFocus', 'onBlur', 'onFocusChange'];
 
@@ -363,111 +361,80 @@ export const Search: TokenFieldStory = () => {
 };
 
 export const ComboBoxExample: TokenFieldStory = () => {
+  let [value, setValue] = useState(new TokenSegmentList([]));
+  let selectedKeys = useMemo(
+    () => value.segments.filter(seg => seg.type === 'token').map(seg => seg.value.username),
+    [value]
+  );
+  let segment = value.segments[value.caretPosition.index];
+  let inputValue = segment?.type === 'text' ? segment.text : '';
+
   return (
-    <ComboBox selectionMode="multiple" style={{width: 500}}>
+    <ComboBox
+      selectionMode="multiple"
+      style={{width: 500}}
+      value={selectedKeys}
+      inputValue={inputValue}
+      onChange={keys => {
+        let added = new Set();
+        for (let key of keys) {
+          if (!selectedKeys.includes(key)) {
+            added.add(key);
+          }
+        }
+        let removed = new Set();
+        for (let key of selectedKeys) {
+          if (!keys.includes(key)) {
+            removed.add(key);
+          }
+        }
+
+        setValue(value => {
+          for (let key of removed) {
+            let index = value.segments.findIndex(
+              seg => seg.type === 'token' && seg.value.username === key
+            );
+            value = value.replaceRangeWithSegments(
+              {index: index, offset: 0},
+              {index: index, offset: value.segments[index]?.text.length ?? 0},
+              false
+            );
+          }
+
+          // TODO: if the user selects multiple existing segments and then selects a value from the menu,
+          // should we replace the selected segments?
+          let segment = value.segments[value.caretPosition.index];
+          return value.replaceRangeWithSegments(
+            {index: value.caretPosition.index, offset: 0},
+            // If caret is in a text segment, replace the text segment with the new token. Otherwise, insert it.
+            segment?.type === 'text'
+              ? {
+                  index: value.caretPosition.index,
+                  offset: value.segments[value.caretPosition.index]?.text.length ?? 0
+                }
+              : {index: value.caretPosition.index, offset: 0},
+            [...added].map(key => {
+              let item = usernames.find(user => user.username === key)!;
+              return {type: 'token', text: item.username, value: item};
+            }),
+            false
+          );
+        });
+      }}>
       <Label>Users</Label>
       <div className="combobox-field">
-        <ComboBoxTagInput />
+        <TokenField value={value} onChange={setValue} style={{paddingInlineEnd: 36}}>
+          {segment => <Token>{segment.text}</Token>}
+        </TokenField>
         <FieldButton>
           <ChevronDown />
         </FieldButton>
       </div>
       <Popover hideArrow className="combobox-popover">
         <ComboBoxListBox items={usernames}>
-          {state => <ComboBoxItem>{state.username}</ComboBoxItem>}
+          {state => <ComboBoxItem id={state.username}>{state.username}</ComboBoxItem>}
         </ComboBoxListBox>
       </Popover>
     </ComboBox>
   );
 };
-
-function ComboBoxTagInput() {
-  let state = useContext(ComboBoxStateContext);
-  let inputCtx = useSlottedContext(InputContext);
-  let [value, setValue] = useState(() => {
-    let selectedItems: TokenFieldSegment[] =
-      state?.selectedItems.map(item => ({
-        type: 'token' as const,
-        text: item.textValue,
-        value: item.value
-      })) ?? [];
-    selectedItems.push({type: 'text', text: state?.inputValue ?? ''});
-    return new TokenSegmentList(selectedItems);
-  });
-
-  let [lastSelectedItems, setLastSelectedItems] = useState(state?.selectedItems || []);
-  let [lastInputValue, setLastInputValue] = useState(state?.inputValue ?? '');
-
-  if (
-    state &&
-    (state?.selectedItems !== lastSelectedItems || lastInputValue !== state?.inputValue)
-  ) {
-    setValue(value => {
-      let selected = state?.selectedItems ?? [];
-      let selectedValues = new Set(selected.map(item => item.value));
-
-      let segments = value.segments.filter(
-        seg => seg.type === 'text' || selectedValues.has(seg.value)
-      );
-
-      let existingValues = new Set(
-        segments.filter(seg => seg.type === 'token').map(seg => seg.value)
-      );
-
-      let newTokens: TokenFieldSegment[] = selected
-        .filter(item => !existingValues.has(item.value))
-        .map(item => ({
-          type: 'token' as const,
-          text: item.textValue,
-          value: item.value
-        }));
-
-      let caret = value.caretPosition;
-      let removedBeforeCaret = 0;
-      for (let i = 0; i < caret.index && i < value.segments.length; i++) {
-        let seg = value.segments[i];
-        if (seg.type === 'token' && !selectedValues.has(seg.value)) {
-          removedBeforeCaret++;
-        }
-      }
-
-      let insertIndex = Math.min(caret.index - removedBeforeCaret, segments.length);
-      segments.splice(insertIndex, 0, ...newTokens);
-
-      if (!segments.some(seg => seg.type === 'text')) {
-        segments.push({type: 'text', text: state?.inputValue ?? ''});
-      }
-
-      let caretIndex = Math.min(insertIndex + newTokens.length, segments.length - 1);
-      if (segments[caretIndex]?.type === 'text') {
-        segments[caretIndex] = {type: 'text', text: state?.inputValue ?? ''};
-      }
-
-      let caretPosition = {
-        index: caretIndex,
-        offset:
-          segments[caretIndex]?.type === 'text' ? (state?.inputValue ?? '').length : caret.offset
-      };
-
-      return new TokenSegmentList(segments, {caretPosition});
-    });
-    setLastSelectedItems(state?.selectedItems || []);
-    setLastInputValue(state?.inputValue ?? '');
-  }
-
-  return (
-    <TokenField
-      {...(inputCtx as any)}
-      defaultValue={undefined}
-      value={value}
-      onChange={list => {
-        let segment = list.segments[list.caretPosition.index];
-        state?.setInputValue(segment?.type === 'text' ? segment.text : '');
-        setValue(list);
-      }}
-      aria-label="Users"
-      style={{paddingInlineEnd: 36}}>
-      {segment => <Token>{segment.text}</Token>}
-    </TokenField>
-  );
-}
diff --git a/packages/react-aria-components/src/ComboBox.tsx b/packages/react-aria-components/src/ComboBox.tsx
index b834adb560d..7448ed79bb6 100644
--- a/packages/react-aria-components/src/ComboBox.tsx
+++ b/packages/react-aria-components/src/ComboBox.tsx
@@ -31,6 +31,7 @@ import {CollectionBuilder} from 'react-aria/CollectionBuilder';
 import {ComboBoxState, useComboBoxState} from 'react-stately/useComboBoxState';
 import {createHideableComponent} from 'react-aria/private/collections/Hidden';
 import {FieldErrorContext} from './FieldError';
+import {FieldInputContext} from './Autocomplete';
 import {filterDOMProps} from 'react-aria/filterDOMProps';
 import {FormContext} from './Form';
 import {GlobalDOMAttributes, Key, RefObject} from '@react-types/shared';
@@ -174,7 +175,14 @@ export const ComboBox = /*#__PURE__*/ createHideableComponent(function ComboBox<
 });
 
 // Contexts to clear inside the popover.
-const CLEAR_CONTEXTS = [LabelContext, ButtonContext, InputContext, GroupContext, TextContext];
+const CLEAR_CONTEXTS = [
+  LabelContext,
+  ButtonContext,
+  InputContext,
+  FieldInputContext,
+  GroupContext,
+  TextContext
+];
 
 interface ComboBoxInnerProps<T> {
   props: ComboBoxProps<T, SelectionMode>;
@@ -298,6 +306,15 @@ function ComboBoxInner<T>({props, collection, comboBoxRef: ref}: ComboBoxInnerPr
         [LabelContext, {...labelProps, ref: labelRef}],
         [ButtonContext, {...buttonProps, ref: buttonRef, isPressed: state.isOpen}],
         [InputContext, {...inputProps, ref: inputRef}],
+        [
+          FieldInputContext,
+          {
+            ...inputProps,
+            ref: inputRef,
+            value: state.inputValue,
+            onChange: v => state.setInputValue(v as string)
+          } as any
+        ],
         [OverlayTriggerStateContext, state],
         [
           PopoverContext,
diff --git a/packages/react-aria-components/src/utils.tsx b/packages/react-aria-components/src/utils.tsx
index 2fbc6316962..5b75ce90f2c 100644
--- a/packages/react-aria-components/src/utils.tsx
+++ b/packages/react-aria-components/src/utils.tsx
@@ -44,7 +44,7 @@ export type SlottedContextValue<T> = SlottedValue<T> | T | null | undefined;
 export type ContextValue<T, E> = SlottedContextValue<WithRef<T, E>>;
 
 type ProviderValue<T> = [Context<T>, T];
-type ProviderValues<A, B, C, D, E, F, G, H, I, J, K, L> =
+type ProviderValues<A, B, C, D, E, F, G, H, I, J, K, L, M> =
   | [ProviderValue<A>]
   | [ProviderValue<A>, ProviderValue<B>]
   | [ProviderValue<A>, ProviderValue<B>, ProviderValue<C>]
@@ -126,17 +126,32 @@ type ProviderValues<A, B, C, D, E, F, G, H, I, J, K, L> =
       ProviderValue<J>,
       ProviderValue<K>,
       ProviderValue<L>
+    ]
+  | [
+      ProviderValue<A>,
+      ProviderValue<B>,
+      ProviderValue<C>,
+      ProviderValue<D>,
+      ProviderValue<E>,
+      ProviderValue<F>,
+      ProviderValue<G>,
+      ProviderValue<H>,
+      ProviderValue<I>,
+      ProviderValue<J>,
+      ProviderValue<K>,
+      ProviderValue<L>,
+      ProviderValue<M>
     ];
 
-interface ProviderProps<A, B, C, D, E, F, G, H, I, J, K, L> {
-  values: ProviderValues<A, B, C, D, E, F, G, H, I, J, K, L>;
+interface ProviderProps<A, B, C, D, E, F, G, H, I, J, K, L, M> {
+  values: ProviderValues<A, B, C, D, E, F, G, H, I, J, K, L, M>;
   children: ReactNode;
 }
 
-export function Provider<A, B, C, D, E, F, G, H, I, J, K, L>({
+export function Provider<A, B, C, D, E, F, G, H, I, J, K, L, M>({
   values,
   children
-}: ProviderProps<A, B, C, D, E, F, G, H, I, J, K, L>): JSX.Element {
+}: ProviderProps<A, B, C, D, E, F, G, H, I, J, K, L, M>): JSX.Element {
   for (let [Context, value] of values) {
     // @ts-ignore
     children = <Context.Provider value={value}>{children}</Context.Provider>;
diff --git a/packages/react-aria/src/interactions/createEventHandler.ts b/packages/react-aria/src/interactions/createEventHandler.ts
index 18e04c3b7dc..0d162f1c7b4 100644
--- a/packages/react-aria/src/interactions/createEventHandler.ts
+++ b/packages/react-aria/src/interactions/createEventHandler.ts
@@ -58,7 +58,7 @@ export function createEventHandler<T extends SyntheticEvent>(
 
     handler(event);
 
-    if (shouldStopPropagation) {
+    if (shouldStopPropagation && !('continuePropagation' in e)) {
       e.stopPropagation();
     }
   };

From 168e19918b2d831776acb736120bad4d4ef305de Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Wed, 24 Jun 2026 12:24:13 -0700
Subject: [PATCH 21/34] refactor combobox into reusable subclass

---
 .../@react-spectrum/ai/src/TokenField.tsx     |  19 ++-
 .../ai/src/TokenSegmentList.ts                |  26 ++--
 .../ai/stories/TokenField.stories.tsx         | 119 ++++++++++--------
 3 files changed, 86 insertions(+), 78 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index 16dacf32ecc..aac32e0f28e 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -20,7 +20,7 @@ import {
 } from './TokenSegmentList';
 import {FieldInputContext} from 'react-aria-components/Autocomplete';
 import {filterDOMProps} from 'react-aria/filterDOMProps';
-import {FocusableProps} from '@react-types/shared';
+import {FocusableProps, forwardRefType} from '@react-types/shared';
 import {getActiveElement} from 'react-aria/private/utils/shadowdom/DOMFunctions';
 import {getOwnerDocument} from 'react-aria/private/utils/domHelpers';
 import {isMac} from 'react-aria/private/utils/platform';
@@ -47,11 +47,11 @@ interface TokenFieldRenderProps {
   isFocusVisible: boolean;
 }
 
-export interface TokenFieldProps
+export interface TokenFieldProps<T extends TokenSegmentList>
   extends StyleRenderProps<TokenFieldRenderProps>, SlotProps, FocusableProps {
-  value?: TokenSegmentList;
-  defaultValue?: TokenSegmentList;
-  onChange?: (value: TokenSegmentList) => void;
+  value?: T;
+  defaultValue?: T;
+  onChange?: (value: T) => void;
   children: (segment: TokenSegment) => React.ReactElement;
   multiline?: boolean;
   isReadOnly?: boolean;
@@ -65,10 +65,9 @@ export interface TokenFieldProps
 
 export const CLIPBOARD_MIME_TYPE = 'application/vnd.react-aria.tokens+json';
 
-export const TokenField = forwardRef(function TokenField(
-  props: TokenFieldProps,
-  forwardedRef: ForwardedRef<HTMLDivElement | null>
-) {
+export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function TokenField<
+  T extends TokenSegmentList
+>(props: TokenFieldProps<T>, forwardedRef: ForwardedRef<HTMLDivElement | null>) {
   let {
     value: valueProp,
     defaultValue: defaultValueProp = new TokenSegmentList([]),
@@ -502,7 +501,7 @@ export const TokenField = forwardRef(function TokenField(
         {onPaste: props.onPaste}
       )}
       ref={mergeRefs(ref, autocompleteRef as any)}
-      role={autocompleteProps.role || 'textbox'}
+      role={autocompleteProps['role'] || 'textbox'}
       contentEditable={!isDisabled && !isReadOnly}
       suppressContentEditableWarning
       aria-multiline={multiline}
diff --git a/packages/@react-spectrum/ai/src/TokenSegmentList.ts b/packages/@react-spectrum/ai/src/TokenSegmentList.ts
index 5b8518dcd2c..1940458e4d9 100644
--- a/packages/@react-spectrum/ai/src/TokenSegmentList.ts
+++ b/packages/@react-spectrum/ai/src/TokenSegmentList.ts
@@ -47,8 +47,8 @@ export class TokenSegmentList {
   readonly segments: readonly TokenFieldSegment[];
   caretPosition: Position = {index: 0, offset: 0};
   // Linked list representing the undo/redo history.
-  private previous: TokenSegmentList | null = null;
-  private next: TokenSegmentList | null = null;
+  private previous: this | null = null;
+  private next: this | null = null;
   private isCoalescing = true;
 
   constructor(tokens: readonly TokenFieldSegment[], options?: TokenSegmentListOptions) {
@@ -56,15 +56,15 @@ export class TokenSegmentList {
     this.caretPosition = options?.caretPosition ?? {index: 0, offset: 0};
   }
 
-  protected createSegmentList(segments: readonly TokenFieldSegment[]): TokenSegmentList {
+  protected createSegmentList(segments: readonly TokenFieldSegment[]): this {
     const Constructor = this.constructor as new (
       segments: readonly TokenFieldSegment[],
       options?: TokenSegmentListOptions
-    ) => TokenSegmentList;
+    ) => this;
     return new Constructor(segments);
   }
 
-  withCaretPosition(caretPosition: Position): TokenSegmentList {
+  withCaretPosition(caretPosition: Position): this {
     if (
       this.caretPosition.index === caretPosition.index &&
       this.caretPosition.offset === caretPosition.offset
@@ -122,7 +122,7 @@ export class TokenSegmentList {
   }
 
   /** Replace the text between two positions with new text. */
-  replaceRange(start: Position, end: Position, text: string, coalesce = true): TokenSegmentList {
+  replaceRange(start: Position, end: Position, text: string, coalesce = true): this {
     return this.replaceRangeWithSegments(
       start,
       end,
@@ -137,7 +137,7 @@ export class TokenSegmentList {
     end: Position,
     insert: TokenFieldSegment[],
     coalesce = true
-  ): TokenSegmentList {
+  ): this {
     start = this.clampPosition(start);
     end = this.clampPosition(end);
     let startSegment = this.segments[start.index];
@@ -303,7 +303,7 @@ export class TokenSegmentList {
     segmenter: Intl.Segmenter,
     direction: Direction,
     coalesce = true
-  ): TokenSegmentList {
+  ): this {
     let boundary = this.findBoundaryWithSegmenter(position, segmenter, direction);
     if (boundary) {
       return this.replaceRange(
@@ -319,7 +319,7 @@ export class TokenSegmentList {
   }
 
   /** Delete text to the next or previous line break. */
-  deleteLine(position: Position, direction: Direction, coalesce = true): TokenSegmentList {
+  deleteLine(position: Position, direction: Direction, coalesce = true): this {
     if (this.segments.length === 0) {
       return this;
     }
@@ -338,7 +338,7 @@ export class TokenSegmentList {
   }
 
   /** Converts the text at a position into a token. */
-  insertToken(position: Position): TokenSegmentList {
+  insertToken(position: Position): this {
     let segment = this.segments[position.index];
     if (segment && segment.type === 'text') {
       return this.replaceRangeWithSegments(
@@ -354,7 +354,7 @@ export class TokenSegmentList {
   }
 
   /** Create a new list containing a subset of the segments. */
-  slice(start: Position, end: Position): TokenSegmentList {
+  slice(start: Position, end: Position): this {
     start = this.clampPosition(start);
     end = this.clampPosition(end);
     if (start.index === end.index && start.offset === end.offset) {
@@ -389,11 +389,11 @@ export class TokenSegmentList {
     return this.segments.map(seg => seg.text).join('');
   }
 
-  undo(): TokenSegmentList {
+  undo(): this {
     return this.previous ?? this;
   }
 
-  redo(): TokenSegmentList {
+  redo(): this {
     return this.next ?? this;
   }
 
diff --git a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
index 5e01b561e39..22b0a084638 100644
--- a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
@@ -21,6 +21,7 @@ import {ComboBoxItem, ComboBoxListBox} from 'vanilla-starter/ComboBox';
 import {Direction, type TokenFieldSegment, TokenSegmentList} from '../src/TokenSegmentList';
 import {FieldButton, Label} from 'vanilla-starter/Form';
 import {Header, Menu, MenuItem, MenuSection} from 'vanilla-starter/Menu';
+import {Key} from '@react-types/shared';
 import {Popover} from 'vanilla-starter/Popover';
 import {positionToDOMRange, Token, TokenField} from '../src/TokenField';
 import 'vanilla-starter/TagGroup.css';
@@ -360,67 +361,75 @@ export const Search: TokenFieldStory = () => {
   );
 };
 
+class ComboBoxSegmentList extends TokenSegmentList {
+  getSelectedKeys(): Key[] {
+    return this.segments.filter(seg => seg.type === 'token').map(seg => seg.value.username);
+  }
+
+  getInputValue(): string {
+    let segment = this.segments[this.caretPosition.index];
+    return segment?.type === 'text' ? segment.text : '';
+  }
+
+  setSelectedKeys(keys: Key[]): ComboBoxSegmentList {
+    let selectedKeys = this.getSelectedKeys();
+    let added = new Set();
+    for (let key of keys) {
+      if (!selectedKeys.includes(key)) {
+        added.add(key);
+      }
+    }
+    let removed = new Set();
+    for (let key of selectedKeys) {
+      if (!keys.includes(key)) {
+        removed.add(key);
+      }
+    }
+
+    let value = this;
+    for (let key of removed) {
+      let index = value.segments.findIndex(
+        seg => seg.type === 'token' && seg.value.username === key
+      );
+      value = value.replaceRangeWithSegments(
+        {index: index, offset: 0},
+        {index: index, offset: value.segments[index]?.text.length ?? 0},
+        [],
+        false
+      );
+    }
+
+    // TODO: if the user selects multiple existing segments and then selects a value from the menu,
+    // should we replace the selected segments?
+    let segment = value.segments[value.caretPosition.index];
+    return value.replaceRangeWithSegments(
+      {index: value.caretPosition.index, offset: 0},
+      // If caret is in a text segment, replace the text segment with the new token. Otherwise, insert it.
+      segment?.type === 'text'
+        ? {
+            index: value.caretPosition.index,
+            offset: value.segments[value.caretPosition.index]?.text.length ?? 0
+          }
+        : {index: value.caretPosition.index, offset: 0},
+      [...added].map(key => {
+        let item = usernames.find(user => user.username === key)!;
+        return {type: 'token', text: item.username, value: item};
+      }),
+      false
+    );
+  }
+}
+
 export const ComboBoxExample: TokenFieldStory = () => {
-  let [value, setValue] = useState(new TokenSegmentList([]));
-  let selectedKeys = useMemo(
-    () => value.segments.filter(seg => seg.type === 'token').map(seg => seg.value.username),
-    [value]
-  );
-  let segment = value.segments[value.caretPosition.index];
-  let inputValue = segment?.type === 'text' ? segment.text : '';
+  let [value, setValue] = useState(new ComboBoxSegmentList([]));
 
   return (
     <ComboBox
       selectionMode="multiple"
       style={{width: 500}}
-      value={selectedKeys}
-      inputValue={inputValue}
-      onChange={keys => {
-        let added = new Set();
-        for (let key of keys) {
-          if (!selectedKeys.includes(key)) {
-            added.add(key);
-          }
-        }
-        let removed = new Set();
-        for (let key of selectedKeys) {
-          if (!keys.includes(key)) {
-            removed.add(key);
-          }
-        }
-
-        setValue(value => {
-          for (let key of removed) {
-            let index = value.segments.findIndex(
-              seg => seg.type === 'token' && seg.value.username === key
-            );
-            value = value.replaceRangeWithSegments(
-              {index: index, offset: 0},
-              {index: index, offset: value.segments[index]?.text.length ?? 0},
-              false
-            );
-          }
-
-          // TODO: if the user selects multiple existing segments and then selects a value from the menu,
-          // should we replace the selected segments?
-          let segment = value.segments[value.caretPosition.index];
-          return value.replaceRangeWithSegments(
-            {index: value.caretPosition.index, offset: 0},
-            // If caret is in a text segment, replace the text segment with the new token. Otherwise, insert it.
-            segment?.type === 'text'
-              ? {
-                  index: value.caretPosition.index,
-                  offset: value.segments[value.caretPosition.index]?.text.length ?? 0
-                }
-              : {index: value.caretPosition.index, offset: 0},
-            [...added].map(key => {
-              let item = usernames.find(user => user.username === key)!;
-              return {type: 'token', text: item.username, value: item};
-            }),
-            false
-          );
-        });
-      }}>
+      value={value.getSelectedKeys()}
+      inputValue={value.getInputValue()}
+      onChange={keys => setValue(value.setSelectedKeys(keys))}>
       <Label>Users</Label>
       <div className="combobox-field">
         <TokenField value={value} onChange={setValue} style={{paddingInlineEnd: 36}}>

From abf5d52bcf0d6d964c944526dffde0138474e1d0 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Wed, 24 Jun 2026 17:08:25 -0700
Subject: [PATCH 22/34] use generic type for token values

---
 .../@react-spectrum/ai/src/TokenField.tsx     |  8 ++-
 .../ai/src/TokenSegmentList.ts                | 38 ++++--------
 .../ai/stories/TokenField.stories.tsx         | 60 ++++++++++---------
 .../ai/test/TokenSegmentList.test.ts          | 49 ++-------------
 .../ai/test/utils/tokenFieldBrowserUtils.tsx  | 10 ++--
 5 files changed, 60 insertions(+), 105 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index aac32e0f28e..0699cbce587 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -47,12 +47,14 @@ interface TokenFieldRenderProps {
   isFocusVisible: boolean;
 }
 
-export interface TokenFieldProps<T extends TokenSegmentList>
+export interface TokenFieldProps<T extends TokenSegmentList = TokenSegmentList>
   extends StyleRenderProps<TokenFieldRenderProps>, SlotProps, FocusableProps {
   value?: T;
   defaultValue?: T;
   onChange?: (value: T) => void;
-  children: (segment: TokenSegment) => React.ReactElement;
+  children: (
+    segment: TokenSegment<T extends TokenSegmentList<infer V> ? V : never>
+  ) => React.ReactElement;
   multiline?: boolean;
   isReadOnly?: boolean;
   isDisabled?: boolean;
@@ -66,7 +68,7 @@ export interface TokenFieldProps<T extends TokenSegmentList>
 export const CLIPBOARD_MIME_TYPE = 'application/vnd.react-aria.tokens+json';
 
 export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function TokenField<
-  T extends TokenSegmentList
+  T extends TokenSegmentList = TokenSegmentList
 >(props: TokenFieldProps<T>, forwardedRef: ForwardedRef<HTMLDivElement | null>) {
   let {
     value: valueProp,
diff --git a/packages/@react-spectrum/ai/src/TokenSegmentList.ts b/packages/@react-spectrum/ai/src/TokenSegmentList.ts
index 1940458e4d9..324fae69297 100644
--- a/packages/@react-spectrum/ai/src/TokenSegmentList.ts
+++ b/packages/@react-spectrum/ai/src/TokenSegmentList.ts
@@ -10,18 +10,18 @@
  * governing permissions and limitations under the License.
  */
 
-export type TokenFieldSegment = TextSegment | TokenSegment;
+export type TokenFieldSegment<T = any> = TextSegment | TokenSegment<T>;
 
 export interface TextSegment {
   type: 'text';
   text: string;
 }
 
-export interface TokenSegment {
+export interface TokenSegment<T = any> {
   type: 'token';
   text: string;
   /** An arbitrary value associated with the token. */
-  value?: any;
+  value?: T;
 }
 
 export interface Position {
@@ -43,22 +43,22 @@ export interface TokenSegmentListOptions {
 /**
  * A list of segments containing editable text and non-editable tokens.
  */
-export class TokenSegmentList {
-  readonly segments: readonly TokenFieldSegment[];
+export class TokenSegmentList<T = any> {
+  readonly segments: readonly TokenFieldSegment<T>[];
   caretPosition: Position = {index: 0, offset: 0};
   // Linked list representing the undo/redo history.
   private previous: this | null = null;
   private next: this | null = null;
   private isCoalescing = true;
 
-  constructor(tokens: readonly TokenFieldSegment[], options?: TokenSegmentListOptions) {
+  constructor(tokens: readonly TokenFieldSegment<T>[], options?: TokenSegmentListOptions) {
     this.segments = tokens;
     this.caretPosition = options?.caretPosition ?? {index: 0, offset: 0};
   }
 
-  protected createSegmentList(segments: readonly TokenFieldSegment[]): this {
+  protected createSegmentList(segments: readonly TokenFieldSegment<T>[]): this {
     const Constructor = this.constructor as new (
-      segments: readonly TokenFieldSegment[],
+      segments: readonly TokenFieldSegment<T>[],
       options?: TokenSegmentListOptions
     ) => this;
     return new Constructor(segments);
@@ -103,7 +103,7 @@ export class TokenSegmentList {
     return {type: 'text', text};
   }
 
-  protected tokenize(text: string): TokenFieldSegment[] {
+  protected tokenize(text: string): TokenFieldSegment<T>[] {
     return [this.createTextSegment(text)];
   }
 
@@ -135,7 +135,7 @@ export class TokenSegmentList {
   replaceRangeWithSegments(
     start: Position,
     end: Position,
-    insert: TokenFieldSegment[],
+    insert: TokenFieldSegment<T>[],
     coalesce = true
   ): this {
     start = this.clampPosition(start);
@@ -337,22 +337,6 @@ export class TokenSegmentList {
     return this;
   }
 
-  /** Converts the text at a position into a token. */
-  insertToken(position: Position): this {
-    let segment = this.segments[position.index];
-    if (segment && segment.type === 'text') {
-      return this.replaceRangeWithSegments(
-        {index: position.index, offset: 0},
-        {index: position.index, offset: segment.text.length},
-        [{type: 'token', text: segment.text}],
-        false
-      );
-    }
-
-    this.caretPosition = position;
-    return this;
-  }
-
   /** Create a new list containing a subset of the segments. */
   slice(start: Position, end: Position): this {
     start = this.clampPosition(start);
@@ -374,7 +358,7 @@ export class TokenSegmentList {
     let [, startSplit] = this.splitSegment(startSegment, start.offset);
     let [endSplit] = this.splitSegment(endSegment, end.offset);
 
-    let result: TokenFieldSegment[] = [];
+    let result: TokenFieldSegment<T>[] = [];
     if (startSplit) {
       result.push(startSplit);
     }
diff --git a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
index 22b0a084638..75fa0cebc63 100644
--- a/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/TokenField.stories.tsx
@@ -56,8 +56,12 @@ class TokenizingSegmentList extends TokenSegmentList {
     return new this(segments, tokenRegex);
   }
 
-  createSegmentList(segments: TokenFieldSegment[]): TokenSegmentList {
-    return new TokenizingSegmentList(segments, this.tokenRegex);
+  createSegmentList(segments: TokenFieldSegment[]): this {
+    let Constructor = this.constructor as new (
+      tokens: TokenFieldSegment[],
+      tokenRegex: RegExp
+    ) => this;
+    return new Constructor(segments, this.tokenRegex);
   }
 
   tokenize(text: string): TokenFieldSegment[] {
@@ -361,9 +365,9 @@ export const Search: TokenFieldStory = () => {
   );
 };
 
-class ComboBoxSegmentList extends TokenSegmentList {
+class ComboBoxSegmentList extends TokenSegmentList<Key> {
   getSelectedKeys(): Key[] {
-    return this.segments.filter(seg => seg.type === 'token').map(seg => seg.value.username);
+    return this.segments.filter(seg => seg.type === 'token').map(seg => seg.value!);
   }
 
   getInputValue(): string {
@@ -373,10 +377,10 @@ class ComboBoxSegmentList extends TokenSegmentList {
 
   setSelectedKeys(keys: Key[]): ComboBoxSegmentList {
     let selectedKeys = this.getSelectedKeys();
-    let added = new Set();
+    let added: Key[] = [];
     for (let key of keys) {
       if (!selectedKeys.includes(key)) {
-        added.add(key);
+        added.push(key);
       }
     }
     let removed = new Set();
@@ -388,9 +392,7 @@ class ComboBoxSegmentList extends TokenSegmentList {
 
     let value = this;
     for (let key of removed) {
-      let index = value.segments.findIndex(
-        seg => seg.type === 'token' && seg.value.username === key
-      );
+      let index = value.segments.findIndex(seg => seg.type === 'token' && seg.value! === key);
       value = value.replaceRangeWithSegments(
         {index: index, offset: 0},
         {index: index, offset: value.segments[index]?.text.length ?? 0},
@@ -399,24 +401,28 @@ class ComboBoxSegmentList extends TokenSegmentList {
       );
     }
 
-    // TODO: if the user selects multiple existing segments and then selects a value from the menu,
-    // should we replace the selected segments?
-    let segment = value.segments[value.caretPosition.index];
-    return value.replaceRangeWithSegments(
-      {index: value.caretPosition.index, offset: 0},
-      // If caret is in a text segment, replace the text segment with the new token. Otherwise, insert it.
-      segment?.type === 'text'
-        ? {
-            index: value.caretPosition.index,
-            offset: value.segments[value.caretPosition.index]?.text.length ?? 0
-          }
-        : {index: value.caretPosition.index, offset: 0},
-      [...added].map(key => {
-        let item = usernames.find(user => user.username === key)!;
-        return {type: 'token', text: item.username, value: item};
-      }),
-      false
-    );
+    if (added.length > 0) {
+      // TODO: if the user selects multiple existing segments and then selects a value from the menu,
+      // should we replace the selected segments?
+      let segment = value.segments[value.caretPosition.index];
+      value = value.replaceRangeWithSegments(
+        {index: value.caretPosition.index, offset: 0},
+        // If caret is in a text segment, replace the text segment with the new token. Otherwise, insert it.
+        segment?.type === 'text'
+          ? {
+              index: value.caretPosition.index,
+              offset: value.segments[value.caretPosition.index]?.text.length ?? 0
+            }
+          : {index: value.caretPosition.index, offset: 0},
+        added.map(value => {
+          // TODO: add a way to lookup a custom text value
+          return {type: 'token', text: String(value), value: value};
+        }),
+        false
+      );
+    }
+
+    return value;
   }
 }
 
diff --git a/packages/@react-spectrum/ai/test/TokenSegmentList.test.ts b/packages/@react-spectrum/ai/test/TokenSegmentList.test.ts
index a8275cefa72..a4b1a27fb1f 100644
--- a/packages/@react-spectrum/ai/test/TokenSegmentList.test.ts
+++ b/packages/@react-spectrum/ai/test/TokenSegmentList.test.ts
@@ -39,8 +39,12 @@ class TokenizingSegmentList extends TokenSegmentList {
     return new this(segments, tokenRegex);
   }
 
-  createSegmentList(segments: TokenFieldSegment[]): TokenSegmentList {
-    return new TokenizingSegmentList(segments, this.tokenRegex);
+  createSegmentList(segments: TokenFieldSegment[]): this {
+    const Constructor = this.constructor as new (
+      tokens: TokenFieldSegment[],
+      tokenRegex: RegExp
+    ) => this;
+    return new Constructor(segments, this.tokenRegex);
   }
 
   tokenize(text: string): TokenFieldSegment[] {
@@ -958,38 +962,6 @@ describeOrSkip('TokenSegmentList', () => {
     });
   });
 
-  describe('insertToken', () => {
-    it('turns entire text segment into a token', () => {
-      let list = new TokenSegmentList([text('hello')]);
-      let {segments: value, caretPosition: caret} = list.insertToken({index: 0, offset: 0});
-      expect(value).toEqual([token('hello')]);
-      expect(caret).toEqual({index: 1, offset: 0});
-    });
-
-    it('ignores offset and still tokenizes full text run', () => {
-      let list = new TokenSegmentList([text('hello')]);
-      let {segments: value, caretPosition: caret} = list.insertToken({index: 0, offset: 3});
-      expect(value).toEqual([token('hello')]);
-      expect(caret).toEqual({index: 1, offset: 0});
-    });
-
-    it('no-op when index points at token', () => {
-      let segs = [text('a'), token('T')];
-      let list = new TokenSegmentList(segs);
-      let {segments: value, caretPosition: caret} = list.insertToken({index: 1, offset: 0});
-      expect(value).toEqual(segs);
-      expect(caret).toEqual({index: 1, offset: 0});
-    });
-
-    it('no-op when index is out of range', () => {
-      let segs = [text('a')];
-      let list = new TokenSegmentList(segs);
-      let {segments: value, caretPosition: caret} = list.insertToken({index: 5, offset: 0});
-      expect(value).toEqual(segs);
-      expect(caret).toEqual({index: 5, offset: 0});
-    });
-  });
-
   describe('undo/redo', () => {
     it('returns the same instance when there is nothing to undo', () => {
       let list = new TokenSegmentList([text('a')]);
@@ -1090,15 +1062,6 @@ describeOrSkip('TokenSegmentList', () => {
       expect(initial.redo()).toBe(other);
     });
 
-    it('insertToken is a separate undo step from coalesced typing', () => {
-      let list = new TokenSegmentList([text('hi')]);
-      let typed = list.replaceRange({index: 0, offset: 2}, {index: 0, offset: 2}, '!');
-      let tokenized = typed.insertToken({index: 0, offset: 0});
-      expect(tokenized.segments).toEqual([token('hi!')]);
-      expect(tokenized.undo()).toBe(typed);
-      expect(typed.undo()).toBe(list);
-    });
-
     it('coalesces consecutive delete operations into one undo step', () => {
       let list = new TokenSegmentList([text('abc')]);
       let afterC = list.delete({index: 0, offset: 3}, graphemeSegmenter, Direction.Backward);
diff --git a/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx b/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx
index 3e8d3f44866..24c3f557ec6 100644
--- a/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx
+++ b/packages/@react-spectrum/ai/test/utils/tokenFieldBrowserUtils.tsx
@@ -40,11 +40,11 @@ export const abTokCd = segments(text('ab'), token('TOK'), text('cd'));
 
 /** Story sample for adjacent-token arrow navigation. */
 export const adjacentTokensSample = new TokenSegmentList([
-  {type: 'token', text: 'Hello'},
-  {type: 'text', text: ' tokens testing '},
-  {type: 'token', text: 'World'},
-  {type: 'token', text: 'Testing'},
-  {type: 'text', text: ' test'}
+  token('Hello'),
+  text(' tokens testing '),
+  token('World'),
+  token('Testing'),
+  text(' test')
 ]);
 
 export function expectFieldText(value: TokenSegmentList, str: string) {

From 4be301f34c13388321c797fc3c957afdd18d80c8 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Wed, 24 Jun 2026 22:27:51 -0700
Subject: [PATCH 23/34] Improve IME composition event handling

---
 .../@react-spectrum/ai/src/TokenField.tsx     | 168 ++++++++++---
 .../TokenField.composition.browser.test.tsx   | 235 ++++++++++++++++++
 vitest.browser.config.ts                      |  46 ++++
 3 files changed, 417 insertions(+), 32 deletions(-)
 create mode 100644 packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index 0699cbce587..e37205224bb 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -121,12 +121,27 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
       ref.current === getActiveElement(getOwnerDocument(ref.current))
     ) {
       setCursor(ref.current, state.caretPosition);
-      caretPosition.current = state.caretPosition;
     }
+
+    caretPosition.current = state.caretPosition;
   });
 
+  let mutationTracker = useMutationTracker(ref);
+  let compositionStart = useRef<[Position, Position] | null>(null);
+
   // Handle text editing commands and prevent browser default behavior.
   useEvent(ref, 'beforeinput', e => {
+    // Android sometimes doesn't fire a compositionend event before a regular input event.
+    if (compositionStart.current && !e.isComposing) {
+      mutationTracker.stop();
+      compositionStart.current = null;
+    }
+
+    // Ignore events during composition.
+    if (e.isComposing) {
+      return;
+    }
+
     let selection = window.getSelection();
     if (!selection || selection.rangeCount === 0) {
       return;
@@ -254,20 +269,36 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
   });
 
   // Composition events are not cancelable, so we need to store the start position and update the value in the compositionend event.
-  let compositionStart = useRef<[Position, Position] | null>(null);
   useEvent(ref, 'compositionstart', () => {
-    let selection = window.getSelection();
-    if (!selection || selection.rangeCount === 0) {
-      return;
+    // Track mutations to the DOM during composition so we can undo them in compositionend.
+    mutationTracker.start();
+
+    let range = window.getSelection()?.getRangeAt(0);
+    if (range) {
+      let [start, end] = rangeToPositions(ref.current!, range);
+      compositionStart.current = [start, end];
+
+      // Normalize the range to ensure it is not inside a token, otherwise the browser
+      // will attempt to insert the composed text into the token instead of replacing it.
+      let r = createDOMRange(ref.current!, start, end);
+      if (r.startContainer !== range.startContainer || r.startOffset !== range.startOffset) {
+        range.setStart(r.startContainer, r.startOffset);
+      }
+      if (r.endContainer !== range.endContainer || r.endOffset !== range.endOffset) {
+        range.setEnd(r.endContainer, r.endOffset);
+      }
     }
-    let range = selection.getRangeAt(0);
-    compositionStart.current = rangeToPositions(ref.current!, range);
   });
 
   useEvent(ref, 'compositionend', e => {
+    // Undo all DOM mutations that occurred during composition so that it
+    // matches React's virtual dom, then re-apply the update to React state.
+    mutationTracker.stop();
+
     let range = compositionStart.current;
     if (range) {
-      apply(tokens => tokens.replaceRange(range[0], range[1], e.data));
+      compositionStart.current = null;
+      apply(tokens => tokens.replaceRange(range[0], range[1], e.data || ''));
     }
   });
 
@@ -320,26 +351,28 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
   });
 
   useSelectionChange(ref, () => {
+    if (compositionStart.current) {
+      return;
+    }
+
     state.endCoalescing();
 
     // When the cursor moves next to a token, announce it.
     // Otherwise the screen reader will only announce the first/last character.
     if (window.getSelection()?.isCollapsed) {
       let [start, end] = getSelection(ref.current!)!;
-      if (start.index === end.index && start.offset === 0) {
+      if (start.offset === 0) {
         let segment = state.segments[start.index];
-        if (segment?.type === 'token') {
-          announce(segment.text, 'assertive');
+        if (segment?.type !== 'token') {
+          segment = state.segments[start.index - 1];
         }
-      } else if (start.offset === state.segments[start.index]?.text.length) {
-        let segment = state.segments[start.index + 1];
         if (segment?.type === 'token') {
           announce(segment.text, 'assertive');
         }
-      }
 
-      // Update the caret position in the value.
-      setState(value => value.withCaretPosition(end));
+        // Update the caret position in the value.
+        setState(value => value.withCaretPosition(end));
+      }
     }
   });
 
@@ -654,7 +687,7 @@ function getPosition(container: Element, node: Node, offset: number): Position {
     if (offset === 0 && node.previousSibling?.nodeType === Node.TEXT_NODE) {
       index--;
       offset = node.previousSibling?.textContent?.length ?? 0;
-    } else if (atEnd && node.nextSibling) {
+    } else if (atEnd) {
       index++;
       offset = 0;
     }
@@ -685,24 +718,33 @@ export function positionToDOMRange(root: Element, pos: Position): Range {
 
 function createDOMRange(root: Element, start: Position, end: Position): Range {
   let range = document.createRange();
-  let [startChild, startOffset] = getDOMOffset(root, start);
-  let [endChild, endOffset] = getDOMOffset(root, end);
-  range.setStart(startChild, startOffset);
-  range.setEnd(endChild, endOffset);
-  return range;
-}
+  let startChild = root.childNodes[start.index];
+  if (!startChild) {
+    range.setStart(root, Math.min(root.childNodes.length, start.index));
+  } else if (startChild.nodeType === Node.ELEMENT_NODE) {
+    // Place the cursor outside the token wrapper element.
+    if (start.offset > 0) {
+      range.setStartAfter(startChild);
+    } else {
+      range.setStartBefore(startChild);
+    }
+  } else {
+    range.setStart(startChild, start.offset);
+  }
 
-function getDOMOffset(root: Element, pos: Position): [Node, number] {
-  let child = root.childNodes[pos.index];
-  if (!child) {
-    return [root, Math.min(root.childNodes.length, pos.index)];
-  } else if (child.nodeType === Node.ELEMENT_NODE) {
-    // Place the cursor in one of the zero width space nodes.
-    return [child, pos.offset > 0 ? 2 : 0];
+  let endChild = root.childNodes[end.index];
+  if (!endChild) {
+    range.setEnd(root, Math.min(root.childNodes.length, end.index));
+  } else if (endChild.nodeType === Node.ELEMENT_NODE) {
+    if (end.offset > 0) {
+      range.setEndAfter(endChild);
+    } else {
+      range.setEndBefore(endChild);
+    }
   } else {
-    // Place the cursor in the text node.
-    return [child, pos.offset];
+    range.setEnd(endChild, end.offset);
   }
+  return range;
 }
 
 function isSamePosition(a: Position, b: Position): boolean {
@@ -752,3 +794,65 @@ function useSelectionChange(ref: React.RefObject<Element | null>, handler: () =>
     }
   });
 }
+
+function useMutationTracker(ref: React.RefObject<Element | null>) {
+  let mutationTracker = useRef<(() => void) | null>(null);
+
+  // Disconnect the mutation observer if the field unmounts mid-composition.
+  useLayoutEffect(
+    () => () => {
+      mutationTracker.current?.();
+      mutationTracker.current = null;
+    },
+    []
+  );
+
+  return {
+    start() {
+      // Android sometimes fires two compositionstart events in a row, without a compositionend.
+      // In that case, reuse the existing tracker.
+      mutationTracker.current ||= trackMutations(ref.current!);
+    },
+    stop() {
+      mutationTracker.current?.();
+      mutationTracker.current = null;
+    }
+  };
+}
+
+// Tracks mutations to the DOM until the returned function is called,
+// at which point the mutations are reverted.
+function trackMutations(element: Element) {
+  let mutations: MutationRecord[] = [];
+  let observer = new MutationObserver(records => {
+    mutations.push(...records);
+  });
+
+  observer.observe(element, {
+    childList: true,
+    subtree: true,
+    characterData: true,
+    characterDataOldValue: true
+  });
+
+  return () => {
+    mutations.push(...observer.takeRecords());
+    observer.disconnect();
+
+    for (let record of mutations.reverse()) {
+      switch (record.type) {
+        case 'childList':
+          for (let node of record.removedNodes) {
+            record.target.insertBefore(node, record.nextSibling);
+          }
+          for (let node of record.addedNodes) {
+            record.target.removeChild(node);
+          }
+          break;
+        case 'characterData':
+          record.target.nodeValue = record.oldValue;
+          break;
+      }
+    }
+  };
+}
diff --git a/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
new file mode 100644
index 00000000000..3deec451981
--- /dev/null
+++ b/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
@@ -0,0 +1,235 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * IME composition tests that emulate soft-keyboard (Android) text entry.
+ *
+ * Android's keyboard (Gboard/Samsung) routes nearly all editing — including plain
+ * English typing, autocorrect, the suggestion bar, and backspace — through
+ * non-cancelable composition events, and frequently recomposes the entire current
+ * word rather than the single keystroke. We reproduce that here with real composition
+ * events driven over CDP (Input.imeSetComposition / Input.insertText), which produce
+ * trusted events AND real contentEditable DOM mutation, unlike synthetic dispatchEvent.
+ *
+ * CDP is Chromium-only, so these tests are gated to Chromium.
+ */
+
+import {
+  abTokCd,
+  focusField,
+  navigateCaret,
+  renderControlledTokenField,
+  segments,
+  setFieldSelection,
+  text,
+  token,
+  waitForFieldText
+} from './utils/tokenFieldBrowserUtils';
+import {commands, userEvent} from 'vitest/browser';
+import {describe, expect, it} from 'vitest';
+import {isFirefox, isWebKit} from 'react-aria/private/utils/platform';
+import React from 'react';
+import {render} from 'vitest-browser-react';
+import {Token, TokenField} from '../src/TokenField';
+import {TokenSegmentList} from '../src/TokenSegmentList';
+
+declare module 'vitest/browser' {
+  interface BrowserCommands {
+    lockClipboard: () => Promise<void>;
+    unlockClipboard: () => void;
+    setComposition: (
+      text: string,
+      selectionStart: number,
+      selectionEnd: number,
+      replacementStart?: number,
+      replacementEnd?: number
+    ) => Promise<void>;
+    commitComposition: (text: string) => Promise<void>;
+  }
+}
+
+/**
+ * Types a word the way a soft keyboard does: grows an active composition one grapheme
+ * at a time (compositionstart + a series of compositionupdate), then commits it. If
+ * `commit` differs from the typed string it emulates an autocorrect/replacement on commit.
+ */
+async function composeWord(word: string, commit = word) {
+  for (let i = 1; i <= word.length; i++) {
+    let sub = word.slice(0, i);
+    await commands.setComposition(sub, sub.length, sub.length);
+  }
+  await commands.commitComposition(commit);
+}
+
+/** Visible text of the field (DOM), with the token zero-width-space markers removed. */
+function domText(textbox: {element: () => Element}): string {
+  return textbox.element().textContent?.replace(/​/g, '') ?? '';
+}
+
+/** Asserts the user-visible DOM text, which can diverge from the model after a composition. */
+async function expectDOMText(textbox: {element: () => Element}, str: string) {
+  await expect.poll(() => domText(textbox)).toBe(str);
+}
+
+// CDP composition is Chromium only.
+const itAndroid = isFirefox() || isWebKit() ? it.skip : it;
+const describeOrSkip = parseInt(React.version, 10) < 19 ? describe.skip : describe;
+
+describeOrSkip('TokenField IME composition (Android)', () => {
+  itAndroid('types a word via composition into an empty field', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+    await focusField(textbox);
+    await composeWord('hello');
+    await waitForFieldText(getValue, 'hello');
+    await expectDOMText(textbox, 'hello');
+  });
+
+  itAndroid('types via composition after existing text', async () => {
+    let list = segments(text('ab'));
+    let {textbox, getValue} = await renderControlledTokenField(list);
+    await navigateCaret(textbox, list, {index: 0, offset: 2});
+    await composeWord('cd');
+    await waitForFieldText(getValue, 'abcd');
+    await expectDOMText(textbox, 'abcd');
+  });
+
+  itAndroid('commits an autocorrected word', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+    await focusField(textbox);
+    // User types "teh", keyboard autocorrects to "the" on commit.
+    await composeWord('teh', 'the');
+    await waitForFieldText(getValue, 'the');
+    await expectDOMText(textbox, 'the');
+  });
+
+  itAndroid('types via composition after a token', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(abTokCd);
+    // Caret just after the token (start of trailing "cd").
+    await navigateCaret(textbox, abTokCd, {index: 2, offset: 0});
+    await composeWord('x');
+    await waitForFieldText(getValue, 'abTOKxcd');
+    await expectDOMText(textbox, 'abTOKxcd');
+  });
+
+  itAndroid('backspaces within an active composition', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+    await focusField(textbox);
+    // Grow an active (uncommitted) composition, then shrink it, then commit.
+    await commands.setComposition('h', 1, 1);
+    await commands.setComposition('he', 2, 2);
+    await commands.setComposition('hel', 3, 3);
+    await commands.setComposition('hell', 4, 4);
+    await commands.setComposition('hello', 5, 5);
+    await commands.setComposition('hell', 4, 4);
+    await commands.setComposition('hel', 3, 3);
+    await commands.commitComposition('hel');
+    await waitForFieldText(getValue, 'hel');
+    await expectDOMText(textbox, 'hel');
+  });
+
+  // Android recomposes the whole current word (autocorrect, suggestion bar) by replacing
+  // the existing characters. Driven via Input.imeSetComposition replacement offsets
+  // (absolute, [start,end) into the text). Negative/caret-relative offsets crash the renderer.
+  itAndroid('recomposes the whole current word', async () => {
+    let list = segments(text('hello'));
+    let {textbox, getValue} = await renderControlledTokenField(list);
+    await navigateCaret(textbox, list, {index: 0, offset: 5});
+    await commands.setComposition('HELLO', 5, 5, 0, 5);
+    await commands.commitComposition('HELLO');
+    await waitForFieldText(getValue, 'HELLO');
+    await expectDOMText(textbox, 'HELLO');
+  });
+
+  itAndroid('composes a word immediately before a token', async () => {
+    // Caret at the very start, before "ab" / token / "cd".
+    let {textbox, getValue} = await renderControlledTokenField(abTokCd);
+    await navigateCaret(textbox, abTokCd, {index: 0, offset: 0});
+    await composeWord('x');
+    await waitForFieldText(getValue, 'xabTOKcd');
+    await expectDOMText(textbox, 'xabTOKcd');
+  });
+
+  itAndroid('composes between two adjacent tokens', async () => {
+    let list = new TokenSegmentList([token('A'), token('B')]);
+    let {textbox, getValue} = await renderControlledTokenField(list);
+    // Caret between the two tokens.
+    await navigateCaret(textbox, list, {index: 1, offset: 0});
+    await composeWord('x');
+    await waitForFieldText(getValue, 'AxB'); // text "x" inserted between tokens A and B
+    await expectDOMText(textbox, 'AxB');
+  });
+
+  // Regression test for on-device duplication when typing immediately after a leading token.
+  // The browser composes into a text node it places after the contentEditable=false token;
+  // without the compositionend DOM-reconciliation the DOM would show 'TOKhellohello' even
+  // though the model is the correct 'TOKhello'.
+  itAndroid('composes immediately after a lone leading token without duplicating', async () => {
+    let list = new TokenSegmentList([token('TOK')]);
+    let {textbox, getValue} = await renderControlledTokenField(list);
+    await focusField(textbox);
+    await userEvent.keyboard('{End}');
+    await composeWord('hello');
+    await waitForFieldText(getValue, 'TOKhello'); // model is correct
+    await expectDOMText(textbox, 'TOKhello'); // DOM must match the model, not 'TOKhellohello'
+  });
+
+  itAndroid('replaces a clicked (selected) token via composition', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(abTokCd);
+    await focusField(textbox);
+    // Clicking a token selects the whole element (userSelect: all).
+    let tokenEl = textbox.element().querySelector('[contenteditable="false"]') as HTMLElement;
+    await userEvent.click(tokenEl);
+    await composeWord('x');
+    await waitForFieldText(getValue, 'abxcd');
+    await expectDOMText(textbox, 'abxcd');
+  });
+
+  itAndroid('replaces a selected token via composition (boundary range)', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(abTokCd);
+    await focusField(textbox);
+    // End of "ab" through start of "cd" — spans the token, the shape a click produces.
+    setFieldSelection(textbox.element(), {index: 0, offset: 2}, {index: 2, offset: 0});
+    await composeWord('x');
+    await waitForFieldText(getValue, 'abxcd');
+    await expectDOMText(textbox, 'abxcd');
+  });
+
+  // If the controlled parent re-renders the field while a composition is active,
+  // React reconciliation can clobber the text node the IME is composing into,
+  // corrupting or duplicating input. Here we force an external re-render.
+  itAndroid('survives an external re-render mid-composition', async () => {
+    let forceRender: () => void = () => {};
+    function Harness() {
+      let [value, setValue] = React.useState(() => segments(text('')));
+      let [, setTick] = React.useState(0);
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      forceRender = () => setTick(t => t + 1);
+      return (
+        <TokenField value={value} onChange={setValue} aria-label="rerender-field">
+          {segment => <Token>{segment.text}</Token>}
+        </TokenField>
+      );
+    }
+    let screen = await render(<Harness />);
+    let textbox = screen.getByRole('textbox', {name: 'rerender-field'});
+    await focusField(textbox);
+
+    await commands.setComposition('h', 1, 1);
+    await commands.setComposition('he', 2, 2);
+    forceRender(); // parent re-renders while composition is active
+    await commands.setComposition('hel', 3, 3);
+    await commands.setComposition('hell', 4, 4);
+    await commands.commitComposition('hello');
+
+    await expectDOMText(textbox, 'hello');
+  });
+});
diff --git a/vitest.browser.config.ts b/vitest.browser.config.ts
index aeede49a7a6..62348430ff4 100644
--- a/vitest.browser.config.ts
+++ b/vitest.browser.config.ts
@@ -163,10 +163,34 @@ function iconWrapperPlugin(): Plugin {
 
 let unlock: ((value: any) => void) | null = null;
 
+// Cache one CDP session per page so we don't re-attach on every composition step.
+// Chromium only — used by the IME/composition commands below.
+const cdpSessions = new WeakMap<object, Promise<any>>();
+function getCDP(page: any, context: any): Promise<any> {
+  let session = cdpSessions.get(page);
+  if (!session) {
+    session = context.newCDPSession(page);
+    cdpSessions.set(page, session!);
+  }
+  return session!;
+}
+
 declare module 'vitest/browser' {
   interface BrowserCommands {
     lockClipboard: () => Promise<void>;
     unlockClipboard: () => void;
+    // Drive a real IME composition via CDP to emulate soft-keyboard (e.g. Android) input.
+    // Chromium only. selectionStart/End and replacementStart/End are passed straight to
+    // Input.imeSetComposition (offsets are relative to the current caret).
+    setComposition: (
+      text: string,
+      selectionStart: number,
+      selectionEnd: number,
+      replacementStart?: number,
+      replacementEnd?: number
+    ) => Promise<void>;
+    // Commit text that doesn't come from a key press (finalizes an active composition).
+    commitComposition: (text: string) => Promise<void>;
   }
 }
 
@@ -255,6 +279,28 @@ export default defineConfig({
             unlock(null);
             unlock = null;
           }
+        },
+        setComposition: async (
+          {page, context}: any,
+          text,
+          selectionStart,
+          selectionEnd,
+          replacementStart,
+          replacementEnd
+        ) => {
+          const cdp = await getCDP(page, context);
+          const params: Record<string, unknown> = {text, selectionStart, selectionEnd};
+          if (replacementStart != null) {
+            params.replacementStart = replacementStart;
+          }
+          if (replacementEnd != null) {
+            params.replacementEnd = replacementEnd;
+          }
+          await cdp.send('Input.imeSetComposition', params);
+        },
+        commitComposition: async ({page, context}: any, text) => {
+          const cdp = await getCDP(page, context);
+          await cdp.send('Input.insertText', {text});
         }
       }
     },

From 57f66797c4689cd768fa623f9b1deb950f8ca47a Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 26 Jun 2026 13:50:52 -0700
Subject: [PATCH 24/34] refactor composition event handling to emit onChange
 but not re-render

this fixes autocomplete
---
 .../@react-spectrum/ai/src/TokenField.tsx     | 215 +++++++++++-------
 .../TokenField.composition.browser.test.tsx   | 182 +++++++++++++++
 2 files changed, 312 insertions(+), 85 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/TokenField.tsx b/packages/@react-spectrum/ai/src/TokenField.tsx
index e37205224bb..62d637ce6ea 100644
--- a/packages/@react-spectrum/ai/src/TokenField.tsx
+++ b/packages/@react-spectrum/ai/src/TokenField.tsx
@@ -26,7 +26,16 @@ import {getOwnerDocument} from 'react-aria/private/utils/domHelpers';
 import {isMac} from 'react-aria/private/utils/platform';
 import {mergeProps} from 'react-aria/mergeProps';
 import {mergeRefs} from 'react-aria/mergeRefs';
-import React, {ForwardedRef, forwardRef, HTMLAttributes, useMemo, useRef, useState} from 'react';
+import React, {
+  ForwardedRef,
+  forwardRef,
+  HTMLAttributes,
+  memo,
+  useCallback,
+  useMemo,
+  useRef,
+  useState
+} from 'react';
 import {RenderProps, StyleRenderProps, useRenderProps} from 'react-aria-components/useRenderProps';
 import {SlotProps, useSlottedContext} from 'react-aria-components/slots';
 import {useControlledState} from 'react-stately/useControlledState';
@@ -103,43 +112,84 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
   let dropPosition = useRef<Position | null>(null);
   let transferredData = useRef<TokenFieldSegment[] | null>(null);
 
+  let nextValue = useRef<TokenSegmentList | null>(null);
   let apply = (fn: (value: TokenSegmentList) => TokenSegmentList) => {
     setState(value => {
       let newValue = fn(value);
+      nextValue.current = newValue;
       onAutocompleteChange?.(newValue.toString());
       return newValue;
     });
   };
 
+  // Composition events are not cancelable. The browser will mutate the DOM, making it out of sync with React.
+  // To account for this, we prevent React from re-rendering during composition, and track DOM mutations performed
+  // by the browser. When composition ends, we revert the DOM to its original state, and re-render with React.
+  // Mutating the DOM in any way during composition breaks the IME, causing composition to end unexpectedly.
+  // During composition, we still emit updates via onChange to ensure that things like autocomplete work,
+  // but we don't actually re-render to the DOM unless the value changes from what we expect (e.g. inserting a completion).
+  let [isComposing, setComposing] = useState(false);
+  let mutationTracker = useMutationTracker(ref);
+  let startComposition = useCallback(() => {
+    mutationTracker.start();
+    setComposing(true);
+  }, [mutationTracker]);
+  let stopComposition = useCallback(() => {
+    mutationTracker.stop();
+    setComposing(false);
+  }, [mutationTracker]);
+
+  useEvent(ref, 'compositionstart', () => {
+    startComposition();
+
+    let range = window.getSelection()?.getRangeAt(0);
+    if (range) {
+      let [start, end] = rangeToPositions(ref.current!, range);
+
+      // Normalize the range to ensure it is not inside a token, otherwise the browser
+      // will attempt to insert the composed text into the token instead of replacing it.
+      let r = createDOMRange(ref.current!, start, end);
+      if (r.startContainer !== range.startContainer || r.startOffset !== range.startOffset) {
+        range.setStart(r.startContainer, r.startOffset);
+      }
+      if (r.endContainer !== range.endContainer || r.endOffset !== range.endOffset) {
+        range.setEnd(r.endContainer, r.endOffset);
+      }
+    }
+  });
+
+  useEvent(ref, 'compositionend', stopComposition);
+
+  // If a prop update occurs during composition that doesn't match the expected value,
+  // end composition and re-render the controlled value.
+  useLayoutEffect(() => {
+    if (isComposing && state !== nextValue.current) {
+      stopComposition();
+    }
+    nextValue.current = state;
+  });
+
   let caretPosition = useRef<Position | null>(null);
   useLayoutEffect(() => {
-    // Only move the caret when the field is already focused.
     if (
       ref.current &&
       state.caretPosition &&
-      state.caretPosition !== caretPosition.current &&
-      ref.current === getActiveElement(getOwnerDocument(ref.current))
+      !isComposing &&
+      state.caretPosition !== caretPosition.current
     ) {
-      setCursor(ref.current, state.caretPosition);
+      // Only move the caret when the field is already focused.
+      if (ref.current === getActiveElement(getOwnerDocument(ref.current))) {
+        setCursor(ref.current, state.caretPosition);
+      }
+      caretPosition.current = state.caretPosition;
     }
-
-    caretPosition.current = state.caretPosition;
   });
 
-  let mutationTracker = useMutationTracker(ref);
-  let compositionStart = useRef<[Position, Position] | null>(null);
-
   // Handle text editing commands and prevent browser default behavior.
   useEvent(ref, 'beforeinput', e => {
     // Android sometimes doesn't fire a compositionend event before a regular input event.
-    if (compositionStart.current && !e.isComposing) {
-      mutationTracker.stop();
-      compositionStart.current = null;
-    }
-
-    // Ignore events during composition.
-    if (e.isComposing) {
-      return;
+    if (isComposing && !e.isComposing) {
+      stopComposition();
     }
 
     let selection = window.getSelection();
@@ -153,6 +203,8 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
     switch (e.inputType) {
       case 'insertText':
       case 'insertReplacementText':
+      case 'insertCompositionText':
+      case 'insertFromComposition': // Removed from the spec, but still fired by Safari.
       case 'insertFromPaste':
       case 'insertFromYank':
       case 'insertFromDrop': {
@@ -187,7 +239,10 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
             start,
             end,
             data,
-            e.inputType === 'insertText' // Don't coalesce paste/drop events with other edits.
+            // Don't coalesce paste/drop events with other edits.
+            e.inputType === 'insertText' ||
+              e.inputType === 'insertCompositionText' ||
+              e.inputType === 'insertFromComposition'
           )
         );
         break;
@@ -214,7 +269,8 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
       case 'deleteSoftLineForward':
       case 'deleteSoftLineBackward':
       case 'deleteContent':
-      case 'deleteByCut': {
+      case 'deleteByCut':
+      case 'deleteCompositionText': {
         if (!range.collapsed) {
           apply(tokens => tokens.replaceRange(start, end, ''));
           break;
@@ -268,40 +324,6 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
     e.preventDefault();
   });
 
-  // Composition events are not cancelable, so we need to store the start position and update the value in the compositionend event.
-  useEvent(ref, 'compositionstart', () => {
-    // Track mutations to the DOM during composition so we can undo them in compositionend.
-    mutationTracker.start();
-
-    let range = window.getSelection()?.getRangeAt(0);
-    if (range) {
-      let [start, end] = rangeToPositions(ref.current!, range);
-      compositionStart.current = [start, end];
-
-      // Normalize the range to ensure it is not inside a token, otherwise the browser
-      // will attempt to insert the composed text into the token instead of replacing it.
-      let r = createDOMRange(ref.current!, start, end);
-      if (r.startContainer !== range.startContainer || r.startOffset !== range.startOffset) {
-        range.setStart(r.startContainer, r.startOffset);
-      }
-      if (r.endContainer !== range.endContainer || r.endOffset !== range.endOffset) {
-        range.setEnd(r.endContainer, r.endOffset);
-      }
-    }
-  });
-
-  useEvent(ref, 'compositionend', e => {
-    // Undo all DOM mutations that occurred during composition so that it
-    // matches React's virtual dom, then re-apply the update to React state.
-    mutationTracker.stop();
-
-    let range = compositionStart.current;
-    if (range) {
-      compositionStart.current = null;
-      apply(tokens => tokens.replaceRange(range[0], range[1], e.data || ''));
-    }
-  });
-
   let writeClipboardData = (e: ClipboardEvent | DragEvent) => {
     if ('clipboardData' in e) {
       e.preventDefault();
@@ -351,7 +373,7 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
   });
 
   useSelectionChange(ref, () => {
-    if (compositionStart.current) {
+    if (isComposing) {
       return;
     }
 
@@ -431,9 +453,16 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
   let wordModKey = isMac() ? 'Alt' : 'Control';
   let shortcuts: Record<string, () => boolean | void> = {
     [`${mod}+z`]: () => {
+      // If composing, the browser handles undo natively.
+      if (isComposing) {
+        return false;
+      }
       apply(state => state.undo());
     },
     [isMac() ? 'Shift+Meta+z' : 'Control+y']: () => {
+      if (isComposing) {
+        return false;
+      }
       apply(state => state.redo());
     },
     ArrowLeft: () => {
@@ -550,25 +579,27 @@ export const TokenField = /*#__PURE__*/ (forwardRef as forwardRefType)(function
       data-disabled={isDisabled || undefined}
       data-readonly={isReadOnly || undefined}
       style={{...renderProps.style, whiteSpace: 'pre-wrap'}}>
-      {state.segments.map((v, i) => {
-        switch (v.type) {
-          case 'token': {
-            let token = children(v);
-            return (
-              // Wrap tokens in zero-width spaces so the cursor is placed correctly.
-              <span key={i}>
-                {'\u200b'}
-                {token}
-                {'\u200b'}
-              </span>
-            );
+      <CompositionRenderBlocker isComposing={isComposing}>
+        {state.segments.map((v, i) => {
+          switch (v.type) {
+            case 'token': {
+              let token = children(v);
+              return (
+                // Wrap tokens in zero-width spaces so the cursor is placed correctly.
+                <span key={i}>
+                  {'\u200b'}
+                  {token}
+                  {'\u200b'}
+                </span>
+              );
+            }
+            case 'text':
+              return v.text;
           }
-          case 'text':
-            return v.text;
-        }
-      })}
-      {/* Force cursor to the next line if the last segment ends with a newline. */}
-      {state.segments.at(-1)?.text.endsWith('\n') && <br />}
+        })}
+        {/* Force cursor to the next line if the last segment ends with a newline. */}
+        {state.segments.at(-1)?.text.endsWith('\n') && <br />}
+      </CompositionRenderBlocker>
     </div>
   );
 });
@@ -669,6 +700,7 @@ function getPosition(container: Element, node: Node, offset: number): Position {
   if (node.nodeType === Node.ELEMENT_NODE) {
     let tokenNode = node.childNodes[1];
     let atEnd: boolean;
+    let endOffset = 0;
     if (originalNode === tokenNode) {
       // Cursor is inside the token.
       atEnd = offset > 0;
@@ -678,6 +710,9 @@ function getPosition(container: Element, node: Node, offset: number): Position {
     } else {
       // Cursor is on one of the zero width spaces.
       atEnd = originalNode !== tokenNode.previousSibling;
+      // If the offset is greater than 1, the browser is trying to insert text into
+      // the zero width space node. This will actually end up in the next text node.
+      endOffset = atEnd && offset > 1 ? offset - 1 : 0;
     }
 
     offset = atEnd ? (tokenNode?.textContent?.length ?? 0) : 0;
@@ -689,7 +724,7 @@ function getPosition(container: Element, node: Node, offset: number): Position {
       offset = node.previousSibling?.textContent?.length ?? 0;
     } else if (atEnd) {
       index++;
-      offset = 0;
+      offset = endOffset;
     }
   }
   return {index, offset};
@@ -807,17 +842,20 @@ function useMutationTracker(ref: React.RefObject<Element | null>) {
     []
   );
 
-  return {
-    start() {
-      // Android sometimes fires two compositionstart events in a row, without a compositionend.
-      // In that case, reuse the existing tracker.
-      mutationTracker.current ||= trackMutations(ref.current!);
-    },
-    stop() {
-      mutationTracker.current?.();
-      mutationTracker.current = null;
-    }
-  };
+  return useMemo(
+    () => ({
+      start() {
+        // Android sometimes fires two compositionstart events in a row, without a compositionend.
+        // In that case, reuse the existing tracker.
+        mutationTracker.current ||= trackMutations(ref.current!);
+      },
+      stop() {
+        mutationTracker.current?.();
+        mutationTracker.current = null;
+      }
+    }),
+    [ref]
+  );
 }
 
 // Tracks mutations to the DOM until the returned function is called,
@@ -856,3 +894,10 @@ function trackMutations(element: Element) {
     }
   };
 }
+
+// Prevents React from re-rendering during composition events.
+const CompositionRenderBlocker = memo(
+  ({children}: {children: React.ReactNode; isComposing: boolean}) => children,
+  (prevProps, nextProps) =>
+    nextProps.isComposing ? true : prevProps.children === nextProps.children
+);
diff --git a/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
index 3deec451981..64c644f275d 100644
--- a/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
@@ -26,6 +26,8 @@
 import {
   abTokCd,
   focusField,
+  isMacPlatform,
+  modKey,
   navigateCaret,
   renderControlledTokenField,
   segments,
@@ -232,4 +234,184 @@ describeOrSkip('TokenField IME composition (Android)', () => {
 
     await expectDOMText(textbox, 'hello');
   });
+
+  // Android sometimes fires compositionstart and then a regular (non-composing) input event
+  // without ever firing compositionend, leaving the field stuck in composing state (render
+  // blocked, DOM diverged from the model). The beforeinput handler ends composition when a
+  // non-composing event arrives mid-composition. We reproduce the exact sequence with CDP:
+  // setComposition starts a composition, then a real keypress fires insertText (isComposing
+  // false) with no compositionend in between.
+  itAndroid('recovers when a non-composing input arrives before compositionend', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+    await focusField(textbox);
+
+    await commands.setComposition('h', 1, 1);
+    await userEvent.keyboard('x');
+
+    // The component is not stuck composing: the DOM re-rendered to match the model (a stuck
+    // composition would leave the blocked DOM diverged from the model), with both characters
+    // present and no duplication.
+    await expect.poll(() => domText(textbox)).toBe(getValue().toString());
+    expect(getValue().toString()).toHaveLength(2);
+    expect([...getValue().toString()].sort().join('')).toBe('hx');
+
+    // The field still accepts normal edits afterward (composition state was cleared).
+    await userEvent.keyboard('z');
+    await expect.poll(() => getValue().toString().length).toBe(3);
+  });
+
+  itAndroid('replaces a multi-character text selection via composition', async () => {
+    let list = segments(text('hello'));
+    let {textbox, getValue} = await renderControlledTokenField(list);
+    await focusField(textbox);
+    setFieldSelection(textbox.element(), {index: 0, offset: 0}, {index: 0, offset: 5});
+    await composeWord('z');
+    await waitForFieldText(getValue, 'z');
+    await expectDOMText(textbox, 'z');
+  });
+
+  // Redo goes through the same compose-aware guard as undo: while composing it returns false
+  // so the browser handles it, rather than running the component's model redo (which would
+  // desync the model from the IME-controlled DOM).
+  itAndroid('lets the browser handle redo during composition', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+    let mod = modKey();
+    await focusField(textbox);
+    await composeWord('ab');
+    await userEvent.keyboard(`{${mod}>}z{/${mod}}`); // undo (not composing) -> ''
+    await commands.setComposition('q', 1, 1); // start a composition (model -> 'q')
+
+    let redo = isMacPlatform() ? `{Shift>}{${mod}>}z{/${mod}}{/Shift}` : '{Control>}y{/Control}';
+    await userEvent.keyboard(redo);
+
+    // The component did not redo: the model stays at the composed 'q' and matches the DOM.
+    await expect.poll(() => getValue().toString()).toBe('q');
+    expect(domText(textbox)).toBe(getValue().toString());
+  });
+
+  // Triggering undo mid-composition must not run the component's model undo: that would
+  // revert the model while the IME keeps mutating the DOM, leaving the two out of sync.
+  // Instead the shortcut is ignored (returns false) so the browser handles undo natively.
+  itAndroid('lets the browser handle undo during composition', async () => {
+    let {textbox, getValue} = await renderControlledTokenField(segments(text('')));
+    let mod = modKey();
+    await focusField(textbox);
+    await composeWord('hi'); // commit a word to build undo history
+    await commands.setComposition('x', 1, 1); // start a new composition (model -> 'hix')
+
+    await userEvent.keyboard(`{${mod}>}z{/${mod}}`);
+
+    // The component did not undo: the model is unchanged and still matches the DOM.
+    // (Without the fix, the model would revert to '' while the DOM still shows 'hix'.)
+    let domText = () => textbox.element().textContent?.replace(/​/g, '') ?? '';
+    await expect.poll(() => getValue().toString()).toBe('hix');
+    expect(domText()).toBe(getValue().toString());
+  });
+
+  // onChange must fire for each composition update (before compositionend) so external UI
+  // such as autocomplete can react to the in-progress text.
+  itAndroid('emits onChange during composition', async () => {
+    let changes: string[] = [];
+    function Harness() {
+      let [value, setValue] = React.useState(() => segments(text('')));
+      return (
+        <TokenField
+          value={value}
+          onChange={v => {
+            changes.push(v.toString());
+            setValue(v);
+          }}
+          aria-label="onchange-field">
+          {segment => <Token>{segment.text}</Token>}
+        </TokenField>
+      );
+    }
+    let screen = await render(<Harness />);
+    let textbox = screen.getByRole('textbox', {name: 'onchange-field'});
+    await focusField(textbox);
+
+    // Grow an active composition WITHOUT committing.
+    await commands.setComposition('h', 1, 1);
+    await commands.setComposition('he', 2, 2);
+    await commands.setComposition('hel', 3, 3);
+
+    // Updates were emitted mid-composition, before any compositionend.
+    await expect.poll(() => changes.at(-1)).toBe('hel');
+    expect(changes).toContain('h');
+
+    await commands.commitComposition('hel');
+    await expectDOMText(textbox, 'hel');
+  });
+
+  // While composing, onChange fires (so state updates) but React must not re-render the
+  // editable subtree — re-rendering would reset the DOM nodes and break the IME. We assert
+  // a token child is not re-invoked during composition, then is once composition ends.
+  itAndroid('does not re-render the editable content until composition ends', async () => {
+    let renderCount = 0;
+    function CountingToken({children}: {children: string}) {
+      renderCount++;
+      return <Token>{children}</Token>;
+    }
+    function Harness() {
+      // Leading token (rendered via the child fn) followed by editable text.
+      let [value, setValue] = React.useState(() => new TokenSegmentList([token('A'), text('')]));
+      return (
+        <TokenField value={value} onChange={setValue} aria-label="norerender-field">
+          {segment => <CountingToken>{segment.text}</CountingToken>}
+        </TokenField>
+      );
+    }
+    let screen = await render(<Harness />);
+    let textbox = screen.getByRole('textbox', {name: 'norerender-field'});
+    await focusField(textbox);
+    // Caret after the token.
+    await userEvent.keyboard('{End}');
+
+    let countBefore = renderCount;
+    await commands.setComposition('h', 1, 1);
+    await commands.setComposition('he', 2, 2);
+    await commands.setComposition('hel', 3, 3);
+
+    // onChange has updated state, but the editable content was not re-rendered.
+    expect(renderCount).toBe(countBefore);
+
+    await commands.commitComposition('hel');
+    // Composition ended -> the content re-renders to match the model.
+    await expect.poll(() => renderCount).toBeGreaterThan(countBefore);
+    await expectDOMText(textbox, 'Ahel');
+  });
+
+  // If a controlled update arrives mid-composition that doesn't match the composed value
+  // (e.g. the user picks an autocomplete completion), composition ends early and the DOM
+  // re-renders so it matches the controlled value rather than the in-progress composition.
+  itAndroid('ends composition early when a controlled update inserts a completion', async () => {
+    let valueRef = {current: segments(text(''))};
+    let setValueExternal: (v: TokenSegmentList) => void = () => {};
+    function Harness() {
+      let [value, setValue] = React.useState(() => segments(text('')));
+      valueRef.current = value;
+      setValueExternal = setValue;
+      return (
+        <TokenField value={value} onChange={setValue} aria-label="completion-field">
+          {segment => <Token>{segment.text}</Token>}
+        </TokenField>
+      );
+    }
+    let screen = await render(<Harness />);
+    let textbox = screen.getByRole('textbox', {name: 'completion-field'});
+    await focusField(textbox);
+
+    // User composes the start of a word.
+    await commands.setComposition('c', 1, 1);
+    await commands.setComposition('ca', 2, 2);
+    await commands.setComposition('cal', 3, 3);
+    await expect.poll(() => valueRef.current.toString()).toBe('cal');
+
+    // The user selects a completion: the parent replaces the value with a token. This does
+    // not match the in-progress composition, so composition ends early and the DOM updates.
+    setValueExternal(new TokenSegmentList([token('Calendar')]));
+
+    await expectDOMText(textbox, 'Calendar');
+    expect(valueRef.current.toString()).toBe('Calendar');
+  });
 });

From 3b6bd4f340ce695f150491767af2f3c1117095c8 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 26 Jun 2026 14:56:29 -0700
Subject: [PATCH 25/34] cleanup

---
 packages/@react-spectrum/ai/stories/styles.global.css           | 2 +-
 .../ai/test/TokenField.composition.browser.test.tsx             | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/ai/stories/styles.global.css b/packages/@react-spectrum/ai/stories/styles.global.css
index 15b2cac8eef..665027e5685 100644
--- a/packages/@react-spectrum/ai/stories/styles.global.css
+++ b/packages/@react-spectrum/ai/stories/styles.global.css
@@ -7,7 +7,7 @@
   border-radius: 8px;
   outline: none;
   width: 100%;
-  max-width: 500px;
+  max-width: min(85vw, 500px);
   border: 2px solid var(--gray-400);
   background-color: var(--gray-50);
   font: var(--font-size) system-ui;
diff --git a/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx b/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
index 64c644f275d..a7167a73987 100644
--- a/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
+++ b/packages/@react-spectrum/ai/test/TokenField.composition.browser.test.tsx
@@ -390,6 +390,7 @@ describeOrSkip('TokenField IME composition (Android)', () => {
     function Harness() {
       let [value, setValue] = React.useState(() => segments(text('')));
       valueRef.current = value;
+      // eslint-disable-next-line react-hooks/exhaustive-deps
       setValueExternal = setValue;
       return (
         <TokenField value={value} onChange={setValue} aria-label="completion-field">

From 1fa7a923820dacd89891e59a7ef326be346f55e8 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Tue, 7 Jul 2026 10:30:20 -0700
Subject: [PATCH 26/34] lint

---
 packages/@react-spectrum/ai/src/loader/react.tsx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
index ae49ec752fd..6750fb6cfab 100644
--- a/packages/@react-spectrum/ai/src/loader/react.tsx
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -188,9 +188,11 @@ export function PixelLoader(props: PixelLoaderProps) {
   const [tick, setTick] = React.useState(0);
 
   // Restart from the first icon whenever the sequence changes.
-  React.useEffect(() => {
+  let [lastSequence, setLastSequence] = React.useState(sequence);
+  if (lastSequence !== sequence) {
+    setLastSequence(sequence);
     setTick(0);
-  }, [sequence]);
+  }
 
   // Advance the sequence one icon per cycle while playing. Single-icon
   // loaders never start a timer — they're a pure infinite CSS loop.

From 15e31c9bd77eebb32679779c3e77178257b7767f Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 9 Jul 2026 18:20:12 -0700
Subject: [PATCH 27/34] update pixel loader

---
 .../@react-spectrum/ai/src/PromptField.tsx    | 10 ++-
 .../ai/src/PromptFieldContainer.tsx           |  2 +
 .../@react-spectrum/ai/src/loader/data.ts     | 28 ++++----
 .../@react-spectrum/ai/src/loader/react.tsx   | 69 ++++++++++---------
 4 files changed, 58 insertions(+), 51 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index ac36b899923..96c95d12cfc 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -307,12 +307,16 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
         display: 'flex',
         gap: 12,
         alignItems: 'baseline',
-        color: 'body',
+        color: {
+          default: 'transparent-overlay-600',
+          isFocused: 'body'
+        },
+        transition: 'default',
         paddingStart: 4,
         width: 'full'
-      })}>
+      })({isFocused: isFocused || prompt.segments.length > 0})}>
       <CenterBaseline>
-        <PixelLoader size={24} playing={isGenerating} icon={pixelLoader} />
+        <PixelLoader playing={isGenerating} icon={pixelLoader} />
       </CenterBaseline>
       <Autocomplete>
         <TokenField
diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
index c5114c04a81..42f6a2b7e1b 100644
--- a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -125,10 +125,12 @@ const containerBackground = css(`
       --bg-stop-3: light-dark(white, ${color('gray-75')});
       --bg-stop-4: light-dark(white, ${color('gray-75')});
       --border-color: ${token(`container.border.focus`)};
+      --drop-shadow-color: transparent;
 
       &[data-hovered] {
         ${stops('idle', 'hover', 'subtle')}
         --border-color: ${token(`container.border.default`)};
+        --drop-shadow-color: light-dark(${brand(0.5826, 0.2265, -0.4, 0.05)}, ${brand(0.6617, 0.2508, -0.5, 0.05)});
       }
     }
 
diff --git a/packages/@react-spectrum/ai/src/loader/data.ts b/packages/@react-spectrum/ai/src/loader/data.ts
index 0a22ee1a9b4..cdd34d9d1a0 100644
--- a/packages/@react-spectrum/ai/src/loader/data.ts
+++ b/packages/@react-spectrum/ai/src/loader/data.ts
@@ -31,18 +31,18 @@ interface BuildOptions {
 // ai-logo: original 12-cell diamond layout with hand-tuned timings.
 // ─────────────────────────────────────────────────────────────
 export const aiLogo: Cell[] = [
-  {cx: 500, cy: 800, outer: true, stagger: 0, exitStart: 47, fadeIn: [1, 4], fadeOut: [47, 59]},
-  {cx: 300, cy: 700, outer: true, stagger: 2, exitStart: 48, fadeIn: [4, 7], fadeOut: [48, 60]},
-  {cx: 700, cy: 700, outer: true, stagger: 4, exitStart: 49, fadeIn: [6, 9], fadeOut: [49, 61]},
-  {cx: 400, cy: 600, outer: false, stagger: 6, exitStart: 50, fadeIn: [9, 12], fadeOut: [50, 62]},
-  {cx: 600, cy: 600, outer: false, stagger: 8, exitStart: 51, fadeIn: [13, 16], fadeOut: [51, 63]},
-  {cx: 200, cy: 500, outer: true, stagger: 10, exitStart: 52, fadeIn: [14, 17], fadeOut: [52, 64]},
-  {cx: 800, cy: 500, outer: true, stagger: 14, exitStart: 54, fadeIn: [18, 21], fadeOut: [54, 66]},
-  {cx: 400, cy: 400, outer: false, stagger: 16, exitStart: 55, fadeIn: [21, 24], fadeOut: [55, 67]},
-  {cx: 600, cy: 400, outer: false, stagger: 18, exitStart: 56, fadeIn: [23, 26], fadeOut: [56, 68]},
-  {cx: 300, cy: 300, outer: true, stagger: 20, exitStart: 57, fadeIn: [26, 29], fadeOut: [57, 69]},
-  {cx: 700, cy: 300, outer: true, stagger: 22, exitStart: 58, fadeIn: [27, 30], fadeOut: [58, 70]},
-  {cx: 500, cy: 200, outer: true, stagger: 24, exitStart: 59, fadeIn: [31, 34], fadeOut: [59, 71]}
+  {cx: 240, cy: 360, outer: true, stagger: 0, exitStart: 47, fadeIn: [1, 4], fadeOut: [47, 59]},
+  {cx: 160, cy: 320, outer: true, stagger: 2, exitStart: 48, fadeIn: [4, 7], fadeOut: [48, 60]},
+  {cx: 320, cy: 320, outer: true, stagger: 4, exitStart: 49, fadeIn: [6, 9], fadeOut: [49, 61]},
+  {cx: 200, cy: 280, outer: false, stagger: 6, exitStart: 50, fadeIn: [9, 12], fadeOut: [50, 62]},
+  {cx: 280, cy: 280, outer: false, stagger: 8, exitStart: 51, fadeIn: [13, 16], fadeOut: [51, 63]},
+  {cx: 120, cy: 240, outer: true, stagger: 10, exitStart: 52, fadeIn: [14, 17], fadeOut: [52, 64]},
+  {cx: 360, cy: 240, outer: true, stagger: 14, exitStart: 54, fadeIn: [18, 21], fadeOut: [54, 66]},
+  {cx: 200, cy: 200, outer: false, stagger: 16, exitStart: 55, fadeIn: [21, 24], fadeOut: [55, 67]},
+  {cx: 280, cy: 200, outer: false, stagger: 18, exitStart: 56, fadeIn: [23, 26], fadeOut: [56, 68]},
+  {cx: 160, cy: 160, outer: true, stagger: 20, exitStart: 57, fadeIn: [26, 29], fadeOut: [57, 69]},
+  {cx: 320, cy: 160, outer: true, stagger: 22, exitStart: 58, fadeIn: [27, 30], fadeOut: [58, 70]},
+  {cx: 240, cy: 120, outer: true, stagger: 24, exitStart: 59, fadeIn: [31, 34], fadeOut: [59, 71]}
 ];
 
 // ─────────────────────────────────────────────────────────────
@@ -697,8 +697,8 @@ export function buildCells(positions: number[][], options: BuildOptions = {}): C
     const stagger = staggers[i];
     const exitStart = 47 + (stagger / maxStagger) * 12;
     return {
-      cx: 200 + col * 100,
-      cy: 200 + (row + rowOffset) * 100,
+      cx: 120 + col * 40,
+      cy: 120 + (row + rowOffset) * 40,
       outer: false,
       stagger,
       exitStart,
diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
index 6750fb6cfab..19d0f24e493 100644
--- a/packages/@react-spectrum/ai/src/loader/react.tsx
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -35,19 +35,18 @@ const TOTAL_FRAMES = 72;
 const FPS = 30;
 const DURATION_MS = (TOTAL_FRAMES / FPS) * 1000;
 
-// Per-cell vertical offsets in the 1000-unit VIEWBOX space: start off
+// Per-cell vertical offsets in the 24-unit space: start off
 // the top, overshoot just past the settled position, exit off the bottom.
-const Y_START = -876.156;
-const Y_OVERSHOOT = 18;
-const Y_EXIT = 1015;
+const Y_START = -26;
+const Y_OVERSHOOT = 1;
+const Y_EXIT = 26;
 
-// The animation lives in a fixed VIEWBOX-sized coordinate space (matching
-// the source Lottie's 1000×1000 canvas) that is scaled down to the
+// The animation lives in a fixed VIEWBOX-sized coordinate space that is scaled down to the
 // rendered `size`. Cells are absolutely positioned in this space, so all
 // the translateY offsets below are in these units — identical to the old
 // SVG viewBox math, just on HTML elements the compositor can accelerate.
-const VIEWBOX = 1000;
-const CELL = 100;
+const VIEWBOX = 480;
+const CELL = VIEWBOX / 12;
 
 // ─────────────────────────────────────────────────────────────
 // CSS @keyframes generation. Each piecewise segment of the motion
@@ -148,7 +147,6 @@ interface PixelLoaderProps {
   speed?: number;
   color?: string;
   className?: string;
-  style?: React.CSSProperties;
 }
 
 // ─────────────────────────────────────────────────────────────
@@ -161,13 +159,12 @@ interface PixelLoaderProps {
 // ─────────────────────────────────────────────────────────────
 export function PixelLoader(props: PixelLoaderProps) {
   const {
-    size = 64,
+    size = 21,
     playing = true,
     icon = aiLogo,
     speed = 1,
     color = 'currentColor',
     className,
-    style,
     ...rest
   } = props;
 
@@ -212,8 +209,14 @@ export function PixelLoader(props: PixelLoaderProps) {
   const iteration = isSequence ? '1 forwards' : 'infinite';
 
   // Map the VIEWBOX coordinate space down to the rendered size.
-  const px = typeof size === 'number' ? size : parseFloat(size);
-  const scaleFactor = px / VIEWBOX;
+  const cellSize = size / 7;
+  const offset = (size - cellSize * 7) / 2;
+  const matrix = Array.from({length: 7}, (_, i) => Array.from({length: 7}, (_, j) => false));
+  for (let c of cells) {
+    let x = (c.cx - 120) / CELL;
+    let y = (c.cy - 120) / CELL;
+    matrix[y][x] = true;
+  }
 
   return (
     <div
@@ -225,24 +228,21 @@ export function PixelLoader(props: PixelLoaderProps) {
         height: size,
         lineHeight: 0,
         overflow: 'clip',
-        position: 'relative',
-        ...style
+        position: 'relative'
       }}
       {...rest}>
       {playing ? <style>{css}</style> : null}
-      {/* VIEWBOX → size scale, mapping the 1000-unit coordinate space to `size`.
-          Keyed by `tick` so each sequence swap remounts and restarts cleanly. */}
-      <div
-        style={{
-          position: 'absolute',
-          top: 0,
-          left: 0,
-          width: VIEWBOX,
-          height: VIEWBOX,
-          transformOrigin: '0 0',
-          transform: `scale(${scaleFactor})`
-        }}>
-        {cells.map((c, i) => (
+      {cells.map((c, i) => {
+        let x = (c.cx - 120) / CELL;
+        let y = (c.cy - 120) / CELL;
+
+        // Convex-corner rounding: round a corner only when both orthogonal neighbors toward it are absent.
+        let left = matrix[y][x - 1];
+        let right = matrix[y][x + 1];
+        let top = matrix[y - 1]?.[x];
+        let bottom = matrix[y + 1]?.[x];
+        let corner = (a, b) => (!a && !b ? '1px' : '0px');
+        return (
           // When not playing, cells render with no animation — at their
           // settled position (left/top) and fully opaque, i.e. the
           // fully-assembled poster pose.
@@ -250,10 +250,11 @@ export function PixelLoader(props: PixelLoaderProps) {
             key={i}
             style={{
               position: 'absolute',
-              left: c.cx - CELL / 2,
-              top: c.cy - CELL / 2,
-              width: CELL,
-              height: CELL,
+              left: x * cellSize + offset,
+              top: y * cellSize + offset,
+              width: cellSize,
+              height: cellSize,
+              borderRadius: `${corner(left, top)} ${corner(right, top)} ${corner(right, bottom)} ${corner(left, bottom)}`,
               backgroundColor: color,
               ...(playing && {
                 animation:
@@ -263,8 +264,8 @@ export function PixelLoader(props: PixelLoaderProps) {
               })
             }}
           />
-        ))}
-      </div>
+        );
+      })}
     </div>
   );
 }

From 876e3b9a21275de1048691e07f2fb8e15ebe9d55 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 9 Jul 2026 18:31:39 -0700
Subject: [PATCH 28/34] cleanup

---
 .../react-docgen-typescript.ts                   | 16 +++-------------
 1 file changed, 3 insertions(+), 13 deletions(-)

diff --git a/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts b/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts
index cf5e293b1a5..ba7bd5b5f80 100644
--- a/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts
+++ b/packages/dev/parcel-transformer-storybook/react-docgen-typescript.ts
@@ -1,4 +1,3 @@
-import os from 'os';
 import path from 'path';
 import ts from 'typescript';
 import {ComponentDoc, Parser} from 'react-docgen-typescript';
@@ -10,19 +9,10 @@ export function getCacheDir(options: PluginOptions) {
   return path.join(options.projectRoot, 'node_modules', '.cache', 'docgen');
 }
 
-// macOS limits Unix socket paths to 104 characters. Use os.tmpdir() for the
-// socket when the project-relative path would exceed that.
-const UNIX_SOCKET_MAX = 104;
-
 function getSocketPath(options: PluginOptions) {
-  if (process.platform === 'win32') {
-    return path.join('\\\\?\\pipe', getCacheDir(options), options.instanceId);
-  }
-  let sock = path.join(getCacheDir(options), options.instanceId);
-  if (sock.length > UNIX_SOCKET_MAX) {
-    sock = path.join(os.tmpdir(), 'parcel-docgen-' + options.instanceId);
-  }
-  return sock;
+  return process.platform === 'win32'
+    ? path.join('\\\\?\\pipe', getCacheDir(options), options.instanceId)
+    : path.join(getCacheDir(options), options.instanceId);
 }
 
 // TypeScript is single threaded, but Parcel is multi-threaded.

From e1e3155d33a78e7322b2ec54df63e3da86fb3f05 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 9 Jul 2026 18:35:13 -0700
Subject: [PATCH 29/34] lint

---
 packages/@react-spectrum/ai/src/loader/react.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
index 19d0f24e493..37fc33aae1b 100644
--- a/packages/@react-spectrum/ai/src/loader/react.tsx
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -211,7 +211,7 @@ export function PixelLoader(props: PixelLoaderProps) {
   // Map the VIEWBOX coordinate space down to the rendered size.
   const cellSize = size / 7;
   const offset = (size - cellSize * 7) / 2;
-  const matrix = Array.from({length: 7}, (_, i) => Array.from({length: 7}, (_, j) => false));
+  const matrix = Array.from({length: 7}, () => Array.from({length: 7}, () => false));
   for (let c of cells) {
     let x = (c.cx - 120) / CELL;
     let y = (c.cy - 120) / CELL;

From bbb94eb0f35bea16e60f20f0b6cdf3ad12c70666 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Thu, 9 Jul 2026 18:39:34 -0700
Subject: [PATCH 30/34] more cleanup

---
 .../@react-spectrum/ai/src/loader/data.ts     | 20 ++++----
 .../@react-spectrum/ai/src/loader/react.tsx   | 48 ++++++-------------
 2 files changed, 26 insertions(+), 42 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/loader/data.ts b/packages/@react-spectrum/ai/src/loader/data.ts
index cdd34d9d1a0..850c9939c80 100644
--- a/packages/@react-spectrum/ai/src/loader/data.ts
+++ b/packages/@react-spectrum/ai/src/loader/data.ts
@@ -1,12 +1,14 @@
-// Loader cell-position data, ported from
-// experiments/pixel-fall-animation/index.html.
-//
-// Each icon is an independently-exported `Cell[]` so unused icons tree-
-// shake away; a preset is a `Cell[][]` (a sequence of icons). Import only
-// what you render: `import {brush} from '...'` then `<PixelLoader icon={brush} />`,
-// or a preset `import {cc} from '...'` then `<PixelLoader icon={cc} />`.
-//
-// Coordinates are in the source Lottie's 1000×1000 canvas.
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
 
 export interface Cell {
   cx: number;
diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
index 37fc33aae1b..0acf69723dc 100644
--- a/packages/@react-spectrum/ai/src/loader/react.tsx
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -1,19 +1,18 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
 // React pixel-fall loader. Renders plain HTML divs and lets the browser
-// drive the animation natively via generated CSS @keyframes — no
-// requestAnimationFrame loop, and no SVG. Cells animate only `transform`
-// and `opacity`, with exactly ONE `replace` animation per property per
-// cell, so Chrome composites both on the GPU (off the main thread) for
-// near-zero idle CPU. (An earlier shared-keyframe variant using
-// `animation-composition: add` and stacked opacity animations was ~2x
-// the CPU because additive/stacked animations fall back to the main
-// thread — composited residency matters far more than keyframe count.)
-//
-// The easing control points and Y offsets are the single
-// source of truth — the keyframes below are emitted from them. When not
-// playing, cells render with no animation: settled (translateY 0) and
-// opaque, i.e. the fully-assembled poster pose.
-//
-// Multi-icon sequences (presets) play one icon per 2.4s cycle and
+// drive the animation natively via generated CSS @keyframes. Multi-icon
+// sequences (presets) play one icon per 2.4s cycle and
 // advance via a single timer — only the current icon's cells are in the
 // DOM. A single-icon loader stays a pure infinite CSS loop with no JS.
 
@@ -149,14 +148,6 @@ interface PixelLoaderProps {
   className?: string;
 }
 
-// ─────────────────────────────────────────────────────────────
-// Component. Only `size` and `playing` are load-bearing for the
-// PromptField usage. `icon` takes a single icon (`Cell[]`) or a
-// sequence (`Cell[][]`) imported from ./data; `speed`, `color`,
-// `className`, and `style` are supported because they're free. When not
-// playing, the loader renders a single static poster frame (no
-// animation).
-// ─────────────────────────────────────────────────────────────
 export function PixelLoader(props: PixelLoaderProps) {
   const {
     size = 21,
@@ -168,11 +159,7 @@ export function PixelLoader(props: PixelLoaderProps) {
     ...rest
   } = props;
 
-  // Normalize to a sequence. A `Cell[][]` (first element is itself an
-  // array) is already a sequence; a flat `Cell[]` is wrapped. A single-
-  // icon sequence loops forever in pure CSS; a multi-icon sequence
-  // advances one icon per cycle via the timer below, so only the current
-  // icon's cells are ever in the DOM.
+  // Normalize to a sequence.
   const sequence = React.useMemo(
     () => (Array.isArray(icon[0]) ? icon : [icon]) as Cell[][],
     [icon]
@@ -181,7 +168,6 @@ export function PixelLoader(props: PixelLoaderProps) {
   const duration = DURATION_MS / (speed || 1);
 
   // `tick` increments once per cycle; the current icon is `tick % len`.
-  // It's also the remount key, so each swap restarts the animation cleanly.
   const [tick, setTick] = React.useState(0);
 
   // Restart from the first icon whenever the sequence changes.
@@ -208,7 +194,6 @@ export function PixelLoader(props: PixelLoaderProps) {
   // (`forwards`) until the next remount; a single icon loops forever.
   const iteration = isSequence ? '1 forwards' : 'infinite';
 
-  // Map the VIEWBOX coordinate space down to the rendered size.
   const cellSize = size / 7;
   const offset = (size - cellSize * 7) / 2;
   const matrix = Array.from({length: 7}, () => Array.from({length: 7}, () => false));
@@ -243,9 +228,6 @@ export function PixelLoader(props: PixelLoaderProps) {
         let bottom = matrix[y + 1]?.[x];
         let corner = (a, b) => (!a && !b ? '1px' : '0px');
         return (
-          // When not playing, cells render with no animation — at their
-          // settled position (left/top) and fully opaque, i.e. the
-          // fully-assembled poster pose.
           <div
             key={i}
             style={{

From e34c773bf5195774053b2f8e6e6779b29aa48b15 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 10 Jul 2026 09:15:43 -0700
Subject: [PATCH 31/34] make placeholder customizable, export loader icons

---
 packages/@react-spectrum/ai/exports/loader.ts   |  1 +
 packages/@react-spectrum/ai/intl/en-US.json     |  3 ++-
 packages/@react-spectrum/ai/src/PromptField.tsx | 10 ++++++++--
 3 files changed, 11 insertions(+), 3 deletions(-)
 create mode 100644 packages/@react-spectrum/ai/exports/loader.ts

diff --git a/packages/@react-spectrum/ai/exports/loader.ts b/packages/@react-spectrum/ai/exports/loader.ts
new file mode 100644
index 00000000000..4c0c853ec7d
--- /dev/null
+++ b/packages/@react-spectrum/ai/exports/loader.ts
@@ -0,0 +1 @@
+export * from '../src/loader/data';
diff --git a/packages/@react-spectrum/ai/intl/en-US.json b/packages/@react-spectrum/ai/intl/en-US.json
index adc6cbede25..555ea77c69a 100644
--- a/packages/@react-spectrum/ai/intl/en-US.json
+++ b/packages/@react-spectrum/ai/intl/en-US.json
@@ -2,5 +2,6 @@
   "chat.newMessage": "New message",
   "messagefeedback.thumbDown": "Bad response",
   "messagefeedback.thumbUp": "Good response",
-  "responsestatus.loading": "Loading"
+  "responsestatus.loading": "Loading",
+  "promptfield.placeholder": "Ready to get started? Ask a question, share an idea, or add a task."
 }
diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index 96c95d12cfc..c401fb780c7 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -37,6 +37,8 @@ import {
 } from './TokenSegmentList';
 import {IconContext} from '@react-spectrum/s2';
 import {Image, Text} from '@react-spectrum/s2/Card';
+// @ts-ignore
+import intlMessages from '../intl/*.json';
 import {isFileDropItem, useDrop} from 'react-aria-components/useDrop';
 import {Link} from '@react-spectrum/s2/Link';
 import {Menu, MenuItem, MenuItemProps, MenuTrigger} from '@react-spectrum/s2/Menu';
@@ -49,6 +51,7 @@ import {PromptFocusContext} from './Chat';
 import Send from '@react-spectrum/s2/icons/ArrowUpSend';
 import Stop from '@react-spectrum/s2/icons/StopProcessing';
 import {useFocusWithin} from 'react-aria/useFocusWithin';
+import {useLocalizedStringFormatter} from 'react-aria/useLocalizedStringFormatter';
 
 export interface PromptFieldAttachment {
   id: string;
@@ -266,10 +269,11 @@ export interface PromptTokenFieldProps {
   ) => React.ReactNode[] | null | Promise<React.ReactNode[] | null>;
   children?: (segment: TokenSegment) => React.ReactElement;
   pixelLoader?: Cell[] | Cell[][];
+  placeholder?: string;
 }
 
 export function PromptTokenField(props: PromptTokenFieldProps) {
-  let {completionTrigger, renderCompletions, children, pixelLoader} = props;
+  let {completionTrigger, renderCompletions, children, pixelLoader, placeholder} = props;
   let {
     prompt,
     setPrompt,
@@ -280,6 +284,7 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
     onSubmit,
     isGenerating
   } = useContext(PromptFieldContext);
+  let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-spectrum/ai');
   let [isFocused, setFocused] = useState(false);
 
   let [filterAnchor, filterValue] = useMemo(() => {
@@ -312,6 +317,7 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
           isFocused: 'body'
         },
         transition: 'default',
+        transitionDuration: 350,
         paddingStart: 4,
         width: 'full'
       })({isFocused: isFocused || prompt.segments.length > 0})}>
@@ -324,7 +330,7 @@ export function PromptTokenField(props: PromptTokenFieldProps) {
           onChange={setPrompt}
           multiline
           aria-label="Prompt"
-          data-placeholder="Ready to get started? Ask a question, share an idea, or add a task."
+          data-placeholder={placeholder || stringFormatter.format('promptfield.placeholder')}
           ref={inputRef}
           onFocus={e => {
             if (e.isTrusted) {

From 6aa054186352887d0fc038fbe0449484d13fea52 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 10 Jul 2026 09:52:13 -0700
Subject: [PATCH 32/34] Update attachment styles

---
 .../@react-spectrum/ai/src/HorizontalCard.tsx | 43 ++-----------------
 .../@react-spectrum/ai/src/PromptField.tsx    | 17 ++++++--
 .../ai/src/PromptFieldContainer.tsx           | 24 ++++++++++-
 .../ai/stories/PromptField.stories.tsx        | 20 ++++++++-
 4 files changed, 58 insertions(+), 46 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/HorizontalCard.tsx b/packages/@react-spectrum/ai/src/HorizontalCard.tsx
index 920078102c1..a9f71686e8a 100644
--- a/packages/@react-spectrum/ai/src/HorizontalCard.tsx
+++ b/packages/@react-spectrum/ai/src/HorizontalCard.tsx
@@ -115,46 +115,11 @@ let card = style({
   flexDirection: 'row',
   position: 'relative',
   borderRadius,
-  '--s2-container-bg': {
-    type: 'backgroundColor',
-    value: {
-      variant: {
-        primary: 'elevated',
-        secondary: 'layer-1',
-        tertiary: 'layer-2'
-      },
-      isBasic: {
-        variant: {
-          primary: 'layer-2',
-          secondary: 'layer-1',
-          tertiary: 'layer-2',
-          quiet: 'layer-2'
-        }
-      },
-      forcedColors: 'ButtonFace'
-    }
-  },
-  backgroundColor: '--s2-container-bg',
-  // TODO: No box shadow for basic, secondary, dark
-  // also none for basic tertiary
-  boxShadow: {
-    default: 'emphasized',
-    isHovered: 'elevated',
-    isFocusVisible: 'elevated',
-    isSelected: 'elevated',
-    forcedColors: '[0 0 0 1px var(--hcm-buttonborder, ButtonBorder)]',
-    variant: {
-      tertiary: {
-        // Render border with box-shadow to avoid affecting layout.
-        default: `[0 0 0 2px ${color('gray-100')}]`,
-        isHovered: `[0 0 0 2px ${color('gray-200')}]`,
-        isFocusVisible: `[0 0 0 2px ${color('gray-200')}]`,
-        isSelected: 'none',
-        forcedColors: '[0 0 0 2px var(--hcm-buttonborder, ButtonBorder)]'
-      },
-      quiet: 'none'
-    }
+  backgroundColor: {
+    default: lightDark('transparent-white-300', 'transparent-black-300'),
+    forcedColors: 'ButtonFace'
   },
+  boxShadow: `[inset 0 0 0 1px light-dark(${color('transparent-black-300')}, ${color('transparent-white-300')})]`,
   forcedColorAdjust: 'none',
   transition: 'default',
   fontFamily: 'sans',
diff --git a/packages/@react-spectrum/ai/src/PromptField.tsx b/packages/@react-spectrum/ai/src/PromptField.tsx
index c401fb780c7..e18d031b5be 100644
--- a/packages/@react-spectrum/ai/src/PromptField.tsx
+++ b/packages/@react-spectrum/ai/src/PromptField.tsx
@@ -17,7 +17,13 @@ import {Autocomplete} from 'react-aria-components/Autocomplete';
 import {Button} from '@react-spectrum/s2/Button';
 import {Cell} from './loader/data';
 import {CenterBaseline} from '@react-spectrum/s2/CenterBaseline';
-import {color, css, style, StyleString} from '@react-spectrum/s2/style' with {type: 'macro'};
+import {
+  color,
+  css,
+  iconStyle,
+  style,
+  StyleString
+} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {
   createContext,
   createRef,
@@ -152,7 +158,7 @@ export function PromptField(props: PromptFieldProps) {
   // Not using RAC DropZone because it adds its own focusable button,
   // and we want to avoid an extra tab. We support pasting files directly into the input.
   let inputRef = useRef<HTMLDivElement>(null);
-  let {dropProps} = useDrop({
+  let {dropProps, isDropTarget} = useDrop({
     ref: inputRef,
     hasDropButton: true,
     isDisabled: !acceptedAttachmentTypes,
@@ -210,6 +216,7 @@ export function PromptField(props: PromptFieldProps) {
           role="group"
           variant={variant}
           isGenerating={isGenerating ?? false}
+          isDropTarget={isDropTarget}
           styles={styles}
           inputRef={inputRef}>
           {children}
@@ -485,7 +492,11 @@ export function PromptToken(props: PromptTokenProps) {
         gap: 4,
         verticalAlign: 'baseline'
       })}>
-      <IconContext.Provider value={{render: icon => <CenterBaseline>{icon}</CenterBaseline>}}>
+      <IconContext.Provider
+        value={{
+          styles: iconStyle({size: 'XS'}),
+          render: icon => <CenterBaseline>{icon}</CenterBaseline>
+        }}>
         {props.children}
       </IconContext.Provider>
     </Token>
diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
index 42f6a2b7e1b..1d74244adc7 100644
--- a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -242,12 +242,13 @@ interface PropFieldContainerProps extends Omit<GroupProps, 'children'> {
   children: React.ReactNode;
   variant: 'balanced' | 'prominent' | 'subtle';
   isGenerating: boolean;
+  isDropTarget: boolean;
   styles?: StyleString;
   inputRef: React.RefObject<HTMLDivElement | null>;
 }
 
 export function PromptFieldContainer(props: PropFieldContainerProps) {
-  let {variant, isGenerating, styles, inputRef, ...otherProps} = props;
+  let {variant, isGenerating, isDropTarget, styles, inputRef, ...otherProps} = props;
   let [isFocused, setFocused] = useState(false);
 
   return (
@@ -297,11 +298,30 @@ export function PromptFieldContainer(props: PropFieldContainerProps) {
                 gap: 16,
                 padding: 16,
                 cursor: 'text',
-                borderRadius: '[24px]'
+                borderRadius: '[24px]',
+                position: 'relative'
               }),
               styles
             )
           }>
+          {isDropTarget && (
+            <div
+              className={style({
+                pointerEvents: 'none',
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                height: '100%',
+                boxSizing: 'border-box',
+                borderRadius: 'inherit',
+                backgroundColor: 'blue-800/10',
+                borderStyle: 'solid',
+                borderWidth: 2,
+                borderColor: 'blue-800'
+              })}
+            />
+          )}
           {props.children}
         </div>
       )}
diff --git a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
index f6fbe389af7..f5f7ea02b66 100644
--- a/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
+++ b/packages/@react-spectrum/ai/stories/PromptField.stories.tsx
@@ -34,6 +34,7 @@ import {
   SubmenuTrigger,
   Text
 } from '@react-spectrum/s2/Menu';
+import {Content} from '@react-spectrum/s2/Content';
 import Data from '@react-spectrum/s2/icons/Data';
 import * as data from '../src/loader/data';
 import {iconStyle, style} from '@react-spectrum/s2/style' with {type: 'macro'};
@@ -68,9 +69,18 @@ const meta: Meta<typeof PromptField> = {
       options: Object.keys(data),
       description: 'Sets the icon to use for the pixel loader.',
       table: {category: 'Theming'}
+    },
+    attachmentVariant: {
+      control: 'radio',
+      options: ['thumbnail', 'card']
     }
   },
-  args: {brand: 'rgb(236, 105, 255)', pixelLoader: 'aiLogo', ...getActionArgs(events)},
+  args: {
+    brand: 'rgb(236, 105, 255)',
+    pixelLoader: 'aiLogo',
+    attachmentVariant: 'thumbnail',
+    ...getActionArgs(events)
+  },
   title: 'AI/PromptField',
   decorators: [
     (Story, {args}) => (
@@ -235,7 +245,7 @@ export const Everything = args => {
           return newState;
         });
       }}>
-      <PromptFieldAttachmentList dependencies={[attachmentState]}>
+      <PromptFieldAttachmentList dependencies={[attachmentState, args.attachmentVariant]}>
         {attachment => {
           let state = attachmentState.get(attachment.id);
           return (
@@ -243,6 +253,12 @@ export const Everything = args => {
               uploadProgress={state?.status === 'uploading' ? state?.progress : undefined}>
               {/* TODO: what about non-image attachments? */}
               {attachment.image && <Image src={attachment.image} slot="thumbnail" />}
+              {args.attachmentVariant === 'card' && (
+                <Content>
+                  <Text slot="title">{attachment.file.name}</Text>
+                  <Text slot="description">{attachment.file.type}</Text>
+                </Content>
+              )}
             </Attachment>
           );
         }}

From 61a06b6b247a2c5091a416053e6ff43acf3cd968 Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 10 Jul 2026 10:14:17 -0700
Subject: [PATCH 33/34] Adjust position for outer cells on high DPI displays.

---
 .../@react-spectrum/ai/src/loader/react.tsx   | 21 +++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/packages/@react-spectrum/ai/src/loader/react.tsx b/packages/@react-spectrum/ai/src/loader/react.tsx
index 0acf69723dc..b470dba07ae 100644
--- a/packages/@react-spectrum/ai/src/loader/react.tsx
+++ b/packages/@react-spectrum/ai/src/loader/react.tsx
@@ -203,6 +203,8 @@ export function PixelLoader(props: PixelLoaderProps) {
     matrix[y][x] = true;
   }
 
+  const isHighDPI = window.devicePixelRatio >= 2;
+
   return (
     <div
       aria-hidden="true"
@@ -227,15 +229,26 @@ export function PixelLoader(props: PixelLoaderProps) {
         let top = matrix[y - 1]?.[x];
         let bottom = matrix[y + 1]?.[x];
         let corner = (a, b) => (!a && !b ? '1px' : '0px');
+
+        // Adjust position for outer cells on high DPI displays.
+        let xPx = x * cellSize + offset;
+        let yPx = y * cellSize + offset;
+        if (isHighDPI && c.outer && xPx > size / 2) {
+          xPx -= 0.5;
+        }
+        if (isHighDPI && c.outer && yPx > size / 2) {
+          yPx -= 0.5;
+        }
+
         return (
           <div
             key={i}
             style={{
               position: 'absolute',
-              left: x * cellSize + offset,
-              top: y * cellSize + offset,
-              width: cellSize,
-              height: cellSize,
+              left: xPx,
+              top: yPx,
+              width: cellSize + (isHighDPI && c.outer ? 0.5 : 0),
+              height: cellSize + (isHighDPI && c.outer ? 0.5 : 0),
               borderRadius: `${corner(left, top)} ${corner(right, top)} ${corner(right, bottom)} ${corner(left, bottom)}`,
               backgroundColor: color,
               ...(playing && {

From 130d69b071d65887278f087e795bf9a1f7ccd0cd Mon Sep 17 00:00:00 2001
From: Devon Govett <devongovett@gmail.com>
Date: Fri, 10 Jul 2026 10:56:45 -0700
Subject: [PATCH 34/34] add prominent outline glow

---
 .../@react-spectrum/ai/src/PromptFieldContainer.tsx  | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
index 1d74244adc7..2d2f2bb9303 100644
--- a/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
+++ b/packages/@react-spectrum/ai/src/PromptFieldContainer.tsx
@@ -92,8 +92,10 @@ const containerBackground = css(`
   --border-color: ${token(`container.border.default`)};
   --inset-shadow-color: ${color('transparent-white-50')};
   --drop-shadow-color: light-dark(${brand(0.5826, 0.2265, -0.4, 0.05)}, ${brand(0.6617, 0.2508, -0.5, 0.05)});
+  --prominent-outline-glow: ;
 
   box-shadow:
+    var(--prominent-outline-glow)
     inset 0 0 0 1px var(--border-color),
     inset 0 6px 15px 0 var(--inset-shadow-color),
     inset 0 0 0 0 transparent, /* placeholder for generating state so transition is smooth */
@@ -101,6 +103,16 @@ const containerBackground = css(`
     inset 0 24px 32px 0 ${color('transparent-white-50')},
     0 -3px 10px 1px var(--drop-shadow-color);
 
+  &[data-variant=prominent] {
+    /* trailing comma is intentional so it can be interpolated above */
+    --prominent-outline-glow:
+      0 20px 20px -24px ${token('outline-glow.gradient.generating.stop-3')},
+      inset 0 -20px 20px -24px ${token('outline-glow.gradient.generating.stop-3')},;
+    &[data-focused] {
+      --prominent-outline-glow: 0 20px 20px -24px transparent, inset 0 -20px 20px -24px transparent,;
+    }
+  }
+
   &[data-state=idle] {
     &[data-variant=balanced] {
       ${stops('idle', 'default', 'balanced')}