chore: update docs

Author: riteshshukla04

docs/content/docs/concepts/runtime-functions.mdx

@@ -19,8 +19,8 @@ target runtime, called by stable id, with JSON-serialized arguments.
 ```tsx
 import { call, runtimeFunction } from '@react-native-runtimes/core';
 
-export const fibonacci = runtimeFunction((n: number) => {
-  return fib(n);
+export const fibonacci = runtimeFunction((n: number): number => {
+  return n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
 });
 
 const result = await call(fibonacci).on('worker-runtime')(38);
@@ -35,15 +35,17 @@ runtimes, or against different worker pools.
 async function refreshCache(key: string) {
   'background';
   await cacheStore.hydrate();
-  return cacheStore.get(key);
+  return cacheStore.getPathState(key);
 }
 
 const value = await refreshCache('settings');
 ```
 
-The first directive (`'background'`, `'main'`, or any runtime name) is the
-target. Metro rewrites the function into a registered runtime function plus a
-local scheduled alias, so call sites stay ordinary.
+The first directive (`'background'` or any other secondary runtime name) is
+the target. Metro rewrites the function into a registered runtime function
+plus a local scheduled alias, so call sites stay ordinary. Directives target
+**secondary** runtimes — to get data back to the main runtime, return a value
+or write to [shared state](/docs/shared-state/overview).
 
 <Callout type="info" title="Use the directive for fixed-runtime helpers">
   When a function semantically belongs to one runtime, the directive form
@@ -63,10 +65,12 @@ Code is never sent over the wire. Only **id + args**.
 ## Constraints
 
 - Arguments and return values must be JSON-serializable.
-- The function must be **exported** and wrapped in `runtimeFunction` *or* use a top-level directive.
-- Directive functions must be declared at module scope.
-- Closures aren't captured — pass everything through arguments.
-- Inline lambdas and non-exported functions are not supported.
+- `runtimeFunction(...)` values must be **exported** at module scope. Directive
+  functions only need to be declared at module scope — Metro exports the
+  generated registration for you.
+- Closures aren't captured — pass everything through arguments (module-scope
+  imports work, since every runtime loads the same bundle).
+- Inline lambdas are not supported.
 
 See [Scheduling functions on another runtime](/docs/threaded-runtime/scheduling-functions)
 for the full API.

docs/content/docs/concepts/runtimes.mdx

@@ -14,9 +14,10 @@ const RUNTIME_NAME = 'messages-runtime';
 ```
 
 When you ask for `messages-runtime` to render something, native spawns the
-runtime (if it doesn't already exist), executes the same bundle inside it,
-loads `.threaded-runtime/entry` to register components and functions, and then
-mounts a `ThreadedRuntimeHost` that renders the requested component.
+runtime (if it doesn't already exist) and executes the same bundle inside it.
+The bundle's `index.js` requires `.threaded-runtime/entry`, which registers
+components and functions, and native then mounts a `ThreadedRuntimeHost` that
+renders the requested component.
 
 ## Naming runtimes
 
@@ -59,7 +60,6 @@ A runtime can be implicitly started by any of these:
 - Mounting `<ThreadedScreen runtimeName="..." />` (auto-prewarms)
 - Calling `ThreadedRuntime.runHeadlessTask` with that runtime name
 - Calling `call(fn).on('...')(...)`
-- Native dispatch: `ThreadedRuntime.dispatchHeadlessTask`
 
 ## Cost
 
@@ -79,15 +79,19 @@ runtimes by their logical owner:
 
 ## Discovery
 
-Inside any threaded runtime, two globals describe where you are:
+Use `getCurrentRuntime()` to find out which runtime your code is running on:
 
 ```ts
-declare const __THREADED_RUNTIME_ENV__: {
-  kind: 'main' | 'threaded' | 'business';
-  runtimeName: string;
-};
+import { getCurrentRuntime, isMainRuntime } from '@react-native-runtimes/core';
+
+const { isMain, name, kind } = getCurrentRuntime();
+// main runtime:       { isMain: true,  name: 'main',             kind: null }
+// threaded runtime:   { isMain: false, name: 'messages-runtime', kind: 'threaded-runtime' }
+// business runtime:   { isMain: false, name: 'background',       kind: 'business-runtime' }
 ```
 
-This is how the per-runtime bootstrap mechanism works — the generated entry
-checks `runtimeName` and conditionally requires `index.<runtime>.ts`. See
+Under the hood, native sets a `__THREADED_RUNTIME_ENV__` global (with
+`runtimeName` and `kind`) in every secondary runtime before the bundle
+evaluates. The generated entry uses it to conditionally require
+`index.<runtime>.ts`. See
 [Metro setup](/docs/getting-started/metro-setup#per-runtime-bootstrap-files).

docs/content/docs/concepts/shared-state.mdx

@@ -60,10 +60,11 @@ Subscribers fire for **related paths**, not only exact matches:
 That makes broad subscriptions ("anything under conversations changed") cheap
 to express.
 
-<Callout title="One writer per path is the rule of thumb" type="info">
-  If two runtimes can both write to the same path, prefer `update(...)` or a
-  reducer — they read the current value through the lock and write back, so
-  concurrent updates compose instead of clobbering each other.
+<Callout title="One writer per path is the rule" type="warn">
+  Writes are last-writer-wins — there is no compare-and-swap. `update(...)`
+  reads the runtime's local mirror of the value, so two runtimes writing the
+  same path concurrently can still clobber each other. Design so each path has
+  a single writing runtime; other runtimes read and subscribe.
 </Callout>
 
 ## When to reach for it instead of props

docs/content/docs/concepts/threaded-components.mdx

@@ -28,9 +28,9 @@ main runtime                       messages-runtime
        (native view)                     (real component)
 ```
 
-The boundary is a native view, not a JS bridge. Props cross it once, then the
-threaded runtime owns rendering, scheduling, and re-rendering for that
-subtree.
+The boundary is a native view, not a JS bridge. Props cross it once at mount
+(changing them later remounts the surface), then the threaded runtime owns
+rendering, scheduling, and re-rendering for that subtree.
 
 ## Direct child rule
 
@@ -58,6 +58,10 @@ subtree.
 Metro needs a stable, file-based reference to register. It rewrites the direct
 child into an exported `const` and registers it under a stable id.
 
+Auto-registration only sees **function declarations in the same file** as the
+`<OnRuntime>` usage. For a component imported from another file, export it
+wrapped in `threadedComponent('name', Component)` instead.
+
 <Callout title="When the direct child rule feels restrictive" type="info">
   Use `threadedComponent` to give the component an explicit id, then put any
   wrapper you like *inside* that component. The registered component is the
@@ -66,8 +70,8 @@ child into an exported `const` and registers it under a stable id.
 
 ## Props cross the boundary as JSON
 
-Props are serialized at the main runtime and deserialized on the threaded
-runtime. They must be JSON-safe:
+Props are serialized at the main runtime when the surface mounts and
+deserialized on the threaded runtime. They must be JSON-safe:
 
 - ✅ Strings, numbers, booleans, `null`
 - ✅ Plain objects and arrays of the above

docs/content/docs/getting-started/android-setup.mdx

@@ -116,13 +116,12 @@ nativecompose::threadedruntime::dispatchHeadlessTask(
 );
 ```
 
-Native dispatch is queued — if the target runtime is still starting, the
-runtime flushes the task once it's ready. The returned status reflects whether
-the dispatch was accepted, not whether the JS body has finished.
+Dispatch is fire-and-forget: the task is queued, the runtime is started if
+needed, and queued tasks are flushed once the runtime is ready.
 
 ## Common issues
 
-<Callout type="warn" title="`Could not find Nitro module`">
+<Callout type="warn" title="`Cannot create an instance of HybridObject ... It has not yet been registered`">
   Add `NitroModulesPackage()` to `setExtraReactPackagesProvider` and make sure
   the package is also in your normal host packages (so the main runtime can
   use it too).

docs/content/docs/getting-started/installation.mdx

@@ -27,12 +27,17 @@ cd ios
 bundle exec pod install
 ```
 
-Configure the threaded runtime from the app delegate **before any secondary
-runtime is created**:
+Expose the `ThreadedRuntime` class to Swift through your bridging header
 
-```swift title="AppDelegate.swift"
-import NativeComposeThreadedRuntime
 
+```objc title="MyApp-Bridging-Header.h"
+#import <NativeComposeThreadedRuntime/ThreadedRuntime.h>
+```
+
+Then configure the threaded runtime from the app delegate **before any
+secondary runtime is created**:
+
+```swift title="AppDelegate.swift"
 ThreadedRuntime.configure(
   withReactNativeDelegate: delegate,
   launchOptions: launchOptions
@@ -121,11 +126,6 @@ const config = {};
 
 module.exports = withThreadedRuntime(
   mergeConfig(getDefaultConfig(__dirname), config),
-  {
-    roots: ['App.tsx', 'src'],
-    generatedDir: '.threaded-runtime',
-    generatedEntry: 'entry.js',
-  },
 );
 ```
 
@@ -135,23 +135,23 @@ Add the generated folder to `.gitignore`:
 .threaded-runtime/
 ```
 
-Load the generated entry only inside threaded runtimes:
+Load the generated entry at the top of `index.js`, in **every** runtime:
 
 ```js title="index.js"
-if (global.__THREADED_RUNTIME_ENV__ || global._is_it_a_list_env === true) {
-  require('./.threaded-runtime/entry');
-}
+require('./.threaded-runtime/entry');
 ```
 
-The generated entry registers lazy component loaders and the
-`ThreadedRuntimeHost` root used by native.
+The generated entry registers lazy component loaders, runtime functions, and
+the `ThreadedRuntimeHost` root used by native. It is safe on the main runtime
+(component requires stay lazy) and required there so the runtime-function
+registry exists for dispatching calls to secondary runtimes.
 
 <Callout type="info" title="Tip: per-runtime startup code">
   For startup code that should only run on a specific runtime, create a
   root-level file named `index.<runtime>.ts` — for example
-  `index.background.ts`. The generated entry emits a static conditional
-  require for it and matches `<runtime>` against
-  `global.__THREADED_RUNTIME_ENV__.kind` and `.runtimeName`.
+  `index.background.ts`. The generated entry requires it only when
+  `global.__THREADED_RUNTIME_ENV__.runtimeName` or `.kind` matches
+  `<runtime>`.
 </Callout>
 
 See [Metro setup](/docs/getting-started/metro-setup) for the full plugin
@@ -189,6 +189,6 @@ Rebuild the app. If you see the text, the runtime, the Metro plugin, and the
 native side are all wired up correctly.
 
 <Callout type="success" title="Next">
-  Read [Rendering components on a background runtime](/docs/threaded-runtime/render-components)
+  Read [Rendering components on a secondary runtime](/docs/threaded-runtime/render-components)
   to learn the full `OnRuntime` / `ThreadedScreen` / `threadedComponent` API.
 </Callout>

docs/content/docs/getting-started/ios-setup.mdx

@@ -27,34 +27,39 @@ If pod install fails with a Nitro-related error, ensure
 
 <Step>
 
+### Expose ThreadedRuntime to Swift
+
+Add the header to your bridging header (create one if the project doesn't
+have it yet). Don't `import NativeComposeThreadedRuntime` in Swift — it pulls
+Nitro's C++ umbrella into the Swift importer and can fail the build:
+
+```objc title="MyApp-Bridging-Header.h"
+#import <NativeComposeThreadedRuntime/ThreadedRuntime.h>
+```
+
+</Step>
+
+<Step>
+
 ### Configure the runtime from the app delegate
 
-Configure threading **before any secondary runtime is created** — typically
-the very first call in your delegate setup:
+Pass the React Native factory delegate to `configure` **before any secondary
+runtime is created** — right after the delegate is set up, before
+`startReactNative`:
 
 ```swift title="AppDelegate.swift"
-import NativeComposeThreadedRuntime
-
-@main
-class AppDelegate: RCTAppDelegate {
-  override func application(
-    _ application: UIApplication,
-    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
-  ) -> Bool {
-    ThreadedRuntime.configure(
-      withReactNativeDelegate: self,
-      launchOptions: launchOptions
-    )
-
-    // ... your existing setup
-    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
-  }
-}
+let delegate = ReactNativeDelegate()
+let factory = RCTReactNativeFactory(delegate: delegate)
+delegate.dependencyProvider = RCTAppDependencyProvider()
+
+// Add this line:
+ThreadedRuntime.configure(withReactNativeDelegate: delegate, launchOptions: launchOptions)
 ```
 
 <Callout type="warn" title="Order matters">
-  If you call `prewarmRuntime` before `configure`, the runtime cannot find the
-  React Native delegate and the prewarm will fail silently.
+  Creating a threaded runtime (including `prewarmRuntime`) before `configure`
+  crashes with `ThreadedRuntime.configureWithReactNativeDelegate must be
+  called before creating iOS threaded runtimes.`
 </Callout>
 
 </Step>
@@ -106,7 +111,6 @@ nativecompose::threadedruntime::prewarmRuntime(
 </Callout>
 
 <Callout type="warn" title="Threaded surfaces show up blank">
-  Confirm that your `index.js` loads `.threaded-runtime/entry` when
-  `global.__THREADED_RUNTIME_ENV__` is set — without it, the secondary runtime
-  has no components registered.
+  Confirm that your `index.js` requires `./.threaded-runtime/entry` — without
+  it, the secondary runtime has no components registered.
 </Callout>

docs/content/docs/getting-started/metro-setup.mdx

@@ -17,37 +17,31 @@ const config = {};
 
 module.exports = withThreadedRuntime(
   mergeConfig(getDefaultConfig(__dirname), config),
-  {
-    roots: ['App.tsx', 'src'],
-    generatedDir: '.threaded-runtime',
-    generatedEntry: 'entry.js',
-  },
 );
 ```
 
 ## Options
 
 | Option | Default | What it controls |
 | --- | --- | --- |
-| `roots` | `['App.tsx', 'src']` | Files and folders Metro scans for `OnRuntime`, `threadedComponent`, `runtimeFunction`, and directive functions. |
-| `generatedDir` | `.threaded-runtime` | Where the generated entry and the registration tables are written. Add this folder to `.gitignore`. |
+| `roots` | `['App.tsx', 'src']` | Files and folders scanned for `OnRuntime`, `threadedComponent`, `runtimeFunction`, and directive functions. |
+| `generatedDir` | `.threaded-runtime` | Where the generated entry is written. Add this folder to `.gitignore`. |
 | `generatedEntry` | `entry.js` | Filename of the generated entry inside `generatedDir`. |
+| `projectRoot` | Metro's `projectRoot` | Base directory for scanning and for generated ids. |
 
 ## Loading the generated entry
 
 The generated entry registers component loaders, runtime functions, and the
-`ThreadedRuntimeHost` root. It must be loaded **only inside secondary
-runtimes**, never on the main runtime:
+`ThreadedRuntimeHost` root. Require it at the top of `index.js` so it runs in
+**every** runtime:
 
 ```js title="index.js"
-if (global.__THREADED_RUNTIME_ENV__ || global._is_it_a_list_env === true) {
-  require('./.threaded-runtime/entry');
-}
+require('./.threaded-runtime/entry');
 ```
 
-The two globals exist for backwards compatibility — both indicate the bundle
-is being evaluated in a secondary runtime. New code should rely on
-`__THREADED_RUNTIME_ENV__`.
+Component registrations are lazy (`() => require(...)`), so this adds nothing
+to main-runtime startup. Loading it on main is required for the JSI function
+dispatch mechanism, which enables calling functions on secondary runtimes.
 
 ## .gitignore
 
@@ -66,12 +60,12 @@ root-level file with the runtime's name:
 index.background.ts
 ```
 
-The Metro plugin discovers files matching `index.<runtime>.ts(x)` in the
-project root and emits a static conditional require. When native starts a
-runtime named `background`, the generated entry loads `index.background.ts`
-inside that runtime only.
+The Metro plugin discovers files matching `index.<runtime>.ts` in the project
+root and emits a static conditional require. The generated entry loads
+`index.background.ts` only inside runtimes whose **name or kind** is
+`background`.
 
-```tsx title="index.background.ts"
+```ts title="index.background.ts"
 import { registerThreadedHeadlessTask } from '@react-native-runtimes/core';
 import { business } from './src/businessStore';
 
@@ -80,6 +74,7 @@ registerThreadedHeadlessTask<{ reason: string }>(
   async ({ payload }) => {
     await business.hydrate();
     await business.update(state => ({
+      ...state,
       lastRefreshReason: payload.reason,
       refreshCount: state.refreshCount + 1,
     }));
@@ -108,11 +103,6 @@ index.sync-engine.ts
 
 ## Troubleshooting
 
-<Callout type="warn" title="Metro picks up the generated entry on the main runtime">
-  Double-check the `if (global.__THREADED_RUNTIME_ENV__ ...)` guard in your
-  `index.js`. The generated entry is large and should never load on main.
-</Callout>
-
 <Callout type="warn" title="A threaded component isn't being registered">
   Add its file to `roots` or place it under one of the existing roots. Files
   outside the configured roots are invisible to the plugin.