fix(mobile): Stabilize native stack option updates

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@

apps/mobile/src/native/StackHeader.tsx

@@ -11,6 +11,7 @@ import {
  useEffect,
  useLayoutEffect,
  useMemo,
+ useRef,
  type ReactElement,
  type ReactNode,
 } from "react";
@@ -61,20 +62,116 @@ function normalizeScreenOptions(
  return normalized as NativeStackNavigationOptions;
 }
 
+function optionsSignature(value: unknown, seen = new WeakSet<object>()): string {
+ if (value === null) return "null";
+ switch (typeof value) {
+ case "boolean":
+ case "number":
+ case "string":
+ return JSON.stringify(value);
+ case "undefined":
+ return "undefined";
+ case "function":
+ // Header factories are frequently recreated inline. Their source is
+ // stable across equivalent renders, while a reference comparison would
+ // make navigation.setOptions re-enter the navigator indefinitely.
+ return `function:${Function.prototype.toString.call(value)}`;
+ case "symbol":
+ return `symbol:${String(value)}`;
+ case "bigint":
+ return `bigint:${String(value)}`;
+ case "object": {
+ const object = value as object;
+ if (seen.has(object)) return "[circular]";
+ seen.add(object);
+ if (Array.isArray(value)) {
+ return `[${value.map((entry) => optionsSignature(entry, seen)).join(",")}]`;
+ }
+ // React refs carry mutable native instances that must not make static
+ // screen options appear different after every render.
+ if ("current" in object) return "[ref]";
+ return `{${Object.keys(value as Record<string, unknown>)
+ .sort()
+ .map(
+ (key) =>
+ `${JSON.stringify(key)}:${optionsSignature((value as Record<string, unknown>)[key], seen)}`,
+ )
+ .join(",")}}`;
+ }
+ }
+ return String(value);
+}
+
+function stabilizeOptionFunctions(
+ value: unknown,
+ path: string,
+ latestFunctions: Map<string, (...args: unknown[]) => unknown>,
+ wrappers: Map<string, (...args: unknown[]) => unknown>,
+ seen = new WeakSet<object>(),
+): unknown {
+ if (typeof value === "function") {
+ latestFunctions.set(path, value as (...args: unknown[]) => unknown);
+ let wrapper = wrappers.get(path);
+ if (!wrapper) {
+ wrapper = (...args: unknown[]) => {
+ return latestFunctions.get(path)?.(...args);
+ };
+ wrappers.set(path, wrapper);
+ }
+ return wrapper;
+ }
+ if (Array.isArray(value)) {
+ if (seen.has(value)) return value;
+ seen.add(value);
+ return value.map((entry, index) =>
+ stabilizeOptionFunctions(entry, `${path}[${index}]`, latestFunctions, wrappers, seen),
+ );
+ }
+ if (value !== null && typeof value === "object") {
+ if (seen.has(value) || "current" in value) return value;
+ seen.add(value);
+ return Object.fromEntries(
+ Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+ key,
+ stabilizeOptionFunctions(entry, `${path}.${key}`, latestFunctions, wrappers, seen),
+ ]),
+ );
+ }
+ return value;
+}
+
 export function NativeStackScreenOptions(props: {
  readonly options?: AppNativeStackNavigationOptions;
  readonly listeners?: Record<string, (event: never) => void>;
  readonly name?: string;
 }) {
  const navigation = useNativeStackNavigation();
+ const lastAppliedOptionsSignatureRef = useRef<string | undefined>(undefined);
+ const latestOptionFunctionsRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
+ const optionFunctionWrappersRef = useRef(new Map<string, (...args: unknown[]) => unknown>());
  const normalizedOptions = useMemo(() => normalizeScreenOptions(props.options), [props.options]);
+ const stableOptions = normalizedOptions
+ ? (stabilizeOptionFunctions(
+ normalizedOptions,
+ "options",
+ latestOptionFunctionsRef.current,
+ optionFunctionWrappersRef.current,
+ ) as NativeStackNavigationOptions)
+ : undefined;
 
  useLayoutEffect(() => {
- if (!navigation || !normalizedOptions) {
+ if (!navigation || !stableOptions) {
+ return;
+ }
+ const signature = optionsSignature(stableOptions);
+ // Avoid re-entering navigation state when semantically equal options are
+ // reapplied every layout (common when callers pass unstable object literals).
+ if (lastAppliedOptionsSignatureRef.current === signature) {
  return;
  }
- navigation.setOptions(normalizedOptions);
- }, [navigation, normalizedOptions]);
+ lastAppliedOptionsSignatureRef.current = signature;
+ navigation.setOptions(stableOptions);
+ }, [navigation, stableOptions]);
 
  useEffect(() => {
  if (!navigation || !props.listeners) {

patches/@react-navigation%2Fnative-stack@7.17.6.patch

@@ -1,3 +1,5 @@
+diff --git a/lib/module/views/useHeaderConfigProps.js b/lib/module/views/useHeaderConfigProps.js
+index 0b75c70b4e0d233ee3b5faaf9cfbc40d4f8ed494..eb174e3fde91a7783f132b3fb16b01175ec19220 100644
 --- a/lib/module/views/useHeaderConfigProps.js
 +++ b/lib/module/views/useHeaderConfigProps.js
 @@ -19,6 +19,12 @@