stream-chat-react-native-core 9.12.1 → 9.14.0

package/src/ai-components/generative-ui/AIUIArguments.ts

@@ -0,0 +1,117 @@
+import type { AIUIJSONSchema, AIUIParameter } from './AIUIComponentDefinition';
+import { aiUIParametersOf } from './AIUIComponentDefinition';
+import { isRecord } from './AIUIHelpers';
+
+// Thrown inside decoding only, so a value that does not fit stops it at once.
+class DoesNotFit extends Error {}
+
+const RFC_3339 = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/**
+ * A date the agent wrote: an RFC 3339 moment, or a whole day as `yyyy-MM-dd` that the calendar
+ * has, which is that day's start where the person is. Anything else is not a date.
+ */
+export const aiUIDate = (text: string): Date | undefined => {
+  if (RFC_3339.test(text)) {
+    const moment = new Date(text);
+    return Number.isNaN(moment.getTime()) ? undefined : moment;
+  }
+  const day = DAY.exec(text);
+  if (!day) return undefined;
+  const [year, month, date] = [Number(day[1]), Number(day[2]), Number(day[3])];
+  const start = new Date(year, month - 1, date);
+  start.setFullYear(year);
+  return start.getFullYear() === year && start.getMonth() === month - 1 && start.getDate() === date
+    ? start
+    : undefined;
+};
+
+/** `place_name` as `placeName`, the way the agent's snake_case reads in JavaScript. */
+export const aiUICamelCase = (key: string) => {
+  const [, leading = '', middle = '', trailing = ''] = /^(_*)(.*?)(_*)$/.exec(key) ?? [];
+  if (!middle.includes('_')) return key;
+  const [first = '', ...rest] = middle.split('_').filter(Boolean);
+  return (
+    leading +
+    first +
+    rest.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join('') +
+    trailing
+  );
+};
+
+const camelCased = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(camelCased);
+  if (!isRecord(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [aiUICamelCase(key), camelCased(item)]),
+  );
+};
+
+const decodeObject = (value: unknown, parameters: AIUIParameter[]) => {
+  if (!isRecord(value)) throw new DoesNotFit();
+  const declared = new Set(parameters.map(({ name }) => name));
+  const decoded: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (!declared.has(key)) decoded[aiUICamelCase(key)] = camelCased(item);
+  }
+  for (const { isRequired, name, type } of parameters) {
+    const item = value[name];
+    if (item === undefined || item === null) {
+      if (isRequired) throw new DoesNotFit();
+      continue;
+    }
+    decoded[aiUICamelCase(name)] = decodeValue(item, type);
+  }
+  return decoded;
+};
+
+const decodeValue = (value: unknown, schema: AIUIJSONSchema): unknown => {
+  switch (schema.type) {
+    case 'string': {
+      if (typeof value !== 'string') throw new DoesNotFit();
+      if (Array.isArray(schema.enum) && !schema.enum.includes(value)) throw new DoesNotFit();
+      if (schema.format === 'date' || schema.format === 'date-time') {
+        const date = aiUIDate(value);
+        if (!date) throw new DoesNotFit();
+        return date;
+      }
+      return value;
+    }
+    case 'number':
+      if (typeof value !== 'number' || !Number.isFinite(value)) throw new DoesNotFit();
+      return value;
+    case 'integer':
+      if (!Number.isInteger(value)) throw new DoesNotFit();
+      return value;
+    case 'boolean':
+      if (typeof value !== 'boolean') throw new DoesNotFit();
+      return value;
+    case 'array': {
+      if (!Array.isArray(value)) throw new DoesNotFit();
+      const items = isRecord(schema.items) ? schema.items : {};
+      return value.map((item) => decodeValue(item, items));
+    }
+    case 'object':
+      return decodeObject(value, aiUIParametersOf(schema));
+    default:
+      return camelCased(value);
+  }
+};
+
+/**
+ * The arguments the agent wrote for a component, as its view reads them: keys in camelCase,
+ * dates as `Date`s. `undefined` while they do not fit its parameters, such as while they are
+ * still streaming in: a required one is missing, or one is of the wrong type.
+ */
+export const decodeAIUIArguments = <Arguments = Record<string, unknown>>(
+  args: Record<string, unknown>,
+  parameters: AIUIParameter[],
+): Arguments | undefined => {
+  try {
+    return decodeObject(args, parameters) as Arguments;
+  } catch (error) {
+    if (error instanceof DoesNotFit) return undefined;
+    throw error;
+  }
+};

package/src/ai-components/generative-ui/AIUIComponent.tsx

@@ -0,0 +1,106 @@
+import React, { type ComponentType, useMemo } from 'react';
+
+import { decodeAIUIArguments } from './AIUIArguments';
+import type { AIUIComponentDefinition } from './AIUIComponentDefinition';
+import { AIUIEntrance } from './AIUIEntrance';
+import { AIUIErrorBoundary } from './AIUIErrorBoundary';
+import type { AIUIHost } from './AIUIHost';
+
+/** Where an app's component is shown, and how it tells the agent what the person did. */
+export type AIUIComponentContext = {
+  /**
+   * Tells the agent about one of the component's events, as the person's next message.
+   * `label` is what the person did, in their words, such as "Tell me more about St. Naum".
+   */
+  emit: (event: string, label: string, payload?: Record<string, unknown>) => void;
+  /** The conversation's host, for running the app's tools and opening links. */
+  host: AIUIHost;
+  /** Whether the agent is still writing the reply's UI, so the arguments may still change. */
+  isStreaming: boolean;
+  /** The reply the component is in. */
+  messageId: string;
+};
+
+export type AIUIComponentProps<Arguments> = {
+  /** What the agent filled in: keys in camelCase, dates as `Date`s. */
+  args: Arguments;
+  context: AIUIComponentContext;
+};
+
+/**
+ * One of the app's views that the agent can place in a reply's UI, in whichever format it
+ * writes, such as a map or a card over the app's own data.
+ */
+export type AIUIComponent = {
+  Component: ComponentType<AIUIComponentProps<never>>;
+  /** Its description, the same on every platform and for the agent. */
+  definition: AIUIComponentDefinition;
+};
+
+/**
+ * One of the app's components, with what its view reads from the agent's arguments. The view
+ * gets them only once they fit the definition's parameters, so it can rely on their types.
+ *
+ * A conversation reuses its views: one scrolled out of sight shows another reply's UI next, so
+ * state the view keeps of its own has to start afresh for a new `context.messageId`.
+ */
+export const defineAIUIComponent = <Arguments,>(
+  definition: AIUIComponentDefinition,
+  Component: ComponentType<AIUIComponentProps<Arguments>>,
+): AIUIComponent => ({
+  // The arguments are checked against `definition` before the view gets them.
+  Component: Component as unknown as ComponentType<AIUIComponentProps<never>>,
+  definition,
+});
+
+// What an app's component was given, to try it again once that changes or the reply is written.
+const attemptOf = (args: Record<string, unknown>, isStreaming: boolean) => {
+  try {
+    return `${isStreaming}\u0000${JSON.stringify(args)}`;
+  } catch {
+    return args;
+  }
+};
+
+/**
+ * An app's component for the arguments the agent wrote, coming in as it shows, or nothing
+ * while they don't fit its parameters, such as while they are still streaming in. Renderers
+ * place the app's components with it. One that throws leaves only itself out of the reply's
+ * UI, is tried again when its arguments change, and is reported once the reply is written.
+ */
+export const AIUIComponentView = ({
+  args,
+  component,
+  context,
+}: {
+  args: Record<string, unknown>;
+  component: AIUIComponent;
+  context: AIUIComponentContext;
+}) => {
+  const { host, isStreaming, messageId } = context;
+  // Worked out again only when the arguments change, for a renderer that keeps the same object
+  // while they don't, as the A2UI renderer does.
+  const decoded = useMemo(
+    () => decodeAIUIArguments(args, component.definition.parameters),
+    [args, component],
+  );
+  const resetKey = useMemo(
+    () => (decoded === undefined ? undefined : attemptOf(decoded, isStreaming)),
+    [decoded, isStreaming],
+  );
+  if (decoded === undefined) return null;
+  const { Component } = component;
+  return (
+    <AIUIErrorBoundary
+      onError={(error) => {
+        // While the reply streams, what the component was given may still be incomplete.
+        if (!isStreaming) host.reportRenderError(error, messageId);
+      }}
+      resetKey={resetKey}
+    >
+      <AIUIEntrance>
+        <Component args={decoded as never} context={context} />
+      </AIUIEntrance>
+    </AIUIErrorBoundary>
+  );
+};

package/src/ai-components/generative-ui/AIUIComponentDefinition.ts

@@ -0,0 +1,163 @@
+import { isRecord } from './AIUIHelpers';
+
+/** A JSON Schema, as a component's parameters are described to the agent. */
+export type AIUIJSONSchema = Record<string, unknown>;
+
+/** Something the agent fills in for a component. */
+export type AIUIParameter = {
+  /** Whether the agent must fill it in. */
+  isRequired: boolean;
+  /** The name the agent fills it in by, such as `title`. */
+  name: string;
+  /** What it holds, as a JSON Schema, such as `AIUIParameterType.string`. */
+  type: AIUIJSONSchema;
+  /** What it is, for the agent. */
+  description?: string;
+};
+
+/** Something a component reports when the person uses it, such as tapping a place. */
+export type AIUIComponentEvent = {
+  /** When it happens, for the agent. */
+  description: string;
+  /** The name it is reported by, such as `ask_about`. */
+  name: string;
+  /** What it carries, in order. */
+  parameters: AIUIParameter[];
+};
+
+/**
+ * An app's component as the agent knows it: its name, what it shows, what the agent fills in
+ * and what it reports. It is portable JSON, the same on every platform, so one description
+ * (such as a `UIComponents.json` shared with the iOS and Android apps) serves them all.
+ */
+export type AIUIComponentDefinition = {
+  /** What it shows and when to use it, for the agent. */
+  description: string;
+  /** What it reports when the person uses it. */
+  events: AIUIComponentEvent[];
+  /** The name the agent places it by, such as `place_card`. */
+  name: string;
+  /**
+   * What the agent fills in, in order: a format such as OpenUI Lang passes arguments by
+   * position.
+   */
+  parameters: AIUIParameter[];
+};
+
+/** The types a parameter commonly has, as JSON Schemas. */
+export const AIUIParameterType = {
+  /** A list of values of one type. */
+  array: (items: AIUIJSONSchema): AIUIJSONSchema => ({ items, type: 'array' }),
+  boolean: { type: 'boolean' } as AIUIJSONSchema,
+  /** A day, such as `2026-11-14`. */
+  date: { format: 'date', type: 'string' } as AIUIJSONSchema,
+  /** A moment, such as `2026-11-14T09:30:00Z`. */
+  dateTime: { format: 'date-time', type: 'string' } as AIUIJSONSchema,
+  /** One of a fixed set of strings. */
+  enumeration: (values: string[]): AIUIJSONSchema => ({ enum: values, type: 'string' }),
+  integer: { type: 'integer' } as AIUIJSONSchema,
+  number: { type: 'number' } as AIUIJSONSchema,
+  /** An object with named fields, in order. */
+  object: (fields: AIUIParameter[]): AIUIJSONSchema => aiUIObjectSchema(fields),
+  string: { type: 'string' } as AIUIJSONSchema,
+  /** A link, such as an image's. */
+  url: { format: 'uri', type: 'string' } as AIUIJSONSchema,
+};
+
+/** A parameter the agent must fill in. */
+export const requiredAIUIParameter = (
+  name: string,
+  type: AIUIJSONSchema,
+  description?: string,
+): AIUIParameter => ({ description, isRequired: true, name, type });
+
+/** A parameter the agent may leave out. */
+export const optionalAIUIParameter = (
+  name: string,
+  type: AIUIJSONSchema,
+  description?: string,
+): AIUIParameter => ({ description, isRequired: false, name, type });
+
+// The key that keeps the order of an object's fields, which JSON objects don't have.
+const ORDER_KEY = 'x-order';
+
+const strings = (value: unknown) =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];
+
+/** Parameters as a JSON Schema object, the way a tool's are described, keeping their order. */
+export const aiUIObjectSchema = (parameters: AIUIParameter[]): AIUIJSONSchema => ({
+  [ORDER_KEY]: parameters.map(({ name }) => name),
+  properties: Object.fromEntries(
+    parameters.map(({ description, name, type }) => [
+      name,
+      description === undefined ? type : { ...type, description },
+    ]),
+  ),
+  required: parameters.filter(({ isRequired }) => isRequired).map(({ name }) => name),
+  type: 'object',
+});
+
+/** The fields of a JSON Schema object, in the order it keeps, then by name. */
+export const aiUIParametersOf = (schema: unknown): AIUIParameter[] => {
+  if (!isRecord(schema)) return [];
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = new Set(strings(schema.required));
+  const ordered = strings(schema[ORDER_KEY]).filter((name) => name in properties);
+  const rest = Object.keys(properties)
+    .filter((name) => !ordered.includes(name))
+    .sort();
+  return [...ordered, ...rest].flatMap((name) => {
+    const field = properties[name];
+    if (!isRecord(field)) return [];
+    const { description, ...type } = field;
+    return [
+      {
+        description: typeof description === 'string' ? description : undefined,
+        isRequired: required.has(name),
+        name,
+        type,
+      },
+    ];
+  });
+};
+
+/**
+ * Reads a component's portable JSON, such as one entry of a `UIComponents.json`, or returns
+ * `undefined` for one without a name.
+ */
+export const parseAIUIComponentDefinition = (
+  json: unknown,
+): AIUIComponentDefinition | undefined => {
+  if (!isRecord(json) || typeof json.name !== 'string' || json.name === '') {
+    return undefined;
+  }
+  const events = Array.isArray(json.events) ? json.events : [];
+  return {
+    description: typeof json.description === 'string' ? json.description : '',
+    events: events.flatMap((event) =>
+      isRecord(event) && typeof event.name === 'string'
+        ? [
+            {
+              description: typeof event.description === 'string' ? event.description : '',
+              name: event.name,
+              parameters: aiUIParametersOf(event.parameters),
+            },
+          ]
+        : [],
+    ),
+    name: json.name,
+    parameters: aiUIParametersOf(json.parameters),
+  };
+};
+
+/** A component's portable JSON, as `parseAIUIComponentDefinition` reads it back. */
+export const aiUIComponentDefinitionJSON = (definition: AIUIComponentDefinition) => ({
+  description: definition.description,
+  events: definition.events.map(({ description, name, parameters }) => ({
+    description,
+    name,
+    ...(parameters.length ? { parameters: aiUIObjectSchema(parameters) } : {}),
+  })),
+  name: definition.name,
+  parameters: aiUIObjectSchema(definition.parameters),
+});

package/src/ai-components/generative-ui/AIUIDocument.ts

@@ -0,0 +1,77 @@
+import { isRecord, isSameJSON } from './AIUIHelpers';
+
+/**
+ * The format a reply's UI is written in, such as `a2ui` or `openui`. Formats are an open set:
+ * a renderer says which one it reads.
+ */
+export type AIUIFormat = 'a2ui' | 'openui' | (string & {});
+
+/**
+ * The UI an agent wrote for a reply, which shows in place of the reply's text.
+ */
+export type AIUIDocument = {
+  /** The document in its format's own shape: a program's text, or JSON. */
+  content: unknown;
+  /** The format it is written in. */
+  format: AIUIFormat;
+  /** Whether the agent is still writing it. */
+  isStreaming: boolean;
+  /** The format's version, when the agent names one. */
+  version?: string;
+};
+
+/**
+ * A reply's `ai_ui` field as the agents router writes it. An app that reads it from its Stream
+ * messages types it there with `ai_ui?: AIUIDocumentJSON` in its `CustomMessageData`.
+ */
+export type AIUIDocumentJSON = {
+  /** The document in its format's own shape: usually text, such as A2UI's JSON lines. */
+  content: unknown;
+  format: AIUIFormat;
+  /** `streaming` while the agent writes it, then `complete`. */
+  status?: 'streaming' | 'complete' | (string & {});
+  /** The version of the field's own layout; a newer one than this SDK reads shows the text. */
+  v?: number;
+  version?: string;
+};
+
+/** The custom field of a message that holds its document. */
+export const AI_UI_CUSTOM_DATA_KEY = 'ai_ui';
+/** The newest version of the `ai_ui` field this SDK reads. */
+export const AI_UI_SUPPORTED_VERSION = 1;
+
+/**
+ * Reads the document of a message's `ai_ui` field, or returns `undefined` when it carries none
+ * this SDK can read: no format, no content, or a field newer than this SDK, which can lay its
+ * documents out differently. The reply then shows its text.
+ */
+export const parseAIUIDocument = (field: unknown): AIUIDocument | undefined => {
+  if (!isRecord(field)) return undefined;
+  const { content, format, status, v, version } = field;
+  if (typeof format !== 'string' || format === '') return undefined;
+  if (content === undefined || content === null) return undefined;
+  if (typeof v === 'number' && v > AI_UI_SUPPORTED_VERSION) return undefined;
+  return {
+    content,
+    format,
+    isStreaming: status === 'streaming',
+    ...(typeof version === 'string' && version !== '' ? { version } : {}),
+  };
+};
+
+/** The content of a document when it is text, such as an OpenUI program or A2UI's JSON lines. */
+export const aiUIDocumentText = (document: AIUIDocument) =>
+  typeof document.content === 'string' ? document.content : undefined;
+
+/**
+ * Whether two documents are the same, content included. A message is a new object on every
+ * update while a reply streams, so a document is compared by what it holds.
+ */
+export const isSameAIUIDocument = (a: AIUIDocument | undefined, b: AIUIDocument | undefined) =>
+  a === b ||
+  (!!a &&
+    !!b &&
+    a.format === b.format &&
+    a.version === b.version &&
+    a.isStreaming === b.isStreaming &&
+    isSameJSON(a.content, b.content));

package/src/ai-components/generative-ui/AIUIEntrance.tsx

@@ -0,0 +1,229 @@
+import React, {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { Platform, type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native';
+import Animated, {
+  Easing,
+  ReduceMotion,
+  useAnimatedStyle,
+  useSharedValue,
+  withDelay,
+  withSpring,
+  withTiming,
+} from 'react-native-reanimated';
+
+import { useReduceMotion } from '../voice-visualization/useReduceMotion';
+
+/**
+ * Spaces out the parts of a reply's UI that come in together, so they come in one after another
+ * rather than at once.
+ */
+export class AIUICascade {
+  /** How long after the part before it a part comes in, in seconds. */
+  static readonly step = 0.1;
+  /** The longest a part waits for the parts before it, in seconds. */
+  static readonly longestWait = 0.4;
+
+  private next = 0;
+
+  /** How long a part that comes in at `now`, in seconds, waits for the parts before it. */
+  delay(now = (typeof performance === 'undefined' ? Date.now() : performance.now()) / 1000) {
+    const start = Math.min(Math.max(now, this.next), now + AIUICascade.longestWait);
+    this.next = start + AIUICascade.step;
+    return start - now;
+  }
+}
+
+type AIUIStage = {
+  cascade: AIUICascade;
+  /** Whether what shows now comes in with the part around it, rather than on its own. */
+  isCarried: boolean;
+};
+
+const AIUIStageContext = createContext<AIUIStage | undefined>(undefined);
+
+// A spring with a response of 0.7 and a damping of 0.88. It settles in about as long.
+const SPRING = { dampingRatio: 0.88, duration: 700 };
+// With reduced motion a part only fades, which the system setting would otherwise skip.
+const FADE = {
+  duration: 300,
+  easing: Easing.out(Easing.ease),
+  reduceMotion: ReduceMotion.Never,
+};
+// How far a part rises into place, how small it starts, and how far out of focus.
+const RISE = 16;
+const START_SCALE = 0.97;
+const START_BLUR = 8;
+// A blur only Android 12 and later draws; elsewhere a part comes in without it.
+const CAN_BLUR = Platform.OS === 'android' && Number(Platform.Version) >= 31;
+
+// Shows its content, bringing it in after the cascade's delay when it starts hidden.
+const useEntrance = (
+  startsHidden: boolean,
+  cascade: AIUICascade | undefined,
+  resetKey?: unknown,
+) => {
+  const reduceMotion = useReduceMotion();
+  const [shownFor, setShownFor] = useState(resetKey);
+  const [hasShownState, setHasShown] = useState(!startsHidden);
+  const isReset = !Object.is(shownFor, resetKey);
+  if (isReset) {
+    setShownFor(resetKey);
+    setHasShown(!startsHidden);
+  }
+  const hasShown = isReset ? !startsHidden : hasShownState;
+  const progress = useSharedValue(startsHidden ? 0 : 1);
+  const progressFor = useRef(resetKey);
+  useLayoutEffect(() => {
+    if (Object.is(progressFor.current, resetKey)) return;
+    progressFor.current = resetKey;
+    progress.value = startsHidden ? 0 : 1;
+  });
+  useEffect(() => {
+    if (hasShown) return;
+    const delay = (cascade?.delay() ?? 0) * 1000;
+    progress.value = withDelay(delay, reduceMotion ? withTiming(1, FADE) : withSpring(1, SPRING));
+    setHasShown(true);
+  }, [cascade, hasShown, progress, reduceMotion]);
+  const style = useAnimatedStyle(() => {
+    const shown = Math.min(progress.value, 1);
+    if (reduceMotion) return { opacity: shown };
+    return {
+      opacity: shown,
+      transform: [
+        { translateY: (1 - progress.value) * RISE },
+        { scale: START_SCALE + (1 - START_SCALE) * progress.value },
+      ],
+      // Back in focus as it settles: a blur this small draws nothing.
+      ...(CAN_BLUR ? { filter: [{ blur: Math.max(0, 1 - shown) * START_BLUR }] } : {}),
+    };
+  }, [reduceMotion]);
+  return { hasShown, style };
+};
+
+/**
+ * A reply's generated UI as a whole: it comes in when it first shows while the agent writes it,
+ * and shows at once when it was written before, such as a reply from history.
+ */
+export const AIUIEntranceStage = ({
+  children,
+  isStreaming,
+  resetKey,
+  style,
+}: {
+  children: ReactNode;
+  /** Whether the agent is writing the UI as it first shows. */
+  isStreaming: boolean;
+  /**
+   * Which reply's UI it shows: when it changes, it shows the UI as one mounted for it would, as
+   * when a list reuses it for another reply.
+   */
+  resetKey?: unknown;
+  style?: StyleProp<ViewStyle>;
+}) => {
+  const [held, setHeld] = useState(() => ({
+    cascade: new AIUICascade(),
+    isLive: isStreaming,
+    resetKey,
+  }));
+  let shown = held;
+  if (!Object.is(held.resetKey, resetKey)) {
+    shown = { cascade: new AIUICascade(), isLive: isStreaming, resetKey };
+    setHeld(shown);
+  }
+  const { cascade, isLive } = shown;
+  const { hasShown, style: entrance } = useEntrance(isLive, cascade, resetKey);
+  const stage = useMemo(
+    () => ({ cascade, isCarried: !isLive || !hasShown }),
+    [cascade, hasShown, isLive],
+  );
+  return (
+    <AIUIStageContext.Provider value={stage}>
+      <Animated.View style={[styles.entrance, entrance, style]}>{children}</Animated.View>
+    </AIUIStageContext.Provider>
+  );
+};
+
+/**
+ * Whether a part of a reply's generated UI comes in, as it was when the part first showed: a
+ * part that shows at once, such as one of a reply from history, can show in a plain view. A part
+ * mounted before it has anything to show passes `shows` as false until it does.
+ */
+export const useAIUIComesIn = (shows = true) => {
+  const stage = useContext(AIUIStageContext);
+  const [comesIn, setComesIn] = useState<boolean | undefined>(() =>
+    shows ? !!stage && !stage.isCarried : undefined,
+  );
+  if (comesIn !== undefined || !shows) return comesIn ?? false;
+  const now = !!stage && !stage.isCarried;
+  setComesIn(now);
+  return now;
+};
+
+/**
+ * What a part of a reply's generated UI needs to come in when it shows, for a renderer that
+ * animates a view of its own rather than wrap the part in `AIUIEntrance`: the animated `style`
+ * for that view, and `scope`, to wrap what the part shows in, so what shows with it comes in
+ * with it. The same entrance as `AIUIEntrance`'s.
+ */
+export const useAIUIEntrance = () => {
+  const stage = useContext(AIUIStageContext);
+  const { hasShown, style } = useEntrance(!!stage && !stage.isCarried, stage?.cascade);
+  const inner = useMemo(
+    () => stage && { cascade: stage.cascade, isCarried: stage.isCarried || !hasShown },
+    [hasShown, stage],
+  );
+  const scope = useMemo(
+    () => (children: ReactNode) => (
+      <AIUIStageContext.Provider value={inner}>{children}</AIUIStageContext.Provider>
+    ),
+    [inner],
+  );
+  return { scope, style: [styles.entrance, style] };
+};
+
+/**
+ * Brings a part of a reply's generated UI in when it shows, such as when the agent writes it:
+ * the part fades in, rising into place and, on Android 12 and later, coming into focus, after the
+ * parts that came in just before it. What shows together with the reply's UI, or with a part
+ * around it, comes in with that, so a reply written before it showed shows at once. With reduced
+ * motion it only fades.
+ *
+ * Renderers give it to each part they place. Every app component has it.
+ */
+export const AIUIEntrance = ({
+  children,
+  style,
+}: {
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}) => {
+  const comesIn = useAIUIComesIn();
+  return comesIn ? (
+    <EnteringPart style={style}>{children}</EnteringPart>
+  ) : (
+    <View style={[styles.entrance, style]}>{children}</View>
+  );
+};
+
+const EnteringPart = ({
+  children,
+  style,
+}: {
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}) => {
+  const { scope, style: entrance } = useAIUIEntrance();
+  return <Animated.View style={[entrance, style]}>{scope(children)}</Animated.View>;
+};
+
+const styles = StyleSheet.create({
+  entrance: { transformOrigin: 'top' },
+});