feat: support React 19 Activity API (#289)

Adds `inactiveBehavior` option to `@lifecycleBound` to control what
happens to a graph when its host component is hidden inside a React 19
`<Activity>` tree. Also fixes `useObservable` hooks so they re-apply
when the component is unpaused.

- New `inactiveBehavior: 'unmount' | 'retain'` option on
`@lifecycleBound` (default: `'retain'`)
- When `retain`, a sentinel DOM node detects whether the cleanup effect
fired due to an Activity pause vs a real unmount — skipping graph
teardown in the former case
- When `unmount`, the graph is cleared on every unmount as before
- `useObservable` hooks are now re-applied when a component resumes from
an Activity pause (previously observers were not re-registered after
unpause)
- Bump `react`/`react-dom` devDependencies to 19.2.4 (Activity API;
consumer peerDep range `>=16.8.0` unchanged)
- Document the new option in Graphs.mdx

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: guyca <12352397+guyca@users.noreply.github.com>

Author: guyca

AGENTS.md

@@ -0,0 +1,2 @@
+## Target platforms
+This library targets both web bundlers (webpack/vite) and React Native (Metro/Hermes).

packages/documentation/docs/documentation/usage/Graphs.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-tags: [Graph, Lifecycle-bound]
+tags: [Graph, Lifecycle-bound, Inactive-behavior]
 ---
 
 import Tabs from '@theme/Tabs';
@@ -175,6 +175,28 @@ class HomeGraph extends ObjectGraph<HomeScreenProps> {
 #### The lifecycle of a lifecycle-bound graph
 Lifecycle-bound graphs are created when they are requested and are destroyed when the last component or hook that requested them is unmounted. This means that the dependencies provided by a lifecycle-bound graph are shared between components and hooks within the same UI scope and are destroyed when the UI scope is destroyed.
 
+#### Inactive behavior
+By default, lifecycle-bound graphs are retained during transient `useEffect` cleanups — such as React Native activity pauses or React StrictMode remounts — and only cleared when the component is actually removed from the tree. This prevents the graph from being destroyed and recreated unnecessarily.
+
+Setting `inactiveBehavior` to `'unmount'` reverts to eager cleanup, where the graph is cleared on every `useEffect` cleanup regardless of whether the component has truly unmounted.
+
+```ts title="A lifecycle-bound graph with eager cleanup"
+import {lifecycleBound, graph, ObjectGraph, provides} from 'react-obsidian';
+
+@lifecycleBound({ inactiveBehavior: 'unmount' }) @graph()
+class AuthGraph extends ObjectGraph {
+  @provides()
+  userService(): UserService {
+    return new UserService();
+  }
+}
+```
+
+| Value | Behavior |
+|-------|----------|
+| `'retain'` (default) | Graph retained during transient cleanups; cleared only on real unmount |
+| `'unmount'` | Graph cleared on every `useEffect` cleanup |
+
 ## Graph composition
 Graph composition is a powerful feature that allows you to create complex dependency graphs by combining smaller graphs. Composing graphs is useful when you want to reuse a graph in multiple places. For example, you might have a singleton graph that provides application-level dependencies. You might also have a lifecycle-bound graph that provides dependencies for a specific UI flow. You can compose these graphs together so that the lifecycle-bound graph can also inject the dependencies provided by the singleton graph.
 

packages/eslint-plugin-obsidian/package.json

@@ -2,7 +2,7 @@
   "name": "eslint-plugin-obsidian",
   "description": "ESLint rules for Obsidian",
   "main": "dist/index.js",
-  "version": "2.30.0",
+  "version": "2.31.0-alpha.8",
   "scripts": {
     "build": "npx tsc --project tsconfig.prod.json",
     "test": "npx jest --colors",
@@ -25,7 +25,7 @@
   "dependencies": {
     "lodash": "^4.17.21",
     "ts-morph": "^25.0.1",
-    "ts-morph-extensions": "^2.30.0"
+    "ts-morph-extensions": "^2.31.0-alpha.8"
   },
   "devDependencies": {
     "@babel/core": "7.26.10",

packages/react-obsidian/global.d.ts

@@ -1 +1,3 @@
 import 'jest-extended';
+import '@testing-library/jest-dom';
+

packages/react-obsidian/jest.setup-after-env.js

@@ -1,3 +1,4 @@
 require('setimmediate');
 require('./clearGraphs');
+require('@testing-library/jest-dom');
 

packages/react-obsidian/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-obsidian",
-  "version": "2.30.0",
+  "version": "2.31.0-alpha.8",
   "description": "Dependency injection framework for React and React Native applications",
   "scripts": {
     "prepack": "yarn lint && tsc --project tsconfig.prod.json",
@@ -39,13 +39,15 @@
     "@babel/preset-typescript": "7.26.0",
     "@babel/types": "7.24.5",
     "@stylistic/eslint-plugin": "^1.7.0",
-    "@testing-library/react": "14.x.x",
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.x.x",
     "@types/hoist-non-react-statics": "^3.3.1",
     "@types/jest": "^30.0.0",
     "@types/jest-when": "^3.5.5",
     "@types/lodash": "^4.14.176",
-    "@types/react": "18.3.x",
-    "@types/react-dom": "18.3.x",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "babel-plugin-parameter-decorator": "1.x.x",
@@ -65,8 +67,8 @@
     "jest-mock-extended": "^3.0.7",
     "jest-when": "^3.7.0",
     "lodash": "^4.17.21",
-    "react": "18.2.x",
-    "react-dom": "18.2.x",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
     "setimmediate": "^1.0.5",
     "typescript": "^5.7.3"
   },

packages/react-obsidian/src/decorators/LifecycleBound.ts

@@ -2,12 +2,14 @@ import {Reflect} from '../utils/reflect';
 
 type Options = {
   scope?: 'component' | 'feature' | (string & {});
+  inactiveBehavior?: 'unmount' | 'retain';
 };
 
 export function lifecycleBound(options?: Options) {
   return (constructor: any) => {
     Reflect.defineMetadata('isLifecycleBound', true, constructor);
     Reflect.defineMetadata('lifecycleScope', options?.scope ?? 'feature', constructor);
+    Reflect.defineMetadata('inactiveBehavior', options?.inactiveBehavior ?? 'retain', constructor);
     return constructor;
   };
 }

packages/react-obsidian/src/graph/ObjectGraph.ts

@@ -10,6 +10,10 @@ import { getConstructorOrParentConstructor } from '../utils/object';
 export abstract class ObjectGraph<T = unknown> implements Graph {
   private propertyRetriever = new PropertyRetriever(this);
 
+  get inactiveBehavior(): 'unmount' | 'retain' {
+    return Reflect.getMetadata('inactiveBehavior', this.constructor) ?? 'unmount';
+  }
+
   get name(): string {
     const target = getConstructorOrParentConstructor(this.constructor, ObjectGraph.name);
     if (Reflect.hasMetadata('memoizedName', target)) {

packages/react-obsidian/src/injectors/components/ComponentInjector.tsx

@@ -1,8 +1,9 @@
-import React, { PropsWithChildren } from 'react';
+import React, { PropsWithChildren, useRef } from 'react';
 import hoistNonReactStatics from 'hoist-non-react-statics';
 import { ObjectGraph } from '../../graph/ObjectGraph';
 import PropsInjector from './PropsInjector';
 import useGraph from './useGraph';
+import Sentinel from './Sentinel';
 import { Constructable } from '../../types';
 import { genericMemo, isMemoizedComponent } from '../../utils/React';
 import { GraphContext } from './graphContext';
@@ -14,7 +15,7 @@ export default class ComponentInjector {
     keyOrGraph: string | Constructable<ObjectGraph>,
   ): React.FunctionComponent<Partial<P>> {
     const Wrapped = this.wrapComponent(Target, keyOrGraph);
-    hoistNonReactStatics(Wrapped, Target);
+    hoistNonReactStatics(Wrapped as any, Target as any);
     return Wrapped;
   }
 
@@ -28,12 +29,14 @@ export default class ComponentInjector {
 
     return genericMemo((passedProps: P) => {
       const injectionToken = useInjectionToken(keyOrGraph);
-      const graph = useGraph<P>(keyOrGraph, Target, passedProps, injectionToken);
+      const containerRef = useRef(null);
+      const graph = useGraph<P>(keyOrGraph, Target, passedProps, injectionToken, containerRef);
       const proxiedProps = new PropsInjector(graph).inject(passedProps);
 
       return (
         <GraphContext.Provider value={{injectionToken}}>
-          {Target(proxiedProps as unknown as PropsWithChildren<P>)}
+          {graph.inactiveBehavior === 'retain' && <Sentinel ref={containerRef} />}
+          {Target(proxiedProps as unknown as PropsWithChildren<P>) as React.ReactNode}
         </GraphContext.Provider>
       );
     }, compare);

packages/react-obsidian/src/injectors/components/Sentinel.native.tsx

@@ -0,0 +1,12 @@
+import React, { forwardRef } from 'react';
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports, global-require
+const { View } = require('react-native');
+
+const style = { position: 'absolute' as const, width: 0, height: 0, overflow: 'hidden' as const };
+
+const Sentinel = forwardRef<any>((_, ref) => (
+  <View ref={ref} collapsable={false} style={style} />
+));
+
+export default Sentinel;