chore(lint): every React effect states its reason at the call site (#26161)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: juliusmarminge

AGENTS.md

@@ -199,7 +199,7 @@ Architecture and its constraints: `docs/internals/overview.md`. Glossary: `docs/
   options, and pass combinators as additional function-builder arguments.
 - Inferred types over annotations. `any` is the enemy.
 - Default to no comment. Write one only for a constraint, an external quirk, or an invariant the code can't show, in one line where you can and four at most. Don't restate names or signatures, narrate steps, record history, or explain the fix you just made; the PR carries that. `t3code/no-low-value-comments` enforces the length cap and the mechanical cases.
-- React effects are for synchronizing with something outside React. Derive in render and act in handlers instead of syncing state, but don't hide real lifecycle work in refs or stores to dodge one. The `t3code/react-effect-budget` lint rule holds each file to its count in `scripts/effect-budget.json`; a new effect states its reason with `// oxlint-disable-next-line t3code/react-effect-budget -- <why>`.
+- React effects are for synchronizing with something outside React. Derive in render and act in handlers instead of syncing state, but don't hide real lifecycle work in refs or stores to dodge one. The `t3code/no-unreasoned-state-sync` lint rule reports every effect; one that stays states its reason with `// oxlint-disable-next-line t3code/no-unreasoned-state-sync -- <why>`.
 - Our users drive agents all day and notice a dropped frame, a lying spinner, and a stale label. No continuously repainting animations; they peg the GPU on high-refresh displays.
 - If a rule here fights the task in front of you, say so loudly and get a human sign-off before breaking it.
 

apps/mobile/src/App.tsx

@@ -195,6 +195,7 @@ disposeOnFoundationReplace(typeof module === "undefined" ? undefined : module.ho
 function SplashScreenCoordinator() {
   const { isReady } = useAppearancePreferences();
 
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- hides the native splash screen once appearance preferences have loaded
   useEffect(() => {
     if (isReady) void SplashScreen.hide();
   }, [isReady]);

apps/mobile/src/components/ComposerEditor.tsx

@@ -61,6 +61,7 @@ export function ComposerEditor({
     ? preferencesResult.value.composerEnterBehavior
     : undefined;
   const contextHistory = createComposerDraftContextHistory();
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- releases the attachment file leases held for native text undo when the history is replaced or unmounts
   useEffect(() => () => contextHistory.dispose(), [contextHistory]);
   const changeText = (text: string) => {
     const restored = contextHistory.restore(

apps/mobile/src/components/FilePreview.ios.tsx

@@ -34,6 +34,7 @@ function NativeFilePreview(props: {
     else Dialog.alert("Could not open preview", "The file could not be loaded. Please try again.");
   });
 
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- presents the native file preview and dismisses it on cleanup
   useEffect(() => {
     let canceled = false;
     const presentation =

apps/mobile/src/components/FilePreview.tsx

@@ -55,6 +55,7 @@ function DocumentPreview(props: {
         "A compatible viewer must be installed. Check your connection and try again.",
       );
   });
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- opens the attachment in an external viewer and aborts the open on cleanup
   useEffect(() => {
     const controller = new AbortController();
     const input = {

apps/mobile/src/components/FilePreviewModal.tsx

@@ -86,6 +86,7 @@ function ResolvedFilePreview(props: {
     props.onRequestClose();
   });
   // Resolves once per presentation and holds local file leases until it closes.
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- resolves preview files and holds their local file leases until the preview closes
   useEffect(() => {
     if (items.every((item) => "uri" in item)) return;
     const controller = new AbortController();

apps/mobile/src/components/MediaVideoPlayer.tsx

@@ -33,6 +33,7 @@ function LoadedMediaVideo(props: {
     useMediaVideoPlayback(player, props, playback);
   const previousPlaybackRequested = useRef(false);
   const onPlaybackStart = useEffectEvent(() => props.onPlaybackStart?.());
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- subscribes to native video player events to keep the shared audio session in step
   useEffect(() => {
     const subscription = player.addListener("playingChange", ({ isPlaying }) => {
       if (isPlaying && !active.current && !fullscreen.current) playback.pause();
@@ -74,6 +75,7 @@ function LoadedMediaVideo(props: {
     if (!signal.aborted && props.playRequested) await playIfUninterrupted();
   });
 
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- loads the video source into the native player and aborts the load on cleanup
   useEffect(() => {
     const controller = new AbortController();
     // oxlint-disable-next-line react/set-state-in-effect -- Starting a native media load publishes pending before its async result.

apps/mobile/src/components/ProjectFavicon.tsx

@@ -165,6 +165,7 @@ function ProjectFaviconImage(props: {
   );
   // Registers with the module-level loader before the Image's native onLoad/onError can fire,
   // so stale loads for a superseded URL under the same cacheKey are ignored.
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- marks this favicon URL as the current request in the module registry before the native Image reports load or error
   useLayoutEffect(() => {
     if (faviconRequest === null) return;
     return beginProjectFaviconRequest(faviconRequest);

apps/mobile/src/components/VideoPreviewModal.ios.tsx

@@ -65,6 +65,7 @@ function NativeVideoPreview(props: {
     }
   });
 
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- presents the native fullscreen video and owns its audio session and file lease until cleanup
   useEffect(() => {
     const controller = new AbortController();
     let token: ReturnType<typeof acquireAudioSession> | null = null;

apps/mobile/src/components/ui/Notice.tsx

@@ -16,6 +16,7 @@ export function Notice(props: {
   readonly dismissLabel?: string;
 }) {
   const danger = props.tone === "danger";
+  // oxlint-disable-next-line t3code/no-unreasoned-state-sync -- announces the message to VoiceOver through AccessibilityInfo
   useEffect(() => {
     // Live regions reach TalkBack; VoiceOver needs an explicit announcement.
     if (Platform.OS === "ios") AccessibilityInfo.announceForAccessibility(props.message);