@q9labsai/chalk-react-native 4.0.0

package/src/components/SpaceView.shared.test.tsx

@@ -0,0 +1,115 @@
+import { readFileSync } from "node:fs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const state = vi.hoisted(() => ({
+  controller: {
+    actionsOpen: false,
+    activeReactions: [],
+    canChat: true,
+    canParticipants: true,
+    derived: { allParticipants: [], gridPages: [], isCompactViewport: false, isStageMode: false, primaryContent: "grid", screenShareTrack: null, screenSharer: null },
+    handRaised: false,
+    handleLeave: vi.fn(),
+    isCameraOff: false,
+    isMuted: false,
+    layout: { layout: "grid" },
+    openPanel: vi.fn(),
+    panel: null,
+    raisedHandCount: 0,
+    reactionPickerOpen: false,
+    selfName: "Taylor",
+    setActionsOpen: vi.fn(),
+    setReactionPickerOpen: vi.fn(),
+    simulatorMediaDisabled: false,
+    spaceName: "Design space",
+    chat: { unreadCount: 0 },
+    whiteboard: { canDraw: true, elements: [], isOpen: false, openParticipants: [] },
+  },
+  useSpaceViewController: vi.fn(),
+}));
+
+vi.mock("react-native", () => ({
+  Alert: { alert: vi.fn() },
+  StyleSheet: { create: <T,>(styles: T) => styles },
+  Text: "Text",
+  View: "View",
+}));
+vi.mock("../ui/theme", () => ({ Theme: { colors: { darkCanvas: "#0a0a0b", primary: "#1bb6a6", primaryForeground: "#ffffff" } } }));
+vi.mock("../ui/native-theme", () => ({
+  useNativeTheme: () => ({ colors: { darkCanvas: "#0a0a0b", primary: "#1bb6a6", primaryForeground: "#ffffff" } }),
+}));
+vi.mock("../utils/ios-simulator", () => ({ getIosSimulatorMediaMessage: () => "Media is unavailable in the simulator." }));
+vi.mock("./ReactionPicker", () => ({ ReactionPicker: "ReactionPicker" }));
+vi.mock("./native-space-view/SpaceActionMenu", () => ({ SpaceActionMenu: "SpaceActionMenu", selectSpaceReaction: vi.fn() }));
+vi.mock("./native-space-view/SettingsSheet", () => ({ SettingsSheet: "SettingsSheet" }));
+vi.mock("./native-space-view/SpacePanelSheet", () => ({ SpacePanelSheet: "SpacePanelSheet" }));
+vi.mock("./native-space-view/SpaceBottomDock.android", () => ({ SpaceBottomDockAndroid: "SpaceBottomDockAndroid" }));
+vi.mock("./native-space-view/SpaceGrid.android", () => ({ SpaceGridAndroid: "SpaceGridAndroid" }));
+vi.mock("./native-space-view/SpaceStage.android", () => ({ SpaceStageAndroid: "SpaceStageAndroid" }));
+vi.mock("./native-space-view/SpaceTopBar.android", () => ({ SpaceTopBarAndroid: "SpaceTopBarAndroid" }));
+vi.mock("./native-space-view/SpaceWhiteboardSurface", () => ({ SpaceWhiteboardSurface: "SpaceWhiteboardSurface" }));
+vi.mock("./native-space-view/useSpaceViewController", () => ({ useSpaceViewController: state.useSpaceViewController }));
+
+import { SpaceViewShared } from "./SpaceView.shared";
+
+describe("SpaceViewShared", () => {
+  const source = readFileSync(new URL("./SpaceView.shared.tsx", import.meta.url), "utf8");
+
+  beforeEach(() => {
+    state.controller.whiteboard.isOpen = false;
+    state.useSpaceViewController.mockClear();
+    state.useSpaceViewController.mockReturnValue(state.controller);
+  });
+
+  afterEach(() => {
+    state.controller.whiteboard.isOpen = false;
+    state.useSpaceViewController.mockClear();
+  });
+
+  it("passes reconnecting state and capability-gated controls to the native surface", () => {
+    const props = { onLeave: vi.fn(), reconnecting: true, logoUrl: "https://cdn.example.test/logo.png", spaceName: "Design space" };
+    const tree = SpaceViewShared(props);
+
+    expect(state.useSpaceViewController).toHaveBeenCalledWith(props);
+    expect(findText(tree)).toContain("Reconnecting… controls will resume shortly.");
+    expect(findElement(tree, "SpaceTopBarAndroid")).toMatchObject({ props: { logoUrl: props.logoUrl, spaceName: props.spaceName } });
+    expect(findElement(tree, "SpaceBottomDockAndroid")).toMatchObject({ props: { onOpenChat: expect.any(Function), unreadChatCount: 0 } });
+  });
+
+  it("renders the whiteboard surface instead of a stage or grid when it is open", () => {
+    state.controller.whiteboard.isOpen = true;
+
+    const tree = SpaceViewShared({ onLeave: vi.fn() });
+
+    expect(findElement(tree, "SpaceWhiteboardSurface")).toBeTruthy();
+    expect(findElement(tree, "SpaceStageAndroid")).toBeUndefined();
+    expect(findElement(tree, "SpaceGridAndroid")).toBeUndefined();
+  });
+
+  it("mounts the canonical panel sheet that owns the attachment composer", () => {
+    const panelSource = readFileSync(new URL("./native-space-view/SpacePanelSheet.tsx", import.meta.url), "utf8");
+    const chatSource = readFileSync(new URL("./native-space-view/SpaceChatSheet.tsx", import.meta.url), "utf8");
+
+    expect(source).toContain("<SpacePanelSheet controller={controller} />");
+    expect(source).not.toContain("<SpacePanel controller={controller} />");
+    expect(source).toContain("<SettingsSheet controller={controller}");
+    expect(panelSource).toContain("<SpaceChatSheet");
+    expect(chatSource).toContain('accessibilityLabel="Attach file"');
+    expect(chatSource).toContain("controller.removeChatAttachment(index)");
+  });
+});
+
+function findElement(value: unknown, type: string): { readonly props?: Record<string, unknown> } | undefined {
+  if (Array.isArray(value)) return value.map((child) => findElement(child, type)).find(Boolean);
+  if (!value || typeof value !== "object") return undefined;
+  const element = value as { readonly type?: unknown; readonly props?: Record<string, unknown> };
+  if (element.type === type) return element;
+  return findElement(element.props?.children, type);
+}
+
+function findText(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) return value.flatMap(findText);
+  if (!value || typeof value !== "object") return [];
+  return findText((value as { readonly props?: { readonly children?: unknown } }).props?.children);
+}

package/src/components/SpaceView.shared.tsx

@@ -0,0 +1,87 @@
+import { Alert, StyleSheet, Text, View } from "react-native";
+
+import { Theme } from "../ui/theme";
+import { useNativeTheme } from "../ui/native-theme";
+import { getIosSimulatorMediaMessage } from "../utils/ios-simulator";
+import { ReactionPicker } from "./ReactionPicker";
+import type { SpaceViewProps } from "./SpaceView";
+import { SpaceGridAndroid } from "./native-space-view/SpaceGrid.android";
+import { SpaceBottomDockAndroid } from "./native-space-view/SpaceBottomDock.android";
+import { SpaceActionMenu, selectSpaceReaction } from "./native-space-view/SpaceActionMenu";
+import { SpaceStageAndroid } from "./native-space-view/SpaceStage.android";
+import { SpaceTopBarAndroid } from "./native-space-view/SpaceTopBar.android";
+import { SpaceWhiteboardSurface } from "./native-space-view/SpaceWhiteboardSurface";
+import { SettingsSheet } from "./native-space-view/SettingsSheet";
+import { SpacePanelSheet } from "./native-space-view/SpacePanelSheet";
+import { useSpaceViewController } from "./native-space-view/useSpaceViewController";
+
+export function SpaceViewShared(props: SpaceViewProps): React.JSX.Element {
+  const controller = useSpaceViewController(props);
+  const theme = useNativeTheme();
+  const toggleMedia = (action: () => void) => {
+    if (controller.simulatorMediaDisabled) {
+      Alert.alert("Media unavailable", getIosSimulatorMediaMessage());
+      return;
+    }
+    action();
+  };
+
+  return (
+    <View style={[styles.space, { backgroundColor: theme.colors.darkCanvas }]}>
+      <SpaceTopBarAndroid formattedDuration={controller.formattedDuration} logoUrl={props.logoUrl} participantCount={controller.participantCount} spaceName={controller.spaceName} />
+      {props.reconnecting ? (
+        <View accessibilityLiveRegion="polite" style={[styles.recovery, { backgroundColor: theme.colors.primary }]}>
+          <Text style={[styles.recoveryText, { color: theme.colors.primaryForeground }]}>Reconnecting… controls will resume shortly.</Text>
+        </View>
+      ) : null}
+      <View style={styles.stage}>
+        {controller.whiteboard.isOpen ? (
+          <SpaceWhiteboardSurface whiteboard={controller.whiteboard} />
+        ) : controller.derived.isStageMode || controller.layout.layout !== "grid" ? (
+          <SpaceStageAndroid
+            activeReactions={controller.activeReactions}
+            handRaised={controller.handRaised}
+            isCompactViewport={controller.derived.isCompactViewport}
+            isMuted={controller.isMuted}
+            layoutMode={controller.layout.layout}
+            primaryContent={controller.derived.primaryContent}
+            raisedHandCount={controller.raisedHandCount}
+            screenShareTrack={controller.derived.screenShareTrack}
+            screenSharer={controller.derived.screenSharer}
+            selfName={controller.selfName}
+            stripParticipants={controller.derived.allParticipants}
+            whiteboard={{
+              isOpen: controller.whiteboard.isOpen,
+              canDraw: controller.whiteboard.canDraw,
+              elementCount: controller.whiteboard.elements.length,
+              participantCount: controller.whiteboard.openParticipants.length,
+            }}
+          />
+        ) : (
+          <SpaceGridAndroid gridPages={controller.derived.gridPages} participants={controller.derived.allParticipants} />
+        )}
+      </View>
+      <SpaceBottomDockAndroid
+        isCameraOff={controller.isCameraOff}
+        isMuted={controller.isMuted}
+        onLeave={controller.handleLeave}
+        onOpenChat={controller.canChat ? () => controller.openPanel("chat") : undefined}
+        onOpenMore={() => controller.setActionsOpen(true)}
+        onToggleAudio={() => toggleMedia(controller.toggleAudio)}
+        onToggleVideo={() => toggleMedia(controller.toggleVideo)}
+        simulatorMediaDisabled={controller.simulatorMediaDisabled}
+        unreadChatCount={controller.chat.unreadCount}
+      />
+      <SpaceActionMenu controller={controller} />
+      {controller.panel === "settings" ? <SettingsSheet controller={controller} isOpen onClose={controller.closePanel} /> : <SpacePanelSheet controller={controller} />}
+      <ReactionPicker isOpen={controller.reactionPickerOpen} onClose={() => controller.setReactionPickerOpen(false)} onSelect={(reaction) => selectSpaceReaction(controller, reaction)} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  space: { flex: 1, backgroundColor: Theme.colors.darkCanvas },
+  stage: { flex: 1, width: "100%", overflow: "hidden", justifyContent: "center" },
+  recovery: { alignItems: "center", paddingHorizontal: 16, paddingVertical: 8 },
+  recoveryText: { fontSize: 13, fontWeight: "700" },
+});

package/src/components/SpaceView.test.tsx

@@ -0,0 +1,15 @@
+import { describe, expect, it, vi } from "vitest";
+
+vi.mock("../platform/platform", () => ({ resolvePlatformVariant: () => "android" }));
+vi.mock("./SpaceView.android", () => ({ SpaceViewAndroid: () => null }));
+vi.mock("./SpaceView.ios-pad", () => ({ SpaceViewIosPad: () => null }));
+vi.mock("./SpaceView.ios-phone", () => ({ SpaceViewIosPhone: () => null }));
+vi.mock("./SpaceView.macos", () => ({ SpaceViewMacos: () => null }));
+
+describe("SpaceView", () => {
+  it("selects the platform-specific Space", async () => {
+    const { SpaceView } = await import("./SpaceView");
+
+    expect(SpaceView({ onLeave: vi.fn() })).toBeTruthy();
+  });
+});

package/src/components/SpaceView.tsx

@@ -0,0 +1,52 @@
+import type { ChatUploadFile } from "@q9labsai/chalk-client";
+import { resolvePlatformVariant } from "../platform/platform";
+import type { Layout } from "../ui/native-types";
+import { SpaceViewAndroid } from "./SpaceView.android";
+import { SpaceViewIosPad } from "./SpaceView.ios-pad";
+import { SpaceViewIosPhone } from "./SpaceView.ios-phone";
+import { SpaceViewMacos } from "./SpaceView.macos";
+import type { SpaceViewDiagnosticsSnapshot } from "./native-space-view/diagnostics";
+
+export interface SpaceViewFeatures {
+  chat?: boolean;
+  participants?: boolean;
+  admission?: boolean;
+  screenShare?: boolean;
+  reactions?: boolean;
+  handRaise?: boolean;
+  whiteboard?: boolean;
+  info?: boolean;
+  settings?: boolean;
+}
+
+export interface SpaceViewProps {
+  spaceName?: string;
+  inviteLink?: string;
+  logoUrl?: string;
+  reconnecting?: boolean;
+  layout?: Layout;
+  onLayoutChange?: (layout: Layout) => void;
+  features?: SpaceViewFeatures;
+  onLeave: () => void | Promise<void>;
+  onEndEpisode?: () => void | Promise<void>;
+  onDiagnosticsChange?: (snapshot: SpaceViewDiagnosticsSnapshot) => void;
+  /** Selects files; the SDK owns bounds, upload, and send sequencing. */
+  pickChatFiles?: () => Promise<readonly ChatUploadFile[]>;
+}
+
+export type { SpaceViewDiagnosticsSnapshot };
+
+export function SpaceView(props: SpaceViewProps): React.JSX.Element {
+  switch (resolvePlatformVariant()) {
+    case "ios-pad":
+      return <SpaceViewIosPad {...props} />;
+    case "ios-phone":
+      return <SpaceViewIosPhone {...props} />;
+    case "macos":
+      return <SpaceViewMacos {...props} />;
+    case "tvos":
+    case "android":
+    default:
+      return <SpaceViewAndroid {...props} />;
+  }
+}

package/src/components/android-connection-service-controller.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AndroidConnectionServiceControllerDependencies, AndroidConnectionServiceControllerInput } from "./android-connection-service-controller";
+import { AndroidConnectionServiceController } from "./android-connection-service-controller";
+
+async function flushMicrotasks(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+function createInput(overrides: Partial<AndroidConnectionServiceControllerInput> = {}): AndroidConnectionServiceControllerInput {
+  return {
+    displayName: "Guest",
+    enabled: true,
+    hasVideo: true,
+    joinNonce: 1,
+    onDisconnectRequest: vi.fn(),
+    phase: "joining",
+    spaceId: "space-1",
+    spaceName: "Daily Standup",
+    ...overrides,
+  };
+}
+
+function createDependencies() {
+  let listener: Parameters<AndroidConnectionServiceControllerDependencies["addListener"]>[0] | undefined;
+  const dependencies: AndroidConnectionServiceControllerDependencies = {
+    addListener: vi.fn((nextListener) => {
+      listener = nextListener;
+      return vi.fn();
+    }),
+    endCall: vi.fn(async () => true),
+    ensureRegistered: vi.fn(async () => true),
+    setActive: vi.fn(async () => true),
+    startCall: vi.fn(async () => true),
+  };
+  return { dependencies, getListener: () => listener };
+}
+
+describe("AndroidConnectionServiceController", () => {
+  it("starts, activates, and filters disconnect events for the current call", async () => {
+    const onDisconnectRequest = vi.fn();
+    const { dependencies, getListener } = createDependencies();
+    const controller = new AndroidConnectionServiceController(createInput({ onDisconnectRequest }), dependencies);
+    const unsubscribe = controller.subscribe(() => {});
+
+    expect(dependencies.ensureRegistered).toHaveBeenCalledTimes(1);
+    expect(dependencies.startCall).toHaveBeenCalledWith({
+      callId: "space-1:1",
+      displayName: "Guest",
+      hasVideo: true,
+      spaceId: "space-1",
+      spaceName: "Daily Standup",
+    });
+
+    controller.update(createInput({ onDisconnectRequest, phase: "live" }));
+    await flushMicrotasks();
+    expect(dependencies.setActive).toHaveBeenCalledWith("space-1:1");
+
+    getListener()?.({ callId: "other:1", reason: "remote", type: "disconnect" });
+    getListener()?.({ callId: "space-1:1", reason: "remote", type: "disconnect" });
+    expect(onDisconnectRequest).toHaveBeenCalledTimes(1);
+
+    controller.update(createInput({ onDisconnectRequest, phase: "entrance" }));
+    await flushMicrotasks();
+    expect(dependencies.endCall).toHaveBeenCalledWith("space-1:1", { reason: "canceled" });
+
+    unsubscribe();
+  });
+
+  it("ends an active call locally and removes the native listener on unsubscribe", () => {
+    const { dependencies } = createDependencies();
+    const controller = new AndroidConnectionServiceController(createInput(), dependencies);
+    const unsubscribe = controller.subscribe(() => {});
+
+    unsubscribe();
+
+    expect(dependencies.endCall).toHaveBeenCalledWith("space-1:1", { reason: "local" });
+    expect(dependencies.addListener).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/android-connection-service-controller.ts

@@ -0,0 +1,132 @@
+import type { AndroidConnectionServiceCall, AndroidConnectionServiceDisconnectReason } from "../android/connection-service";
+import type { SpaceLifecyclePhase } from "./space-lifecycle";
+
+export interface AndroidConnectionServiceControllerInput {
+  readonly displayName: string;
+  readonly enabled: boolean;
+  readonly hasVideo: boolean;
+  readonly joinNonce: number;
+  readonly onDisconnectRequest: () => void;
+  readonly phase: SpaceLifecyclePhase;
+  readonly spaceId: string;
+  readonly spaceName: string;
+}
+
+export interface AndroidConnectionServiceControllerDependencies {
+  readonly addListener: (listener: (event: { type: "disconnect"; callId: string; reason: AndroidConnectionServiceDisconnectReason }) => void) => () => void;
+  readonly endCall: (callId: string, options: { reason: AndroidConnectionServiceDisconnectReason }) => Promise<boolean>;
+  readonly ensureRegistered: () => Promise<boolean>;
+  readonly setActive: (callId: string) => Promise<boolean>;
+  readonly startCall: (call: AndroidConnectionServiceCall) => Promise<boolean>;
+}
+
+export class AndroidConnectionServiceController {
+  #dependencies: AndroidConnectionServiceControllerDependencies;
+  #input: AndroidConnectionServiceControllerInput;
+  #listeners = new Set<() => void>();
+  #resourcesEnabled = false;
+  #currentCallId: string | null = null;
+  #currentJoinNonce: number | null = null;
+  #activatedCallId: string | null = null;
+  #removeListener: (() => void) | undefined;
+  #syncScheduled = false;
+
+  constructor(input: AndroidConnectionServiceControllerInput, dependencies: AndroidConnectionServiceControllerDependencies) {
+    this.#input = input;
+    this.#dependencies = dependencies;
+  }
+
+  readonly getSnapshot = (): null => null;
+
+  readonly subscribe = (listener: () => void): (() => void) => {
+    this.#listeners.add(listener);
+    if (this.#listeners.size === 1) {
+      this.#sync();
+    }
+
+    return () => {
+      this.#listeners.delete(listener);
+      if (this.#listeners.size === 0) {
+        this.#stop();
+      }
+    };
+  };
+
+  readonly update = (input: AndroidConnectionServiceControllerInput): void => {
+    this.#input = input;
+    if (this.#listeners.size === 0) return;
+    this.#scheduleSync();
+  };
+
+  #scheduleSync(): void {
+    if (this.#syncScheduled) return;
+    this.#syncScheduled = true;
+    queueMicrotask(() => {
+      this.#syncScheduled = false;
+      if (this.#listeners.size === 0) return;
+      this.#sync();
+    });
+  }
+
+  #sync(): void {
+    const input = this.#input;
+    if (!input.enabled) {
+      this.#stop();
+      return;
+    }
+
+    this.#startResources();
+
+    if (input.phase === "joining" && this.#currentJoinNonce !== input.joinNonce) {
+      const callId = `${input.spaceId}:${input.joinNonce}`;
+      this.#currentJoinNonce = input.joinNonce;
+      this.#currentCallId = callId;
+      this.#activatedCallId = null;
+      void this.#dependencies.startCall({
+        callId,
+        displayName: input.displayName,
+        hasVideo: input.hasVideo,
+        spaceId: input.spaceId,
+        spaceName: input.spaceName,
+      });
+    }
+
+    if (input.phase === "live") {
+      const callId = this.#currentCallId;
+      if (callId && this.#activatedCallId !== callId) {
+        this.#activatedCallId = callId;
+        void this.#dependencies.setActive(callId);
+      }
+    }
+
+    if (input.phase !== "entrance" && input.phase !== "left") return;
+    const callId = this.#currentCallId;
+    if (!callId) return;
+
+    this.#currentCallId = null;
+    this.#activatedCallId = null;
+    void this.#dependencies.endCall(callId, { reason: input.phase === "entrance" ? "canceled" : "local" });
+  }
+
+  #startResources(): void {
+    if (this.#resourcesEnabled) return;
+    this.#resourcesEnabled = true;
+    void this.#dependencies.ensureRegistered();
+    this.#removeListener = this.#dependencies.addListener((event) => {
+      if (event.type !== "disconnect" || event.callId !== this.#currentCallId) return;
+      this.#input.onDisconnectRequest();
+    });
+  }
+
+  #stop(): void {
+    this.#removeListener?.();
+    this.#removeListener = undefined;
+    const callId = this.#currentCallId;
+    this.#currentCallId = null;
+    this.#activatedCallId = null;
+    this.#resourcesEnabled = false;
+
+    if (!callId) return;
+    void this.#dependencies.endCall(callId, { reason: "local" });
+  }
+}

package/src/components/episode-diagnostic-render-observer.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from "vitest";
+import { observeNativeFrameNotObservable } from "./episode-diagnostic-render-observer";
+
+const REGISTRY = Symbol.for("@chalk/private/episode-diagnostic-render-registry/v1");
+
+describe("observeNativeFrameNotObservable", () => {
+  it("emits an explicit gap because the native RTC view exposes no first-frame callback", () => {
+    const track = {};
+    const report = vi.fn();
+    (globalThis as unknown as Record<symbol, unknown>)[REGISTRY] = new WeakMap([[track, report]]);
+
+    observeNativeFrameNotObservable(track);
+
+    expect(report).toHaveBeenCalledWith("not_observable");
+  });
+
+  it("is inert when diagnostics did not register the track", () => {
+    const report = vi.fn();
+    (globalThis as unknown as Record<symbol, unknown>)[REGISTRY] = new WeakMap();
+
+    expect(() => observeNativeFrameNotObservable({})).not.toThrow();
+    expect(report).not.toHaveBeenCalled();
+  });
+});

package/src/components/episode-diagnostic-render-observer.ts

@@ -0,0 +1,12 @@
+const REGISTRY = Symbol.for("@chalk/private/episode-diagnostic-render-registry/v1");
+
+type RenderReporter = (observation: "first_frame" | "not_observable") => void;
+type DiagnosticGlobal = typeof globalThis & { [REGISTRY]?: WeakMap<object, RenderReporter> };
+
+export function observeNativeFrameNotObservable(track: object): void {
+  try {
+    (globalThis as DiagnosticGlobal)[REGISTRY]?.get(track)?.("not_observable");
+  } catch {
+    // Native rendering stays independent from diagnostic observation.
+  }
+}

package/src/components/native-animation-controller.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it, vi } from "vitest";
+import { createAnimationRefController, type StoppableAnimation } from "./native-animation-controller";
+
+function createAnimation(): StoppableAnimation {
+  return {
+    start: vi.fn(),
+    stop: vi.fn(),
+  };
+}
+
+describe("createAnimationRefController", () => {
+  it("starts animations once per attachment and stops them on detachment", () => {
+    const firstAnimation = createAnimation();
+    const secondAnimation = createAnimation();
+    const ref = createAnimationRefController(() => [firstAnimation, secondAnimation]);
+
+    ref({});
+    ref({});
+
+    expect(firstAnimation.start).toHaveBeenCalledOnce();
+    expect(secondAnimation.start).toHaveBeenCalledOnce();
+    expect(firstAnimation.stop).not.toHaveBeenCalled();
+
+    ref(null);
+    ref(null);
+
+    expect(firstAnimation.stop).toHaveBeenCalledOnce();
+    expect(secondAnimation.stop).toHaveBeenCalledOnce();
+  });
+
+  it("creates a fresh animation set when a node is attached again", () => {
+    const firstAnimation = createAnimation();
+    const secondAnimation = createAnimation();
+    const createAnimations = vi.fn().mockReturnValueOnce([firstAnimation]).mockReturnValueOnce([secondAnimation]);
+    const ref = createAnimationRefController(createAnimations);
+
+    ref({});
+    ref(null);
+    ref({});
+
+    expect(createAnimations).toHaveBeenCalledTimes(2);
+    expect(firstAnimation.start).toHaveBeenCalledOnce();
+    expect(firstAnimation.stop).toHaveBeenCalledOnce();
+    expect(secondAnimation.start).toHaveBeenCalledOnce();
+    expect(secondAnimation.stop).not.toHaveBeenCalled();
+  });
+});

package/src/components/native-animation-controller.ts

@@ -0,0 +1,36 @@
+export interface StoppableAnimation {
+  start(): void;
+  stop(): void;
+}
+
+export type AnimationRefCallback<Node> = (node: Node | null) => void;
+
+export function createAnimationRefController<Node>(createAnimations: () => readonly StoppableAnimation[]): AnimationRefCallback<Node> {
+  let attached = false;
+  let animations: readonly StoppableAnimation[] = [];
+
+  return (node) => {
+    if (node === null) {
+      if (!attached) {
+        return;
+      }
+
+      attached = false;
+      for (const animation of animations) {
+        animation.stop();
+      }
+      animations = [];
+      return;
+    }
+
+    if (attached) {
+      return;
+    }
+
+    attached = true;
+    animations = createAnimations();
+    for (const animation of animations) {
+      animation.start();
+    }
+  };
+}

package/src/components/native-chat.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { formatChatAttachmentSize, isLatestChatMessageVisible } from "./native-chat";
+
+describe("native chat viewport", () => {
+  it("reports the latest message only when the viewport reaches the content bottom", () => {
+    expect(isLatestChatMessageVisible({ contentHeight: 600, viewportHeight: 300, scrollOffset: 120 })).toBe(false);
+    expect(isLatestChatMessageVisible({ contentHeight: 600, viewportHeight: 300, scrollOffset: 292 })).toBe(true);
+  });
+
+  it("does not treat unmeasured content as visible", () => {
+    expect(isLatestChatMessageVisible({ contentHeight: 0, viewportHeight: 300, scrollOffset: 0 })).toBe(false);
+    expect(isLatestChatMessageVisible({ contentHeight: 300, viewportHeight: 0, scrollOffset: 0 })).toBe(false);
+  });
+});
+
+describe("native chat attachment metadata", () => {
+  it("formats byte lengths for compact attachment rows", () => {
+    expect(formatChatAttachmentSize(512)).toBe("512 B");
+    expect(formatChatAttachmentSize(1_536)).toBe("1.5 KB");
+    expect(formatChatAttachmentSize(2_097_152)).toBe("2.0 MB");
+  });
+});

package/src/components/native-chat.ts

@@ -0,0 +1,23 @@
+export interface NativeChatViewport {
+  readonly contentHeight: number;
+  readonly viewportHeight: number;
+  readonly scrollOffset: number;
+}
+
+const LATEST_MESSAGE_VISIBILITY_TOLERANCE = 8;
+
+export function isLatestChatMessageVisible({ contentHeight, viewportHeight, scrollOffset }: NativeChatViewport): boolean {
+  if (contentHeight <= 0 || viewportHeight <= 0) return false;
+  return scrollOffset + viewportHeight >= contentHeight - LATEST_MESSAGE_VISIBILITY_TOLERANCE;
+}
+
+export function formatChatAttachmentSize(byteLength: number): string {
+  if (byteLength < 1024) return `${byteLength} B`;
+  if (byteLength < 1024 * 1024) return `${formatUnit(byteLength / 1024)} KB`;
+  if (byteLength < 1024 * 1024 * 1024) return `${formatUnit(byteLength / (1024 * 1024))} MB`;
+  return `${formatUnit(byteLength / (1024 * 1024 * 1024))} GB`;
+}
+
+function formatUnit(value: number): string {
+  return value >= 10 ? value.toFixed(0) : value.toFixed(1);
+}