@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

package/src/hooks/use-browser-session.ts

@@ -16,12 +16,31 @@ import {
   type EmbeddedBrowserInteractionClientOverride,
   useEmbeddedBrowserInteraction,
 } from "../session-context";
+import { isNonRetryableInteractionError } from "../lib/interaction-errors";
 import { usePageLiveActivity } from "./internal";
 
+/** Immutable input fence; queued actions never need the encoded screenshot. */
+export type BrowserFrameInputFence = Pick<
+  BrowserFrame,
+  | "browserSessionId"
+  | "controllerGeneration"
+  | "targetId"
+  | "targetGeneration"
+  | "documentGeneration"
+  | "frameId"
+>;
+
+export type BrowserInputFailure = Pick<BrowserActionReceipt, "operationId" | "error"> & {
+  state: Exclude<BrowserActionReceipt["state"], "completed">;
+};
+
 export type UseBrowserSessionOptions = EmbeddedBrowserInteractionClientOverride & {
   browserSessionId: string | null;
   enabled?: boolean | undefined;
   pollIntervalMs?: number | undefined;
+  /** Keep session/tab inventory current without repeatedly fetching the full
+   * accessibility tree while a live frame is available or the viewer is hidden. */
+  semanticObservationEnabled?: boolean | undefined;
 };
 
 export type UseBrowserSessionResult = {
@@ -32,7 +51,13 @@ export type UseBrowserSessionResult = {
   loading: boolean;
   mutating: boolean;
   error: Error | null;
+  inputFailure: BrowserInputFailure | null;
   refresh: () => Promise<void>;
+  observeForInput: () => Promise<BrowserObservation>;
+  actFromObservation: (
+    action: BrowserAction,
+    observation: BrowserObservation,
+  ) => Promise<BrowserActionReceipt>;
   selectTarget: (targetId: string) => Promise<BrowserTarget>;
   openTarget: (url?: string) => Promise<BrowserTarget>;
   closeTarget: (targetId: string) => Promise<void>;
@@ -44,8 +69,9 @@ export type UseBrowserSessionResult = {
    *  the controller fence instead of targeting a newer page. */
   actFromFrame: (
     action: BrowserAction | BrowserActionBatch,
-    frame: BrowserFrame,
+    frame: BrowserFrameInputFence,
     operationId?: string,
+    observationMode?: "none" | "input",
   ) => Promise<BrowserActionReceipt>;
   readClipboard: () => Promise<BrowserClipboard>;
   diagnostics: (options?: BrowserDiagnosticsOptions) => Promise<BrowserDiagnosticBatch>;
@@ -57,6 +83,13 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
   const { client, workspaceId } = useEmbeddedBrowserInteraction(options);
   const browserSessionId = options.browserSessionId;
   const enabled = (options.enabled ?? true) && browserSessionId !== null;
+  const semanticObservationEnabled = options.semanticObservationEnabled ?? true;
+  const semanticObservationEnabledRef = useRef(semanticObservationEnabled);
+  semanticObservationEnabledRef.current = semanticObservationEnabled;
+  const previousSemanticObservationRef = useRef({
+    browserSessionId,
+    enabled: semanticObservationEnabled,
+  });
   const pageLive = usePageLiveActivity();
   const pollIntervalMs = Math.max(750, options.pollIntervalMs ?? 2_000);
   const [state, setState] = useState<{
@@ -68,15 +101,25 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     loading: boolean;
     mutating: boolean;
     error: Error | null;
+    inputFailure: BrowserInputFailure | null;
   }>(() => emptyState(browserSessionId, enabled));
   const visible =
     state.browserSessionId === browserSessionId ? state : emptyState(browserSessionId, enabled);
+  const refreshBlocked = isNonRetryableInteractionError(visible.error);
+  const inputFailureRef = useRef(visible.inputFailure);
+  inputFailureRef.current = visible.inputFailure;
   const selectedTargetIdRef = useRef<string | null>(visible.selectedTargetId);
   selectedTargetIdRef.current = visible.selectedTargetId;
+  const selectedTargetRef = useRef<BrowserTarget | null>(
+    visible.targets.find((target) => target.id === visible.selectedTargetId) ?? null,
+  );
+  selectedTargetRef.current =
+    visible.targets.find((target) => target.id === visible.selectedTargetId) ?? null;
   const observationRef = useRef<{
     browserSessionId: string | null;
     observation: BrowserObservation | null;
   }>({ browserSessionId, observation: visible.observation });
+  const lastObservationAtRef = useRef(0);
   if (observationRef.current.browserSessionId !== browserSessionId) {
     observationRef.current = {
       browserSessionId,
@@ -104,77 +147,133 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     requestRef.current = { id, controller: null };
   }, []);
 
-  const refresh = useCallback(async (): Promise<void> => {
-    if (!enabled || !browserSessionId) return;
-    const id = requestRef.current.id + 1;
-    requestRef.current.controller?.abort();
-    const controller = new AbortController();
-    requestRef.current = { id, controller };
-    try {
-      const [session, targetResponse] = await Promise.all([
-        client.getBrowserSession(workspaceId, browserSessionId, {
-          signal: controller.signal,
-        }),
-        client.listBrowserTargets(workspaceId, browserSessionId, {
-          signal: controller.signal,
-        }),
-      ]);
-      if (!mountedRef.current || requestRef.current.id !== id) return;
-      const selected = chooseTarget(targetResponse.targets, selectedTargetIdRef.current);
-      selectedTargetIdRef.current = selected?.id ?? null;
-      observationRef.current = { browserSessionId, observation: null };
-      setState((current) =>
-        current.browserSessionId === browserSessionId
-          ? {
-              ...current,
-              session,
-              targets: targetResponse.targets,
-              selectedTargetId: selected?.id ?? null,
-              observation: null,
-              loading: false,
-              error: null,
-            }
-          : current,
-      );
-      if (!selected) return;
+  const refreshInventory = useCallback(
+    async (checkInput = false) => {
+      if (!enabled || !browserSessionId) return;
+      const checkedInputFailure = inputFailureRef.current;
+      const id = requestRef.current.id + 1;
+      requestRef.current.controller?.abort();
+      const controller = new AbortController();
+      requestRef.current = { id, controller };
       try {
-        const observation = await client.observeBrowserTarget(
-          workspaceId,
-          browserSessionId,
-          selected.id,
-          { signal: controller.signal },
-        );
+        const [session, targetResponse] = await Promise.all([
+          client.getBrowserSession(workspaceId, browserSessionId, {
+            signal: controller.signal,
+          }),
+          client.listBrowserTargets(workspaceId, browserSessionId, {
+            signal: controller.signal,
+          }),
+        ]);
         if (!mountedRef.current || requestRef.current.id !== id) return;
-        observationRef.current = { browserSessionId, observation };
+        const selected = chooseTarget(targetResponse.targets, selectedTargetIdRef.current);
+        selectedTargetIdRef.current = selected?.id ?? null;
+        const previousObservation =
+          observationRef.current.browserSessionId === browserSessionId
+            ? observationRef.current.observation
+            : null;
+        const retainedObservation =
+          selected && previousObservation && sameObservationTarget(previousObservation, selected)
+            ? previousObservation
+            : null;
+        observationRef.current = { browserSessionId, observation: retainedObservation };
         setState((current) =>
-          current.browserSessionId === browserSessionId &&
-          current.selectedTargetId === observation.target.id
-            ? { ...current, observation }
+          current.browserSessionId === browserSessionId
+            ? {
+                ...current,
+                session,
+                targets: targetResponse.targets,
+                selectedTargetId: selected?.id ?? null,
+                observation: retainedObservation,
+                loading: false,
+                error: null,
+                // Media and background polling cannot confirm an input outcome.
+                // Only an explicit fresh check clears the notice it began with.
+                inputFailure:
+                  checkInput &&
+                  session.id === browserSessionId &&
+                  targetResponse.browserSessionId === browserSessionId &&
+                  current.inputFailure === checkedInputFailure
+                    ? null
+                    : current.inputFailure,
+              }
             : current,
         );
+        if (!selected || !semanticObservationEnabledRef.current) return;
+        try {
+          const observation = await client.observeBrowserTarget(
+            workspaceId,
+            browserSessionId,
+            selected.id,
+            { signal: controller.signal },
+          );
+          if (!mountedRef.current || requestRef.current.id !== id) return;
+          observationRef.current = { browserSessionId, observation };
+          lastObservationAtRef.current = Date.now();
+          setState((current) =>
+            current.browserSessionId === browserSessionId &&
+            current.selectedTargetId === observation.target.id
+              ? { ...current, observation }
+              : current,
+          );
+        } catch (cause) {
+          if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
+            return;
+          // Target inventory and the media plane remain authoritative for the
+          // human-facing browser. A failed semantic snapshot must not blank or
+          // disable an otherwise live visual browser.
+          void cause;
+        }
       } catch (cause) {
         if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
           return;
-        // Target inventory and the media plane remain authoritative for the
-        // human-facing browser. A failed semantic snapshot must not blank or
-        // disable an otherwise live visual browser.
-        void cause;
+        setState((current) =>
+          current.browserSessionId === browserSessionId
+            ? {
+                ...current,
+                loading: false,
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+              }
+            : current,
+        );
+      } finally {
+        if (requestRef.current.id === id) {
+          requestRef.current = { id, controller: null };
+        }
       }
-    } catch (cause) {
-      if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id) return;
+    },
+    [browserSessionId, client, enabled, workspaceId],
+  );
+
+  const refresh = useCallback(async () => await refreshInventory(true), [refreshInventory]);
+
+  const refreshSemantic = useCallback(async (): Promise<void> => {
+    if (!enabled || !browserSessionId) return;
+    const target = selectedTargetRef.current;
+    if (!target) return;
+    const id = requestRef.current.id + 1;
+    requestRef.current.controller?.abort();
+    const controller = new AbortController();
+    requestRef.current = { id, controller };
+    try {
+      const observation = await client.observeBrowserTarget(
+        workspaceId,
+        browserSessionId,
+        target.id,
+        { signal: controller.signal },
+      );
+      if (!mountedRef.current || requestRef.current.id !== id) return;
+      if (!sameObservationTarget(observation, selectedTargetRef.current)) return;
+      observationRef.current = { browserSessionId, observation };
+      lastObservationAtRef.current = Date.now();
       setState((current) =>
-        current.browserSessionId === browserSessionId
-          ? {
-              ...current,
-              loading: false,
-              error: cause instanceof Error ? cause : new Error(String(cause)),
-            }
+        current.browserSessionId === browserSessionId && current.selectedTargetId === target.id
+          ? { ...current, observation }
           : current,
       );
+    } catch {
+      // A failed semantic fallback cannot disable an otherwise live browser.
     } finally {
-      if (requestRef.current.id === id) {
-        requestRef.current = { id, controller: null };
-      }
+      if (requestRef.current.id === id) requestRef.current = { id, controller: null };
     }
   }, [browserSessionId, client, enabled, workspaceId]);
 
@@ -190,27 +289,58 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
         ? { ...current, loading: true }
         : emptyState(browserSessionId, true),
     );
-    void refresh();
+    void refreshInventory();
     return () => {
       mountedRef.current = false;
       invalidateRefresh();
     };
-  }, [browserSessionId, enabled, invalidateRefresh, refresh]);
+  }, [browserSessionId, enabled, invalidateRefresh, refreshInventory]);
+
+  useEffect(() => {
+    const previous = previousSemanticObservationRef.current;
+    previousSemanticObservationRef.current = {
+      browserSessionId,
+      enabled: semanticObservationEnabled,
+    };
+    if (
+      enabled &&
+      semanticObservationEnabled &&
+      previous.browserSessionId === browserSessionId &&
+      !previous.enabled
+    ) {
+      // The media stream disappeared or the user returned to the Browser tab.
+      // A just-returned action/tab observation is already a fresh fallback.
+      // Otherwise drop the old tree/fence until a new read settles.
+      const currentObservation = observationRef.current.observation;
+      if (
+        currentObservation &&
+        sameObservationTarget(currentObservation, selectedTargetRef.current) &&
+        Date.now() - lastObservationAtRef.current < pollIntervalMs
+      ) {
+        return;
+      }
+      observationRef.current = { browserSessionId, observation: null };
+      setState((current) =>
+        current.browserSessionId === browserSessionId ? { ...current, observation: null } : current,
+      );
+      void refreshSemantic();
+    }
+  }, [browserSessionId, enabled, pollIntervalMs, refreshSemantic, semanticObservationEnabled]);
 
   useEffect(() => {
-    if (!enabled || !pageLive || visible.mutating) return;
+    if (!enabled || !pageLive || visible.mutating || refreshBlocked) return;
     const timer = setInterval(() => {
-      if (!requestRef.current.controller) void refresh();
+      if (!requestRef.current.controller) void refreshInventory();
     }, pollIntervalMs);
     return () => clearInterval(timer);
-  }, [enabled, pageLive, pollIntervalMs, refresh, visible.mutating]);
+  }, [enabled, pageLive, pollIntervalMs, refreshInventory, refreshBlocked, visible.mutating]);
 
   useEffect(() => {
-    if (!enabled || !browserSessionId || !pageLive) return;
+    if (!enabled || !browserSessionId || !pageLive || refreshBlocked) return;
     let disposed = false;
     const heartbeat = () => {
       void client.heartbeatBrowserSession(workspaceId, browserSessionId).catch(() => {
-        if (!disposed) void refresh();
+        if (!disposed) void refreshInventory();
       });
     };
     const timer = setInterval(heartbeat, 30_000);
@@ -218,7 +348,7 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
       disposed = true;
       clearInterval(timer);
     };
-  }, [browserSessionId, client, enabled, pageLive, refresh, workspaceId]);
+  }, [browserSessionId, client, enabled, pageLive, refreshInventory, refreshBlocked, workspaceId]);
 
   const runMutation = useCallback(
     async <T>(scopeBrowserSessionId: string, operation: () => Promise<T>): Promise<T> => {
@@ -299,6 +429,7 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
         }
         selectedTargetIdRef.current = target.id;
         observationRef.current = { browserSessionId, observation };
+        lastObservationAtRef.current = Date.now();
         setState((current) =>
           current.browserSessionId === browserSessionId
             ? {
@@ -330,6 +461,7 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
         const target = observation.target;
         selectedTargetIdRef.current = target.id;
         observationRef.current = { browserSessionId, observation };
+        lastObservationAtRef.current = Date.now();
         setState((current) =>
           current.browserSessionId === browserSessionId
             ? {
@@ -363,6 +495,7 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
           : null;
         selectedTargetIdRef.current = selected?.id ?? null;
         observationRef.current = { browserSessionId, observation };
+        if (observation) lastObservationAtRef.current = Date.now();
         setState((current) =>
           current.browserSessionId === browserSessionId
             ? {
@@ -382,7 +515,13 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     async (
       action: BrowserAction | BrowserActionBatch,
       operationId: string,
-      frame: BrowserFrame | null,
+      frame:
+        | (Pick<BrowserFrame, "browserSessionId" | "targetId" | "targetGeneration"> & {
+            frameId: string | null;
+            documentGeneration: string | null;
+          })
+        | null,
+      observationMode: "none" | "input" = "none",
     ): Promise<BrowserActionReceipt> => {
       if (!browserSessionId) throw new Error("No BrowserSession is selected.");
       if (frame && frame.browserSessionId !== browserSessionId) {
@@ -414,14 +553,25 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
         const receipt = await client.actInBrowser(workspaceId, browserSessionId, {
           operationId,
           ...fence,
-          observationMode: "none",
+          observationMode,
           action,
         });
+        if (receipt.state !== "completed") {
+          const inputFailure: BrowserInputFailure = {
+            operationId: receipt.operationId,
+            state: receipt.state,
+            error: receipt.error,
+          };
+          setState((current) =>
+            current.browserSessionId === browserSessionId ? { ...current, inputFailure } : current,
+          );
+        }
         if (receipt.observation) {
           observationRef.current = {
             browserSessionId,
             observation: receipt.observation,
           };
+          lastObservationAtRef.current = Date.now();
           setState((current) =>
             current.browserSessionId === browserSessionId
               ? {
@@ -455,9 +605,41 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
   const actFromFrame = useCallback(
     async (
       action: BrowserAction | BrowserActionBatch,
-      frame: BrowserFrame,
+      frame: BrowserFrameInputFence,
       operationId: string = crypto.randomUUID(),
-    ): Promise<BrowserActionReceipt> => await dispatchAction(action, operationId, frame),
+      observationMode: "none" | "input" = "none",
+    ): Promise<BrowserActionReceipt> =>
+      await dispatchAction(action, operationId, frame, observationMode),
+    [dispatchAction],
+  );
+
+  const observeForInput = useCallback(async (): Promise<BrowserObservation> => {
+    const target = selectedTargetRef.current;
+    if (!browserSessionId || !target) throw new Error("No browser tab is selected.");
+    const observation = await client.observeBrowserTarget(workspaceId, browserSessionId, target.id);
+    if (
+      !mountedRef.current ||
+      observation.browserSessionId !== browserSessionId ||
+      !sameObservationTarget(observation, selectedTargetRef.current)
+    ) {
+      throw new Error("The browser page changed. Open the options again.");
+    }
+    return observation;
+  }, [browserSessionId, client, workspaceId]);
+
+  const actFromObservation = useCallback(
+    async (action: BrowserAction, observation: BrowserObservation) => {
+      if (!sameObservationTarget(observation, selectedTargetRef.current)) {
+        throw new Error("The browser page changed. Open the options again.");
+      }
+      return await dispatchAction(action, crypto.randomUUID(), {
+        browserSessionId: observation.browserSessionId,
+        targetId: observation.target.id,
+        targetGeneration: observation.target.targetGeneration,
+        documentGeneration: observation.target.documentGeneration,
+        frameId: observation.frameId,
+      });
+    },
     [dispatchAction],
   );
 
@@ -495,7 +677,10 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     loading: visible.loading,
     mutating: visible.mutating,
     error: visible.error,
+    inputFailure: visible.inputFailure,
     refresh,
+    observeForInput,
+    actFromObservation,
     selectTarget,
     openTarget,
     closeTarget,
@@ -516,6 +701,7 @@ function emptyState(browserSessionId: string | null, loading: boolean) {
     loading,
     mutating: false,
     error: null as Error | null,
+    inputFailure: null as BrowserInputFailure | null,
   };
 }
 
@@ -538,6 +724,20 @@ function replaceTarget(targets: readonly BrowserTarget[], target: BrowserTarget)
   return next.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
 }
 
+function sameObservationTarget(
+  observation: BrowserObservation,
+  target: BrowserTarget | null,
+): boolean {
+  return (
+    target !== null &&
+    observation.browserSessionId === target.browserSessionId &&
+    observation.target.id === target.id &&
+    observation.target.controllerGeneration === target.controllerGeneration &&
+    observation.target.targetGeneration === target.targetGeneration &&
+    observation.target.documentGeneration === target.documentGeneration
+  );
+}
+
 function isMissingBrowserTarget(error: unknown): boolean {
   return error instanceof OpenGeniApiError && error.code === "target_not_found";
 }

package/src/hooks/use-browser-sessions.ts

@@ -60,6 +60,7 @@ export function useBrowserSessions(
   const enabled = options.enabled ?? true;
   const [state, setState] = useState<{
     workspaceId: string;
+    active: boolean;
     revision: number;
     sessions: BrowserSession[];
     loading: boolean;
@@ -89,6 +90,7 @@ export function useBrowserSessions(
       requestRef.current = { id, controller };
       setState((current) => ({
         ...(current.workspaceId === workspaceId ? current : emptyState(workspaceId, true)),
+        active: true,
         loading: foreground,
         refreshing: !foreground,
         error: foreground || current.workspaceId !== workspaceId ? null : current.error,
@@ -100,6 +102,7 @@ export function useBrowserSessions(
         if (!mountedRef.current || requestRef.current.id !== id) return;
         setState({
           workspaceId,
+          active: true,
           revision: response.revision,
           sessions: sortBrowserSessions(response.sessions),
           loading: false,
@@ -229,7 +232,9 @@ export function useBrowserSessions(
     revision: visibleState.revision,
     sessions: visibleState.sessions,
     relevantSessions,
-    loading: visibleState.loading,
+    // A disabled registry is deliberately empty. Expose the first re-enabled
+    // render as loading so consumers do not reconcile against that empty gap.
+    loading: enabled ? !visibleState.active || visibleState.loading : false,
     refreshing: visibleState.refreshing,
     error: visibleState.error,
     refresh,
@@ -243,6 +248,7 @@ export function useBrowserSessions(
 function emptyState(workspaceId: string, loading: boolean) {
   return {
     workspaceId,
+    active: false,
     revision: 0,
     sessions: [] as BrowserSession[],
     loading,

package/src/hooks/use-channels.ts

@@ -1,6 +1,7 @@
 import type { Channel, CreateChannelRequest, Session, UpdateChannelRequest } from "@opengeni/sdk";
-import { useCallback } from "react";
+import { useCallback, useMemo, useSyncExternalStore } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
+import { channelCacheFor } from "./channel-cache";
 import { useMutationRunner, usePolledValue } from "./internal";
 
 export type UseChannelsOptions = ClientOverride & {
@@ -15,6 +16,7 @@ export type UseChannelsResult = {
   refresh: () => Promise<void>;
   create: (request: CreateChannelRequest) => Promise<Channel | null>;
   update: (channelId: string, request: UpdateChannelRequest) => Promise<Channel | null>;
+  reorder: (channelIds: string[]) => Promise<Channel[] | null>;
   remove: (channelId: string) => Promise<boolean>;
   /** Re-file a session into a channel; null moves it back to the inbox. */
   moveSession: (sessionId: string, channelId: string | null) => Promise<Session | null>;
@@ -30,25 +32,33 @@ export type UseChannelsResult = {
  */
 export function useChannels(options: UseChannelsOptions = {}): UseChannelsResult {
   const { client, workspaceId } = useOpenGeni(options);
-  const load = useCallback(
-    async () => await client.listChannels(workspaceId),
-    [client, workspaceId],
-  );
-  const { data, loading, error, refresh } = usePolledValue(load, {
+  const cache = useMemo(() => channelCacheFor(client, workspaceId), [client, workspaceId]);
+  const snapshot = useSyncExternalStore(cache.subscribe, cache.getSnapshot, cache.getSnapshot);
+  const load = useCallback(async () => {
+    const ticket = cache.beginLoad();
+    const channels = await client.listChannels(workspaceId);
+    cache.acceptLoad(ticket, channels);
+    return channels;
+  }, [cache, client, workspaceId]);
+  const { loading, error, refresh } = usePolledValue(load, {
     pollIntervalMs: options.pollIntervalMs,
     enabled: options.enabled,
   });
-  const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
+  const { run, mutating, mutationError, clearMutationError } = useMutationRunner(cache);
 
   const create = useCallback(
     async (request: CreateChannelRequest): Promise<Channel | null> => {
       const result = await run(() => client.createChannel(workspaceId, request));
       if (result) {
+        // Publish the canonical write response before this promise can resolve.
+        // The composer may create a session with this id immediately, while a
+        // sibling rail hook could still have an older list request in flight.
+        cache.publishCreated(result);
         await refresh();
       }
       return result;
     },
-    [client, workspaceId, run, refresh],
+    [cache, client, workspaceId, run, refresh],
   );
 
   const update = useCallback(
@@ -76,6 +86,15 @@ export function useChannels(options: UseChannelsOptions = {}): UseChannelsResult
     [client, workspaceId, run, refresh],
   );
 
+  const reorder = useCallback(
+    async (channelIds: string[]): Promise<Channel[] | null> => {
+      const result = await run(() => client.reorderChannels(workspaceId, { channelIds }));
+      if (result) await refresh();
+      return result;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
   const moveSession = useCallback(
     async (sessionId: string, channelId: string | null): Promise<Session | null> => {
       return await run(() => client.updateSessionChannel(workspaceId, sessionId, { channelId }));
@@ -84,12 +103,15 @@ export function useChannels(options: UseChannelsOptions = {}): UseChannelsResult
   );
 
   return {
-    channels: data ?? [],
-    loading,
+    // Cache snapshots replace arrays instead of mutating them, so preserve the
+    // stable reference expected from the previous polled-value implementation.
+    channels: snapshot.channels as Channel[],
+    loading: loading && !snapshot.ready,
     error,
     refresh,
     create,
     update,
+    reorder,
     remove,
     moveSession,
     mutating,