update docs for accuracy

Author: LadyBluenotes

src/routes/reference/component-apis/children.mdx

@@ -24,8 +24,11 @@ import { children } from "solid-js";
 ## Type
 
 ```ts
-function children(fn: Accessor<JSX.Element>): Accessor<JSX.Element> & {
-	toArray: () => JSX.Element[];
+type ResolvedJSXElement = Exclude<JSX.Element, JSX.ArrayElement>;
+type ResolvedChildren = ResolvedJSXElement | ResolvedJSXElement[];
+
+function children(fn: Accessor<JSX.Element>): Accessor<ResolvedChildren> & {
+	toArray: () => ResolvedJSXElement[];
 };
 ```
 
@@ -40,15 +43,15 @@ Accessor that returns the component's `children` value.
 
 ## Return value
 
-- **Type:** `Accessor<JSX.Element> & { toArray: () => JSX.Element[] }`
+- **Type:** `Accessor<ResolvedChildren> & { toArray: () => ResolvedJSXElement[] }`
 
 Returns an accessor for the resolved children.
 The accessor also exposes `toArray()`.
 
 ## Behavior
 
 - The returned accessor memoizes the resolved children, so repeated reads use the resolved result instead of recreating the child structure.
-- `children` resolves functions, arrays, fragments, and nested child structures from `props.children`.
+- `children` resolves nested arrays, fragments, and zero-argument child accessors from `props.children`.
 - `toArray()` returns the resolved children as an array. It returns `[]` when the resolved value is `null` or `undefined`.
 
 ## Examples

src/routes/reference/lifecycle/on-cleanup.mdx

@@ -51,6 +51,7 @@ Returns `fn` unchanged.
 - In a component, the cleanup runs when that component is unmounted.
 - In a tracking scope such as [`createEffect`](/reference/basic-reactivity/create-effect), [`createMemo`](/reference/basic-reactivity/create-memo), or [`createRoot`](/reference/reactive-utilities/create-root), the cleanup runs when that scope is disposed or re-executes.
 - Multiple cleanup functions run when the owning scope is cleaned up.
+- Calling `onCleanup` outside a reactive owner does not register a cleanup. In development, Solid warns that the cleanup will never run.
 - On the server, cleanup also runs when server-side owners or reactive branches are disposed.
 
 ## Examples

src/routes/reference/lifecycle/on-mount.mdx

@@ -49,6 +49,7 @@ Non-tracking function executed once on mount.
 - `fn` does not track reactive dependencies.
 - Internally, `onMount(fn)` is equivalent to `createEffect(() => untrack(fn))`.
 - By the time `onMount` runs, refs have already been assigned.
+- Returning a function from `fn` does not register cleanup. Use [`onCleanup`](/reference/lifecycle/on-cleanup) inside `onMount` when cleanup is needed.
 
 ## Examples
 

src/routes/reference/secondary-primitives/create-deferred.mdx

@@ -78,6 +78,7 @@ Returns an accessor that exposes the deferred value.
 - The deferred accessor initially reflects the current source value.
 - Later updates are deferred through Solid's scheduler until later execution or until `timeoutMs` is reached, so the returned accessor can lag behind the source accessor.
 - `equals` controls whether downstream dependents are notified for a new value.
+- `createDeferred` defers propagation of the accessor value. It does not debounce writes to the source accessor.
 - On the server, `createDeferred` returns the source accessor unchanged.
 
 ## Examples

src/routes/reference/secondary-primitives/create-render-effect.mdx

@@ -12,12 +12,11 @@ tags:
   - lifecycle
 version: "1.0"
 description: >-
-  Execute effects immediately during rendering with createRenderEffect. Run side
-  effects as DOM creates, before refs are set or connected.
+  Create a reactive computation that runs immediately during the render phase.
 ---
 
-The `createRenderEffect` primitive creates a reactive computation that automatically tracks reactive values, such as [signals](/concepts/signals), accessed within the provided function.
-This function re-runs whenever any of its dependencies change.
+`createRenderEffect` creates a reactive computation that runs during the render phase as DOM is created and updated.
+It tracks reactive reads inside the provided function and re-runs whenever those dependencies change.
 
 ## Execution Timing
 
@@ -30,15 +29,12 @@ This function re-runs whenever any of its dependencies change.
 ### Subsequent Runs
 
 - After the initial render, the render effect **re-runs whenever any of its tracked dependencies change**.
-- Re-runs occur **after** all pure computations (such as [memos](/concepts/derived-values/memos)) have completed within the same update cycle.
 - When multiple dependencies change within the same batch, the render effect **runs once per batch**.
-- The **order of re-runs** among multiple render effects is **not guaranteed**.
 
 ### Server-Side Rendering
 
 - During SSR, render effects **run once on the server**, since they are part of the synchronous rendering phase.
-- On the client, an initial run still occurs during the client rendering phase to initialize the reactive system;
-  that client initial run is separate from the server run.
+- On the client, an initial run still occurs during the client rendering phase.
 - After hydration, subsequent runs occur on the client when dependencies change.
 
 ## Import
@@ -69,7 +65,7 @@ function createRenderEffect<Next, Init>(
 
 ### `fn`
 
-- **Type:** `EffectFunction<undefined | NoInfer<Next> | EffectFunction<Init | Next, Next>`
+- **Type:** `EffectFunction<undefined | NoInfer<Next>, Next> | EffectFunction<Init | Next, Next>`
 - **Required:** Yes
 
 A function to be executed as the render effect.
@@ -102,69 +98,33 @@ A name for the render effect, which can be useful for identification in debuggin
 
 `createRenderEffect` does not return a value.
 
-## Examples
-
-### Basic Usage
-
-```tsx
-import { createSignal, createRenderEffect } from "solid-js";
+## Behavior
 
-function Counter() {
-	const [count, setCount] = createSignal(0);
+- `createRenderEffect` runs immediately when it is created.
+- Its initial run happens during the render phase, before mounted DOM is connected and before refs are assigned.
+- Later runs happen when tracked dependencies change.
+- Most application code should use [`createEffect`](/reference/basic-reactivity/create-effect). `createRenderEffect` is mainly for render-phase work where that timing is required.
 
-	// This runs immediately during render, and re-runs when the count changes.
-	createRenderEffect(() => {
-		console.log("Count: ", count());
-	});
-
-	return (
-		<div>
-			<p>Count: {count()}</p>
-			<button onClick={() => setCount((prev) => prev + 1)}>Increment</button>
-		</div>
-	);
-}
-```
+## Examples
 
-### Execution Timing
+### Ref timing
 
 ```tsx
-import { createSignal, createEffect, createRenderEffect } from "solid-js";
-
-function Counter() {
-	const [count, setCount] = createSignal(0);
-
-	// This is part of the component's synchronous execution.
-	console.log("Hello from counter");
+import { createRenderEffect, onMount } from "solid-js";
 
-	// This effect is scheduled to run after the initial render is complete.
-	createEffect(() => {
-		console.log("Effect:", count());
-	});
+function Example() {
+	let element: HTMLDivElement | undefined;
 
-	// By contrast, a render effect runs synchronously during the render phase.
 	createRenderEffect(() => {
-		console.log("Render effect:", count());
+		console.log("render effect", element); // undefined on the initial run
 	});
 
-	// Setting a signal during the render phase re-runs render effects, but not effects, which are
-	// still scheduled.
-	setCount(1);
-
-	// A microtask is scheduled to run after the current synchronous code (the render phase) finishes.
-	queueMicrotask(() => {
-		// Now that rendering is complete, signal updates will trigger effects immediately.
-		setCount(2);
+	onMount(() => {
+		console.log("mounted", element); // <div>
 	});
-}
 
-// Output:
-// Hello from counter
-// Render effect: 0
-// Render effect: 1
-// Effect: 1
-// Render effect: 2
-// Effect: 2
+	return <div ref={element}>Hello</div>;
+}
 ```
 
 ## Related