From 30ba3ded453cef91f3cfa4c4c760ec58fa31f683 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 12:11:24 -0700
Subject: [PATCH 01/88] docs: enhance documentation for batch, onCleanup,
 onMount, and untrack

---
 src/routes/reference/lifecycle/on-cleanup.mdx | 72 ++++++++++++++---
 src/routes/reference/lifecycle/on-mount.mdx   | 58 ++++++++++++--
 .../reference/reactive-utilities/batch.mdx    | 78 ++++++++++++-------
 .../reference/reactive-utilities/untrack.mdx  | 74 ++++++++++++++++--
 4 files changed, 232 insertions(+), 50 deletions(-)

diff --git a/src/routes/reference/lifecycle/on-cleanup.mdx b/src/routes/reference/lifecycle/on-cleanup.mdx
index f2963120e..e8ae07337 100644
--- a/src/routes/reference/lifecycle/on-cleanup.mdx
+++ b/src/routes/reference/lifecycle/on-cleanup.mdx
@@ -16,34 +16,56 @@ description: >-
   components unmount or tracking scopes dispose. Essential for proper cleanup.
 ---
 
-`onCleanup` registers a cleanup method that executes on disposal and recalculation of the current tracking scope.
-Can be used anywhere to clean up any side effects left behind by initialization.
+`onCleanup` registers a cleanup function on the current reactive scope.
+The cleanup runs when that scope is disposed or refreshed.
 
-When used in a Component, it runs when the component is unmounted.
-When used in tracking scope, such [`createEffect`](/reference/basic-reactivity/create-effect), [`createMemo`](/reference/basic-reactivity/create-memo) or a [`createRoot`](/reference/reactive-utilities/create-root), it runs when the tracking scope is disposed or refreshed.
+## Import
 
 ```ts
 import { onCleanup } from "solid-js";
+```
+
+## Type
 
-function onCleanup(fn: () => void): void;
+```ts
+function onCleanup<T extends () => any>(fn: T): T;
 ```
 
-Without the `onCleanup` function, the event listener would remain attached to the `document` even after the component is removed from the page.
-This can cause memory leaks and other issues.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => any`
+- **Required:** Yes
+
+Cleanup function registered on the current reactive scope.
+
+## Return value
+
+- **Type:** `T`
+
+Returns the same function that was passed in.
+
+## Behavior
+
+- 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.
+- On the server, cleanup also runs when server-side reactive branches are disposed.
+
+## Examples
+
+### Remove an event listener
 
 ```tsx
 import { createSignal, onCleanup } from "solid-js";
 
 const Component = () => {
 	const [count, setCount] = createSignal(0);
-
 	const handleClick = () => setCount((value) => value + 1);
 
 	document.addEventListener("click", handleClick);
 
-	/**
-	 * Remove the event listener when the component is removed/unmounted from the page.
-	 */
 	onCleanup(() => {
 		document.removeEventListener("click", handleClick);
 	});
@@ -51,3 +73,31 @@ const Component = () => {
 	return <main>Document has been clicked {count()} times</main>;
 };
 ```
+
+### Clean up before an effect re-runs
+
+```tsx
+import { createEffect, createSignal, onCleanup } from "solid-js";
+
+function Example() {
+	const [topic, setTopic] = createSignal("news");
+
+	createEffect(() => {
+		const currentTopic = topic();
+
+		console.log("subscribing to", currentTopic);
+
+		onCleanup(() => {
+			console.log("cleaning up", currentTopic);
+		});
+	});
+
+	return <button onClick={() => setTopic("sports")}>Change topic</button>;
+}
+```
+
+## Related
+
+- [`onMount`](/reference/lifecycle/on-mount)
+- [`createEffect`](/reference/basic-reactivity/create-effect)
+- [`createRoot`](/reference/reactive-utilities/create-root)
diff --git a/src/routes/reference/lifecycle/on-mount.mdx b/src/routes/reference/lifecycle/on-mount.mdx
index eac027ec4..ce3f27ef9 100644
--- a/src/routes/reference/lifecycle/on-mount.mdx
+++ b/src/routes/reference/lifecycle/on-mount.mdx
@@ -16,28 +16,74 @@ description: >-
   refs, setting up third-party libraries, and one-time initializations.
 ---
 
-Registers a method that runs after initial rendering is done and the elements are mounted to the page.
-Ideal for using [refs](/reference/jsx-attributes/ref) and managing other one-time setup.
+`onMount` registers a function that runs once after the initial render for the current component or root.
 
-```tsx
+## Import
+
+```ts
 import { onMount } from "solid-js";
+```
+
+## Type
 
+```ts
 function onMount(fn: () => void): void;
 ```
 
-This is an alias for an effect that is non-tracking, meaning that it is equivalent to a [`createEffect`](/reference/basic-reactivity/create-effect) with no dependencies.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => void`
+- **Required:** Yes
+
+Function executed once on mount.
+
+## Return value
+
+`onMount` does not return a value.
+
+## Behavior
+
+- Runs once after the initial render.
+- Does not track reactive dependencies inside `fn`.
+- Internally, `onMount(fn)` is equivalent to `createEffect(() => untrack(fn))`.
+- Runs after refs have been assigned.
+
+## Examples
+
+### Access a ref after mount
 
 ```tsx
-// example that shows how to use onMount to get a reference to an element
 import { onMount } from "solid-js";
 
 function MyComponent() {
 	let ref: HTMLButtonElement;
 
-	// when the component is mounted, the button will be disabled
 	onMount(() => {
 		ref.disabled = true;
 	});
+
 	return <button ref={ref}>Focus me!</button>;
 }
 ```
+
+### Run one-time browser setup
+
+```tsx
+import { onMount } from "solid-js";
+
+function Example() {
+	onMount(() => {
+		console.log(window.location.pathname);
+	});
+
+	return <div>Mounted</div>;
+}
+```
+
+## Related
+
+- [`onCleanup`](/reference/lifecycle/on-cleanup)
+- [`createEffect`](/reference/basic-reactivity/create-effect)
+- [`untrack`](/reference/reactive-utilities/untrack)
diff --git a/src/routes/reference/reactive-utilities/batch.mdx b/src/routes/reference/reactive-utilities/batch.mdx
index 4642408f8..4c3eeae72 100644
--- a/src/routes/reference/reactive-utilities/batch.mdx
+++ b/src/routes/reference/reactive-utilities/batch.mdx
@@ -15,30 +15,66 @@ description: >-
   recalculations. Essential for optimizing complex state changes.
 ---
 
+`batch` groups multiple reactive updates so downstream computations run once after the batch completes instead of after each individual update.
+
+## Import
+
 ```ts
 import { batch } from "solid-js";
+```
 
+## Type
+
+```ts
 function batch<T>(fn: () => T): T;
 ```
 
-`batch` is a low-level API that batches updates together.
-More precisely, `batch(fn)` holds the execution of downstream computations during the `fn` block, executing them all together once the block `fn` returns.
-Thus, instead of a downstream computation executing after every dependency update, it will update just once at the end of the batch.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => T`
+- **Required:** Yes
+
+Function executed inside the batch.
+
+## Return value
+
+- **Type:** `T`
+
+Returns the value produced by `fn`.
+
+## Behavior
 
-Batching improves performance by avoiding unnecessary recalculation.
-Suppose you have a downstream memo `down` that depends on multiple upstream signals `up1`, `up2`, and `up3`:
+- Downstream computations are deferred until the batch completes.
+- Nested `batch` calls behave like a single larger batch.
+- If you read a stale memo or signal inside the batch, Solid updates it on demand before returning the value.
+- If `fn` is asynchronous, only the updates before the first `await` are batched.
+
+## Automatic batching
+
+Solid automatically batches updates in several cases, including:
+
+- inside [`createEffect`](/reference/basic-reactivity/create-effect) and [`onMount`](/reference/lifecycle/on-mount)
+- inside the setter returned by [`createStore`](/reference/store-utilities/create-store)
+- inside array mutation methods on [`createMutable`](/reference/store-utilities/create-mutable)
+
+## Examples
+
+### Batch multiple signal updates
 
 ```ts
-import { createSignal, createMemo, createEffect } from "solid-js";
+import { batch, createEffect, createMemo, createSignal } from "solid-js";
+
 const [up1, setUp1] = createSignal(1);
 const [up2, setUp2] = createSignal(2);
 const [up3, setUp3] = createSignal(3);
+
 const down = createMemo(() => up1() + up2() + up3());
-// For illustration, monitor when `down` gets recomputed:
 createEffect(() => console.log(down())); // outputs 6
 ```
 
-If you directly update all of the upstream signals outside of batch mode, then `down` will recompute every time.
+Without `batch`, each setter can trigger downstream work:
 
 ```ts
 setUp1(4); // recomputes down, outputs 9
@@ -46,7 +82,7 @@ setUp2(5); // recomputes down, outputs 12
 setUp3(6); // recomputes down, outputs 15
 ```
 
-If instead you update the upstream signals within a `batch`, then `down` will update only once at the end:
+With `batch`, the memo recomputes once at the end:
 
 ```ts
 batch(() => {
@@ -56,21 +92,7 @@ batch(() => {
 }); // recomputes down, outputs 30
 ```
 
-The impact is even more dramatic if you have _m_ downstream computations (memos, effects, etc.) that each depends on _n_ upstream signals.
-Without batching, modifying all _n_ upstream signals would cause _m n_ updates to the downstream computations.
-With batching, modifying all _n_ upstream signals would cause _m_ updates to the downstream computations.
-Given that each update takes at least _n_ time (just to read the upstream signals), this cost savings can be significant.
-Batching is also especially helpful when the downstream effects include DOM updates, which can be expensive.
-
-Solid uses `batch` internally to automatically batch updates for you in a few cases:
-
-- Within [`createEffect`](/reference/basic-reactivity/create-effect) and [`onMount`](/reference/lifecycle/on-mount) (unless they are outside a [root](/reference/reactive-utilities/create-root))
-- Within the [setter of a store](/reference/store-utilities/create-store#setter) (which can update several properties at once)
-- Within array methods (e.g. `Array.prototype.splice`) of a [mutable store](/reference/store-utilities/create-mutable) (which can update several elements at once)
-
-These save you from having to use `batch` yourself in many cases.
-For the most part, automatic batching should be transparent to you, because accessing a signal or memo will cause it to update if it is out of date (as of Solid 1.4).
-For example:
+### Read a memo inside a batch
 
 ```ts
 batch(() => {
@@ -84,6 +106,8 @@ batch(() => {
 }); // recomputes down, outputs 36
 ```
 
-You can think of `batch(fn)` as setting a global "batch mode" variable, calling the function `fn`, and then restoring the global variable to its previous value.
-This means that you can nest `batch` calls, and they will form one big batch.
-It also means that, if `fn` is asynchronous, only the updates before the first `await` will be batched.
+## Related
+
+- [`createEffect`](/reference/basic-reactivity/create-effect)
+- [`createStore`](/reference/store-utilities/create-store)
+- [`createMutable`](/reference/store-utilities/create-mutable)
diff --git a/src/routes/reference/reactive-utilities/untrack.mdx b/src/routes/reference/reactive-utilities/untrack.mdx
index 2b38a9383..1f819d5d9 100644
--- a/src/routes/reference/reactive-utilities/untrack.mdx
+++ b/src/routes/reference/reactive-utilities/untrack.mdx
@@ -16,9 +16,46 @@ description: >-
   by excluding non-updating props from reactive tracking scope.
 ---
 
-Ignores tracking any of the dependencies in the executing code block and returns the value. This helper is useful when a certain `prop` will never update and thus it is ok to use it outside of the tracking scope.
+`untrack` executes a function without collecting dependencies from the current reactive scope.
 
-```tsx title="component.tsx"
+## Import
+
+```ts
+import { untrack } from "solid-js";
+```
+
+## Type
+
+```ts
+function untrack<T>(fn: () => T): T;
+```
+
+## Parameters
+
+### `fn`
+
+- **Type:** `() => T`
+- **Required:** Yes
+
+Function executed outside the current tracking context.
+
+## Return value
+
+- **Type:** `T`
+
+Returns the value produced by `fn`.
+
+## Behavior
+
+- Signals read inside `untrack` do not become dependencies of the surrounding computation.
+- `untrack` does not disable reactivity globally; it only affects reads inside the provided function.
+- Surrounding effects and memos do not subscribe to values read only inside `untrack`.
+
+## Examples
+
+### Read a prop without tracking
+
+```tsx
 import { untrack } from "solid-js";
 
 export function Component(props) {
@@ -28,12 +65,32 @@ export function Component(props) {
 }
 ```
 
-## Initial and Default Values
+### Avoid tracking part of an effect
 
-It is not necessary to manually untrack values that are suppose to serve as a default or initial value to a signal. Even with the linter configured to enforce tracking, the linter will accept it when a `prop` is prefixed with `default` or `initial` as it is a common pattern to use them as such.
+```tsx
+import { createEffect, createSignal, untrack } from "solid-js";
+
+function Example() {
+	const [count, setCount] = createSignal(0);
+	const [label] = createSignal("count");
+
+	createEffect(() => {
+		console.log(
+			untrack(() => label()),
+			count()
+		);
+	});
+
+	return <button onClick={() => setCount((c) => c + 1)}>Increment</button>;
+}
+```
+
+## Notes
+
+Default and initial prop values can be read directly when initializing a signal.
+This pattern commonly appears with names such as `initialName` and `defaultName`.
 
 ```tsx tab title="initialValue" {5}
-// component.tsx
 import { createSignal } from "solid-js";
 
 export function Component(props) {
@@ -44,7 +101,6 @@ export function Component(props) {
 ```
 
 ```tsx tab title="defaultValue" {5}
-// component.tsx
 import { createSignal } from "solid-js";
 
 export function Component(props) {
@@ -53,3 +109,9 @@ export function Component(props) {
 	return <div>{name()}</div>;
 }
 ```
+
+## Related
+
+- [`onMount`](/reference/lifecycle/on-mount)
+- [`createEffect`](/reference/basic-reactivity/create-effect)
+- [`on`](/reference/reactive-utilities/on-util)

From 80c4b9daf7b629a7aba208c0ea538617803dce2b Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 12:19:29 -0700
Subject: [PATCH 02/88] docs: update descriptions for batch, catchError,
 getOwner, onCleanup, onMount, runWithOwner, and untrack

---
 src/routes/reference/lifecycle/on-cleanup.mdx |  4 +-
 src/routes/reference/lifecycle/on-mount.mdx   |  4 +-
 .../reference/reactive-utilities/batch.mdx    |  4 +-
 .../reactive-utilities/catch-error.mdx        | 79 ++++++++++++++++---
 .../reactive-utilities/get-owner.mdx          | 60 +++++++++++---
 .../reactive-utilities/run-with-owner.mdx     | 73 ++++++++++++-----
 .../reference/reactive-utilities/untrack.mdx  |  4 +-
 7 files changed, 176 insertions(+), 52 deletions(-)

diff --git a/src/routes/reference/lifecycle/on-cleanup.mdx b/src/routes/reference/lifecycle/on-cleanup.mdx
index e8ae07337..79ee80fe0 100644
--- a/src/routes/reference/lifecycle/on-cleanup.mdx
+++ b/src/routes/reference/lifecycle/on-cleanup.mdx
@@ -12,8 +12,8 @@ tags:
   - disposal
 version: "1.0"
 description: >-
-  Register cleanup methods in SolidJS to prevent memory leaks. Executes when
-  components unmount or tracking scopes dispose. Essential for proper cleanup.
+  Register a cleanup function on the current reactive scope. The cleanup runs
+  when the scope is disposed or refreshed.
 ---
 
 `onCleanup` registers a cleanup function on the current reactive scope.
diff --git a/src/routes/reference/lifecycle/on-mount.mdx b/src/routes/reference/lifecycle/on-mount.mdx
index ce3f27ef9..fe5009af3 100644
--- a/src/routes/reference/lifecycle/on-mount.mdx
+++ b/src/routes/reference/lifecycle/on-mount.mdx
@@ -12,8 +12,8 @@ tags:
   - initialization
 version: "1.0"
 description: >-
-  Run code after SolidJS components mount to the DOM. Perfect for accessing
-  refs, setting up third-party libraries, and one-time initializations.
+  Register a function that runs once after the initial render of the current
+  component or root.
 ---
 
 `onMount` registers a function that runs once after the initial render for the current component or root.
diff --git a/src/routes/reference/reactive-utilities/batch.mdx b/src/routes/reference/reactive-utilities/batch.mdx
index 4c3eeae72..2d1e8e54c 100644
--- a/src/routes/reference/reactive-utilities/batch.mdx
+++ b/src/routes/reference/reactive-utilities/batch.mdx
@@ -11,8 +11,8 @@ tags:
   - updates
 version: "1.0"
 description: >-
-  Batch multiple signal updates in SolidJS to improve performance by reducing
-  recalculations. Essential for optimizing complex state changes.
+  Group reactive updates so downstream computations run after the batch
+  completes.
 ---
 
 `batch` groups multiple reactive updates so downstream computations run once after the batch completes instead of after each individual update.
diff --git a/src/routes/reference/reactive-utilities/catch-error.mdx b/src/routes/reference/reactive-utilities/catch-error.mdx
index 6d5363792..4a500a6e2 100644
--- a/src/routes/reference/reactive-utilities/catch-error.mdx
+++ b/src/routes/reference/reactive-utilities/catch-error.mdx
@@ -10,21 +10,80 @@ tags:
   - handlers
 version: "1.0"
 description: >-
-  Wrap SolidJS code with error handlers to catch and handle exceptions
-  gracefully. Create error boundaries for robust error management in components.
+  Establish an error boundary for work performed inside the provided function.
 ---
 
-:::note
+`catchError` establishes an error boundary for work performed inside the provided function.
 
-<span>New in v1.7.0</span>
-:::
+## Import
 
-```tsx
+```ts
 import { catchError } from "solid-js";
+```
+
+## Type
+
+```ts
+function catchError<T>(
+	fn: () => T,
+	handler: (err: Error) => void
+): T | undefined;
+```
+
+## Parameters
+
+### `fn`
+
+- **Type:** `() => T`
+- **Required:** Yes
+
+Function executed inside the error boundary.
+
+### `handler`
+
+- **Type:** `(err: Error) => void`
+- **Required:** Yes
+
+Error handler invoked when an error is thrown inside descendant scopes.
 
-function catchError<T>(tryFn: () => T, onError: (err: any) => void): T;
+## Return value
+
+- **Type:** `T | undefined`
+
+Returns the value produced by `fn`.
+If `handler` handles a thrown error, the result is `undefined`.
+
+## Behavior
+
+- Only the nearest matching error boundary handles a thrown error.
+- If `handler` throws, the next parent error boundary handles that error.
+
+## Examples
+
+### Handle an error in a child scope
+
+```tsx
+import { catchError, createEffect, createSignal } from "solid-js";
+
+function Example() {
+	const [count, setCount] = createSignal(0);
+
+	catchError(
+		() => {
+			createEffect(() => {
+				if (count() > 2) throw new Error("count too large");
+			});
+		},
+		(err) => {
+			console.error(err.message);
+		}
+	);
+
+	return <button onClick={() => setCount((c) => c + 1)}>Increment</button>;
+}
 ```
 
-Wraps a `tryFn` with an error handler that fires if an error occurs below that point.
-Only the nearest scope error handlers execute.
-Rethrow to trigger up the line.
+## Related
+
+- [`ErrorBoundary`](/reference/components/error-boundary)
+- [`createEffect`](/reference/basic-reactivity/create-effect)
diff --git a/src/routes/reference/reactive-utilities/get-owner.mdx b/src/routes/reference/reactive-utilities/get-owner.mdx
index 0825246ca..f4e21e3ab 100644
--- a/src/routes/reference/reactive-utilities/get-owner.mdx
+++ b/src/routes/reference/reactive-utilities/get-owner.mdx
@@ -11,26 +11,60 @@ tags:
   - debugging
 version: "1.0"
 description: >-
-  Access the current tracking scope owner in SolidJS for advanced control over
-  cleanup and disposal. Essential for custom reactive primitives.
+  Return the owner for the currently executing reactive scope.
 ---
 
-```tsx
+`getOwner` returns the owner for the currently executing reactive scope.
+
+## Import
+
+```ts
 import { getOwner } from "solid-js";
 import type { Owner } from "solid-js";
+```
+
+## Type
 
-function getOwner(): Owner;
+```ts
+function getOwner(): Owner | null;
 ```
 
-Gets the tracking scope that owns the currently running code, e.g., for passing into a later call to `runWithOwner` outside of the current scope.
+## Parameters
+
+`getOwner` does not take any parameters.
+
+## Return value
+
+- **Type:** `Owner | null`
+
+Returns the current owner or `null` when no owner is active.
 
-Internally, computations (effects, memos, etc.) create owners which are children of their owner, all the way up to the root owner created by `createRoot` or `render`.
-In particular, this ownership tree lets Solid automatically clean up a disposed computation by traversing its subtree and calling all `onCleanup` callbacks.
-For example, when a createEffect's dependencies change, the effect calls all descendant `onCleanup` callbacks before running the effect function again.
-Calling `getOwner` returns the current owner node that is responsible for disposal of the current execution block.
+## Behavior
+
+- Owners determine cleanup and context lookup for descendant computations.
+- A computation created inside the current scope becomes part of the current owner tree unless ownership is overridden.
+- Components are not computations and do not create owner nodes themselves.
+- Calling `getOwner` inside component code returns the owner responsible for rendering and disposing that component subtree.
+- Turning off tracking with [`untrack`](/reference/reactive-utilities/untrack) does not create a new owner.
+
+## Examples
+
+### Capture an owner for later use
+
+```ts
+import { getOwner, runWithOwner } from "solid-js";
+
+const owner = getOwner();
+
+queueMicrotask(() => {
+	runWithOwner(owner, () => {
+		console.log("owner restored");
+	});
+});
+```
 
-Components are not computations, so do not create an owner node, but they are typically rendered from a `createEffect` which does, so the result is similar: when a component gets unmounted, all descendant `onCleanup` callbacks get called.
-Calling `getOwner` from a component scope returns the owner that is responsible for rendering and unmounting that component.
+## Related
 
-Note that the owning tracking scope isn't necessarily tracking.
-For example, untrack turns off tracking for the duration of a function (without creating a new tracking scope), as do components created via JSX (`<Component ...>`).
+- [`runWithOwner`](/reference/reactive-utilities/run-with-owner)
+- [`onCleanup`](/reference/lifecycle/on-cleanup)
+- [`untrack`](/reference/reactive-utilities/untrack)
diff --git a/src/routes/reference/reactive-utilities/run-with-owner.mdx b/src/routes/reference/reactive-utilities/run-with-owner.mdx
index 349243cda..ff728da81 100644
--- a/src/routes/reference/reactive-utilities/run-with-owner.mdx
+++ b/src/routes/reference/reactive-utilities/run-with-owner.mdx
@@ -13,45 +13,76 @@ tags:
   - effects
 version: "1.0"
 description: >-
-  Execute code under a specific owner in SolidJS for proper cleanup and context
-  access, especially in async operations and setTimeout callbacks.
+  Execute a function under the provided owner.
 ---
 
+`runWithOwner` executes a function under the provided owner.
+
+## Import
+
 ```ts
-import { runWithOwner } from "solid-js"
-import type { Owner } from "solid-js"
+import { runWithOwner } from "solid-js";
+import type { Owner } from "solid-js";
+```
 
-function runWithOwner<T>(owner: Owner, fn: (() => void) => T): T
+## Type
+
+```ts
+function runWithOwner<T>(owner: Owner | null, fn: () => T): T | undefined;
 ```
 
-Executes the given function under the provided owner, instead of (and without affecting) the owner of the outer scope.
-By default, computations created by `createEffect`, `createMemo`, etc. are owned by the owner of the currently executing code (the return value of `getOwner`), so in particular these will get disposed when their owner does.
-Calling `runWithOwner` provides a way to override this default to a manually specified owner (typically, the return value from a previous call to `getOwner`), enabling more precise control of when computations get disposed.
+## Parameters
+
+### `owner`
+
+- **Type:** `Owner | null`
+- **Required:** Yes
+
+Owner used while executing `fn`.
+
+### `fn`
 
-Having a (correct) owner is important for two reasons:
+- **Type:** `() => T`
+- **Required:** Yes
 
-- Computations without an owner cannot be cleaned up.
-  For example, if you call `createEffect` without an owner (e.g., in the global scope), the effect will continue running forever, instead of being disposed when its owner gets disposed.
+Function executed under `owner`.
 
-- `useContext` obtains context by walking up the owner tree to find the nearest ancestor providing the desired context.
-  So without an owner you cannot look up any provided context (and with the wrong owner, you might obtain the wrong context).
+## Return value
 
-Manually setting the owner is especially helpful when doing reactivity outside of any owner scope.
-In particular, asynchronous computation (via either `async` functions or callbacks like `setTimeout`) lose their automatically set owner, so remembering the original owner via `getOwner` and restoring it via `runWithOwner` is necessary in these cases.
-For example:
+- **Type:** `T | undefined`
+
+Returns the value produced by `fn`.
+
+## Behavior
+
+- Computations created inside `fn` are attached to the provided owner.
+- Context lookup inside `fn` walks the provided owner tree.
+- Ownership affects cleanup and context resolution.
+- Ownership does not restore dependency tracking across asynchronous boundaries.
+- Code after the first `await` in an `async` function runs without reactive dependency tracking.
+
+## Examples
+
+### Restore an owner in a callback
 
 ```ts
+import { createEffect, getOwner, runWithOwner, useContext } from "solid-js";
+
 const owner = getOwner();
+
 setTimeout(() => {
-	// This callback gets run without owner.
-	// Restore owner via runWithOwner:
 	runWithOwner(owner, () => {
-		const foo = useContext(FooContext);
+		const value = useContext(FooContext);
+
 		createEffect(() => {
-			console.log(foo);
+			console.log(value);
 		});
 	});
 }, 1000);
 ```
 
-**Note:** that owners are not what determines dependency tracking, so `runWithOwner` does not help with tracking in asynchronous functions; use of reactive state in the asynchronous part (e.g. after the first `await`) will not be tracked as a dependency.
+## Related
+
+- [`getOwner`](/reference/reactive-utilities/get-owner)
+- [`useContext`](/reference/component-apis/use-context)
+- [`onCleanup`](/reference/lifecycle/on-cleanup)
diff --git a/src/routes/reference/reactive-utilities/untrack.mdx b/src/routes/reference/reactive-utilities/untrack.mdx
index 1f819d5d9..270c71f0c 100644
--- a/src/routes/reference/reactive-utilities/untrack.mdx
+++ b/src/routes/reference/reactive-utilities/untrack.mdx
@@ -12,8 +12,8 @@ tags:
   - defaults
 version: "1.0"
 description: >-
-  Prevent dependency tracking for static values in SolidJS. Optimize performance
-  by excluding non-updating props from reactive tracking scope.
+  Execute a function without collecting dependencies from the current reactive
+  scope.
 ---
 
 `untrack` executes a function without collecting dependencies from the current reactive scope.

From da1b83ee41d78ce715508cf918823f8ce7eeb37a Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 12:22:47 -0700
Subject: [PATCH 03/88] docs: update documentation for createReaction,
 startTransition, and useTransition

---
 .../reactive-utilities/start-transition.mdx   | 62 ++++++++++++++--
 .../reactive-utilities/use-transition.mdx     | 66 ++++++++++++++---
 .../secondary-primitives/create-reaction.mdx  | 73 ++++++++++++++++---
 3 files changed, 173 insertions(+), 28 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/start-transition.mdx b/src/routes/reference/reactive-utilities/start-transition.mdx
index b628412ea..92a27daf2 100644
--- a/src/routes/reference/reactive-utilities/start-transition.mdx
+++ b/src/routes/reference/reactive-utilities/start-transition.mdx
@@ -11,16 +11,66 @@ tags:
   - batching
 version: "1.0"
 description: >-
-  Start transitions in SolidJS without pending state tracking. Batch async
-  updates for improved performance and smoother user interactions.
+  Start a transition and return a promise that resolves when the transition
+  completes.
 ---
 
+`startTransition` starts a transition without exposing a pending-state accessor.
+
+## Import
+
 ```ts
-import { startTransition } from "solid-js"
+import { startTransition } from "solid-js";
+```
 
-function startTransition: (fn: () => void) => Promise<void>
+## Type
 
+```ts
+function startTransition(fn: () => unknown): Promise<void>;
 ```
 
-Similar to `useTransition` except there is no associated pending state.
-This one can just be used directly to start the Transition.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => unknown`
+- **Required:** Yes
+
+Function executed inside the transition.
+
+## Return value
+
+- **Type:** `Promise<void>`
+
+Resolves when the transition completes.
+
+## Behavior
+
+- Updates scheduled inside `fn` run as a transition.
+- The returned promise resolves after transition work completes.
+- This API does not provide a pending-state accessor.
+
+## Examples
+
+### Start a transition
+
+```tsx
+import { createSignal, startTransition } from "solid-js";
+
+function Example() {
+	const [value, setValue] = createSignal("");
+
+	async function update(next: string) {
+		await startTransition(() => {
+			setValue(next);
+		});
+	}
+
+	return <button onClick={() => update("next")}>{value()}</button>;
+}
+```
+
+## Related
+
+- [`useTransition`](/reference/reactive-utilities/use-transition)
+- [`Suspense`](/reference/components/suspense)
diff --git a/src/routes/reference/reactive-utilities/use-transition.mdx b/src/routes/reference/reactive-utilities/use-transition.mdx
index 71ae753d8..894d633de 100644
--- a/src/routes/reference/reactive-utilities/use-transition.mdx
+++ b/src/routes/reference/reactive-utilities/use-transition.mdx
@@ -12,28 +12,72 @@ tags:
   - concurrent
 version: "1.0"
 description: >-
-  Batch async updates with transitions in SolidJS. Track pending states and
-  defer commits until all async processes complete for smooth UI updates.
+  Return a pending-state accessor and a function that starts a transition.
 ---
 
+`useTransition` returns a pending-state accessor and a function that starts a transition.
+
+## Import
+
 ```ts
 import { useTransition } from "solid-js";
+```
 
+## Type
+
+```ts
 function useTransition(): [
 	pending: () => boolean,
-	startTransition: (fn: () => void) => Promise<void>,
+	start: (fn: () => void) => Promise<void>,
 ];
 ```
 
-Used to batch async updates in a transaction deferring commit until all async processes are complete.
-This is tied into Suspense and only tracks resources read under Suspense boundaries.
+## Parameters
 
-```ts
-const [isPending, start] = useTransition();
+`useTransition` does not take any parameters.
+
+## Return value
+
+- **Type:** `[() => boolean, (fn: () => void) => Promise<void>]`
+
+Returns a tuple containing:
 
-// check if transitioning
-isPending();
+- `pending`: an accessor that reports whether the transition is pending
+- `start`: a function that starts a transition
 
-// wrap in transition
-start(() => setSignal(newValue), () => /* transition is done */)
+## Behavior
+
+- `start` schedules updates inside a transition.
+- `pending()` is `true` while the transition is pending.
+- Transition state integrates with Suspense and resource reads under Suspense boundaries.
+
+## Examples
+
+### Read transition state
+
+```tsx
+import { createSignal, useTransition } from "solid-js";
+
+function Example() {
+	const [value, setValue] = createSignal("");
+	const [pending, start] = useTransition();
+
+	return (
+		<>
+			<button
+				onClick={() => {
+					start(() => setValue("next"));
+				}}
+			>
+				Update
+			</button>
+			<div>{pending() ? "pending" : value()}</div>
+		</>
+	);
+}
 ```
+
+## Related
+
+- [`startTransition`](/reference/reactive-utilities/start-transition)
+- [`Suspense`](/reference/components/suspense)
diff --git a/src/routes/reference/secondary-primitives/create-reaction.mdx b/src/routes/reference/secondary-primitives/create-reaction.mdx
index b29ccf7b9..0ef6c6dea 100644
--- a/src/routes/reference/secondary-primitives/create-reaction.mdx
+++ b/src/routes/reference/secondary-primitives/create-reaction.mdx
@@ -11,28 +11,79 @@ tags:
   - advanced
 version: "1.0"
 description: >-
-  Separate tracking from execution with createReaction. Create one-time reactive
-  side effects that run on first dependency change only.
+  Create a reaction that runs once when the tracked expression is invalidated.
 ---
 
+`createReaction` creates a reaction that invalidates once for each call to the returned tracking function.
+
+## Import
+
 ```ts
 import { createReaction } from "solid-js";
+```
 
-function createReaction(onInvalidate: () => void): (fn: () => void) => void;
+## Type
+
+```ts
+function createReaction(
+	onInvalidate: () => void,
+	options?: { name?: string }
+): (tracking: () => void) => void;
 ```
 
-Sometimes it is useful to separate tracking from re-execution.
-This primitive registers a side effect that is run the first time the expression wrapped by the returned tracking function is notified of a change.
+## Parameters
+
+### `onInvalidate`
+
+- **Type:** `() => void`
+- **Required:** Yes
+
+Callback invoked when the tracked computation is invalidated.
+
+### `options`
+
+- **Type:** `{ name?: string }`
+- **Required:** No
+
+Optional configuration object.
+
+#### `name`
+
+- **Type:** `string`
+- **Required:** No
+
+Debug name used by development tooling.
+
+## Return value
+
+- **Type:** `(tracking: () => void) => void`
+
+Returns a function that executes `tracking` and records its dependencies for a single invalidation.
+
+## Behavior
+
+- The returned tracking function records dependencies read during `tracking`.
+- `onInvalidate` runs on the first change to any recorded dependency.
+- After invalidation, the reaction does not run again until the tracking function is called again.
+
+## Examples
+
+### Track a signal for one invalidation
 
 ```ts
-const [s, set] = createSignal("start");
+import { createReaction, createSignal } from "solid-js";
 
-const track = createReaction(() => console.log("something"));
+const [value, setValue] = createSignal("start");
 
-// run the reaction next time `s` changes.
-track(() => s());
+const track = createReaction(() => console.log("changed"));
 
-set("end"); // "something"
+track(() => value());
 
-set("final"); // no-op since the reaction only runs on the first update, need to call `track` again.
+setValue("end"); // logs "changed"
+setValue("final"); // no-op until track() runs again
 ```
+
+## Related
+
+- [`createEffect`](/reference/basic-reactivity/create-effect)
+- [`createComputed`](/reference/secondary-primitives/create-computed)

From d448223381d3ce5caab9158ced9993575d2f29ae Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 12:33:00 -0700
Subject: [PATCH 04/88] docs: update documentation for from, indexArray,
 mapArray, and observable

---
 .../reference/reactive-utilities/from.mdx     |  88 +++++++++++----
 .../reactive-utilities/index-array.mdx        | 106 +++++++++++++-----
 .../reactive-utilities/map-array.mdx          | 103 ++++++++++++-----
 .../reactive-utilities/observable.mdx         |  50 +++++++--
 4 files changed, 255 insertions(+), 92 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/from.mdx b/src/routes/reference/reactive-utilities/from.mdx
index 1fe6be429..306d7a3d4 100644
--- a/src/routes/reference/reactive-utilities/from.mdx
+++ b/src/routes/reference/reactive-utilities/from.mdx
@@ -11,45 +11,85 @@ tags:
   - integration
 version: "1.0"
 description: >-
-  Convert RxJS observables and external producers into SolidJS signals. Seamless
-  integration with third-party reactive libraries and state managers.
+  Convert an external producer or subscribable into a Solid accessor.
 ---
 
-```tsx
+`from` creates an accessor from an external producer or subscribable source.
+
+## Import
+
+```ts
 import { from } from "solid-js";
+```
 
-function from<T>(
-	producer:
-		| ((setter: (v: T) => T) => () => void)
-		| {
-				subscribe: (
-					fn: (v: T) => void
-				) => (() => void) | { unsubscribe: () => void };
-		  }
-): () => T | undefined;
+## Type
+
+```ts
+function from<T>(producer: Producer<T>, initialValue: T): () => T;
+function from<T>(producer: Producer<T | undefined>): () => T | undefined;
+
+type Producer<T> =
+	| ((setter: Setter<T>) => () => void)
+	| {
+			subscribe: (
+				fn: (value: T) => void
+			) => (() => void) | { unsubscribe: () => void };
+	  };
 ```
 
-A helper to make it easier to interop with external producers like RxJS observables or with Svelte Stores.
-This basically turns any subscribable (object with a subscribe method) into a Signal and manages subscription and disposal.
+## Parameters
+
+### `producer`
+
+- **Type:** `Producer<T>` or `Producer<T | undefined>`
+- **Required:** Yes
+
+Producer function or subscribable object.
+
+### `initialValue`
+
+- **Type:** `T`
+- **Required:** No
+
+Initial value for the accessor.
 
-```tsx
-const signal = from(obsv$);
+## Return value
+
+- **Type:** `() => T` or `() => T | undefined`
+
+Returns an accessor backed by the external source.
+
+## Behavior
+
+- A producer function receives a Solid setter and returns a cleanup function.
+- A subscribable source must expose `subscribe()`.
+- Returned subscriptions are cleaned up with the owning Solid scope.
+- When `initialValue` is omitted, the accessor can return `undefined`.
+
+## Examples
+
+### Create an accessor from a subscribable source
+
+```ts
+import { from } from "solid-js";
+
+const signal = from(observableSource);
 ```
 
-It can also take a custom producer function where the function is passed a setter function that returns an unsubscribe function:
+### Create an accessor from a producer function
+
+```ts
+import { from } from "solid-js";
 
-```tsx
 const clock = from((set) => {
 	const interval = setInterval(() => {
-		set((v) => v + 1);
+		set((value) => value + 1);
 	}, 1000);
 
 	return () => clearInterval(interval);
-});
+}, 0);
 ```
 
-## Arguments
+## Related
 
-| Name     | Type                                                                                                                           | Description                                  |
-| :------- | :----------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- |
-| producer | `((setter: (v: T) => T) => () => void) \| { subscribe: (fn: (v: T) => void) => (() => void) \| { unsubscribe: () => void }; }` | The producer function or subscribable object |
+- [`observable`](/reference/reactive-utilities/observable)
diff --git a/src/routes/reference/reactive-utilities/index-array.mdx b/src/routes/reference/reactive-utilities/index-array.mdx
index 421b836a8..5aa4959af 100644
--- a/src/routes/reference/reactive-utilities/index-array.mdx
+++ b/src/routes/reference/reactive-utilities/index-array.mdx
@@ -11,43 +11,91 @@ tags:
   - optimization
 version: "1.0"
 description: >-
-  Map arrays by index in SolidJS where items are signals and indices are
-  constant. Optimized helper for index-based list rendering patterns.
+  Reactively map an array by index and return an accessor for the mapped
+  result.
 ---
 
-```tsx
+`indexArray` reactively maps an array by index.
+
+## Import
+
+```ts
 import { indexArray } from "solid-js";
+```
+
+## Type
 
+```ts
 function indexArray<T, U>(
-	list: () => readonly T[],
-	mapFn: (v: () => T, i: number) => U
+	list: () => readonly T[] | undefined | null | false,
+	mapFn: (value: () => T, index: number) => U,
+	options?: { fallback?: () => any }
 ): () => U[];
 ```
 
-Similar to `mapArray` except it maps by index.
-The item is a signal and the index is now the constant.
-
-Underlying helper for the `<Index>` control flow.
-
-```tsx
-const mapped = indexArray(source, (model) => {
-  return {
-    get id() {
-      return model().id
-    }
-    get firstInitial() {
-      return model().firstName[0];
-    },
-    get fullName() {
-      return `${model().firstName} ${model().lastName}`;
-    },
-  }
-});
+## Parameters
+
+### `list`
+
+- **Type:** `() => readonly T[] | undefined | null | false`
+- **Required:** Yes
+
+Accessor that returns the source array.
+
+### `mapFn`
+
+- **Type:** `(value: () => T, index: number) => U`
+- **Required:** Yes
+
+Mapping function for each index.
+
+### `options`
+
+- **Type:** `{ fallback?: () => any }`
+- **Required:** No
+
+Optional configuration object.
+
+#### `fallback`
+
+- **Type:** `() => any`
+- **Required:** No
+
+Fallback accessor used when the source array is empty or falsy.
+
+## Return value
+
+- **Type:** `() => U[]`
+
+Returns an accessor for the mapped array.
+
+## Behavior
+
+- Items are mapped by index rather than by value identity.
+- The item argument is an accessor.
+- The index argument is a number.
+- Updating an item at the same index updates the corresponding mapped result.
+- This is the underlying helper for [`<Index>`](/reference/components/index-component).
+
+## Examples
+
+### Map an array by index
+
+```ts
+import { createSignal, indexArray } from "solid-js";
+
+const [source] = createSignal([
+	{ firstName: "Ada", lastName: "Lovelace" },
+	{ firstName: "Grace", lastName: "Hopper" },
+]);
+
+const mapped = indexArray(source, (item, index) => ({
+	index,
+	fullName: () => `${item().firstName} ${item().lastName}`,
+}));
 ```
 
-## Arguments
+## Related
 
-| Name  | Type                           | Description           |
-| :---- | :----------------------------- | :-------------------- |
-| list  | `() => readonly T[]`           | The list to map.      |
-| mapFn | `(v: () => T, i: number) => U` | The mapping function. |
+- [`<Index>`](/reference/components/index-component)
+- [`mapArray`](/reference/reactive-utilities/map-array)
diff --git a/src/routes/reference/reactive-utilities/map-array.mdx b/src/routes/reference/reactive-utilities/map-array.mdx
index 80883a7c6..1dd563f67 100644
--- a/src/routes/reference/reactive-utilities/map-array.mdx
+++ b/src/routes/reference/reactive-utilities/map-array.mdx
@@ -11,47 +11,92 @@ tags:
   - optimization
 version: "1.0"
 description: >-
-  Efficiently map reactive arrays in SolidJS with cached transformations.
-  Reduces unnecessary re-renders by tracking items by reference.
+  Reactively map an array by item identity and return an accessor for the mapped
+  result.
 ---
 
+`mapArray` reactively maps an array and caches mapped items by value identity.
+
+## Import
+
 ```ts
 import { mapArray } from "solid-js";
+```
+
+## Type
 
+```ts
 function mapArray<T, U>(
-	list: () => readonly T[],
-	mapFn: (v: T, i: () => number) => U
+	list: () => readonly T[] | undefined | null | false,
+	mapFn: (value: T, index: () => number) => U,
+	options?: { fallback?: () => any }
 ): () => U[];
 ```
 
-Reactive map helper that caches each item by reference to reduce unnecessary mapping on updates.
-It only runs the mapping function once per value and then moves or removes it as needed.
-The index argument is a signal. The map function itself is not tracking.
+## Parameters
+
+### `list`
+
+- **Type:** `() => readonly T[] | undefined | null | false`
+- **Required:** Yes
+
+Accessor that returns the source array.
+
+### `mapFn`
+
+- **Type:** `(value: T, index: () => number) => U`
+- **Required:** Yes
+
+Mapping function for each item.
+
+### `options`
+
+- **Type:** `{ fallback?: () => any }`
+- **Required:** No
 
-Underlying helper for the `<For>` control flow.
+Optional configuration object.
+
+#### `fallback`
+
+- **Type:** `() => any`
+- **Required:** No
+
+Fallback accessor used when the source array is empty or falsy.
+
+## Return value
+
+- **Type:** `() => U[]`
+
+Returns an accessor for the mapped array.
+
+## Behavior
+
+- Items are cached by value identity.
+- The index argument is an accessor.
+- `mapFn` is not a tracking scope.
+- Reordering reuses existing mapped items when their source values are retained.
+- This is the underlying helper for [`<For>`](/reference/components/for).
+
+## Examples
+
+### Map an array with cached items
 
 ```ts
-const mapped = mapArray(source, (model) => {
-	const [name, setName] = createSignal(model.name);
-	const [description, setDescription] = createSignal(model.description);
-
-	return {
-		id: model.id,
-		get name() {
-			return name();
-		},
-		get description() {
-			return description();
-		},
-		setName,
-		setDescription,
-	};
-});
+import { createSignal, mapArray } from "solid-js";
+
+const [source] = createSignal([
+	{ id: 1, name: "A" },
+	{ id: 2, name: "B" },
+]);
+
+const mapped = mapArray(source, (item, index) => ({
+	id: item.id,
+	name: item.name,
+	position: index,
+}));
 ```
 
-## Arguments
+## Related
 
-| Name  | Type                           | Description              |
-| :---- | :----------------------------- | :----------------------- |
-| list  | `() => readonly T[]`           | The source array to map. |
-| mapFn | `(v: T, i: () => number) => U` | The mapping function.    |
+- [`<For>`](/reference/components/for)
+- [`indexArray`](/reference/reactive-utilities/index-array)
diff --git a/src/routes/reference/reactive-utilities/observable.mdx b/src/routes/reference/reactive-utilities/observable.mdx
index e879bae13..6992d6110 100644
--- a/src/routes/reference/reactive-utilities/observable.mdx
+++ b/src/routes/reference/reactive-utilities/observable.mdx
@@ -12,29 +12,59 @@ tags:
   - streams
 version: "1.0"
 description: >-
-  Convert SolidJS signals to Observables for seamless integration with RxJS and
-  other reactive libraries using the observable utility function.
+  Convert a Solid accessor into an Observable-compatible object.
 ---
 
+`observable` creates an Observable-compatible object from a Solid accessor.
+
+## Import
+
 ```ts
 import { observable } from "solid-js";
+```
 
+## Type
+
+```ts
 function observable<T>(input: () => T): Observable<T>;
 ```
 
-This method takes a signal and produces an Observable.
-You can consume it from another Observable library of your choice, typically with the `from` operator.
+## Parameters
+
+### `input`
+
+- **Type:** `() => T`
+- **Required:** Yes
+
+Accessor used as the observable source.
+
+## Return value
+
+- **Type:** `Observable<T>`
+
+Returns an object with `subscribe()` and `[Symbol.observable]()`.
+
+## Behavior
+
+- The returned object is compatible with Observable interop based on `Symbol.observable`.
+- Subscriptions receive values from the accessor.
+- Observable libraries can consume the returned object through standard Observable interop.
+
+## Examples
+
+### Convert an accessor to an Observable-compatible source
 
 ```ts
-// How to integrate rxjs with a Solid signal
-import { observable } from "solid-js";
+import { createSignal, observable } from "solid-js";
 import { from } from "rxjs";
 
-const [s, set] = createSignal(0);
+const [value] = createSignal(0);
 
-const obsv$ = from(observable(s));
+const value$ = from(observable(value));
 
-obsv$.subscribe((v) => console.log(v));
+value$.subscribe((next) => console.log(next));
 ```
 
-You can also use `from` without rxjs; check out this [page](/reference/reactive-utilities/from).
+## Related
+
+- [`from`](/reference/reactive-utilities/from)

From c4de20b82d4736827f4356cb4ff89db5a5edd6cb Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 13:08:42 -0700
Subject: [PATCH 05/88] docs: refine documentation for children, createContext,
 useContext, and related APIs

---
 .../reference/component-apis/children.mdx     |  61 ++-----
 .../component-apis/create-context.mdx         | 153 +++++++++---------
 .../reference/component-apis/use-context.mdx  |  85 +++++++---
 .../reactive-utilities/get-owner.mdx          |   3 +-
 .../reactive-utilities/run-with-owner.mdx     |   3 +-
 .../reactive-utilities/start-transition.mdx   |   2 +-
 .../reactive-utilities/use-transition.mdx     |   2 +-
 7 files changed, 165 insertions(+), 144 deletions(-)

diff --git a/src/routes/reference/component-apis/children.mdx b/src/routes/reference/component-apis/children.mdx
index d4f79c895..45b2a80c5 100644
--- a/src/routes/reference/component-apis/children.mdx
+++ b/src/routes/reference/component-apis/children.mdx
@@ -10,13 +10,10 @@ tags:
   - utilities
 version: "1.0"
 description: >-
-  Resolve and normalize a component's `children` prop into a stable accessor.
-  Useful when you need to read or transform children imperatively inside a
-  component.
+  Resolve a component's `children` prop into a stable accessor.
 ---
 
-`children` normalizes a component's `children` prop into a stable accessor that returns resolved JSX elements.
-It accepts functions, arrays, fragments, and nested structures.
+`children` resolves a component's `children` prop and returns an accessor for the resolved result.
 
 ## Import
 
@@ -41,46 +38,40 @@ type ChildrenReturn = Accessor<ResolvedChildren> & {
 - **Type:** `() => JSX.Element`
 - **Required:** Yes
 
-An accessor that returns the `children` value (typically `props.children`).
+Accessor that returns the component's `children` value.
 
 ## Return value
 
 - **Type:** `ChildrenReturn`
 
-The function returns a callable accessor.
-Calling it yields the resolved children, either a single element or an array.
+Returns an accessor for the resolved children.
+The accessor also exposes `toArray()`.
 
-## Helpers
+## Behavior
 
-### `toArray()`
-
-- **Type:** `() => ResolvedChildren[]`
-
-- **Description:** Returns a flattened array of resolved child elements.
-
-This method is exposed on the returned accessor and is useful for iteration or index-based logic.
+- `children` resolves functions, arrays, fragments, and nested child structures.
+- The returned accessor reads the current resolved value of `props.children`.
+- `toArray()` returns a flattened array of resolved child elements.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
+import { children } from "solid-js";
+
 function Wrapper(props) {
 	const resolved = children(() => props.children);
 
 	return <div>{resolved()}</div>;
 }
-
-// Usage
-<Wrapper>
-	<span>one</span>
-	<span>two</span>
-</Wrapper>;
 ```
 
-### `.toArray()` example
+### Flatten children into an array
 
 ```tsx
+import { children } from "solid-js";
+
 function List(props) {
 	const resolved = children(() => props.children);
 	const items = resolved.toArray();
@@ -93,28 +84,8 @@ function List(props) {
 		</ul>
 	);
 }
-
-// Usage
-<List>
-	<span>one</span>
-	<span>two</span>
-</List>;
 ```
 
-> [!NOTE]
-> `children` resolves the current value of `props.children`.
-> If `props.children` is reactive, the resolved accessor reflects updates.
+## Related
 
-### Working with function-as-children
-
-If `children` is a function, the helper evaluates it and returns its rendered result.
-
-```tsx
-function Slot(props) {
-	const resolved = children(() => props.children);
-	return <div>{resolved()}</div>;
-}
-
-// Usage
-<Slot>{() => <span>dynamic</span>}</Slot>;
-```
+- [`createContext`](/reference/component-apis/create-context)
diff --git a/src/routes/reference/component-apis/create-context.mdx b/src/routes/reference/component-apis/create-context.mdx
index 37070da49..382fb3f28 100644
--- a/src/routes/reference/component-apis/create-context.mdx
+++ b/src/routes/reference/component-apis/create-context.mdx
@@ -12,103 +12,104 @@ tags:
   - dependency-injection
 version: "1.0"
 description: >-
-  Create context providers with createContext to share data across components
-  without prop drilling. Perfect for themes, auth, and global app state.
+  Create a context object with a `Provider` component and a default value.
 ---
 
-Context provides a form of dependency injection in Solid.
-It is used to save from needing to pass data as props through intermediate components (aka **prop drilling**).
-This function creates a new context object that can be used with [useContext](/reference/component-apis/use-context) and offers the Provider control flow.
-The default value is used when no Provider is found above in the hierarchy.
+`createContext` creates a context object.
+The returned object contains a `Provider` component and a `defaultValue`; [`useContext`](/reference/component-apis/use-context) reads the nearest matching provider value.
 
-## Usage
+## Import
 
-To avoid reinstatiating a new context when Hot-Module Replacement (HMR) occurs, it is recommended to use `createContext` in its own module (file).
+```ts
+import { createContext } from "solid-js";
+```
+
+## Type
+
+```ts
+interface Context<T> {
+	id: symbol;
+	Provider: (props: { value: T; children: any }) => any;
+	defaultValue: T;
+}
 
-:::danger[Hot-Module Replacement]
-When using HMR, the context is lost when the module is reloaded.
-Which will cause an error to be thrown as `useContext` will try to access it while it is still reloading.
-:::
+function createContext<T>(
+	defaultValue?: undefined,
+	options?: { name?: string }
+): Context<T | undefined>;
+```
 
-For example:
+## Parameters
 
-```ts title="/context/counter.ts"
-import { createContext } from "solid-js";
+### `defaultValue`
 
-export const INITIAL_COUNT = 0;
+- **Type:** `T`
+- **Required:** No
 
-const INITIAL_STORE_SETTER = {
-	increment: () => {},
-	decrement: () => {},
-};
+Default value returned by [`useContext`](/reference/component-apis/use-context) when no matching provider is found.
 
-export const CounterContext = createContext([
-	{ count: INITIAL_COUNT },
-	INITIAL_STORE_SETTER,
-]);
-```
+### `options`
 
-With the context created in its own module, you can use to instantiate the context provider.
-
-```ts title="/context/counter-component.tsx"
-import { createStore } from 'solid-js/store';
-import { CounterContext, INITIAL_COUNT } from "./counter.ts";
-
-export function CounterProvider(props) {
-    const [value, setValue] = createStore({ count: props.initialCount || INITIAL_COUNT })
-
-    const counter = [
-        value,
-        {
-            increment() {
-                setValue("count", currentCount => currentCount + 1)
-            },
-            decrement() {
-                setValue("count", currentCount => currentCount - 1)
-            },
-        },
-    ]
-
-    return (
-        <CounterContext.Provider value={counter}>
-            {props.children}
-        </CounterContext.Provider>
-    )
-}
-```
+- **Type:** `{ name?: string }`
+- **Required:** No
+
+Optional configuration object.
+
+#### `name`
 
-A few imporant notes on how to pass data through the context API:
+- **Type:** `string`
+- **Required:** No
 
-- The value passed to provider is passed to `useContext` as is.
-- Wrapping as a reactive expression will not work.
-- You should pass in Signals and Stores directly instead of accessing them in the JSX.
+Debug name used by development tooling.
 
-To learn how to consume the context, see the [useContext](/reference/component-apis/use-context) documentation and the [Context concepts entry](/concepts/context).
+## Return value
 
-## Default Values
+- **Type:** `Context<T>` or `Context<T | undefined>`
 
-`createContext()` takes an optional "default value" as an argument.
-If `useContext` is called and there is no corresponding context provider above it in the component hierarchy, then the value passed as `defaultValue` is returned.
+Returns a context object containing `id`, `Provider`, and `defaultValue`.
 
-However, if no `defaultValue` was passed, then `undefined` is returned in this case.
-Also, `defaultValue` (or `undefined`) is returned if `useContext` is called inside an event callback, as it is then outside of the component hierarchy.
+## Behavior
 
-This has implications for TS.
-If no `defaultValue` is passed, then it is possible that `useContext()` will return `undefined`, and the types reflect this.
+- `Context.Provider` passes its `value` prop to descendant calls to [`useContext`](/reference/component-apis/use-context).
+- If no matching provider is found, `useContext` returns `defaultValue` when one was supplied.
+- If no matching provider is found and no default value was supplied, `useContext` returns `undefined`.
+- Calling `useContext` outside the owner tree of a matching provider also returns the default value or `undefined`.
 
-Another (used in the example in the previous section) is provide a default value to `createContext()`.
-In that case, `useContext()` will always return a value, and therefore TS will not complain either.
-The pitfall with this approach is that if you _unintentionally_ use `useContext` outside of a provider, it may not be immediately apparent, because the context is still providing a valid value.
-Therefore, if you expect to always use `useContext` within a provider, it is best to use the error based approach described above.
+## Notes
 
-## Type signature
+- During Hot Module Replacement (HMR), recreating a context in a reloaded module creates a new context object.
+- If provider and consumer modules are temporarily out of sync during reload, `useContext` can read a different context object and return the default value or `undefined`.
+- Defining the context in its own module keeps the exported context object stable across imports.
+
+## Examples
+
+### Create a context with a default value
 
 ```ts
-interface Context<T> {
-	id: symbol;
-	Provider: (props: { value: T; children: any }) => any;
-	defaultValue: T;
-}
+import { createContext } from "solid-js";
+
+type Theme = "light" | "dark";
 
-function createContext<T>(defaultValue?: T): Context<T | undefined>;
+const ThemeContext = createContext<Theme>("light");
 ```
+
+### Create a provider
+
+```tsx
+import { createContext } from "solid-js";
+
+const CounterContext = createContext<number>();
+
+function CounterProvider(props) {
+	return (
+		<CounterContext.Provider value={1}>
+			{props.children}
+		</CounterContext.Provider>
+	);
+}
+```
+
+## Related
+
+- [`useContext`](/reference/component-apis/use-context)
+- [Context](/concepts/context)
diff --git a/src/routes/reference/component-apis/use-context.mdx b/src/routes/reference/component-apis/use-context.mdx
index aa8160eb1..255295d02 100644
--- a/src/routes/reference/component-apis/use-context.mdx
+++ b/src/routes/reference/component-apis/use-context.mdx
@@ -11,40 +11,87 @@ tags:
   - consumption
 version: "1.0"
 description: >-
-  Access context values with useContext to consume data from parent providers.
-  Avoid prop drilling and access shared state throughout your component tree.
+  Read the current value of a context object created by `createContext`.
 ---
 
-Used to grab context within a context provider scope to allow for deep passing of props without having to pass them through each Component function.
-It's therefore used in conjunction with [`createContext`](/reference/component-apis/create-context) to consume the data from a Provider scope and thus avoid passing data through intermediate components (prop drilling).
+`useContext` returns the current value for a context object.
+
+## Import
+
+```ts
+import { useContext } from "solid-js";
+```
+
+## Type
 
 ```ts
-const [state, { increment, decrement }] = useContext(CounterContext);
+interface Context<T> {
+	id: symbol;
+	Provider: (props: { value: T; children: any }) => any;
+	defaultValue: T;
+}
+
+function useContext<T>(context: Context<T>): T;
+```
+
+## Parameters
+
+### `context`
+
+- **Type:** `Context<T>`
+- **Required:** Yes
+
+Context object created by [`createContext`](/reference/component-apis/create-context).
+
+## Return value
+
+- **Type:** `T`
+
+Returns the value provided by the nearest matching `Context.Provider`.
+If no provider is found, it returns the context's default value or `undefined`.
+
+## Behavior
+
+- `useContext` reads the nearest matching provider in the current owner tree.
+- When no provider is found, it returns the default value from [`createContext`](/reference/component-apis/create-context).
+- When no provider is found and no default value was supplied, the result is `undefined`.
+- Calling `useContext` outside the owner tree of a matching provider returns the default value or `undefined`.
+
+## Examples
+
+### Read a context value
+
+```tsx
+import { createContext, useContext } from "solid-js";
+
+const CounterContext = createContext<number>(0);
+
+function CounterValue() {
+	const value = useContext(CounterContext);
+
+	return <span>{value}</span>;
+}
 ```
 
-## Recommended usage
+### Throw when a provider is missing
+
+```ts
+import { createContext, useContext } from "solid-js";
 
-It is often a good idea to wrap `useContext` in a function like so:
+const CounterContext = createContext<number>();
 
-```ts title="/context/counter-component.tsx"
 function useCounterContext() {
 	const context = useContext(CounterContext);
 
-	if (!context) {
-		throw new Error("useCounterContext: cannot find a CounterContext");
+	if (context === undefined) {
+		throw new Error("CounterContext is missing");
 	}
 
 	return context;
 }
 ```
 
-See the API reference of [createContext](/reference/component-apis/create-context) the API on how to generate a Provider scope.
-And check the [Context concepts](/concepts/context) for more information on how to architecture your contexts.
-
-## Type signature
+## Related
 
-```ts
-import { type Context } from "solid-js";
-
-function useContext<T>(context: Context<T>): T;
-```
+- [`createContext`](/reference/component-apis/create-context)
+- [Context](/concepts/context)
diff --git a/src/routes/reference/reactive-utilities/get-owner.mdx b/src/routes/reference/reactive-utilities/get-owner.mdx
index f4e21e3ab..11ececd8a 100644
--- a/src/routes/reference/reactive-utilities/get-owner.mdx
+++ b/src/routes/reference/reactive-utilities/get-owner.mdx
@@ -20,12 +20,13 @@ description: >-
 
 ```ts
 import { getOwner } from "solid-js";
-import type { Owner } from "solid-js";
 ```
 
 ## Type
 
 ```ts
+type Owner = unknown;
+
 function getOwner(): Owner | null;
 ```
 
diff --git a/src/routes/reference/reactive-utilities/run-with-owner.mdx b/src/routes/reference/reactive-utilities/run-with-owner.mdx
index ff728da81..0cf133efa 100644
--- a/src/routes/reference/reactive-utilities/run-with-owner.mdx
+++ b/src/routes/reference/reactive-utilities/run-with-owner.mdx
@@ -22,12 +22,13 @@ description: >-
 
 ```ts
 import { runWithOwner } from "solid-js";
-import type { Owner } from "solid-js";
 ```
 
 ## Type
 
 ```ts
+type Owner = unknown;
+
 function runWithOwner<T>(owner: Owner | null, fn: () => T): T | undefined;
 ```
 
diff --git a/src/routes/reference/reactive-utilities/start-transition.mdx b/src/routes/reference/reactive-utilities/start-transition.mdx
index 92a27daf2..2f526b75f 100644
--- a/src/routes/reference/reactive-utilities/start-transition.mdx
+++ b/src/routes/reference/reactive-utilities/start-transition.mdx
@@ -52,7 +52,7 @@ Resolves when the transition completes.
 
 ## Examples
 
-### Start a transition
+### Basic usage
 
 ```tsx
 import { createSignal, startTransition } from "solid-js";
diff --git a/src/routes/reference/reactive-utilities/use-transition.mdx b/src/routes/reference/reactive-utilities/use-transition.mdx
index 894d633de..749e1e605 100644
--- a/src/routes/reference/reactive-utilities/use-transition.mdx
+++ b/src/routes/reference/reactive-utilities/use-transition.mdx
@@ -53,7 +53,7 @@ Returns a tuple containing:
 
 ## Examples
 
-### Read transition state
+### Basic usage
 
 ```tsx
 import { createSignal, useTransition } from "solid-js";

From 67a8923165eb6579ef9266443877d34b2935f899 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 13:17:08 -0700
Subject: [PATCH 06/88] docs: update documentation for createContext,
 createDeferred, createReaction, createSelector, indexArray, and mapArray

---
 .../component-apis/create-context.mdx         |   7 --
 .../reactive-utilities/index-array.mdx        |   6 -
 .../reactive-utilities/map-array.mdx          |   6 -
 .../secondary-primitives/create-deferred.mdx  |  92 ++++++++++++--
 .../secondary-primitives/create-reaction.mdx  |   6 -
 .../secondary-primitives/create-selector.mdx  | 116 +++++++++++-------
 6 files changed, 151 insertions(+), 82 deletions(-)

diff --git a/src/routes/reference/component-apis/create-context.mdx b/src/routes/reference/component-apis/create-context.mdx
index 382fb3f28..93fd78195 100644
--- a/src/routes/reference/component-apis/create-context.mdx
+++ b/src/routes/reference/component-apis/create-context.mdx
@@ -44,21 +44,14 @@ function createContext<T>(
 ### `defaultValue`
 
 - **Type:** `T`
-- **Required:** No
 
 Default value returned by [`useContext`](/reference/component-apis/use-context) when no matching provider is found.
 
 ### `options`
 
-- **Type:** `{ name?: string }`
-- **Required:** No
-
-Optional configuration object.
-
 #### `name`
 
 - **Type:** `string`
-- **Required:** No
 
 Debug name used by development tooling.
 
diff --git a/src/routes/reference/reactive-utilities/index-array.mdx b/src/routes/reference/reactive-utilities/index-array.mdx
index 5aa4959af..104209c90 100644
--- a/src/routes/reference/reactive-utilities/index-array.mdx
+++ b/src/routes/reference/reactive-utilities/index-array.mdx
@@ -51,15 +51,9 @@ Mapping function for each index.
 
 ### `options`
 
-- **Type:** `{ fallback?: () => any }`
-- **Required:** No
-
-Optional configuration object.
-
 #### `fallback`
 
 - **Type:** `() => any`
-- **Required:** No
 
 Fallback accessor used when the source array is empty or falsy.
 
diff --git a/src/routes/reference/reactive-utilities/map-array.mdx b/src/routes/reference/reactive-utilities/map-array.mdx
index 1dd563f67..1c21f4dac 100644
--- a/src/routes/reference/reactive-utilities/map-array.mdx
+++ b/src/routes/reference/reactive-utilities/map-array.mdx
@@ -51,15 +51,9 @@ Mapping function for each item.
 
 ### `options`
 
-- **Type:** `{ fallback?: () => any }`
-- **Required:** No
-
-Optional configuration object.
-
 #### `fallback`
 
 - **Type:** `() => any`
-- **Required:** No
 
 Fallback accessor used when the source array is empty or falsy.
 
diff --git a/src/routes/reference/secondary-primitives/create-deferred.mdx b/src/routes/reference/secondary-primitives/create-deferred.mdx
index 9f7debad4..980b3b7da 100644
--- a/src/routes/reference/secondary-primitives/create-deferred.mdx
+++ b/src/routes/reference/secondary-primitives/create-deferred.mdx
@@ -11,30 +11,98 @@ tags:
   - updates
 version: "1.0"
 description: >-
-  Defer reactive updates until browser idle with createDeferred. Optimize
-  performance by batching non-critical changes with timeout control.
+  Create a deferred accessor that updates when the browser is idle or when the
+  timeout is reached.
 ---
 
+`createDeferred` returns a deferred accessor for a source accessor.
+
+## Import
+
 ```ts
 import { createDeferred } from "solid-js";
+```
+
+## Type
+
+```ts
+type Accessor<T> = () => T;
 
 function createDeferred<T>(
-	source: () => T,
+	source: Accessor<T>,
 	options?: {
 		timeoutMs?: number;
 		equals?: false | ((prev: T, next: T) => boolean);
 		name?: string;
 	}
-): () => T;
+): Accessor<T>;
 ```
 
-Creates a readonly that only notifies downstream changes when the browser is idle.
-`timeoutMs` is the maximum time to wait before forcing the update.
+## Parameters
+
+### `source`
+
+- **Type:** `Accessor<T>`
+- **Required:** Yes
+
+Accessor used as the deferred source.
+
+### `options`
+
+#### `timeoutMs`
+
+- **Type:** `number`
+
+Maximum delay before the deferred value is updated.
+
+#### `equals`
+
+- **Type:** `false | ((prev: T, next: T) => boolean)`
+
+Comparison function used to determine whether the deferred accessor should notify dependents.
+
+#### `name`
+
+- **Type:** `string`
+
+Debug name used by development tooling.
+
+## Return value
+
+- **Type:** `Accessor<T>`
+
+Returns an accessor that exposes the deferred value.
+
+## Behavior
+
+- The deferred accessor updates after the browser becomes idle or after `timeoutMs` is reached.
+- The returned accessor can lag behind the source accessor.
+- `equals` controls whether downstream dependents are notified for a new value.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { createDeferred, createSignal } from "solid-js";
+
+function Example() {
+	const [value, setValue] = createSignal("");
+	const deferredValue = createDeferred(value);
+
+	return (
+		<>
+			<input
+				value={value()}
+				onInput={(event) => setValue(event.currentTarget.value)}
+			/>
+			<div>{deferredValue()}</div>
+		</>
+	);
+}
+```
 
-## Options
+## Related
 
-| Name      | Type                                       | Description                                            |
-| --------- | ------------------------------------------ | ------------------------------------------------------ |
-| timeoutMs | `number`                                   | The maximum time to wait before forcing the update.    |
-| equals    | `false or ((prev: T, next: T) => boolean)` | A function that returns true if the value has changed. |
-| name      | `string`                                   | The name of the readonly.                              |
+- [`createMemo`](/reference/basic-reactivity/create-memo)
+- [`startTransition`](/reference/reactive-utilities/start-transition)
diff --git a/src/routes/reference/secondary-primitives/create-reaction.mdx b/src/routes/reference/secondary-primitives/create-reaction.mdx
index 0ef6c6dea..9390c818e 100644
--- a/src/routes/reference/secondary-primitives/create-reaction.mdx
+++ b/src/routes/reference/secondary-primitives/create-reaction.mdx
@@ -42,15 +42,9 @@ Callback invoked when the tracked computation is invalidated.
 
 ### `options`
 
-- **Type:** `{ name?: string }`
-- **Required:** No
-
-Optional configuration object.
-
 #### `name`
 
 - **Type:** `string`
-- **Required:** No
 
 Debug name used by development tooling.
 
diff --git a/src/routes/reference/secondary-primitives/create-selector.mdx b/src/routes/reference/secondary-primitives/create-selector.mdx
index a2b4e7ece..205f0e94c 100644
--- a/src/routes/reference/secondary-primitives/create-selector.mdx
+++ b/src/routes/reference/secondary-primitives/create-selector.mdx
@@ -11,66 +11,92 @@ tags:
   - optimization
 version: "1.0"
 description: >-
-  Optimize selection state with createSelector. Reduce DOM updates from n to 2
-  when tracking active items in lists, tabs, or dropdowns.
+  Create a keyed boolean accessor that reports whether a key matches the current
+  source value.
 ---
 
+`createSelector` returns a keyed boolean accessor derived from a source accessor.
+
+## Import
+
 ```ts
 import { createSelector } from "solid-js";
+```
+
+## Type
+
+```ts
+type Accessor<T> = () => T;
 
-function createSelector<T, U>(
-	source: () => T,
-	fn?: (a: U, b: T) => boolean
+function createSelector<T, U = T>(
+	source: Accessor<T>,
+	fn?: (key: U, value: T) => boolean,
+	options?: { name?: string }
 ): (key: U) => boolean;
 ```
 
-Creates a parameterized derived boolean signal `selector(key)` that indicates
-whether `key` is equal to the current value of the `source` signal.
-These signals are optimized to notify each subscriber only when their `key`
-starts or stops matching the reactive `source` value
-(instead of every time `key` changes).
-If you have _n_ different subscribers with different keys,
-and the `source` value changes from `a` to `b`, then
-instead of all _n_ subscribers updating,
-at most two subscribers will update:
-the signal with key `a` will change to `false`,
-and the signal with key `b` will change to `true`.
-Thus it reduces from _n_ updates to 2 updates.
-
-Useful for defining the selection state of several selectable elements.
-For example:
+## Parameters
 
-```tsx
-const [selectedId, setSelectedId] = createSignal()
-const isSelected = createSelector(selectedId)
+### `source`
 
-<For each={list()}>
-	{(item) => <li classList={{ active: isSelected(item.id) }}>{item.name}</li>}
-</For>
-```
+- **Type:** `Accessor<T>`
+- **Required:** Yes
+
+Accessor used as the selection source.
+
+### `fn`
+
+- **Type:** `(key: U, value: T) => boolean`
 
-In the code above, each `li` element receives an `active` class
-exactly when the corresponding `item.id` is equal to `selectedId()`.
-When the `selectedId` signal changes, the `li` element(s) that previously
-had previously matching `id` get the `active` class removed, and the
-`li` element(s) that now have a matching `id` get the `active` class added.
-All other `li` elements get skipped, so if `id`s are distinct,
-only 2 DOM operations get performed.
+Comparison function used to match a key against the current source value.
 
-By contrast, the following code would perform `list().length` DOM operations
-every time the `selectedId` signal changes:
+### `options`
+
+#### `name`
+
+- **Type:** `string`
+
+Debug name used by development tooling.
+
+## Return value
+
+- **Type:** `(key: U) => boolean`
+
+Returns an accessor function that reports whether the provided key matches the current source value.
+
+## Behavior
+
+- The returned function compares each key against the current source value.
+- With the default comparison, matching uses strict equality.
+- Subscribers update when their key starts or stops matching the source value.
+
+## Examples
+
+### Basic usage
 
 ```tsx
-const [selectedId, setSelectedId] = createSignal()
+import { createSelector, createSignal, For } from "solid-js";
+
+function Example(props) {
+	const [selectedId, setSelectedId] = createSignal<number>();
+	const isSelected = createSelector(selectedId);
 
-<For each={list()}>
-	{(item) => <li classList={{ active: selectedId() === item.id }}>{item.name}</li>}
-</For>
+	return (
+		<For each={props.list}>
+			{(item) => (
+				<li
+					classList={{ active: isSelected(item.id) }}
+					onClick={() => setSelectedId(item.id)}
+				>
+					{item.name}
+				</li>
+			)}
+		</For>
+	);
+}
 ```
 
-## Arguments
+## Related
 
-| Name     | Type                      | Description                                                                                                    |
-| :------- | :------------------------ | :------------------------------------------------------------------------------------------------------------- |
-| `source` | `() => T`                 | The source signal to get the value from and compare with keys.                                                 |
-| `fn`     | `(a: U, b: T) => boolean` | A function to compare the key and the value, returning whether they should be treated as equal. Default: `===` |
+- [`createMemo`](/reference/basic-reactivity/create-memo)
+- [`<For>`](/reference/components/for)

From 2057f6abb9b258a03a6dcfbf57414027f758fcfb Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 13:25:05 -0700
Subject: [PATCH 07/88] docs: update documentation for <Dynamic>, mergeProps,
 <Portal>, and splitProps

---
 src/routes/reference/components/dynamic.mdx   | 108 ++++++++++++++----
 src/routes/reference/components/portal.mdx    |  95 +++++++++++----
 .../reactive-utilities/merge-props.mdx        |  68 ++++++++---
 .../reactive-utilities/split-props.mdx        |  75 ++++++++----
 4 files changed, 265 insertions(+), 81 deletions(-)

diff --git a/src/routes/reference/components/dynamic.mdx b/src/routes/reference/components/dynamic.mdx
index ab3c721d6..8229c7e26 100644
--- a/src/routes/reference/components/dynamic.mdx
+++ b/src/routes/reference/components/dynamic.mdx
@@ -2,45 +2,109 @@
 title: <Dynamic>
 order: 5
 use_cases: >-
-  dynamic components, conditional rendering, polymorphic components, runtime
-  component selection, flexible ui, component switching
+  dynamic components, runtime component selection, polymorphic components,
+  rendering custom components or intrinsic elements
 tags:
   - dynamic
   - components
   - jsx
   - polymorphic
   - rendering
-  - conditional
 version: "1.0"
 description: >-
-  Render components dynamically at runtime with the Dynamic component. Perfect
-  for polymorphic components and conditional component rendering.
+  Render a component or intrinsic element selected at runtime, and access the
+  lower-level `createDynamic` helper.
 ---
 
-This component lets you insert an arbitrary Component or tag and passes the props through to it.
+`<Dynamic>` renders the value of its `component` prop as either a custom component or an intrinsic element. `createDynamic` provides the same behavior as a function.
+
+## Import
+
+```ts
+import { Dynamic, createDynamic } from "solid-js/web";
+```
+
+## Type
+
+```ts
+type ValidComponent =
+	| keyof JSX.IntrinsicElements
+	| ((props: any) => JSX.Element);
+
+type DynamicProps<T extends ValidComponent> = {
+	component: T | undefined;
+} & Record<string, unknown>;
+
+function createDynamic<T extends ValidComponent>(
+	component: () => T | undefined,
+	props: Record<string, unknown>
+): JSX.Element;
+
+function Dynamic<T extends ValidComponent>(props: DynamicProps<T>): JSX.Element;
+```
+
+## Props
+
+### `component`
+
+- **Type:** `T | undefined`
+
+Component or intrinsic element to render.
+
+### remaining props
+
+- **Type:** props accepted by the rendered component or element
+
+Props forwarded to the rendered value of `component`.
+
+## Parameters
+
+### `component`
+
+- **Type:** `() => T | undefined`
+
+Accessor that returns the component or intrinsic element to render.
+
+### `props`
+
+- **Type:** `Record<string, unknown>`
+
+Props passed to the rendered component or element.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+Returns the rendered component or element.
+
+## Behavior
+
+- When `component` resolves to a function, Solid calls that component with the provided props.
+- When `component` resolves to a string, Solid creates an intrinsic element of that type and spreads the provided props onto it.
+- `<Dynamic>` calls `createDynamic(() => props.component, others)` internally after separating the `component` prop from the remaining props.
+
+## Examples
+
+### Basic usage
 
 ```tsx
 import { Dynamic } from "solid-js/web";
-import type { JSX } from "solid-js";
-
-function Dynamic<T>(
-	props: T & {
-		children?: any;
-		component?: Component<T> | string | keyof JSX.IntrinsicElements;
-	}
-): () => JSX.Element;
+
+function Example(props) {
+	return <Dynamic component={props.as} value={props.value} />;
+}
 ```
 
-Here's an example of how you can use it:
+### `createDynamic`
 
 ```tsx
-<Dynamic component={MyComponent} someProp={state.something} />
+import { createDynamic } from "solid-js/web";
+
+function Example(props) {
+	return createDynamic(() => props.as, { value: props.value });
+}
 ```
 
-## Props
+## Related
 
-| Name        | Type                                                        | Description                               |
-| :---------- | :---------------------------------------------------------- | :---------------------------------------- |
-| `component` | `Component<T>` \| `string` \| `keyof JSX.IntrinsicElements` | The component to render.                  |
-| `children`  | `any`                                                       | The children to pass to the component.    |
-| `...`       | `T`                                                         | Any other props to pass to the component. |
+- [`<Portal>`](/reference/components/portal)
diff --git a/src/routes/reference/components/portal.mdx b/src/routes/reference/components/portal.mdx
index 1dffac6a5..23c9b7449 100644
--- a/src/routes/reference/components/portal.mdx
+++ b/src/routes/reference/components/portal.mdx
@@ -1,52 +1,103 @@
 ---
 title: <Portal>
-use_cases: "modals, tooltips, overlays, popups, dropdowns, ui layers, escape dom hierarchy"
+use_cases: >-
+  modals, tooltips, overlays, popups, dropdowns, rendering outside parent DOM
+  hierarchy
 tags:
   - portal
-  - modals
   - dom
   - overlays
   - tooltips
   - components
 version: "1.0"
 description: >-
-  Render SolidJS components outside parent DOM hierarchy with Portal. Perfect
-  for modals, tooltips, and overlays that need to escape layout.
+  Render children into a DOM node outside the parent DOM hierarchy.
 ---
 
-`<Portal>` is a component that allows you to render children into a DOM node that exists outside the DOM hierarchy of the parent component.
+`<Portal>` renders its children into a different DOM node while preserving the Solid component hierarchy.
 
-This is useful when your UI has some elements that need to appear on top of everything else, such as modals and tooltips.
+## Import
 
-```tsx
+```ts
 import { Portal } from "solid-js/web";
-import type { JSX } from "solid-js";
+```
 
+## Type
+
+```ts
 function Portal(props: {
 	mount?: Node;
 	useShadow?: boolean;
 	isSVG?: boolean;
+	ref?:
+		| HTMLDivElement
+		| SVGGElement
+		| ((el: HTMLDivElement | SVGGElement) => void);
 	children: JSX.Element;
 }): Text;
 ```
 
-This inserts the element in the mount node.
-Useful for inserting Modals outside of the page layout.
-Events still propagate through the component hierarchy, however `<Portal>` will only run on the client and has hydration _disabled_.
+## Props
+
+### `mount`
+
+- **Type:** `Node`
+
+Mount point for the portal. When omitted, the portal mounts to `document.body`.
+
+### `useShadow`
+
+- **Type:** `boolean`
+
+Creates a shadow root on the portal container when supported.
+
+### `isSVG`
+
+- **Type:** `boolean`
+
+Creates an SVG `<g>` container instead of an HTML `<div>`.
+
+### `ref`
 
-The portal is mounted in a `<div>` unless the target is the document head.
-`useShadow` places the element in a Shadow Root for style isolation, and `isSVG` is required if inserting into an SVG element so that the `<div>` is not inserted.
+- **Type:** `HTMLDivElement | SVGGElement | ((el: HTMLDivElement | SVGGElement) => void)`
+
+Receives the portal container element.
+
+### `children`
+
+- **Type:** `JSX.Element`
+
+Content rendered into the portal container.
+
+## Return value
+
+- **Type:** `Text`
+
+Returns a marker node used to preserve the portal position in the component tree.
+
+## Behavior
+
+- `<Portal>` renders its children outside the parent DOM hierarchy, but events still propagate through the Solid component hierarchy.
+- When the mount target is not `document.head`, the portal creates a container element and appends it to the mount target.
+- When the mount target is `document.head`, the portal inserts its children without creating that container element.
+- Portals render only on the client and are skipped during hydration.
+
+## Examples
+
+### Basic usage
 
 ```tsx
-<Portal mount={document.getElementById("modal")}>
-	<div>My Content</div>
-</Portal>
+import { Portal } from "solid-js/web";
+
+function Example() {
+	return (
+		<Portal mount={document.getElementById("modal-root")!}>
+			<div>My Content</div>
+		</Portal>
+	);
+}
 ```
 
-## Props
+## Related
 
-| Name        | Type      | Default       | Description                                       |
-| :---------- | :-------- | :------------ | :------------------------------------------------ |
-| `mount`     | `Node`    | document.body | The DOM node to mount the portal in.              |
-| `useShadow` | `boolean` | false         | Whether to use a Shadow Root for style isolation. |
-| `isSVG`     | `boolean` | false         | Whether the mount node is an SVG element.         |
+- [`<Dynamic>`](/reference/components/dynamic)
diff --git a/src/routes/reference/reactive-utilities/merge-props.mdx b/src/routes/reference/reactive-utilities/merge-props.mdx
index 85eab1176..b804b7d7d 100644
--- a/src/routes/reference/reactive-utilities/merge-props.mdx
+++ b/src/routes/reference/reactive-utilities/merge-props.mdx
@@ -1,41 +1,75 @@
 ---
 title: mergeProps
 use_cases: >-
-  component props, default values, prop cloning, prop merging, component
-  configuration
+  component props, default values, prop cloning, combining multiple prop
+  sources
 tags:
   - props
   - components
   - reactivity
   - defaults
-  - cloning
   - merging
 version: "1.0"
 description: >-
-  Learn how to merge reactive props in SolidJS for setting component defaults,
-  cloning props objects, and combining multiple prop sources dynamically.
+  Merge multiple prop sources into a single object while preserving reactive
+  property access.
 ---
 
+`mergeProps` merges prop sources from left to right and resolves reads from the last source that defines each property.
+
+## Import
+
 ```ts
 import { mergeProps } from "solid-js";
+```
 
-function mergeProps(...sources: any): any;
+## Type
+
+```ts
+function mergeProps<T extends unknown[]>(
+	...sources: T
+): Record<string, unknown>;
 ```
 
-A reactive object **merge** method.
-Useful for setting default props for components in case caller doesn't provide them.
-Or cloning the props object including reactive properties.
+## Parameters
+
+### `sources`
+
+- **Type:** `unknown[]`
+
+Prop sources to merge.
+
+## Return value
+
+- **Type:** `Record<string, unknown>`
+
+Returns an object that resolves each property from the last source that defines it.
 
-This method works by using a proxy and resolving properties in reverse order.
-This allows for dynamic tracking of properties that aren't present when the prop object is first merged.
+## Behavior
+
+- Later sources override earlier sources for the same property.
+- Function sources are wrapped so property reads stay reactive.
+- When reactive proxies are involved, the merged result uses proxy-backed property resolution.
+- Property lookups are resolved when read rather than copied eagerly from every source.
+
+## Examples
+
+### Basic usage
 
 ```ts
-// default props
-props = mergeProps({ name: "Smith" }, props);
+import { mergeProps } from "solid-js";
+
+const props = mergeProps({ name: "Smith" }, incomingProps);
+```
 
-// clone props
-newProps = mergeProps(props);
+### Clone props
 
-// merge props
-props = mergeProps(props, otherProps);
+```ts
+import { mergeProps } from "solid-js";
+
+const clonedProps = mergeProps(props);
 ```
+
+## Related
+
+- [`splitProps`](/reference/reactive-utilities/split-props)
diff --git a/src/routes/reference/reactive-utilities/split-props.mdx b/src/routes/reference/reactive-utilities/split-props.mdx
index 0973baf63..1f7e03fe9 100644
--- a/src/routes/reference/reactive-utilities/split-props.mdx
+++ b/src/routes/reference/reactive-utilities/split-props.mdx
@@ -1,8 +1,8 @@
 ---
 title: splitProps
 use_cases: >-
-  prop forwarding, component composition, prop separation, child components,
-  prop destructuring
+  prop forwarding, component composition, prop separation, splitting props into
+  multiple groups
 tags:
   - props
   - components
@@ -11,27 +11,61 @@ tags:
   - reactive
 version: "1.0"
 description: >-
-  Split reactive props objects by keys in SolidJS. Perfect for consuming
-  specific props while forwarding others to child components efficiently.
+  Split a reactive props object into multiple reactive subsets and a remainder
+  object.
 ---
 
+`splitProps` partitions a props object by key groups and returns a reactive object for each group plus a final object containing the remaining keys.
+
+## Import
+
 ```ts
 import { splitProps } from "solid-js";
+```
+
+## Type
 
-function splitProps<T>(
+```ts
+function splitProps<T extends Record<string, unknown>>(
 	props: T,
-	...keys: Array<(keyof T)[]>
-): [...parts: Partial<T>];
+	...keys: (readonly (keyof T)[])[]
+): Record<string, unknown>[];
 ```
 
-Splits a reactive object by keys.
+## Parameters
+
+### `props`
+
+- **Type:** `T`
+
+Source props object.
+
+### `keys`
+
+- **Type:** `(readonly (keyof T)[])[]`
+
+Arrays of keys that determine each returned subset.
+
+## Return value
+
+- **Type:** `Record<string, unknown>[]`
 
-It takes a reactive object and any number of arrays of keys; for each array of keys, it will return a reactive object with just those properties of the original object.
-The last reactive object in the returned array will have any leftover properties of the original object.
+Returns one reactive object for each key array and a final object containing keys not assigned to any earlier group.
 
-This can be useful if you want to consume a subset of props and pass the rest to a child.
+## Behavior
+
+- Each returned object preserves reactive property access.
+- Keys are assigned to the first matching group.
+- The last returned object contains keys not included in the provided key arrays.
+- When the source props object is proxy-backed, the returned objects use proxy-backed property access.
+
+## Examples
+
+### Basic usage
 
 ```tsx
+import { splitProps } from "solid-js";
+
 function MyComponent(props) {
 	const [local, others] = splitProps(props, ["children"]);
 
@@ -44,23 +78,24 @@ function MyComponent(props) {
 }
 ```
 
-Because `splitProps` takes any number of arrays, we can split a props object as much as we wish (if, for example, we had multiple child components that each required a subset of the props).
-
-Let's say a component was passed six props:
+### Split multiple groups
 
 ```tsx
-<MyComponent a={1} b={2} c={3} d={4} e={5} foo="bar" />;
-// ...
+import { splitProps } from "solid-js";
 
 function MyComponent(props) {
-	console.log(props); // {a: 1, b: 2, c: 3, d: 4, e: 5, foo: "bar"}
 	const [vowels, consonants, leftovers] = splitProps(
 		props,
 		["a", "e"],
 		["b", "c", "d"]
 	);
-	console.log(vowels); // {a: 1, e: 5}
-	console.log(consonants); // {b: 2, c: 3, d: 4}
-	console.log(leftovers.foo); // bar
+
+	return (
+		<Child vowels={vowels} consonants={consonants} leftovers={leftovers} />
+	);
 }
 ```
+
+## Related
+
+- [`mergeProps`](/reference/reactive-utilities/merge-props)

From 0374d22c2cfbeb24f76cc3e9717ebf67a2a4c134 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 13:36:17 -0700
Subject: [PATCH 08/88] docs: update documentation for <Dynamic>, mergeProps,
 <Portal>, and splitProps

---
 src/routes/reference/components/for.mdx       |  89 +++++++---
 .../reference/components/index-component.mdx  |  95 +++++++----
 src/routes/reference/components/show.mdx      | 156 ++++++++++--------
 .../reference/components/switch-and-match.mdx | 111 +++++++++----
 4 files changed, 283 insertions(+), 168 deletions(-)

diff --git a/src/routes/reference/components/for.mdx b/src/routes/reference/components/for.mdx
index 2128f18a8..631b9a82d 100644
--- a/src/routes/reference/components/for.mdx
+++ b/src/routes/reference/components/for.mdx
@@ -13,53 +13,88 @@ tags:
   - performance
 version: "1.0"
 description: >-
-  Efficiently render lists in SolidJS with the For component. Provides keyed
-  iteration with minimal DOM updates for dynamic array rendering.
+  Render a list by item identity with a child function that receives the item
+  and an index accessor.
 ---
 
-The `<For>` component is used to render a list of items. It is similar to the `.map()` function in JavaScript.
+`<For>` renders a list by item identity.
+
+## Import
 
 ```ts
 import { For } from "solid-js";
-import type { JSX } from "solid-js";
+```
 
-function For<T, U extends JSX.Element>(props: {
-	each: readonly T[];
+## Type
+
+```ts
+type Accessor<T> = () => T;
+
+function For<T extends readonly any[], U extends JSX.Element>(props: {
+	each: T | undefined | null | false;
 	fallback?: JSX.Element;
-	children: (item: T, index: () => number) => U;
-}): () => U[];
+	children: (item: T[number], index: Accessor<number>) => U;
+}): JSX.Element;
 ```
 
-A referentially keyed loop with efficient updating of only changed items. The callback takes the current item as the first argument:
+## Props
 
-```jsx
-<For each={state.list} fallback={<div>Loading...</div>}>
-	{(item) => <div>{item}</div>}
-</For>
-```
+### `each`
+
+- **Type:** `T | undefined | null | false`
+
+Source list.
+
+### `fallback`
+
+- **Type:** `JSX.Element`
+
+Content rendered when `each` is empty or falsy.
+
+### `children`
 
-The `each` prop can also be a function that returns a list. This is useful for creating a loop that depends on a state value:
+- **Type:** `(item: T[number], index: Accessor<number>) => U`
 
-```jsx
-<For each={stateSignal()}>{(item) => <div>{item}</div>}</For>
+Child function. It receives the current item and an index accessor.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+## Behavior
+
+- `<For>` maps items by value identity.
+- The `index` argument is an accessor.
+- Reordering reuses rendered items whose source values are retained.
+- `<For>` uses [`mapArray`](/reference/reactive-utilities/map-array) internally.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { For } from "solid-js";
+
+<For each={state.list} fallback={<div>No items</div>}>
+	{(item) => <div>{item}</div>}
+</For>;
 ```
 
-The optional second argument is an index signal:
+### Access the index
 
-```jsx
-<For each={state.list} fallback={<div>Loading...</div>}>
+```tsx
+import { For } from "solid-js";
+
+<For each={state.list}>
 	{(item, index) => (
 		<div>
 			#{index()} {item}
 		</div>
 	)}
-</For>
+</For>;
 ```
 
-## Props
+## Related
 
-| Name       | Type                                  | Description                                                      |
-| :--------- | :------------------------------------ | :--------------------------------------------------------------- |
-| `each`     | `readonly T[]`                        | The list of items to render.                                     |
-| `fallback` | `JSX.Element`                         | A fallback element to render while the list is loading.          |
-| `children` | `(item: T, index: () => number) => U` | A callback that returns a JSX element for each item in the list. |
+- [`<Index>`](/reference/components/index-component)
+- [`mapArray`](/reference/reactive-utilities/map-array)
diff --git a/src/routes/reference/components/index-component.mdx b/src/routes/reference/components/index-component.mdx
index 3c42430c3..4ec170c1c 100644
--- a/src/routes/reference/components/index-component.mdx
+++ b/src/routes/reference/components/index-component.mdx
@@ -12,64 +12,89 @@ tags:
   - index
 version: "1.0"
 description: >-
-  Render non-keyed lists in SolidJS with Index component. Perfect for primitive
-  arrays where index position matters more than item identity.
+  Render a list by index with a child function that receives an item accessor
+  and a numeric index.
 ---
 
-Non-keyed list iteration (rendered nodes are keyed to an array index). This is useful when there is no conceptual key, like if the data consists of primitives and it is the index that is fixed rather than the value.
+`<Index>` renders a list by index.
+
+## Import
 
 ```ts
 import { Index } from "solid-js";
-import type { JSX } from "solid-js";
-
-function Index<T, U extends JSX.Element>(props: {
-	each: readonly T[];
-	fallback?: JSX.Element;
-	children: (item: () => T, index: number) => U;
-}): () => U[];
 ```
 
-A super simple implementation of this component might look like this:
+## Type
 
-```tsx
-function Index<T, U extends JSX.Element>(props: {
-	each: readonly T[];
+```ts
+type Accessor<T> = () => T;
+
+function Index<T extends readonly any[], U extends JSX.Element>(props: {
+	each: T | undefined | null | false;
 	fallback?: JSX.Element;
-	children: (item: () => T, index: number) => U;
-}) {
-	return () => {
-		const [items, setItems] = createSignal(props.each);
-		return props.each.map((_, i) => props.children(() => items()[i], i));
-	};
-}
+	children: (item: Accessor<T[number]>, index: number) => U;
+}): JSX.Element;
 ```
 
-Here's a look at the implementation of the `Index` component in Solid:
+## Props
+
+### `each`
+
+- **Type:** `T | undefined | null | false`
+
+Source list.
+
+### `fallback`
+
+- **Type:** `JSX.Element`
+
+Content rendered when `each` is empty or falsy.
+
+### `children`
+
+- **Type:** `(item: Accessor<T[number]>, index: number) => U`
+
+Child function. It receives an accessor for the item at that index and the index number.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+## Behavior
+
+- `<Index>` maps items by index rather than by value identity.
+- The `item` argument is an accessor.
+- The `index` argument is a number.
+- Updating a value at the same index updates the corresponding rendered item.
+- `<Index>` uses [`indexArray`](/reference/reactive-utilities/index-array) internally.
+
+## Examples
+
+### Basic usage
 
 ```tsx
-<Index each={state.list} fallback={<div>Loading...</div>}>
+import { Index } from "solid-js";
+
+<Index each={state.list} fallback={<div>No items</div>}>
 	{(item) => <div>{item()}</div>}
-</Index>
+</Index>;
 ```
 
-Notice that the item is a signal unlike the `For` component. This is because the `Index` component is not keyed to the item itself but rather the index.
-
-Optional second argument is an index number:
+### Access the index
 
 ```tsx
-<Index each={state.list} fallback={<div>Loading...</div>}>
+import { Index } from "solid-js";
+
+<Index each={state.list}>
 	{(item, index) => (
 		<div>
 			#{index} {item()}
 		</div>
 	)}
-</Index>
+</Index>;
 ```
 
-## Props
+## Related
 
-| Name     | Type                                  | Description                                                     |
-| :------- | :------------------------------------ | :-------------------------------------------------------------- |
-| each     | `readonly T[]`                        | The array to iterate over.                                      |
-| fallback | `JSX.Element`                         | Optional fallback element to render while the array is loading. |
-| children | `(item: () => T, index: number) => U` | The function that renders the children.                         |
+- [`<For>`](/reference/components/for)
+- [`indexArray`](/reference/reactive-utilities/index-array)
diff --git a/src/routes/reference/components/show.mdx b/src/routes/reference/components/show.mdx
index 7f51f9ca6..b5d843956 100644
--- a/src/routes/reference/components/show.mdx
+++ b/src/routes/reference/components/show.mdx
@@ -13,92 +13,106 @@ tags:
   - toggle
 version: "1.0"
 description: >-
-  Conditionally render UI elements in SolidJS with Show component. Display
-  content based on truthy conditions with optional fallback support.
+  Render children when a condition is truthy, with optional fallback content
+  and keyed behavior.
 ---
 
-The `<Show>` component is used for conditionally rendering UI elements.
-It takes a `when` prop that defines the condition for rendering.
-When the `when` prop is truthy, the children of the `<Show>` component are displayed.
-Additionally, an optional `fallback` prop can be provided to specify an element that is shown when the condition is falsy.
+`<Show>` renders its children when `when` is truthy and renders `fallback` otherwise.
 
-```tsx
-import { createSignal, Show } from "solid-js";
-
-function Example() {
-	const [value, setValue] = createSignal(true);
-	return (
-		<div>
-			<button onClick={() => setValue((prev) => !prev)}>Toggle Show</button>
-			<Show when={value()} fallback={<div>Fallback Element</div>}>
-				<div>Child Element</div>
-			</Show>
-		</div>
-	);
-}
+## Import
+
+```ts
+import { Show } from "solid-js";
+```
+
+## Type
+
+```ts
+type Accessor<T> = () => T;
+
+function Show<T>(props: {
+	when: T | undefined | null | false;
+	keyed?: false;
+	fallback?: JSX.Element;
+	children: JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element);
+}): JSX.Element;
+
+function Show<T>(props: {
+	when: T | undefined | null | false;
+	keyed: true;
+	fallback?: JSX.Element;
+	children: JSX.Element | ((item: NonNullable<T>) => JSX.Element);
+}): JSX.Element;
 ```
 
-## Keyed rendering
+## Props
+
+### `when`
+
+- **Type:** `T | undefined | null | false`
+
+Condition value that determines whether the children are rendered.
+
+### `keyed`
+
+- **Type:** `boolean`
+
+Controls whether function children receive the current value directly instead of an accessor.
+
+### `fallback`
 
-When the `keyed` is set to `true`, any change to the `when` prop — including changes in its reference — will cause the `<Show>` component to re-render its children.
+- **Type:** `JSX.Element`
+
+Content rendered when `when` is falsy.
+
+### `children`
+
+- **Type:** `JSX.Element | ((item) => JSX.Element)`
+
+Content rendered when `when` is truthy. Function children receive an accessor or value based on `keyed`.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+## Behavior
+
+- With `keyed` omitted or `false`, `<Show>` re-renders only when the truthiness of `when` changes.
+- With `keyed={true}`, changes to the `when` value itself trigger a new render even when the value remains truthy.
+- Function children are wrapped in [`untrack`](/reference/reactive-utilities/untrack).
+- With `keyed={false}`, function children receive an accessor for the current non-nullish value; with `keyed={true}`, they receive the value directly.
+
+## Examples
+
+### Basic usage
 
 ```tsx
-import { createSignal, Show } from "solid-js";
-
-function KeyedExample() {
-	const [user, setUser] = createSignal({ name: "John Wick" });
-
-	function update() {
-		// This operation changes the reference of the user object.
-		setUser({ ...user() });
-	}
-
-	return (
-		<div>
-			<button onClick={update}>Update</button>
-			<Show when={user()} keyed>
-				<p>Name: {user().name}</p>
-				{/* Updates shown with each click */}
-				<p>Last updated: {Date.now()}</p>
-			</Show>
-		</div>
-	);
-}
+import { Show } from "solid-js";
+
+<Show when={value()} fallback={<div>Fallback Element</div>}>
+	<div>Child Element</div>
+</Show>;
 ```
 
-## Render function
+### Function child
 
-The `<Show>` component can also accept a render function as its child.
-In this case, the first argument of the render function is an _accessor_ to the `when` prop.
-However, when the `keyed` prop is set to `true`, the argument is the `when` prop itself instead of an accessor.
+```tsx
+import { Show } from "solid-js";
 
-When a render function is used, it is internally wrapped with [`untrack`](/reference/reactive-utilities/untrack).
-As a result, signals accessed directly within the render function's scope will not react to updates.
+<Show when={user()}>{(user) => <div>{user().name}</div>}</Show>;
+```
 
-For example, in the following code, the count displayed in the first `<Show>` component does not update when the `count` signal changes.
-However, the second `<Show>` component does update since the `count` signal is accessed within a JSX element, which creates a tracking scope.
+### Keyed function child
 
 ```tsx
-import { createSignal, Show } from "solid-js";
-
-function RenderFunctionExample() {
-	const [count, setCount] = createSignal(0);
-	return (
-		<div>
-			<button onClick={() => setCount((c) => c + 1)}>Increment</button>
-			{/* This does not update. */}
-			<Show when={count()}>{(c) => count()}</Show>
-			{/* This will update. */}
-			<Show when={count()}>{(c) => <>{count()}</>}</Show>
-		</div>
-	);
-}
+import { Show } from "solid-js";
+
+<Show when={user()} keyed>
+	{(user) => <div>{user.name}</div>}
+</Show>;
 ```
 
-## Props
+## Related
 
-| Name       | Type                              | Description                                           |
-| :--------- | :-------------------------------- | :---------------------------------------------------- |
-| `when`     | `T \| undefined \| null \| false` | The condition value.                                  |
-| `keyed`    | `boolean`                         | Whether to key the block to the value of when.        |
-| `fallback` | `JSX.Element`                     | The fallback to render when the `when` prop is falsy. |
+- [`untrack`](/reference/reactive-utilities/untrack)
+- [`<Switch> / <Match>`](/reference/components/switch-and-match)
diff --git a/src/routes/reference/components/switch-and-match.mdx b/src/routes/reference/components/switch-and-match.mdx
index 98d1dcbfa..e4e65de38 100644
--- a/src/routes/reference/components/switch-and-match.mdx
+++ b/src/routes/reference/components/switch-and-match.mdx
@@ -13,48 +13,91 @@ tags:
   - switch
 version: "1.0"
 description: >-
-  Handle multiple exclusive conditions in SolidJS with Switch and Match. Clean
-  alternative to if-else chains for complex conditional rendering.
+  Render the first matching branch from a set of mutually exclusive conditions.
 ---
 
-Useful for when there are more than 2 mutual exclusive conditions. It is a more flexible version of the if-else-if-else-if-else-... chain.
+`<Switch>` renders the first child `<Match>` whose `when` prop is truthy. `<Match>` can render JSX directly or accept a function child.
+
+## Import
+
+```ts
+import { Match, Switch } from "solid-js";
+```
+
+## Type
 
 ```ts
-import { Switch, Match } from "solid-js";
-import type { MatchProps, JSX } from "solid-js";
+type Accessor<T> = () => T;
 
 function Switch(props: {
 	fallback?: JSX.Element;
 	children: JSX.Element;
-}): () => JSX.Element;
+}): JSX.Element;
+
+function Match<T>(props: {
+	when: T | undefined | null | false;
+	keyed?: false;
+	children: JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element);
+}): JSX.Element;
 
-type MatchProps<T> = {
+function Match<T>(props: {
 	when: T | undefined | null | false;
-	children: JSX.Element | ((item: T) => JSX.Element);
-};
-function Match<T>(props: MatchProps<T>);
+	keyed: true;
+	children: JSX.Element | ((item: NonNullable<T>) => JSX.Element);
+}): JSX.Element;
 ```
 
-A super simple implementation of this component would be:
+## `<Switch>` props
 
-```tsx
-function Switch(props) {
-	let children = props.children;
+### `fallback`
 
-	if (!Array.isArray(children)) children = [children];
+- **Type:** `JSX.Element`
 
-	for (let i = 0; i < children.length; i++) {
-		const child = children[i];
-		if (child.props.when) return child;
-	}
+Content rendered when no child `<Match>` has a truthy `when` value.
 
-	return props.fallback;
-}
-```
+### `children`
+
+- **Type:** `JSX.Element`
+
+Child `<Match>` elements.
+
+## `<Match>` props
+
+### `when`
+
+- **Type:** `T | undefined | null | false`
+
+Condition value for the branch.
 
-For example, it can be used to perform basic routing:
+### `keyed`
+
+- **Type:** `boolean`
+
+Controls whether function children receive the current value directly instead of an accessor.
+
+### `children`
+
+- **Type:** `JSX.Element | ((item) => JSX.Element)`
+
+Content rendered when the branch matches. Function children receive an accessor or value based on `keyed`.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+## Behavior
+
+- `<Switch>` evaluates its child `<Match>` elements in order and renders the first truthy branch.
+- If no branch matches, `<Switch>` renders `fallback`.
+- Function children in `<Match>` follow the same keyed behavior as [`<Show>`](/reference/components/show): with `keyed={false}`, they receive an accessor; with `keyed={true}`, they receive the value directly.
+
+## Examples
+
+### Basic usage
 
 ```tsx
+import { Match, Switch } from "solid-js";
+
 <Switch fallback={<div>Not Found</div>}>
 	<Match when={state.route === "home"}>
 		<Home />
@@ -62,21 +105,19 @@ For example, it can be used to perform basic routing:
 	<Match when={state.route === "settings"}>
 		<Settings />
 	</Match>
-</Switch>
+</Switch>;
 ```
 
-Match also supports function children to serve as keyed flow.
+### Function child
 
-## Props
-
-### Switch
+```tsx
+import { Match, Switch } from "solid-js";
 
-| Name       | Type          | Default     | Description                                                                      |
-| ---------- | ------------- | ----------- | -------------------------------------------------------------------------------- |
-| `fallback` | `JSX.Element` | `undefined` | The fallback element to render if no `Match` component has a truthy `when` prop. |
+<Switch>
+	<Match when={user()}>{(user) => <div>{user().name}</div>}</Match>
+</Switch>;
+```
 
-### Match
+## Related
 
-| Name   | Type                              | Default     | Description                                                               |
-| ------ | --------------------------------- | ----------- | ------------------------------------------------------------------------- |
-| `when` | `T \| undefined \| null \| false` | `undefined` | The condition to check. If it is truthy, the `children` will be rendered. |
+- [`<Show>`](/reference/components/show)

From b1c0bd4dc4020c63a6b7d6e1fd3c27d66b4b82b8 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 13:53:36 -0700
Subject: [PATCH 09/88] docs: update documentation for <Dynamic>, mergeProps,
 <Portal>, and splitProps

---
 .../reference/components/error-boundary.mdx   |  91 +++++-----
 .../reference/components/no-hydration.mdx     |  58 ++++--
 .../reference/components/suspense-list.mdx    |  86 +++++----
 src/routes/reference/components/suspense.mdx  | 165 +++++-------------
 4 files changed, 198 insertions(+), 202 deletions(-)

diff --git a/src/routes/reference/components/error-boundary.mdx b/src/routes/reference/components/error-boundary.mdx
index e3c295ae5..c222b6032 100644
--- a/src/routes/reference/components/error-boundary.mdx
+++ b/src/routes/reference/components/error-boundary.mdx
@@ -2,67 +2,80 @@
 title: <ErrorBoundary>
 order: 5
 use_cases: >-
-  error handling, production apps, preventing crashes, user experience,
-  debugging, fallback ui
+  error handling, rendering fallbacks, preventing subtree crashes, recovering
+  from render errors
 tags:
   - error-handling
   - components
-  - debugging
   - fallback
-  - production
   - stability
 version: "1.0"
 description: >-
-  Catch and handle rendering errors in SolidJS components with ErrorBoundary.
-  Display fallback UI when errors occur in children components.
+  Catch errors thrown while rendering or updating a subtree and render fallback
+  content.
 ---
 
-The `<ErrorBoundary>` component catches errors that occur during the rendering or updating of its children and shows a fallback UI instead.
-This includes:
+`<ErrorBoundary>` catches errors thrown while rendering or updating its children.
 
-- Errors that occur while rendering JSX.
-- Errors that occur within `createEffect`, `createMemo`, and other state management primitives.
-- Errors that occur within `createResource` and other asynchronous state management or data-fetching primitives.
+## Import
 
-However, errors occurring outside the rendering process are **not** captured by error boundaries.
-For instance:
+```ts
+import { ErrorBoundary } from "solid-js";
+```
 
-- Errors that occur inside event handlers.
-- Errors that occur after a `setTimeout`.
+## Type
+
+```ts
+function ErrorBoundary(props: {
+	fallback: JSX.Element | ((err: any, reset: () => void) => JSX.Element);
+	children: JSX.Element;
+}): JSX.Element;
+```
 
 ## Props
 
 ### `fallback`
 
-**Type**: `JSX.Element | ((err: any, reset: () => void) => JSX.Element)`
+- **Type:** `JSX.Element | ((err: any, reset: () => void) => JSX.Element)`
+
+Fallback content. Function fallbacks receive the caught error and a reset function.
+
+### `children`
+
+- **Type:** `JSX.Element`
 
-`fallback` provides content to display when an error occurs.
-If a function is passed, it receives two parameters:
+Subtree wrapped by the boundary.
 
-- `err`: The caught error object.
-- `reset`: A function that forces the `<ErrorBoundary>` to re-render its children and clear the error state.
+## Return value
 
-If there's an error within the `fallback` itself, however, it is not caught by the same `<ErrorBoundary>`.
-Instead, it will bubble up to any parent error boundaries.
+- **Type:** `JSX.Element`
 
-## Example
+## Behavior
+
+- `<ErrorBoundary>` catches errors thrown while rendering JSX and while updating reactive computations in its subtree.
+- Errors thrown from event handlers or from callbacks scheduled outside Solid's rendering and update flow are not caught by the boundary.
+- Function fallbacks receive `reset`, which clears the current error state and re-renders the children.
+- Errors thrown by the fallback itself can be caught by a parent error boundary.
+
+## Examples
+
+### Basic usage
 
 ```tsx
 import { ErrorBoundary } from "solid-js";
-import { ErrorProne } from "./components";
-
-function Example() {
-	return (
-		<ErrorBoundary
-			fallback={(error, reset) => (
-				<div>
-					<p>{error.message}</p>
-					<button onClick={reset}>Try Again</button>
-				</div>
-			)}
-		>
-			<ErrorProne />
-		</ErrorBoundary>
-	);
-}
+
+<ErrorBoundary
+	fallback={(error, reset) => (
+		<div>
+			<p>{error.message}</p>
+			<button onClick={reset}>Try Again</button>
+		</div>
+	)}
+>
+	<ErrorProne />
+</ErrorBoundary>;
 ```
+
+## Related
+
+- [`catchError`](/reference/reactive-utilities/catch-error)
diff --git a/src/routes/reference/components/no-hydration.mdx b/src/routes/reference/components/no-hydration.mdx
index eb142215f..0064ddb96 100644
--- a/src/routes/reference/components/no-hydration.mdx
+++ b/src/routes/reference/components/no-hydration.mdx
@@ -1,35 +1,57 @@
 ---
 title: <NoHydration>
 use_cases: >-
-  static content, ssr optimization, performance, reducing bundle size,
-  server-only rendering
+  static content, server-rendered content, skipping hydration for a subtree
 tags:
   - ssr
   - hydration
-  - optimization
-  - performance
-  - static
   - server-rendering
+  - components
 version: "1.0"
 description: >-
-  Prevent client-side hydration for static content in SolidJS. Optimize
-  performance by skipping hydration for server-rendered static elements.
+  Render children during server rendering and skip hydration for that subtree
+  on the client.
 ---
 
-The `<NoHydration>` component prevents the client-side hydration process from being applied to its children.
-During server-side rendering, components and elements wrapped within `<NoHydration>` will render normally on the server, contributing to the initial HTML output.
-However, during client-side hydration, Solid bypasses the hydration process for the content within `<NoHydration>`.
-This means that elements within `<NoHydration>` will not have event listeners attached by Solid, and their state will not be managed reactively on the client-side after the initial render.
+`<NoHydration>` skips hydration for its subtree on the client.
 
-:::note
-Placing a `<Hydration>` component inside `<NoHydration>` has no effect and will not override the `<NoHydration>` behavior.
-:::
+## Import
 
-## Example
+```ts
+import { NoHydration } from "solid-js/web";
+```
+
+## Type
+
+```ts
+function NoHydration(props: { children?: JSX.Element }): JSX.Element;
+```
+
+## Props
+
+### `children`
+
+- **Type:** `JSX.Element`
+
+Content inside the boundary.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+## Behavior
+
+- During server rendering, children inside `<NoHydration>` render normally.
+- During client hydration, Solid skips hydrating that subtree.
+- Event listeners and reactive updates are not attached to content inside the boundary during hydration.
+- Placing `<Hydration>` inside `<NoHydration>` does not override the no-hydration behavior.
+
+## Examples
+
+### Basic usage
 
 ```tsx
 import { NoHydration } from "solid-js/web";
-import { InteractiveComponent, StaticContent } from "./components";
 
 function Example() {
 	return (
@@ -42,3 +64,7 @@ function Example() {
 	);
 }
 ```
+
+## Related
+
+- [`<Portal>`](/reference/components/portal)
diff --git a/src/routes/reference/components/suspense-list.mdx b/src/routes/reference/components/suspense-list.mdx
index fa7754279..a819185c9 100644
--- a/src/routes/reference/components/suspense-list.mdx
+++ b/src/routes/reference/components/suspense-list.mdx
@@ -2,8 +2,8 @@
 title: <SuspenseList>
 order: 5
 use_cases: >-
-  coordinating loading, multiple async, loading sequences, layout stability,
-  parallel data fetching
+  coordinating suspense boundaries, controlling reveal order, coordinating
+  fallback display
 tags:
   - suspense
   - async
@@ -13,16 +13,20 @@ tags:
   - components
 version: "1.0"
 description: >-
-  Coordinate multiple Suspense components in SolidJS. Control reveal order and
-  manage loading states for parallel async operations smoothly.
+  Coordinate how multiple suspense boundaries reveal their content.
 ---
 
-SuspenseList allows for coordinating multiple parallel Suspense and SuspenseList components. It controls the order in which content is revealed to reduce layout thrashing and has an option to collapse or hide fallback states.
+`<SuspenseList>` coordinates nested suspense boundaries.
+
+## Import
 
 ```ts
 import { SuspenseList } from "solid-js";
-import type { JSX } from "solid-js";
+```
+
+## Type
 
+```ts
 function SuspenseList(props: {
 	children: JSX.Element;
 	revealOrder: "forwards" | "backwards" | "together";
@@ -30,37 +34,59 @@ function SuspenseList(props: {
 }): JSX.Element;
 ```
 
-**Note**: SuspenseList is still in the experimental stage and does not have full `SSR` support.
+## Props
 
-Here's an example of how to use SuspenseList:
+### `children`
 
-```tsx
-<SuspenseList revealOrder="forwards" tail="collapsed">
-	<ProfileDetails user={resource.user} />
-	<Suspense fallback={<h2>Loading posts...</h2>}>
-		<ProfileTimeline posts={resource.posts} />
-	</Suspense>
-	<Suspense fallback={<h2>Loading fun facts...</h2>}>
-		<ProfileTrivia trivia={resource.trivia} />
-	</Suspense>
-</SuspenseList>
-```
-
-## Props
+- **Type:** `JSX.Element`
 
-| Name          | Type                                      | Default      | Description                                                                 |
-| ------------- | ----------------------------------------- | ------------ | --------------------------------------------------------------------------- |
-| `revealOrder` | `"forwards" \| "backwards" \| "together"` | `"forwards"` | Determines the order in which the SuspenseList children should be revealed. |
-| `tail`        | `"collapsed" \| "hidden"`                 | `undefined`  | TODO                                                                        |
+Suspense and suspense-list children inside the list.
 
 ### `revealOrder`
 
-`"forwards" | "backwards" | "together"`
+- **Type:** `"forwards" | "backwards" | "together"`
 
-- `"forwards"`: Reveals each item in the list once the previous item has finished rendering. This is the default.
-- `"backwards"`: Reveals each item in the list once the next item has finished rendering.
-- `"together"`: Reveals all items in the list at the same time.
+Order used to reveal child boundaries.
 
 ### `tail`
 
-`"collapsed" | "hidden"`
+- **Type:** `"collapsed" | "hidden"`
+
+Controls fallback visibility for later items after the first still-pending item.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+## Behavior
+
+- `revealOrder="forwards"` reveals items from first to last.
+- `revealOrder="backwards"` reveals items from last to first.
+- `revealOrder="together"` reveals all items only after all coordinated boundaries are ready.
+- With `tail="collapsed"`, later pending items can keep a fallback visible after the first pending item.
+- With `tail="hidden"`, later pending items hide their fallback after the first pending item.
+
+## Notes
+
+- `<SuspenseList>` is experimental.
+
+## Examples
+
+### Basic usage
+
+```tsx
+import { Suspense, SuspenseList } from "solid-js";
+
+<SuspenseList revealOrder="forwards" tail="collapsed">
+	<Suspense fallback={<h2>Loading profile...</h2>}>
+		<ProfileDetails user={resource.user} />
+	</Suspense>
+	<Suspense fallback={<h2>Loading posts...</h2>}>
+		<ProfileTimeline posts={resource.posts} />
+	</Suspense>
+</SuspenseList>;
+```
+
+## Related
+
+- [`<Suspense>`](/reference/components/suspense)
diff --git a/src/routes/reference/components/suspense.mdx b/src/routes/reference/components/suspense.mdx
index 18bb5ef1b..c66a91041 100644
--- a/src/routes/reference/components/suspense.mdx
+++ b/src/routes/reference/components/suspense.mdx
@@ -2,157 +2,88 @@
 title: <Suspense>
 order: 5
 use_cases: >-
-  async data, loading states, data fetching, api calls, lazy loading, user
-  experience
+  async data, loading states, resources, lazy-loaded components, asynchronous
+  subtrees
 tags:
   - suspense
   - async
   - loading
   - resources
   - components
-  - data-fetching
 version: "1.0"
 description: >-
-  Handle async operations elegantly in SolidJS with Suspense. Show loading
-  states while resources load without blocking UI rendering.
+  Render fallback content while resources read under the boundary are pending.
 ---
 
-A component that tracks all resources read under it and shows a fallback placeholder state until they are resolved. What makes `Suspense` different than `Show` is that it is non-blocking in the sense that both branches exist at the same time even if not currently in the DOM. This means that the fallback can be rendered while the children are loading. This is useful for loading states and other asynchronous operations.
+`<Suspense>` tracks resources read under its boundary.
 
-```tsx
+## Import
+
+```ts
 import { Suspense } from "solid-js";
-import type { JSX } from "solid-js";
+```
+
+## Type
 
+```ts
 function Suspense(props: {
 	fallback?: JSX.Element;
 	children: JSX.Element;
 }): JSX.Element;
 ```
 
-Here's an example of a `Suspense` component that shows a loading spinner while the `User` component is loading.
+## Props
 
-```tsx
-<Suspense fallback={<LoadingSpinner />}>
-	<AsyncComponent />
-</Suspense>
-```
+### `fallback`
 
-## Nested Suspense
-
-`<Suspense>` is triggered whenever a resource is read under the suspense boundary, and waits until all resources read
-under the suspense boundary have resolved. Often, however, you may not want this behavior. For example, if your entire page is
-wrapped in suspense, you may not want a resource that only populates a certain part of the page to trigger suspense.
-In that case, you can wrap that resource usage in its own suspense boundary, and the resource will only trigger the
-closest suspense boundary.
-
-For example, in the code below, only the `title()` resource will trigger the top level suspense boundary, and only the `data()`
-resource will trigger the nested suspense boundary:
-
-```jsx
-const MyComponent = () => {
-	const [title] = createResource(async () => { /* fetcher code here */ })
-	const [data] = createResource(async () => { /* fetcher code here */ })
-	<Suspense>
-		<h1>{title()}</h1>
-		<Suspense>
-			<DataComponent>{data()}</DataComponent>
-		</Suspense>
-	</Suspense>
-}
+- **Type:** `JSX.Element`
 
-```
+Content rendered while tracked resources are pending.
 
-## The purpose of `<Suspense>`
+### `children`
 
-To understand the purpose of suspense, let's consider the following code snippets. These snippets will have some drawbacks which we will solve by using suspense. We will also see how it is possible to use `Suspense` yet not reap its benefits.
+- **Type:** `JSX.Element`
 
-Our example use case is to display a user profile. A naive snippet would look like this:
+Subtree inside the suspense boundary.
 
-```jsx
-const MyComponentWithOptionalChaining = () => {
-	const [profile] = createResource(async () => {
-		/* fetcher code here */
-	});
-	return (
-		<>
-			<div>{profile()?.name}</div>
-			<div>{profile()?.email}</div>
-		</>
-	);
-};
-```
+## Return value
 
-In this code, `profile()` starts as `undefined`, and when the fetcher code finishes, resolves to an object with `name` and `email` properties. Although the resource has not resolved yet, the two `div`s are already created and attached to the document body, albeit with empty text nodes. Once the resource resolves, the `div`s are updated with the appropriate data.
-
-The downside of this approach is that the user is shown an empty component - let's see if we can do better than that in this next snippet:
-
-```jsx
-const MyComponentWithShow = () => {
-	const [profile] = createResource(async () => {
-		/* fetcher code here */
-	});
-	return (
-		<Show when={profile()} fallback={<div>fetching user data</div>}>
-			<div>{profile().name}</div>
-			<div>{profile().email}</div>
-		</Show>
-	);
-};
-```
+- **Type:** `JSX.Element`
 
-In this snippet, we first show a fallback when the resource hasn't resolved yet, and then switch to showing the profile data once it has. This results in a better user experience.
+## Behavior
 
-On the other hand, there is a slight downside to this approach. In our first example (using optional chaining), the divs were created immediately, and once the resource resolves all that is needed to be done is to fill in the text of the `div`s. But in our second example (using `<Show>`), the `div`s are only created once the resource has resolved, which means there is more work that needs to be done after the resource has resolved before the data can be shown to the user (of course, in this toy example the amount of DOM work is relatively trivial).
+- `<Suspense>` is triggered when a resource is read inside the boundary.
+- The boundary waits until pending tracked resources resolve.
+- `<Suspense>` is non-blocking: the subtree still runs while the fallback is rendered.
+- Nested suspense boundaries handle resources read under the nearest boundary.
+- `onMount` and `createEffect` inside the suspended subtree run after the boundary resolves.
 
-We can have the best of both worlds by using {"<Suspense>"}:
+## Examples
 
-```jsx
-const MyComponentWithSuspense = () => {
-	const [profile] = createResource(async () => {
-		/* fetcher code here */
-	});
-	return (
-		<Suspense fallback={<div>fetching user data</div>}>
-			<div>{profile()?.name}</div>
-			<div>{profile()?.email}</div>
-		</Suspense>
-	);
-};
-```
+### Basic usage
+
+```tsx
+import { Suspense } from "solid-js";
 
-In this case, the `div`s are created immediately, but instead of being attached to the document body, the fallback is shown. Once the resource resolves, the text in the `div`s is updated, and then they are attached to the document (and the fallback removed).
-
-It is important to note that _the execution of the component does not pause_ when using suspense. Instead, when a resource is read under a suspense boundary, it ensures that the nodes are not attached to the document until after the resource has resolved. Suspense allows us to have the best of both worlds: do as much work as we can _before_ the resource resolves, and also show a fallback until then.
-
-With this in mind, we can understand that there isn't much gained from suspense in the following code:
-
-```jsx
-const MyComponentWithSuspenseAndShow = () => {
-	const [profile] = createResource(async () => {
-		/* fetcher code here */
-	});
-	return (
-		<Suspense fallback={<div>fetching user data</div>}>
-			<Show when={profile()}>
-				<div>{profile().name}</div>
-				<div>{profile().email}</div>
-			</Show>
-		</Suspense>
-	);
-};
+<Suspense fallback={<LoadingSpinner />}>
+	<AsyncComponent />
+</Suspense>;
 ```
 
-In this code, we don't create _any_ DOM nodes inside {"<Suspense>"} before the resource resolves, so it is pretty much the same as the second example where we only used `<Show>`.
+### Nested suspense
 
-:::note
-Suspense is triggered by reading a resource inside the {"<Suspense>"}{" "}
-boundary. Components wrapped with suspense still run fully, just as they would
-without suspense. However, code wrapped in `onMount` and `createEffect` only
-run after the resource resolves.
-:::
+```tsx
+import { Suspense } from "solid-js";
 
-## Props
+<Suspense fallback={<div>Loading page</div>}>
+	<h1>{title()}</h1>
+	<Suspense fallback={<div>Loading details</div>}>
+		<DataComponent>{data()}</DataComponent>
+	</Suspense>
+</Suspense>;
+```
+
+## Related
 
-| Name       | Type          | Description                                                      |
-| :--------- | :------------ | :--------------------------------------------------------------- |
-| `fallback` | `JSX.Element` | The fallback component to render while the children are loading. |
+- [`<SuspenseList>`](/reference/components/suspense-list)
+- [`createResource`](/reference/basic-reactivity/create-resource)

From e2091bce7bbe047a5f1d7607f3b967c55d78377d Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:01:54 -0700
Subject: [PATCH 10/88] migrate rendering reference pages and split isDev

---
 src/routes/reference/rendering/data.json      |  1 +
 src/routes/reference/rendering/dev.mdx        | 55 ++++++++---
 src/routes/reference/rendering/hydrate.mdx    | 84 ++++++++++++----
 .../reference/rendering/hydration-script.mdx  | 96 +++++++++++++++----
 src/routes/reference/rendering/is-dev.mdx     | 51 ++++++++++
 src/routes/reference/rendering/is-server.mdx  | 34 +++++--
 6 files changed, 263 insertions(+), 58 deletions(-)
 create mode 100644 src/routes/reference/rendering/is-dev.mdx

diff --git a/src/routes/reference/rendering/data.json b/src/routes/reference/rendering/data.json
index cd3ffdce0..3f811d6b3 100644
--- a/src/routes/reference/rendering/data.json
+++ b/src/routes/reference/rendering/data.json
@@ -4,6 +4,7 @@
 		"dev.mdx",
 		"hydrate.mdx",
 		"hydration-script.mdx",
+		"is-dev.mdx",
 		"is-server.mdx",
 		"render.mdx",
 		"render-to-stream.mdx",
diff --git a/src/routes/reference/rendering/dev.mdx b/src/routes/reference/rendering/dev.mdx
index 29c51c8d1..7d5e3209c 100644
--- a/src/routes/reference/rendering/dev.mdx
+++ b/src/routes/reference/rendering/dev.mdx
@@ -1,37 +1,64 @@
 ---
 title: DEV
 use_cases: >-
-  development debugging, build optimization, library development, conditional
-  code, dev-only features
+  development builds, development-only checks, conditional dev-only code
 tags:
   - development
   - debugging
   - builds
-  - optimization
   - conditional
 version: "1.0"
 description: >-
-  Access development-only features in SolidJS with the DEV export. Enable
-  additional checks and debugging tools that are removed in production.
+  Read the development-only `DEV` export from `solid-js`.
 ---
 
+`DEV` is a development-only export from `solid-js`.
+
+## Import
+
 ```ts
 import { DEV } from "solid-js";
+```
 
-const DEV: object | undefined;
+## Type
+
+```ts
+const DEV:
+	| {
+			readonly hooks: {
+				afterUpdate: (() => void) | null;
+				afterCreateOwner: ((owner: unknown) => void) | null;
+				afterCreateSignal: ((signal: unknown) => void) | null;
+				afterRegisterGraph: ((sourceMapValue: unknown) => void) | null;
+			};
+			readonly writeSignal: (...args: unknown[]) => unknown;
+			readonly registerGraph: (...args: unknown[]) => unknown;
+	  }
+	| undefined;
 ```
 
-On the client, Solid provides (via [conditional exports](https://nodejs.org/api/packages.html#conditional-exports)) different builds depending on whether the **development** condition is set.
-Development mode provides some additional checking — e.g. detecting accidental use of multiple instances of Solid — which are removed in production builds.
+## Value
+
+- **Type:** development-only object or `undefined`
 
-If you want code to run only in development mode (most useful in libraries), you can check whether the **DEV** export is defined.
-Note that it is always defined on the server, so you may want to combine with [isServer](/reference/rendering/is-server):
+## Behavior
+
+- In development builds, `DEV` is defined and exposes development hooks.
+- In production builds, `DEV` is `undefined`.
+
+## Examples
+
+### Basic usage
 
 ```ts
-import { DEV } from "solid-js"
-import { isServer } from "solid-js/web"
+import { DEV } from "solid-js";
 
-if (DEV && !isServer) {
-  console.log(...);
+if (DEV) {
+	console.log("development build");
 }
 ```
+
+## Related
+
+- [`isDev`](/reference/rendering/is-dev)
+- [`isServer`](/reference/rendering/is-server)
diff --git a/src/routes/reference/rendering/hydrate.mdx b/src/routes/reference/rendering/hydrate.mdx
index c01962566..fa26080a9 100644
--- a/src/routes/reference/rendering/hydrate.mdx
+++ b/src/routes/reference/rendering/hydrate.mdx
@@ -1,24 +1,35 @@
 ---
 title: hydrate
 use_cases: >-
-  ssr hydration, client initialization, server-rendered apps, spa startup, dom
-  rehydration
+  hydrating server-rendered HTML, attaching client behavior to an SSR subtree
 tags:
   - hydration
   - ssr
   - rendering
-  - initialization
   - dom
 version: "1.0"
 description: >-
-  Hydrate server-rendered HTML with SolidJS client-side code. Essential for
-  initializing SSR applications and attaching interactivity to static HTML.
+  Hydrate server-rendered HTML and attach Solid's client-side behavior to an
+  existing DOM subtree.
 ---
 
+`hydrate` attaches Solid's client-side behavior to DOM that was already rendered on the server.
+
+## Import
+
 ```ts
 import { hydrate } from "solid-js/web";
-import type { JSX } from "solid-js";
-import type { MountableElement } from "solid-js/web";
+```
+
+## Type
+
+```ts
+type MountableElement =
+	| Element
+	| Document
+	| ShadowRoot
+	| DocumentFragment
+	| Node;
 
 function hydrate(
 	fn: () => JSX.Element,
@@ -27,18 +38,57 @@ function hydrate(
 ): () => void;
 ```
 
-This method is similar to `render` except that it attempts to rehydrate what is already rendered to the DOM.
-When initializing in the browser a page has already been server rendered.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => JSX.Element`
+
+Function that returns the root JSX to hydrate.
+
+### `node`
+
+- **Type:** `MountableElement`
+
+DOM node that contains the server-rendered markup.
+
+### `options`
+
+#### `renderId`
+
+- **Type:** `string`
+
+Hydration render identifier.
+
+#### `owner`
+
+- **Type:** `unknown`
+
+Owner used for the hydration root.
+
+## Return value
+
+- **Type:** `() => void`
+
+Dispose function for the hydrated root.
+
+## Behavior
+
+- `hydrate` reuses existing DOM instead of creating a new subtree.
+- The target node is expected to contain server-rendered markup that matches the rendered output.
+- The returned function disposes the hydrated root.
+
+## Examples
+
+### Basic usage
 
 ```ts
-const dispose = hydrate(App, document.getElementById("app"));
+import { hydrate } from "solid-js/web";
+
+const dispose = hydrate(() => <App />, document.getElementById("app")!);
 ```
 
-## Parameters
+## Related
 
-| Prop             | type                | description                                 |
-| ---------------- | ------------------- | ------------------------------------------- |
-| fn               | `() => JSX.Element` | Function that returns the application code. |
-| node             | MountableElement    | DOM Element to mount the application to     |
-| options.renderId | string              |                                             |
-| options.owner    | unknown             |                                             |
+- [`render`](/reference/rendering/render)
+- [`HydrationScript`](/reference/rendering/hydration-script)
diff --git a/src/routes/reference/rendering/hydration-script.mdx b/src/routes/reference/rendering/hydration-script.mdx
index 41af5b0b1..8c661378b 100644
--- a/src/routes/reference/rendering/hydration-script.mdx
+++ b/src/routes/reference/rendering/hydration-script.mdx
@@ -1,38 +1,100 @@
 ---
 title: hydrationScript
 use_cases: >-
-  ssr hydration, server-side rendering, initial page load optimization,
-  capturing events before js loads
+  server rendering, hydration bootstrap, capturing delegated events before
+  client hydration
 tags:
   - ssr
   - hydration
-  - performance
-  - events
   - bootstrap
+  - events
 version: "1.0"
 description: >-
-  Bootstrap client-side hydration in SSR apps with HydrationScript. Capture and
-  replay events before JavaScript loads for seamless user experience.
+  Emit the hydration bootstrap script with `HydrationScript` or
+  `generateHydrationScript`.
 ---
 
+`HydrationScript` and `generateHydrationScript` emit Solid's hydration bootstrap script.
+
+## Import
+
 ```ts
-import { generateHydrationScript, HydrationScript } from "solid-js/web";
-import type { JSX } from "solid-js";
+import { HydrationScript, generateHydrationScript } from "solid-js/web";
+```
 
-function generateHydrationScript(options: {
-	nonce?: string;
-	eventNames?: string[];
-}): string;
+## Type
 
+```ts
 function HydrationScript(props: {
 	nonce?: string;
 	eventNames?: string[];
 }): JSX.Element;
+
+function generateHydrationScript(options: {
+	nonce?: string;
+	eventNames?: string[];
+}): string;
+```
+
+## `HydrationScript` props
+
+### `nonce`
+
+- **Type:** `string`
+
+Nonce applied to the generated `<script>` tag.
+
+### `eventNames`
+
+- **Type:** `string[]`
+
+Delegated event names captured before client scripts load.
+
+## `generateHydrationScript` options
+
+### `nonce`
+
+- **Type:** `string`
+
+Nonce applied to the generated script tag.
+
+### `eventNames`
+
+- **Type:** `string[]`
+
+Delegated event names captured before client scripts load.
+
+## Return value
+
+- **Type:** `JSX.Element` for `HydrationScript`, `string` for `generateHydrationScript`
+
+## Behavior
+
+- The hydration script bootstraps delegated event replay before the runtime loads.
+- `HydrationScript` returns JSX for server-rendered HTML output.
+- `generateHydrationScript` returns a string for manual HTML generation.
+- In browser-only bundles, these exports are no-op placeholders.
+
+## Examples
+
+### `HydrationScript`
+
+```tsx
+import { HydrationScript } from "solid-js/web";
+
+<head>
+	<HydrationScript />
+</head>;
+```
+
+### `generateHydrationScript`
+
+```ts
+import { generateHydrationScript } from "solid-js/web";
+
+const script = generateHydrationScript({ nonce: "nonce-value" });
 ```
 
-Hydration Script is a special script that should be placed once on the page to bootstrap hydration before Solid's runtime has loaded.
-It comes both as a function that can be called and inserted in an HTML string, or as a Component if you are rendering JSX from the `<html>` tag.
+## Related
 
-The options are for the **nonce** to be put on the script tag and any event names for that Solid should capture before scripts have loaded and replay during hydration.
-These events are limited to those that Solid delegates which include most UI Events that are composed and bubble.
-By default it is only click and input events.
+- [`hydrate`](/reference/rendering/hydrate)
diff --git a/src/routes/reference/rendering/is-dev.mdx b/src/routes/reference/rendering/is-dev.mdx
new file mode 100644
index 000000000..8c1305d4e
--- /dev/null
+++ b/src/routes/reference/rendering/is-dev.mdx
@@ -0,0 +1,51 @@
+---
+title: isDev
+use_cases: >-
+  development-build checks, browser-side dev-only branches, bundle-level
+  development flags
+tags:
+  - development
+  - debugging
+  - builds
+  - conditional
+version: "1.0"
+description: >-
+  Read the development-mode boolean exported by `solid-js/web`.
+---
+
+`isDev` is a constant boolean exported by `solid-js/web`.
+
+## Import
+
+```ts
+import { isDev } from "solid-js/web";
+```
+
+## Type
+
+```ts
+const isDev: boolean;
+```
+
+## Behavior
+
+- `isDev` is `true` in the development browser bundle and `false` in production browser bundles.
+- `isDev` is `false` in the server bundle.
+- Because it is exported as a constant, bundlers can eliminate unreachable branches.
+
+## Examples
+
+### Basic usage
+
+```ts
+import { isDev } from "solid-js/web";
+
+if (isDev) {
+	console.log("development browser bundle");
+}
+```
+
+## Related
+
+- [`DEV`](/reference/rendering/dev)
+- [`isServer`](/reference/rendering/is-server)
diff --git a/src/routes/reference/rendering/is-server.mdx b/src/routes/reference/rendering/is-server.mdx
index ee24a1bd5..331f40f54 100644
--- a/src/routes/reference/rendering/is-server.mdx
+++ b/src/routes/reference/rendering/is-server.mdx
@@ -1,35 +1,49 @@
 ---
 title: isServer
 use_cases: >-
-  conditional rendering, ssr vs client code, bundle optimization,
-  environment-specific logic, code splitting
+  server-only branches, client-only branches, bundle-level environment checks
 tags:
   - ssr
   - environment
   - bundling
-  - optimization
   - conditional
 version: "1.0"
 description: >-
-  Detect server or browser environment with isServer. Optimize bundle sizes by
-  conditionally including code for specific runtime environments.
+  Read whether the current `solid-js/web` bundle is the server bundle.
 ---
 
+`isServer` is a constant boolean that indicates whether code is running in the server bundle.
+
+## Import
+
 ```ts
 import { isServer } from "solid-js/web";
+```
 
+## Type
+
+```ts
 const isServer: boolean;
 ```
 
-This indicates that the code is being run as the server or browser bundle.
-As the underlying runtimes export this as a constant boolean it allows bundlers to eliminate the code and their used imports from the respective bundles.
+## Behavior
+
+- `isServer` is `true` in the server bundle and `false` in the browser bundle.
+- Because it is exported as a constant, bundlers can eliminate unreachable branches.
+
+## Examples
+
+### Basic usage
 
 ```ts
 import { isServer } from "solid-js/web";
 
 if (isServer) {
-	// I will never make it to the browser bundle
-} else {
-	// won't be run on the server;
+	serverOnlyWork();
 }
 ```
+
+## Related
+
+- [`DEV`](/reference/rendering/dev)
+- [`isDev`](/reference/rendering/is-dev)

From e3b30c63b75f69cc5508d3987442ee87d9179cf7 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:05:34 -0700
Subject: [PATCH 11/88] migrate server rendering reference pages

---
 .../reference/rendering/render-to-stream.mdx  | 113 +++++++++++++-----
 .../rendering/render-to-string-async.mdx      |  90 +++++++++++---
 .../reference/rendering/render-to-string.mdx  |  74 +++++++++---
 src/routes/reference/rendering/render.mdx     |  76 ++++++++----
 4 files changed, 270 insertions(+), 83 deletions(-)

diff --git a/src/routes/reference/rendering/render-to-stream.mdx b/src/routes/reference/rendering/render-to-stream.mdx
index 5eda94cf0..d67a0ff05 100644
--- a/src/routes/reference/rendering/render-to-stream.mdx
+++ b/src/routes/reference/rendering/render-to-stream.mdx
@@ -1,63 +1,118 @@
 ---
 title: renderToStream
 use_cases: >-
-  streaming ssr, progressive rendering, async data loading, suspense boundaries,
-  large page optimization
+  streaming server rendering, progressive HTML delivery, suspense-driven server
+  output
 tags:
   - ssr
   - streaming
   - async
   - suspense
-  - performance
 version: "1.0"
 description: >-
-  Stream HTML progressively with renderToStream. Render content synchronously
-  then stream async resources as they complete for faster loading.
+  Stream server-rendered HTML and continue writing async content as it
+  resolves.
 ---
 
+`renderToStream` streams server-rendered HTML and continues writing async content as it resolves.
+
+## Import
+
 ```ts
 import { renderToStream } from "solid-js/web";
+```
 
+## Type
+
+```ts
 function renderToStream<T>(
 	fn: () => T,
 	options?: {
 		nonce?: string;
 		renderId?: string;
-		onCompleteShell?: () => void;
-		onCompleteAll?: () => void;
+		onCompleteShell?: (info: { write: (v: string) => void }) => void;
+		onCompleteAll?: (info: { write: (v: string) => void }) => void;
+		onError?: (err: any) => void;
 	}
 ): {
 	pipe: (writable: { write: (v: string) => void }) => void;
-	pipeTo: (writable: WritableStream) => void;
+	pipeTo: (writable: WritableStream) => Promise<void>;
 };
 ```
 
-This method renders to a stream.
-It renders the content synchronously including any Suspense fallback placeholders, and then continues to stream the data and HTML from any async resource as it completes.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => T`
+
+Function that returns the root output to render.
+
+### `options`
+
+#### `nonce`
+
+- **Type:** `string`
+
+Nonce applied to inline scripts emitted during rendering.
+
+#### `renderId`
+
+- **Type:** `string`
+
+Identifier used to namespace the render output.
+
+#### `onCompleteShell`
+
+- **Type:** `(info: { write: (v: string) => void }) => void`
+
+Callback invoked when the shell is ready to flush.
+
+#### `onCompleteAll`
+
+- **Type:** `(info: { write: (v: string) => void }) => void`
+
+Callback invoked after all server suspense boundaries have settled.
+
+#### `onError`
+
+- **Type:** `(err: any) => void`
+
+Callback invoked when a rendering error is encountered.
+
+## Return value
+
+- **Type:** `{ pipe: ..., pipeTo: ... }`
+
+Streaming controller with `pipe` and `pipeTo` methods.
+
+## Behavior
+
+- `renderToStream` writes the shell synchronously, including suspense fallback content.
+- Async content and serialized data continue streaming as resources resolve.
+- `pipe` writes to Node-style writable targets.
+- `pipeTo` writes to a `WritableStream`.
+
+## Examples
+
+### `pipe`
 
 ```ts
-// node
-renderToStream(App).pipe(res);
+import { renderToStream } from "solid-js/web";
 
-// web stream
-const { readable, writable } = new TransformStream();
-renderToStream(App).pipeTo(writable);
+renderToStream(() => <App />).pipe(response);
 ```
 
-`onCompleteShell` fires when synchronous rendering is complete before writing the first flush to the stream out to the browser.
-`onCompleteAll` is called when all server Suspense boundaries have settled.
-`renderId` is used to namespace renders when having multiple top level roots.
+### `pipeTo`
 
-:::note
-This API replaces the previous pipeToWritable and pipeToNodeWritable
-APIs.
-:::
+```ts
+import { renderToStream } from "solid-js/web";
+
+const { writable } = new TransformStream();
+await renderToStream(() => <App />).pipeTo(writable);
+```
 
-## Options
+## Related
 
-| Name            | Type       | Description                                                      |
-| --------------- | ---------- | ---------------------------------------------------------------- |
-| nonce           | string     | The nonce to use for inline scripts.                             |
-| renderId        | string     | The id to use for this render.                                   |
-| onCompleteShell | () => void | A callback that fires when the shell is complete.                |
-| onCompleteAll   | () => void | A callback that fires when all Suspense boundaries have settled. |
+- [`renderToString`](/reference/rendering/render-to-string)
+- [`renderToStringAsync`](/reference/rendering/render-to-string-async)
diff --git a/src/routes/reference/rendering/render-to-string-async.mdx b/src/routes/reference/rendering/render-to-string-async.mdx
index f5ebcd4f9..b9602bf7b 100644
--- a/src/routes/reference/rendering/render-to-string-async.mdx
+++ b/src/routes/reference/rendering/render-to-string-async.mdx
@@ -1,46 +1,104 @@
 ---
 title: renderToStringAsync
 use_cases: >-
-  ssr with async data, suspense resolution, complete page rendering, data
-  serialization, seo optimization
+  async server rendering, waiting for suspense boundaries, HTML generation with
+  async data
 tags:
   - ssr
   - async
   - suspense
-  - serialization
   - rendering
 version: "1.0"
 description: >-
-  Render complete HTML with async data using renderToStringAsync. Waits for all
-  Suspense boundaries before returning serialized results.
+  Render HTML to a string after async suspense boundaries settle.
 ---
 
+`renderToStringAsync` renders HTML to a string after async suspense boundaries settle.
+
+## Import
+
 ```ts
 import { renderToStringAsync } from "solid-js/web";
+```
 
+## Type
+
+```ts
 function renderToStringAsync<T>(
 	fn: () => T,
 	options?: {
 		timeoutMs?: number;
-		renderId?: string;
 		nonce?: string;
+		renderId?: string;
+		noScripts?: boolean;
+		onError?: (err: any) => void;
 	}
 ): Promise<string>;
 ```
 
-Same as `renderToString` except that it will wait for all `<Suspense>` boundaries to resolve before returning the results.
-Resource data is automatically serialized into the script tag and will be hydrated on client load.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => T`
+
+Function that returns the root output to render.
+
+### `options`
+
+#### `timeoutMs`
+
+- **Type:** `number`
+
+Maximum wait time for suspense boundaries before the render resolves.
+
+#### `nonce`
+
+- **Type:** `string`
+
+Nonce applied to inline scripts emitted during rendering.
 
-`renderId` is used to namespace renders when having multiple top level roots.
+#### `renderId`
+
+- **Type:** `string`
+
+Identifier used to namespace the render output.
+
+#### `noScripts`
+
+- **Type:** `boolean`
+
+Disables script emission in the rendered output.
+
+#### `onError`
+
+- **Type:** `(err: any) => void`
+
+Callback invoked when a rendering error is encountered.
+
+## Return value
+
+- **Type:** `Promise<string>`
+
+Promise that resolves to the rendered HTML string.
+
+## Behavior
+
+- `renderToStringAsync` waits for server suspense boundaries to settle before resolving.
+- Resource data is serialized for client hydration unless scripts are disabled.
+- `renderId` namespaces the render output when multiple top-level roots are present.
+
+## Examples
+
+### Basic usage
 
 ```ts
-const html = await renderToStringAsync(App);
+import { renderToStringAsync } from "solid-js/web";
+
+const html = await renderToStringAsync(() => <App />);
 ```
 
-## Options
+## Related
 
-| Name        | Type     | Description                                                                                  |
-| ----------- | -------- | -------------------------------------------------------------------------------------------- |
-| `timeoutMs` | `number` | The number of milliseconds to wait for a `<Suspense>` boundary to resolve before timing out. |
-| `renderId`  | `string` | The id to use for the render.                                                                |
-| `nonce`     | `string` | The nonce to use for the script tag.                                                         |
+- [`renderToString`](/reference/rendering/render-to-string)
+- [`renderToStream`](/reference/rendering/render-to-stream)
diff --git a/src/routes/reference/rendering/render-to-string.mdx b/src/routes/reference/rendering/render-to-string.mdx
index 74dd17262..57e54e04f 100644
--- a/src/routes/reference/rendering/render-to-string.mdx
+++ b/src/routes/reference/rendering/render-to-string.mdx
@@ -1,45 +1,89 @@
 ---
 title: renderToString
 use_cases: >-
-  basic ssr, static site generation, synchronous rendering, progressive
-  hydration, seo pages
+  synchronous server rendering, HTML generation, progressive hydration output
 tags:
   - ssr
   - rendering
   - hydration
   - synchronous
-  - static
 version: "1.0"
 description: >-
-  Generate HTML strings synchronously with renderToString. Perfect for SSR with
-  progressive hydration and static site generation needs.
+  Render HTML to a string synchronously on the server.
 ---
 
+`renderToString` renders HTML to a string synchronously on the server.
+
+## Import
+
 ```ts
 import { renderToString } from "solid-js/web";
+```
+
+## Type
 
+```ts
 function renderToString<T>(
 	fn: () => T,
 	options?: {
 		nonce?: string;
 		renderId?: string;
+		onError?: (err: any) => void;
 	}
 ): string;
 ```
 
-Renders to a string synchronously.
-The function also generates a script tag for progressive hydration.
-Options include eventNames to listen to before the page loads and play back on hydration, and nonce to put on the script tag.
+## Parameters
+
+### `fn`
+
+- **Type:** `() => T`
+
+Function that returns the root output to render.
+
+### `options`
+
+#### `nonce`
+
+- **Type:** `string`
+
+Nonce applied to inline scripts emitted during rendering.
+
+#### `renderId`
 
-`renderId` is used to namespace renders when having multiple top level roots.
+- **Type:** `string`
+
+Identifier used to namespace the render output.
+
+#### `onError`
+
+- **Type:** `(err: any) => void`
+
+Callback invoked when a rendering error is encountered.
+
+## Return value
+
+- **Type:** `string`
+
+Rendered HTML string.
+
+## Behavior
+
+- `renderToString` completes synchronously.
+- The output includes hydration data for progressive hydration.
+- `renderId` namespaces the render output when multiple top-level roots are present.
+
+## Examples
+
+### Basic usage
 
 ```ts
-const html = renderToString(App);
+import { renderToString } from "solid-js/web";
+
+const html = renderToString(() => <App />);
 ```
 
-## Options
+## Related
 
-| Name       | Type     | Description                          |
-| ---------- | -------- | ------------------------------------ |
-| `nonce`    | `string` | The nonce to use for the script tag. |
-| `renderId` | `string` | The id to use for the script tag.    |
+- [`renderToStringAsync`](/reference/rendering/render-to-string-async)
+- [`renderToStream`](/reference/rendering/render-to-stream)
diff --git a/src/routes/reference/rendering/render.mdx b/src/routes/reference/rendering/render.mdx
index 0d0aaac86..0435ca714 100644
--- a/src/routes/reference/rendering/render.mdx
+++ b/src/routes/reference/rendering/render.mdx
@@ -1,44 +1,74 @@
 ---
 title: render
 use_cases: >-
-  app initialization, mounting components, spa entry point, client-side
-  rendering, dom manipulation
+  mounting a client app, browser entry points, attaching a root to the DOM
 tags:
   - mounting
-  - initialization
-  - spa
-  - dom
+  - rendering
   - client
-  - entry
+  - dom
 version: "1.0"
 description: >-
-  Mount your Solid app to the DOM with render. The essential browser entry point
-  for initializing and disposing client-side applications.
+  Mount a Solid root into a DOM node in the browser.
 ---
 
+`render` mounts a Solid root into a DOM node in the browser.
+
+## Import
+
 ```ts
 import { render } from "solid-js/web";
-import type { JSX } from "solid-js";
-import type { MountableElement } from "solid-js/web";
+```
+
+## Type
+
+```ts
+type MountableElement =
+	| Element
+	| Document
+	| ShadowRoot
+	| DocumentFragment
+	| Node;
 
 function render(code: () => JSX.Element, element: MountableElement): () => void;
 ```
 
-This is the browser app entry point.
-Provide a top-level component function and an element to mount to.
-It is recommended this element be empty: while `render` will just append children, the returned dispose function will remove all children.
+## Parameters
+
+### `code`
+
+- **Type:** `() => JSX.Element`
+
+Function that returns the root JSX to mount.
+
+### `element`
+
+- **Type:** `MountableElement`
+
+DOM node that receives the rendered output.
+
+## Return value
+
+- **Type:** `() => void`
+
+Dispose function for the mounted root.
+
+## Behavior
+
+- `render` creates a new root and appends its output to `element`.
+- The first argument must be a function so Solid can establish the root before evaluating JSX.
+- The returned function disposes the root and removes the rendered content.
+
+## Examples
+
+### Basic usage
 
 ```ts
-const dispose = render(App, document.getElementById("app"))
-// or
-const dispose = render(() => <App />, document.getElementById("app"))
-```
+import { render } from "solid-js/web";
 
-It's important that the first argument is a function: do not pass JSX directly (as in `render(<App/>, ...)`), because this will call App before render can set up a root to track signal dependencies within App.
+const dispose = render(() => <App />, document.getElementById("app")!);
+```
 
-## Parameters
+## Related
 
-| Argument | Type                | Description                                 |
-| -------- | ------------------- | ------------------------------------------- |
-| code     | `() => JSX.Element` | Function that returns the application code. |
-| element  | MountableElement    | DOM Element to mount the application to     |
+- [`hydrate`](/reference/rendering/hydrate)

From ed22b63da7c50b0ded21a0fb10defaeee256c989 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:06:42 -0700
Subject: [PATCH 12/88] migrate server rendering reference pages

---
 .../server-utilities/get-request-event.mdx    | 74 ++++++-------------
 1 file changed, 24 insertions(+), 50 deletions(-)

diff --git a/src/routes/reference/server-utilities/get-request-event.mdx b/src/routes/reference/server-utilities/get-request-event.mdx
index 15afc8f38..69b66bf81 100644
--- a/src/routes/reference/server-utilities/get-request-event.mdx
+++ b/src/routes/reference/server-utilities/get-request-event.mdx
@@ -1,82 +1,56 @@
 ---
 title: getRequestEvent
 use_cases: >-
-  server-side rendering, authentication, headers manipulation, cookies, server
-  functions, request context access
+  reading the current request object, accessing request-scoped server context
 tags:
   - server
   - ssr
   - request
-  - headers
-  - authentication
   - context
 version: "1.0"
 description: >-
-  Access server request context with getRequestEvent. Read headers, set cookies,
-  and manage response status in SSR and server functions.
+  Read the current request event from `solid-js/web`.
 ---
 
-Solid uses Async Local Storage as a way of injecting the request context anywhere on the server.
-The server provides a utility function to access this context
-(called a `RequestEvent`).
+`getRequestEvent` returns the current request event when one is available.
 
-```js
-import { getRequestEvent } from "solid-js/web"
-import type { RequestEvent } from "solid-js/web"
+## Import
 
-function getRequestEvent(): RequestEvent | undefined
+```ts
+import { getRequestEvent } from "solid-js/web";
 ```
 
-You can retrieve the request event by calling `getRequestEvent`:
+## Type
 
-```js
-import { getRequestEvent } from "solid-js/web";
+```ts
+interface RequestEvent {
+	request: Request;
+	locals?: Record<string | number | symbol, any>;
+}
 
-const event = getRequestEvent();
+function getRequestEvent(): RequestEvent | undefined;
 ```
 
-## Request
+## Return value
 
-`.request` is the most important property of the `RequestEvent`.
-This is a Web [Request object](https://developer.mozilla.org/en-US/docs/Web/API/Request) that represents the current request to the server.
-You can access properties off of it such as `url` and `headers`.
-`body`, however, does not typically need to be handled directly for things such as server functions or rendering, which already handle mapping.
+- **Type:** `RequestEvent | undefined`
 
-```js
-import { getRequestEvent } from "solid-js/web";
+## Behavior
 
-const event = getRequestEvent();
-if (event) {
-	const auth = event.request.headers.get("Authorization");
-}
-```
+- On the server, the returned event includes the current `Request`.
+- In the server declarations here, `RequestEvent` also includes `locals`.
+- If no request event is available, `getRequestEvent` returns `undefined`.
 
-## Response
+## Examples
 
-The `getRequestEvent` can also be used to stub out the Response - this extends the [options that can be passed to the `Response constructor`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#options).
-This is kept up to date so it can be used to read and write headers and status for the current response.
+### Basic usage
 
-```js
+```ts
 import { getRequestEvent } from "solid-js/web";
 
 const event = getRequestEvent();
+
 if (event) {
-	event.response.headers.append("Set-Cookie", "foo=hello");
-	event.response.status = 201;
+	const auth = event.request.headers.get("Authorization");
 }
 ```
-
-### Change event.response or create a new Response
-
-The `getRequestEvent` event is considered global and lasts the life of the request.
-Therefore, if you are calling a server function on the server during SSR or an RPC call, setting values on `event.response` will reflect on that request.
-
-The returned response will only impact the response when it is an RPC call.
-This is important because some headers previously set may not be needed to be set for the whole page, but only for a specific request.
-
-**Note:** This is important to keep in mind when choosing where to set headers and responses.
-
-:::note[Usage with SolidStart]
-See this guide on [Request
-Events](/solid-start/advanced/request-events).
-:::

From 6d1abb542afc4c4d9eedebb78eb0b5735dab77fd Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:17:16 -0700
Subject: [PATCH 13/88] migrate store creation and mutable store refs

---
 .../store-utilities/create-mutable.mdx        |  75 +++++++----
 .../store-utilities/create-store.mdx          | 122 +++++++++---------
 .../store-utilities/modify-mutable.mdx        |  93 ++++++-------
 3 files changed, 151 insertions(+), 139 deletions(-)

diff --git a/src/routes/reference/store-utilities/create-mutable.mdx b/src/routes/reference/store-utilities/create-mutable.mdx
index 19889ecb1..f518adcb8 100644
--- a/src/routes/reference/store-utilities/create-mutable.mdx
+++ b/src/routes/reference/store-utilities/create-mutable.mdx
@@ -1,38 +1,67 @@
 ---
 title: createMutable
 use_cases: >-
-  mobx migration, vue compatibility, external system integration, mutable state
-  patterns, proxy-based reactivity
+  mutable proxy state, interop with mutable systems, object mutation through a
+  store proxy
 tags:
   - store
   - mutable
   - proxy
   - state
-  - compatibility
 version: "1.0"
 description: >-
-  Create mutable proxy stores with automatic deep tracking. Ideal for MobX/Vue
-  compatibility or integrating external mutable systems.
+  Create a mutable store proxy.
 ---
 
-`createMutable` creates a new mutable Store proxy object that provides a way to selectively trigger updates only when values change.
+`createMutable` creates a mutable store proxy.
 
-By intercepting property access, it allows automatic tracking of deep nesting via proxy making it useful for integrating external systems or serving as a compatibility layer with frameworks like MobX or Vue.
+## Import
 
-```tsx
+```ts
 import { createMutable } from "solid-js/store";
-import type { Store, StoreNode } from "solid-js/store";
+```
+
+## Type
 
-function createMutable<T extends StoreNode>(state: T | Store<T>): Store<T>;
+```ts
+function createMutable<T extends Record<PropertyKey, any>>(
+	state: T,
+	options?: { name?: string }
+): T;
 ```
 
-:::note
-It's important to recognize that a mutable state, which can be passed around and modified anywhere, may complicate the code structure and increase the risk of breaking unidirectional flow.
+## Parameters
+
+### `state`
+
+- **Type:** `T`
+
+Initial mutable state.
+
+### `options`
+
+#### `name`
+
+- **Type:** `string`
+
+Debug name used by development tooling.
+
+## Return value
 
-    For a more robust alternative, it is generally recommended to use `createStore` instead.
-    Additionally, the [`produce`](/reference/store-utilities/produce) utility can provide many of these same benefits without the associated downsides.
+- **Type:** `T`
 
-:::
+Mutable store proxy.
+
+## Behavior
+
+- Property reads and writes go through a proxy.
+- Nested property access is reactive.
+- Mutations update the store in place.
+- Getters and setters defined on the initial object remain available on the mutable store.
+
+## Examples
+
+### Basic usage
 
 ```tsx
 import { createMutable } from "solid-js/store";
@@ -42,18 +71,15 @@ const state = createMutable({
 	list: [],
 });
 
-// read value
-state.someValue;
-
-// set value
 state.someValue = 5;
-
-state.list.push(anotherValue);
+state.list.push("item");
 ```
 
-Mutables support setters along with getters.
+### Getter and setter
 
 ```tsx
+import { createMutable } from "solid-js/store";
+
 const user = createMutable({
 	firstName: "John",
 	lastName: "Smith",
@@ -65,3 +91,8 @@ const user = createMutable({
 	},
 });
 ```
+
+## Related
+
+- [`modifyMutable`](/reference/store-utilities/modify-mutable)
+- [`createStore`](/reference/store-utilities/create-store)
diff --git a/src/routes/reference/store-utilities/create-store.mdx b/src/routes/reference/store-utilities/create-store.mdx
index 5f17cc553..bb66d240e 100644
--- a/src/routes/reference/store-utilities/create-store.mdx
+++ b/src/routes/reference/store-utilities/create-store.mdx
@@ -1,72 +1,88 @@
 ---
 title: createStore
 use_cases: >-
-  complex state management, nested data, arrays and objects, derived values,
-  application state
+  object state, array state, nested state, structured application state
 tags:
   - store
   - state
-  - data-structures
   - objects
   - arrays
 version: "1.0"
 description: >-
-  Manage complex application state with createStore. Handle nested objects,
-  arrays, and derived values with fine-grained reactivity.
+  Create a reactive store and a setter function for structured state.
 ---
 
-Stores were intentionally designed to manage data structures like objects and arrays but are capable of handling other data types, such as strings and numbers.
+`createStore` creates a reactive store and setter function for structured state.
 
-## Types Signature
+## Import
 
-```tsx
+```ts
 import { createStore } from "solid-js/store";
-import type { StoreNode, Store, SetStoreFunction } from "solid-js/store";
+```
+
+## Type
 
-function createStore<T extends StoreNode>(
-	state: T | Store<T>
-): [get: Store<T>, set: SetStoreFunction<T>];
+```ts
+type Store<T> = T;
 
-type Store<T> = T; // conceptually readonly, but not typed as such
+interface SetStoreFunction<T> {
+	(setter: T | Partial<T> | ((prev: T) => T | Partial<T>)): void;
+}
+
+function createStore<T extends object = {}>(
+	store?: T | Store<T>,
+	options?: { name?: string }
+): [Store<T>, SetStoreFunction<T>];
 ```
 
-## Usage
+## Parameters
+
+### `store`
+
+- **Type:** `T | Store<T>`
+
+Initial store value.
+
+### `options`
+
+#### `name`
+
+- **Type:** `string`
+
+Debug name used by development tooling.
+
+## Return value
+
+- **Type:** `[Store<T>, SetStoreFunction<T>]`
+
+Tuple containing the store proxy and its setter.
+
+## Behavior
+
+- The returned store is read through a proxy.
+- The setter can update the whole store or specific paths.
+- Object updates are shallowly merged by the setter.
+- Getters defined on the initial object remain available on the store.
+
+## Examples
+
+### Basic usage
 
 ```tsx
 import { createStore } from "solid-js/store";
 
-// Initialize store
-const [store, setStore] = createStore({
-	userCount: 3,
-	users: [
-		{
-			id: 0,
-			username: "felix909",
-			location: "England",
-			loggedIn: false,
-		},
-		{
-			id: 1,
-			username: "tracy634",
-			location: "Canada",
-			loggedIn: true,
-		},
-		{
-			id: 1,
-			username: "johny123",
-			location: "India",
-			loggedIn: true,
-		},
-	],
+const [state, setState] = createStore({
+	firstName: "John",
+	lastName: "Smith",
 });
 ```
 
-## Getter
-
-Store objects support the use of getters to store derived values.
+### Getter
 
 ```tsx
-const [state, setState] = createStore({
+import { createStore } from "solid-js/store";
+
+const [state] = createStore({
 	user: {
 		firstName: "John",
 		lastName: "Smith",
@@ -77,25 +93,7 @@ const [state, setState] = createStore({
 });
 ```
 
-## Setter
-
-Changes can take the form of function that passes previous state and returns new state or a value.
-Objects are always shallowly merged. Set values to undefined to delete them from the Store.
-In TypeScript, you can delete a value by using a non-null assertion, like `undefined!`.
-
-```tsx
-const [state, setState] = createStore({
-	firstName: "John",
-	lastName: "Miller",
-});
-
-setState({ firstName: "Johnny", middleName: "Lee" });
-// ({ firstName: 'Johnny', middleName: 'Lee', lastName: 'Miller' })
-
-setState((state) => ({ preferredName: state.firstName, lastName: "Milner" }));
-// ({ firstName: 'Johnny', preferredName: 'Johnny', middleName: 'Lee', lastName: 'Milner' })
-```
-
----
+## Related
 
-To learn more about using stores check the [Stores Guide](/concepts/stores), and the **Store utilities** section for more advanced APIs.
+- [`createMutable`](/reference/store-utilities/create-mutable)
+- [Stores](/concepts/stores)
diff --git a/src/routes/reference/store-utilities/modify-mutable.mdx b/src/routes/reference/store-utilities/modify-mutable.mdx
index 0d8db0e49..1310ec05a 100644
--- a/src/routes/reference/store-utilities/modify-mutable.mdx
+++ b/src/routes/reference/store-utilities/modify-mutable.mdx
@@ -1,92 +1,69 @@
 ---
 title: modifyMutable
 use_cases: >-
-  batch updates, mutable store modifications, performance optimization, multiple
-  field changes, reconciliation
+  batched mutable-store updates, applying store modifiers to mutable stores
 tags:
   - store
   - mutable
   - batch
-  - performance
   - updates
 version: "1.0"
 description: >-
-  Batch multiple mutable store changes with modifyMutable. Update multiple
-  fields in one render cycle for better performance.
+  Apply a modifier to a mutable store inside a batch.
 ---
 
-`modifyMutable` streamlines the process of making multiple changes to a mutable Store, as obtained through the use of [`createMutable`](/reference/store-utilities/create-mutable).
+`modifyMutable` applies a modifier to a mutable store inside a batch.
 
-It operates within a single [`batch`](/reference/reactive-utilities/batch), ensuring that dependent computations are updated just once, rather than triggering updates for each individual change.
+## Import
 
-```tsx
+```ts
 import { modifyMutable } from "solid-js/store";
-
-function modifyMutable<T>(mutable: T, modifier: (state: T) => T): void;
 ```
 
-The function takes two arguments:
+## Type
 
-1. The first argument is the mutable Store that needs modification.
-2. The second argument is a Store modifier, which could be one of those returned by [`reconcile`](/reference/store-utilities/reconcile).
+```ts
+function modifyMutable<T>(state: T, modifier: (state: T) => T): void;
+```
 
-:::caution
-When passing in your own modifier function, it's important to be aware that
-its argument is an unwrapped version of the store.
-:::
+## Parameters
 
-For example, if the UI depends on multiple fields of a mutable:
+### `state`
 
-```tsx
-import { createMutable } from "solid-js/store";
+- **Type:** `T`
 
-const state = createMutable({
-	user: {
-		firstName: "John",
-		lastName: "Smith",
-	},
-});
+Mutable store to modify.
 
-<h1>Hello {state.user.firstName + " " + state.user.lastName}</h1>;
-```
+### `modifier`
 
-Modifying n fields in sequence will cause the UI to update n times:
+- **Type:** `(state: T) => T`
 
-```tsx
-state.user.firstName = "Jane";
-state.user.lastName = "Doe";
-```
+Modifier applied to the mutable store.
 
-To trigger just a single update, the fields can be modified using a `batch`:
+## Return value
 
-```tsx
-import { batch } from "solid-js";
+- **Type:** `void`
 
-batch(() => {
-	state.user.firstName = "Jane";
-	state.user.lastName = "Doe";
-});
-```
+## Behavior
 
-`modifyMutable` combined with [`reconcile`](/reference/store-utilities/reconcile) or [`produce`](/reference/store-utilities/produce) provides two alternate ways to do similar things:
+- `modifyMutable` runs inside a [`batch`](/reference/reactive-utilities/batch).
+- Dependent computations update after the modifier completes.
+- The modifier can be a function returned by helpers such as [`reconcile`](/reference/store-utilities/reconcile) or [`produce`](/reference/store-utilities/produce).
 
-```tsx
-import { modifyMutable, reconcile } from "solid-js/store";
+## Examples
 
-// Replace state.user with the specified object (deleting any other fields)
-modifyMutable(
-	state.user,
-	reconcile({
-		firstName: "Jane",
-		lastName: "Doe",
-	})
-);
-```
+### Basic usage
 
 ```tsx
-import { modifyMutable, produce } from "solid-js/store";
+import { createMutable, modifyMutable, produce } from "solid-js/store";
+
+const state = createMutable({
+	user: {
+		firstName: "John",
+		lastName: "Smith",
+	},
+});
 
-// Modify two fields in a batch, triggering just one update
 modifyMutable(
 	state,
 	produce((state) => {
@@ -95,3 +72,9 @@ modifyMutable(
 	})
 );
 ```
+
+## Related
+
+- [`createMutable`](/reference/store-utilities/create-mutable)
+- [`produce`](/reference/store-utilities/produce)
+- [`reconcile`](/reference/store-utilities/reconcile)

From b38966382dd369cc372c29c620260a318dc97ca2 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:28:32 -0700
Subject: [PATCH 14/88] migrate store creation and mutable store refs

---
 .../reference/store-utilities/produce.mdx     | 59 +++++++++----
 .../reference/store-utilities/reconcile.mdx   | 87 ++++++++++++-------
 .../reference/store-utilities/unwrap.mdx      | 56 +++++++++---
 3 files changed, 143 insertions(+), 59 deletions(-)

diff --git a/src/routes/reference/store-utilities/produce.mdx b/src/routes/reference/store-utilities/produce.mdx
index 447b4889b..fb035cc9b 100644
--- a/src/routes/reference/store-utilities/produce.mdx
+++ b/src/routes/reference/store-utilities/produce.mdx
@@ -1,50 +1,73 @@
 ---
 title: produce
 use_cases: >-
-  immutable updates, immer-style mutations, store modifications, complex state
-  changes, nested updates
+  store updates, nested store changes, draft-style mutations
 tags:
   - store
-  - immutable
   - updates
-  - immer
   - mutations
 version: "1.0"
 description: >-
-  Use Immer-inspired produce API to mutate Solid stores immutably. Simplify
-  complex nested updates with familiar mutation syntax.
+  Create a store modifier that applies changes by mutating a draft value.
 ---
 
-`produce` is an [Immer](https://immerjs.github.io/immer/) inspired API for Solid's Store objects that allows the store to be mutated inside the `produce` function.
+`produce` creates a store modifier that applies changes by mutating a draft value.
+
+## Import
 
 ```ts
 import { produce } from "solid-js/store";
-import type { NotWrappable, Store } from "solid-js/store";
+```
+
+## Type
 
-function produce<T>(
-	fn: (state: T) => void
-): (
-	state: T extends NotWrappable ? T : Store<T>
-) => T extends NotWrappable ? T : Store<T>;
+```ts
+function produce<T>(fn: (state: T) => void): (state: T) => T;
 ```
 
-For use with `createStore`:
+## Parameters
+
+### `fn`
+
+- **Type:** `(state: T) => void`
+
+Function that mutates the provided draft state.
+
+## Return value
+
+- **Type:** `(state: T) => T`
+
+Store modifier function.
+
+## Behavior
+
+- `produce` returns a function that can be passed to store setters or [`modifyMutable`](/reference/store-utilities/modify-mutable).
+- The modifier receives a mutable draft of the current state.
+- Nested properties can be changed inside the modifier.
+
+## Examples
+
+### Basic usage
 
 ```tsx
-import { produce } from "solid-js/store";
+import { createStore, produce } from "solid-js/store";
 
 const [state, setState] = createStore({
 	user: {
 		name: "John",
-		age: 30,
 	},
-	list: ["book", "pen"],
+	list: ["book"],
 });
 
 setState(
 	produce((state) => {
 		state.user.name = "Jane";
-		state.list.push("pencil");
+		state.list.push("pen");
 	})
 );
 ```
+
+## Related
+
+- [`modifyMutable`](/reference/store-utilities/modify-mutable)
+- [`reconcile`](/reference/store-utilities/reconcile)
diff --git a/src/routes/reference/store-utilities/reconcile.mdx b/src/routes/reference/store-utilities/reconcile.mdx
index 11ad1cc8d..769bb596a 100644
--- a/src/routes/reference/store-utilities/reconcile.mdx
+++ b/src/routes/reference/store-utilities/reconcile.mdx
@@ -1,58 +1,83 @@
 ---
 title: reconcile
 use_cases: >-
-  api responses, data synchronization, immutable data diffing, observable
-  subscriptions, large data updates
+  syncing store state, applying immutable data updates, diffing incoming data
 tags:
   - store
   - diffing
-  - api
   - synchronization
-  - immutable
 version: "1.0"
 description: >-
-  Efficiently diff and merge data changes with reconcile. Perfect for syncing
-  API responses or handling immutable data updates.
+  Create a store modifier that reconciles existing state with a new value.
 ---
 
-`reconcile` is designed for diffing data changes in situations where granular updates cannot be applied.
-This is useful when dealing with immutable data from stores or handling large API responses.
+`reconcile` creates a store modifier that reconciles existing state with a new value.
 
-```tsx
+## Import
+
+```ts
 import { reconcile } from "solid-js/store";
-import type { NotWrappable, Store } from "solid-js/store";
+```
 
-function reconcile<T>(
-	value: T | Store<T>,
+## Type
+
+```ts
+function reconcile<T extends U, U>(
+	value: T,
 	options?: {
 		key?: string | null;
 		merge?: boolean;
-	} = { key: "id" }
-): (
-	state: T extends NotWrappable ? T : Store<T>
-) => T extends NotWrappable ? T : Store<T>;
+	}
+): (state: U) => T;
 ```
 
-`reconcile` has a `key` option that can be used when available to match items.
-The `value` accepts either a value of type `T` or a Store containing values of type `T`.
-This represents the data to be reconciled.
+## Parameters
+
+### `value`
+
+- **Type:** `T`
+
+New value to reconcile against the current state.
+
+### `options`
+
+#### `key`
+
+- **Type:** `string | null`
 
-The `reconcile` function helps manage data changes by performing a diffing process, making it particularly handy in scenarios where applying granular updates is challenging or inefficient.
+Key used to match items during reconciliation.
 
-The `key` and `merge` options provide flexibility to customize the reconciliation process based on specific needs.
+#### `merge`
+
+- **Type:** `boolean`
+
+Controls whether reconciliation pushes updates to the leaves instead of replacing non-matching branches.
+
+## Return value
+
+- **Type:** `(state: U) => T`
+
+Store modifier function.
+
+## Behavior
+
+- `reconcile` performs a diff between the current state and `value`.
+- With the default `key`, array items are matched by `"id"`.
+- When `merge` is `false`, non-matching branches can be replaced.
+- When `merge` is `true`, reconciliation pushes updates deeper into the structure.
+
+## Examples
+
+### Basic usage
 
 ```ts
-// subscribing to an observable
-const unsubscribe = store.subscribe(({ todos }) => (
-  setState('todos', reconcile(todos));
-);
-onCleanup(() => unsubscribe());
+import { createStore, reconcile } from "solid-js/store";
+
+const [state, setState] = createStore({ todos: [] });
 
+setState("todos", reconcile([{ id: 1, title: "Write docs" }]));
 ```
 
-##### Options
+## Related
 
-| Option | Type    | Default | Description                                                                                                                                                                                                                                                            |
-| ------ | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| key    | string  | "id"    | Specifies the key to be used for matching items during reconciliation                                                                                                                                                                                                  |
-| merge  | boolean | false   | When merge is false, referential checks are performed where possible to determine equality, and items that are not referentially equal are replaced. When merge is true, all diffing is pushed to the leaves, effectively morphing the previous data to the new value. |
+- [`produce`](/reference/store-utilities/produce)
diff --git a/src/routes/reference/store-utilities/unwrap.mdx b/src/routes/reference/store-utilities/unwrap.mdx
index 7ca79f2ae..3a76907c5 100644
--- a/src/routes/reference/store-utilities/unwrap.mdx
+++ b/src/routes/reference/store-utilities/unwrap.mdx
@@ -1,25 +1,61 @@
 ---
 title: unwrap
 use_cases: >-
-  raw data access, proxy removal, debugging, third-party integration, data
-  serialization
+  reading store data without proxies, passing plain data to other APIs
 tags:
   - store
   - proxy
   - data
-  - debugging
-  - utilities
 version: "1.0"
 description: >-
-  Extract raw data from Solid stores without proxy wrapping. Essential for
-  debugging, serialization, or third-party integrations.
+  Remove store proxy wrapping from a store or store subtree.
 ---
 
-`unwrap` returns the underlying data in the store without a proxy.
+`unwrap` removes store proxy wrapping from a store or store subtree.
 
-```tsx
+## Import
+
+```ts
 import { unwrap } from "solid-js/store";
-import type { Store } from "solid-js/store";
+```
+
+## Type
 
-function unwrap(store: Store<T>): T;
+```ts
+function unwrap<T>(item: T): T;
 ```
+
+## Parameters
+
+### `item`
+
+- **Type:** `T`
+
+Store value or store subtree to unwrap.
+
+## Return value
+
+- **Type:** `T`
+
+Unwrapped value.
+
+## Behavior
+
+- Store proxies are removed recursively from returned objects and arrays.
+- Returned objects and arrays are plain values rather than reactive store proxies.
+- Non-proxy input values are returned unchanged.
+
+## Examples
+
+### Basic usage
+
+```ts
+import { createStore, unwrap } from "solid-js/store";
+
+const [state] = createStore({ user: { name: "John" } });
+const user = unwrap(state.user);
+```
+
+## Related
+
+- [`createStore`](/reference/store-utilities/create-store)

From 313cd7a7c022e3612e1878651f2778ca2c04e90b Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:33:26 -0700
Subject: [PATCH 15/88] migrate jsx attribute refs and attribute directives

---
 src/routes/reference/jsx-attributes/attr.mdx | 47 +++++++++++-----
 src/routes/reference/jsx-attributes/bool.mdx | 58 +++++++++++++-------
 src/routes/reference/jsx-attributes/prop.mdx | 45 +++++++++++----
 src/routes/reference/jsx-attributes/ref.mdx  | 47 +++++++++++-----
 4 files changed, 140 insertions(+), 57 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/attr.mdx b/src/routes/reference/jsx-attributes/attr.mdx
index 8352c7d46..469f7a2c3 100644
--- a/src/routes/reference/jsx-attributes/attr.mdx
+++ b/src/routes/reference/jsx-attributes/attr.mdx
@@ -1,29 +1,50 @@
 ---
 title: "attr:*"
 use_cases: >-
-  web components, custom elements, forcing attributes, html attributes, dom
-  properties
+  custom elements, forcing attribute assignment, writing HTML attributes
 tags:
   - attributes
-  - web-components
   - dom
-  - props
-  - typescript
   - custom-elements
 version: "1.0"
 description: >-
-  Force props as HTML attributes instead of properties in SolidJS. Essential for
-  Web Components and custom element attribute handling.
+  Force a JSX key to be written as an attribute instead of a property.
 ---
 
-Forces the prop to be treated as an attribute instead of a property.
-Useful for Web Components where you want to set attributes.
-
-```tsx
-<my-element attr:status={props.status} />
-```
+`attr:*` forces a JSX key to be written as an attribute instead of a property.
 
 :::note[Strong-Typing Custom Attributes]
 Type definitions are required when using TypeScript.
 See the[TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
 :::
+
+## Syntax
+
+```tsx
+<my-element attr:status={value} />
+```
+
+## Value
+
+- **Type:** attribute value
+
+Value written to the attribute after the `attr:` prefix is removed.
+
+## Behavior
+
+- `attr:name={value}` writes the value to the `name` attribute.
+- The `attr:` prefix is removed before the attribute is written.
+- This is useful when an element expects data through attributes rather than DOM properties.
+
+## Examples
+
+### Basic usage
+
+```tsx
+<my-element attr:status={props.status} />
+```
+
+## Related
+
+- [`prop:*`](/reference/jsx-attributes/prop)
+- [`bool:*`](/reference/jsx-attributes/bool)
diff --git a/src/routes/reference/jsx-attributes/bool.mdx b/src/routes/reference/jsx-attributes/bool.mdx
index 4b2699e70..3cfbb279b 100644
--- a/src/routes/reference/jsx-attributes/bool.mdx
+++ b/src/routes/reference/jsx-attributes/bool.mdx
@@ -1,39 +1,59 @@
 ---
 title: "bool:*"
 use_cases: >-
-  web components, custom elements, conditional attributes, boolean attributes,
-  dynamic attribute presence
+  boolean attributes, custom elements, controlling attribute presence
 tags:
   - attributes
-  - web-components
   - boolean
-  - conditional
-  - dynamic
+  - custom-elements
 version: "1.0"
 description: >-
-  Control attribute presence with bool:* directive in SolidJS. Add or remove
-  attributes dynamically based on truthy/falsy values for web components.
+  Control whether an attribute is present by writing through `bool:*`.
 ---
 
-`bool:*` controls the presence of an attribute in an element.
-When the value is `truthy` it adds the `attribute` to the element.
-Alternatively, when the value is `falsy` it removes the `attribute` from the element.
-This attribute is most useful for Web Components.
+`bool:*` controls whether an attribute is present on an element.
+
+:::note[Strong-Typing Custom Boolean Attributes]
+Type definitions are required when using TypeScript.
+See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
+:::
+
+## Syntax
 
 ```tsx
-<my-element bool:status={prop.value} />
+<my-element bool:status={value} />
 ```
 
+## Value
+
+- **Type:** any truthy or falsy value
+
+Truthy values add the attribute. Falsy values remove it.
+
+## Behavior
+
+- `bool:name={value}` adds `name` when `value` is truthy.
+- `bool:name={value}` removes `name` when `value` is falsy.
+- When present, the attribute is written as an empty string attribute.
+
+## Examples
+
+### Basic usage
+
+```tsx
+<my-element bool:status={props.value} />
+```
+
+### Resulting markup
+
 ```tsx
-// Assuming `prop.value` is `truthy`, then it becomes
+// props.value is truthy
 <my-element status />
 
-// And when `falsy`, then it becomes
+// props.value is falsy
 <my-element />
-
 ```
 
-:::note[Strong-Typing Custom Boolean Attributes]
-Type definitions are required when using TypeScript.
-See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
-:::
+## Related
+
+- [`attr:*`](/reference/jsx-attributes/attr)
diff --git a/src/routes/reference/jsx-attributes/prop.mdx b/src/routes/reference/jsx-attributes/prop.mdx
index 8dbdded12..a9c13ecec 100644
--- a/src/routes/reference/jsx-attributes/prop.mdx
+++ b/src/routes/reference/jsx-attributes/prop.mdx
@@ -2,27 +2,50 @@
 title: "prop:*"
 order: 6
 use_cases: >-
-  dom properties, scrolltop manipulation, custom properties, property vs
-  attribute, direct property access
+  forcing property assignment, writing DOM properties, custom element property
+  access
 tags:
   - properties
   - dom
   - attributes
-  - manipulation
-  - custom
 version: "1.0"
 description: >-
-  Force DOM property assignment with prop:* in SolidJS. Set properties directly
-  instead of attributes for specific DOM manipulation needs.
+  Force a JSX key to be written as a DOM property instead of an attribute.
 ---
 
-Forces the prop to be treated as a property instead of an attribute.
-
-```tsx
-<div prop:scrollTop={props.scrollPos + "px"} />
-```
+`prop:*` forces a JSX key to be written as a DOM property instead of an attribute.
 
 :::note[Strong-Typing Custom Properties]
 Type definitions are required when using TypeScript.
 See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
 :::
+
+## Syntax
+
+```tsx
+<div prop:scrollTop={value} />
+```
+
+## Value
+
+- **Type:** property value
+
+Value assigned to the property after the `prop:` prefix is removed.
+
+## Behavior
+
+- `prop:name={value}` assigns the value to the `name` property.
+- The `prop:` prefix is removed before the assignment happens.
+- This is useful when an element expects data through properties rather than attributes.
+
+## Examples
+
+### Basic usage
+
+```tsx
+<div prop:scrollTop={props.scrollPos} />
+```
+
+## Related
+
+- [`attr:*`](/reference/jsx-attributes/attr)
diff --git a/src/routes/reference/jsx-attributes/ref.mdx b/src/routes/reference/jsx-attributes/ref.mdx
index 0ef8edbae..452a6f2cc 100644
--- a/src/routes/reference/jsx-attributes/ref.mdx
+++ b/src/routes/reference/jsx-attributes/ref.mdx
@@ -2,37 +2,56 @@
 title: ref
 order: 7
 use_cases: >-
-  dom access, element manipulation, focus management, measurements, third-party
-  libraries, animations
+  element references, imperative DOM access, component refs
 tags:
   - refs
   - dom
   - elements
-  - access
-  - manipulation
-  - components
 version: "1.0"
 description: >-
-  Access DOM elements directly in SolidJS with refs. Get references to rendered
-  elements for imperative operations and third-party integrations.
+  Capture a rendered element or forwarded component ref.
 ---
 
-Refs are a way of getting access to underlying DOM elements in our JSX. While it is true one could just assign an element to a variable, it is more optimal to leave components in the flow of JSX. Refs are assigned at render time but before the elements are connected to the DOM. They come in 2 flavors.
+`ref` captures a rendered element or forwarded component ref.
+
+## Syntax
+
+```tsx
+<div ref={value} />
+```
+
+## Value
+
+- **Type:** variable binding or callback function
+
+Receives the rendered element or forwarded ref value.
+
+## Behavior
+
+- Refs are assigned during rendering before the element is connected to the DOM.
+- A variable ref assigns the rendered element to the referenced variable.
+- A callback ref is called with the rendered element.
+- Component refs work only when the component forwards the `ref` prop to an underlying element or child component.
+
+## Examples
+
+### Variable ref
 
 ```tsx
-// variable assigned directly by ref
 let myDiv;
 
-// use onMount or createEffect to read after connected to the DOM
 onMount(() => console.log(myDiv));
 
-<div ref={myDiv} />
+<div ref={myDiv} />;
+```
+
+### Callback ref
 
-// Or, callback function (called before connected to the DOM)
-<div ref={el => console.log(el)} />
+```tsx
+<div ref={(el) => console.log(el)} />
 ```
 
-Refs can also be used on Components. They still need to be attached on the other side.
+### Component ref
 
 ```tsx
 function MyComp(props) {

From 20117b92a906f5f1925984cd5c5f541e2184d685 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:34:31 -0700
Subject: [PATCH 16/88] add warning to suspense list

---
 src/routes/reference/components/suspense-list.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/components/suspense-list.mdx b/src/routes/reference/components/suspense-list.mdx
index a819185c9..c46c47ffc 100644
--- a/src/routes/reference/components/suspense-list.mdx
+++ b/src/routes/reference/components/suspense-list.mdx
@@ -16,6 +16,10 @@ description: >-
   Coordinate how multiple suspense boundaries reveal their content.
 ---
 
+:::[warning]
+This is an experimental component
+:::
+
 `<SuspenseList>` coordinates nested suspense boundaries.
 
 ## Import
@@ -66,10 +70,6 @@ Controls fallback visibility for later items after the first still-pending item.
 - With `tail="collapsed"`, later pending items can keep a fallback visible after the first pending item.
 - With `tail="hidden"`, later pending items hide their fallback after the first pending item.
 
-## Notes
-
-- `<SuspenseList>` is experimental.
-
 ## Examples
 
 ### Basic usage

From 921e3b15bdbcfa471ee73a9c1d77dadb559d79c2 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:40:45 -0700
Subject: [PATCH 17/88] jsx styling and content attribute refs

---
 .../reference/jsx-attributes/classlist.mdx    | 62 ++++++++-----------
 .../reference/jsx-attributes/innerhtml.mdx    | 41 +++++++++---
 src/routes/reference/jsx-attributes/style.mdx | 60 ++++++++++--------
 .../reference/jsx-attributes/textcontent.mdx  | 40 +++++++++---
 4 files changed, 124 insertions(+), 79 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/classlist.mdx b/src/routes/reference/jsx-attributes/classlist.mdx
index 679274322..07bc43364 100644
--- a/src/routes/reference/jsx-attributes/classlist.mdx
+++ b/src/routes/reference/jsx-attributes/classlist.mdx
@@ -2,41 +2,46 @@
 title: classList
 order: 1
 use_cases: >-
-  styling components, dynamic classes, conditional styles, toggling classes,
-  reactive styling
+  toggling classes, conditional classes, reactive class updates
 tags:
   - styling
   - css
   - classes
   - reactive
-  - conditional
-  - dom
 version: "1.0"
 description: >-
-  Manage element classes dynamically in SolidJS with class and classList
-  attributes. Toggle multiple classes reactively based on application state.
+  Toggle element classes from an object of class names and boolean values.
 ---
 
-Solid offers two attributes to set the class of an element: `class` and `classList`.
+:::warning
+`className` was deprecated in Solid 1.4 in favor of `class`.
+:::
+
+`classList` toggles element classes from an object of class names and boolean values.
 
-First, `class` can be set like other attributes. For example:
+## Syntax
 
 ```tsx
-// Two static classes
-<div class="active editing" />
+<div classList={{ active: state.active }} />
+```
 
-// One dynamic class, deleting class attribute if it's not needed
-<div class={state.active ? 'active' : undefined} />
+## Value
 
-// Two dynamic classes
-<div class={`${state.active ? 'active' : ''} ${state.currentId === row.id ? 'editing' : ''}`} />
-```
+- **Type:** `Record<string, boolean | undefined | null>`
 
-:::note
-Note that `className` was deprecated in Solid 1.4 in favor of {" "} `class`.
-:::
+Object whose keys are class names and whose values control whether each class is present.
+
+## Behavior
+
+- Each key is treated as a class name.
+- Truthy values add the class and falsy values remove it.
+- Updates are applied per class rather than replacing the whole `class` attribute.
+- `classList` is a compile-time pseudo-attribute and does not work through prop spreads or `<Dynamic>`.
+- If both `class` and `classList` are reactive, updates to `class` can overwrite classes managed by `classList`.
 
-Alternatively, the `classList` pseudo-attribute lets you specify an object, where each key is a class and the value is treated as a boolean representing whether to include that class. For example (matching the last example):
+## Examples
+
+### Basic usage
 
 ```tsx
 <div
@@ -47,23 +52,8 @@ Alternatively, the `classList` pseudo-attribute lets you specify an object, wher
 />
 ```
 
-This example compiles to a render effect that dynamically calls [element.classList.toggle](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList/toggle) to turn each class on or off, only when the corresponding boolean changes. For example, when `state.active` becomes true [false], the element gains [loses] the `active` class.
-
-The value passed into `classList` can be any expression (including a signal getter) that evaluates to an appropriate object. Some examples:
+### Dynamic class name
 
 ```tsx
-// Dynamic class name and value
 <div classList={{ [className()]: classOn() }} />
-
-// Signal class list
-const [classes, setClasses] = createSignal({})
-setClasses((c) => ({ ...c, active: true }))
-<div classList={classes()} />
-```
-
-While possible, mixing `class` and `classList` in Solid can lead to unexpected behavior.
-The safest approach is to use a static string (or nothing) for `class` and keep `classList` reactive.
-You can also use a static computed value for class, such as `class={baseClass()}`, however you must make sure it comes before any `classList` pseudo-attributes.
-If both `class` and `classList` are reactive, changes to `class` will overwrite the entire `class` attribute, potentially undoing any updates made by `classList`.
-
-Because classList is a compile-time pseudo-attribute, it does not work in a prop spread like `<div {...props} />` or in `<Dynamic>`.
+```
\ No newline at end of file
diff --git a/src/routes/reference/jsx-attributes/innerhtml.mdx b/src/routes/reference/jsx-attributes/innerhtml.mdx
index 54083560d..7bd2a9ccc 100644
--- a/src/routes/reference/jsx-attributes/innerhtml.mdx
+++ b/src/routes/reference/jsx-attributes/innerhtml.mdx
@@ -1,25 +1,48 @@
 ---
 title: innerHTML
 use_cases: >-
-  rendering html strings, dynamic html content, third-party html, legacy content
-  migration, sanitized markup
+  rendering HTML strings, replacing element children with parsed markup
 tags:
   - html
   - dom
   - security
-  - content
   - markup
 version: "1.0"
 description: >-
-  Set raw HTML content in SolidJS elements using innerHTML attribute and render
-  HTML strings dynamically.
+  Set an element's `innerHTML` property from JSX.
 ---
 
-The `innerHTML` attribute is equivalent to the [`innerHTML` DOM property](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML).
-This attribute replaces all existing nodes of the element with new nodes generated by parsing the provided string as HTML.
+`innerHTML` sets an element's `innerHTML` property.
 
-:::caution
+## Syntax
 
-Using `innerHTML` with unsanitized user-supplied data can introduce security vulnerabilities.
+```tsx
+<div innerHTML={html} />
+```
+
+## Value
+
+- **Type:** `string`
+
+HTML string parsed into the element.
+
+## Behavior
+
+- Setting `innerHTML` replaces the element's existing children with nodes parsed from the string.
+- The value is written through the DOM `innerHTML` property.
 
+:::caution
+Using `innerHTML` with unsanitized user-supplied data can introduce security vulnerabilities.
 :::
+
+## Examples
+
+### Basic usage
+
+```tsx
+<div innerHTML={markup} />
+```
+
+## Related
+
+- [`textContent`](/reference/jsx-attributes/textcontent)
diff --git a/src/routes/reference/jsx-attributes/style.mdx b/src/routes/reference/jsx-attributes/style.mdx
index 13546e732..ead49483d 100644
--- a/src/routes/reference/jsx-attributes/style.mdx
+++ b/src/routes/reference/jsx-attributes/style.mdx
@@ -2,51 +2,61 @@
 title: style
 order: 7
 use_cases: >-
-  inline styling, dynamic styles, css variables, responsive design, theme
-  customization, animated styles
+  inline styles, dynamic style values, CSS variables
 tags:
   - styling
   - css
   - inline
   - variables
-  - dynamic
-  - properties
 version: "1.0"
 description: >-
-  Apply dynamic inline styles in SolidJS with string or object syntax. Set CSS
-  properties and variables reactively for responsive component styling.
+  Set inline styles with a CSS string or an object of property names and values.
 ---
 
-Solid's style attribute lets you provide either a CSS string or an object where keys are CSS property names:
+`style` sets inline styles from either a CSS string or an object.
+
+## Syntax
 
 ```tsx
-// string
-<div style={`color: green; height: ${state.height}px`} />
+<div style="color: green" />
+<div style={{ color: "green" }} />
+```
 
-// object
-<div style={{
-  color: "green",
-  height: state.height + "px" }}
-/>
+## Value
+
+- **Type:** `string | Record<string, string | undefined | null>`
+
+CSS string or style object.
+
+## Behavior
+
+- String values are written as inline CSS text.
+- Object values are applied property by property with `element.style.setProperty`.
+- Object keys should use lower-case, dash-separated CSS property names.
+- CSS custom properties can be set with keys such as `--my-color`.
+
+## Examples
+
+### CSS string
+
+```tsx
+<div style={`color: green; height: ${state.height}px`} />
 ```
 
-Unlike [React's style attribute](https://reactjs.org/docs/dom-elements.html#style), Solid uses **element.style.setProperty** under the hood. This means you need to use the lower-case, dash-separated version of property names instead of the JavaScript camel-cased version, such as `background-color` rather than `backgroundColor`. This actually leads to better performance and consistency with SSR output.
+### Style object
 
 ```tsx
-// string
-<div style={`color: green; background-color: ${state.color}; height: ${state.height}px`} />
-
-// object
-<div style={{
-  color: "green",
-  "background-color": state.color,
-  height: state.height + "px" }}
+<div
+	style={{
+		color: "green",
+		"background-color": state.color,
+		height: `${state.height}px`,
+	}}
 />
 ```
 
-This also means you can set CSS variables! For example:
+### CSS variable
 
 ```tsx
-// set css variable
 <div style={{ "--my-custom-color": state.themeColor }} />
 ```
diff --git a/src/routes/reference/jsx-attributes/textcontent.mdx b/src/routes/reference/jsx-attributes/textcontent.mdx
index b7da41f98..c7f2f1c3c 100644
--- a/src/routes/reference/jsx-attributes/textcontent.mdx
+++ b/src/routes/reference/jsx-attributes/textcontent.mdx
@@ -1,21 +1,43 @@
 ---
 title: textContent
 use_cases: >-
-  text-only content, performance optimization, plain text rendering, avoiding
-  html parsing, simple text updates
+  text-only content, replacing element children with text
 tags:
   - text
-  - performance
   - content
-  - optimization
   - dom
 version: "1.0"
 description: >-
-  Optimize text rendering with textContent in SolidJS. Bypass diffing for
-  text-only content and improve performance for simple text updates.
+  Set an element's `textContent` property from JSX.
 ---
 
-The `textContent` attribute is equivalent to the [`textContent` DOM property](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
-This attribute replaces all existing child nodes of the element with a single text node containing the provided string.
+`textContent` sets an element's `textContent` property.
 
-Using `textContent` can improve performance when the element's children are known to be exclusively text, as it bypasses the generic diffing process.
+## Syntax
+
+```tsx
+<div textContent={value} />
+```
+
+## Value
+
+- **Type:** `string | number`
+
+Text written to the element.
+
+## Behavior
+
+- Setting `textContent` replaces the element's existing children with a single text node.
+- The value is written through the DOM `textContent` property.
+
+## Examples
+
+### Basic usage
+
+```tsx
+<div textContent={count()} />
+```
+
+## Related
+
+- [`innerHTML`](/reference/jsx-attributes/innerhtml)

From 759a60b7086b44fe8f89f7cb6de449a8d2c189fa Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 14:44:07 -0700
Subject: [PATCH 18/88] jsx event and directive reference pages

---
 src/routes/reference/jsx-attributes/on.mdx   |  60 +++++++----
 src/routes/reference/jsx-attributes/on_.mdx  |  56 ++++++----
 src/routes/reference/jsx-attributes/once.mdx |  30 ++++--
 src/routes/reference/jsx-attributes/use.mdx  | 106 ++++++-------------
 4 files changed, 121 insertions(+), 131 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/on.mdx b/src/routes/reference/jsx-attributes/on.mdx
index 14c47100a..b9c7d72d3 100644
--- a/src/routes/reference/jsx-attributes/on.mdx
+++ b/src/routes/reference/jsx-attributes/on.mdx
@@ -2,51 +2,67 @@
 title: "on:*"
 order: 4
 use_cases: >-
-  custom events, non-bubbling events, capture phase handling, passive listeners,
-  special event options
+  direct event listeners, custom event names, event listener options
 tags:
   - events
   - listeners
   - dom
   - capture
   - passive
-  - handlers
 version: "1.0"
 description: >-
-  Attach non-delegated event handlers with on:* in SolidJS. Control capture,
-  passive, and once options for advanced event handling requirements.
+  Attach an event listener directly to an element with `addEventListener`.
 ---
 
-For events with capital letters, listener options, or if you need to attach event handlers directly to a DOM element instead of optimized delegating via the document, use `on:*` in place of `on*`.
+`on:*` attaches an event listener directly to an element with `addEventListener`.
+
+## Syntax
 
 ```tsx
-<div on:DOMContentLoaded={(e) => console.log("Welcome!")} />
+<div on:wheel={handler} />
 ```
 
-This directly attaches an event handler (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`.
+## Value
 
-:::note
+- **Type:** event handler function or `EventListenerObject & AddEventListenerOptions`
 
-<span>New in v1.9.0</span>
-:::
+Listener passed to `addEventListener`.
+
+## Behavior
+
+- `on:name={handler}` attaches a listener for the event named `name`.
+- The listener is attached directly to the element instead of using Solid's delegated event system.
+- Event names keep the text after `on:` exactly as written.
+- Listener options such as `once`, `passive`, `capture`, and `signal` can be provided by passing an object that implements `handleEvent`.
+
+## Examples
+
+### Basic usage
 
-An aditional special syntax that allows full control of [`capture`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#capture), [`passive`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#passive), [`once`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#once) and [`signal`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#signal) is an intersection or combination of `EventListenerObject` & `AddEventListenerOptions`, as follows:
+```tsx
+<div on:DOMContentLoaded={(e) => console.log("Welcome!", e)} />
+```
+
+### Listener options
 
 ```tsx
 const handler = {
 	handleEvent(e) {
-		console.log(e)
+		console.log(e);
 	},
-	once:true,
-	passive:false,
-	capture:true
-}
+	once: true,
+	passive: false,
+	capture: true,
+};
 
-<div on:wheel={handler} />
+<div on:wheel={handler} />;
+```
 
-// or inline
+:::note
+The object-listener form was added in Solid 1.9.0.
+:::
 
-<div on:click={{passive:true, handleEvent(e) { console.log("Weeeee!")}}} />
-```
+## Related
 
-This new syntax replaces the now deprecated `oncapture:` and it's future proof for any posible new event listener options.
+- [`on*`](/reference/jsx-attributes/on_)
+- [`oncapture:*`](/reference/jsx-attributes/on)
diff --git a/src/routes/reference/jsx-attributes/on_.mdx b/src/routes/reference/jsx-attributes/on_.mdx
index 9f8f314c8..0349efd54 100644
--- a/src/routes/reference/jsx-attributes/on_.mdx
+++ b/src/routes/reference/jsx-attributes/on_.mdx
@@ -2,48 +2,58 @@
 title: on*
 order: 3
 use_cases: >-
-  user interactions, click handlers, form events, keyboard input, mouse events,
-  touch handling
+  delegated UI events, click handlers, input handlers, keyboard handlers
 tags:
   - events
   - handlers
-  - interactions
-  - click
-  - input
   - delegation
+  - dom
 version: "1.0"
 description: >-
-  Handle user events efficiently in SolidJS with onClick and other event
-  handlers. Optimized delegation system for improved performance at scale.
+  Attach an event handler with Solid's delegated event system when the event is
+  supported.
 ---
 
-Event handlers in Solid typically take the form of `onclick` or `onClick` depending on style.
+`on*` attaches an event handler using Solid's delegated event system when the event is supported.
+
+## Syntax
 
 ```tsx
-<div onClick={(e) => console.log(e.currentTarget)} />
+<div onClick={handler} />
 ```
 
-Conceptually, this example attaches a `click` event listener (via [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)) to the `div`. However, Solid actually handles common UI events that bubble and are composed (such as `click`) at the document level, and then synthetically implements delegation (capturing and bubbling). This improves performance for these common events by reducing the number of event handlers.
+## Value
 
-Note that `onClick` handles the event `click`; in general, event names get mapped to lower case. If you need to work with event names containing capital letters, or use listener options such once, passive, capture see [`on:`](/reference/jsx-attributes/on) which attaches event handlers directly (also avoiding fancy delegation via document).
+- **Type:** event handler function or `[handler, data]`
 
-Solid also supports passing a two-element array to the event handler to bind a value to the first argument of the event handler. This doesn't use `bind` or create an additional closure, so it is a highly optimized way of delegating events.
+Event handler, or a handler/data pair for delegated binding.
 
-```tsx
-function handler(itemId, e) {
-	/*...*/
-}
+## Behavior
+
+- Common delegated events are handled at the document level instead of attaching one listener per element.
+- Event names are mapped to lower case, so `onClick` listens to `click`.
+- The two-element array form passes the first item as bound data to the handler.
+- Delegated bindings are not reactive and are not rebound automatically.
+- For direct element listeners, custom event casing, or listener options, use [`on:*`](/reference/jsx-attributes/on).
+
+## Examples
 
-<ul>
-	<For each={state.list}>{(item) => <li onClick={[handler, item.id]} />}</For>
-</ul>;
+### Basic usage
+
+```tsx
+<div onClick={(e) => console.log(e.currentTarget)} />
 ```
 
-Events are never rebound and the bindings are not reactive, as it is expensive to attach and detach listeners. Since event handlers are called like any other function each time an event fires, there is no need for reactivity; shortcut your handler if desired.
+### Handler and bound data
 
 ```tsx
-// if defined, call it; otherwise don't.
-<div onClick={() => props.handleClick?.()} />
+function handler(itemId, e) {
+	console.log(itemId, e);
+}
+
+<For each={state.list}>{(item) => <li onClick={[handler, item.id]} />}</For>;
 ```
 
-Note that `onChange` and `onInput` work according to their native behavior (unlike, say, React). [`onInput`](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) will fire immediately after the value has changed; for most `<input>` fields, [`onChange`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event) will only fire after the field loses focus. The event's `currentTarget` refers to the element that the event was attached to, while `target` gives the element that actually triggered the event (e.g. the user clicked on).
+## Related
+
+- [`on:*`](/reference/jsx-attributes/on)
diff --git a/src/routes/reference/jsx-attributes/once.mdx b/src/routes/reference/jsx-attributes/once.mdx
index 15d2e71e5..69b4f9f3e 100644
--- a/src/routes/reference/jsx-attributes/once.mdx
+++ b/src/routes/reference/jsx-attributes/once.mdx
@@ -2,29 +2,39 @@
 title: "@once"
 order: 5
 use_cases: >-
-  performance optimization, static props, non-reactive values, compile-time
-  optimization, reducing overhead
+  non-reactive JSX expressions, compile-time opt-out from reactive wrapping
 tags:
-  - optimization
-  - performance
-  - static
   - compiler
   - jsx
+  - optimization
 version: "1.0"
 description: >-
-  Optimize SolidJS components with @once decorator for static values. Prevent
-  unnecessary reactive wrapping and improve runtime performance.
+  Mark a JSX expression so the compiler does not wrap it reactively.
 ---
 
-Solid's compiler uses a heuristic for reactive wrapping and lazy evaluation of JSX expressions. Does it contain a function call, a property access, or JSX? If yes we wrap it in a getter when passed to components or in an effect if passed to native elements.
+`/*@once*/` marks a JSX expression so the compiler does not wrap it reactively.
+
+## Syntax
+
+```tsx
+<MyComponent value={/*@once*/ expr} />
+```
+
+## Behavior
+
+- `/*@once*/` applies to the expression that follows it.
+- It tells the compiler not to wrap that expression in reactive access machinery.
+- It can be used in props and in children.
+
+## Examples
 
-Knowing this heuristic and its limitations, we can reduce overhead of things we know will never change by accessing them outside of the JSX. A lone variable will never be wrapped. We can also tell the compiler not to wrap them by starting the expression with a comment decorator `/* @once */`.
+### Prop value
 
 ```tsx
 <MyComponent static={/*@once*/ state.wontUpdate} />
 ```
 
-This also works on children.
+### Child value
 
 ```tsx
 <MyComponent>{/*@once*/ state.wontUpdate}</MyComponent>
diff --git a/src/routes/reference/jsx-attributes/use.mdx b/src/routes/reference/jsx-attributes/use.mdx
index 2cf934561..3dbbde30d 100644
--- a/src/routes/reference/jsx-attributes/use.mdx
+++ b/src/routes/reference/jsx-attributes/use.mdx
@@ -2,39 +2,51 @@
 title: "use:*"
 order: 5
 use_cases: >-
-  complex dom interactions, tooltips, form handling, two-way data binding,
-  reusable element behaviors, custom input components
+  reusable DOM behavior, directives, element setup helpers
 tags:
   - directives
   - dom
-  - forms
-  - bindings
-  - components
-  - typescript
+  - jsx
 version: "1.0"
 description: >-
-  Create custom directives in SolidJS to attach reusable behaviors to DOM
-  elements. Perfect for tooltips, form handling, and two-way data binding.
+  Attach a directive function to a native element with `use:*`.
 ---
 
-Custom directives attach reusable behavior to DOM elements, acting as syntactic sugar over `ref`. They’re ideal for complex DOM interactions like scrolling, tooltips, or form handling, which are cumbersome to repeat in JSX.
+`use:*` attaches a directive function to a native element.
 
-A directive is a function with the following signature
+## Syntax
+
+```tsx
+<input use:model={[value, setValue]} />
+```
+
+## Type
 
 ```ts
+type Accessor<T> = () => T;
+
 function directive(element: HTMLElement, accessor: Accessor<any>): void;
 ```
 
-Directive functions are called at render time but before being added to the DOM. You can do whatever you'd like in them including create signals, effects, register clean-up etc.
+## Value
 
-## Example
+- **Type:** directive argument
 
-A `model` directive for two-way data binding
+Value exposed to the directive through its accessor.
 
-```tsx
-import type { Accessor, Signal } from "solid-js";
+## Behavior
+
+- `use:name={value}` calls the directive named `name` with the element and an accessor for `value`.
+- Directive functions run during rendering before the element is connected to the DOM.
+- Directives only work on native elements, including custom elements.
+- Directives are not forwarded through user-defined components.
+
+## Examples
 
-function model(element: HTMLInputElement, value: Accessor<Signal<string>>) {
+### Basic usage
+
+```tsx
+function model(element, value) {
 	const [field, setField] = value();
 	createRenderEffect(() => (element.value = field()));
 	element.addEventListener("input", ({ target }) => setField(target.value));
@@ -45,64 +57,6 @@ const [name, setName] = createSignal("");
 <input type="text" use:model={[name, setName]} />;
 ```
 
-## TypeScript Support
-
-To type custom directives, extend the `DirectiveFunctions` interface
-
-```ts
-declare module "solid-js" {
-	namespace JSX {
-		interface DirectiveFunctions {
-			model: typeof model;
-		}
-	}
-}
-```
-
-If you just want to constrain the second argument to the directive function, you can extend the older `Directives` interface
-
-```tsx
-declare module "solid-js" {
-	namespace JSX {
-		interface Directives {
-			model: Signal<string>;
-		}
-	}
-}
-```
-
-## Avoiding Tree-Shaking
-
-When importing a directive `d` from another module and using it only as `use:d`, TypeScript (via [babel-preset-typescript](https://babeljs.io/docs/babel-preset-typescript)) may remove the import, as it doesn’t recognize `use:d` as a reference to `d`.
-To prevent this:
-
-1. Use the `onlyRemoveTypeImports: true` option in `babel-preset-typescript`. For `vite-plugin-solid`, add this to `vite.config.ts`
-
-   ```ts
-   import solidPlugin from "vite-plugin-solid";
-
-   export default {
-   	plugins: [
-   		solidPlugin({
-   			typescript: { onlyRemoveTypeImports: true },
-   		}),
-   	],
-   };
-   ```
-
-   Note: This requires consistent use of `export type` and `import type` in your codebase to avoid issues.
-
-2. Add a fake access like `false && d;` in the module
-
-   ```tsx
-   import { model } from "./directives";
-   false && model; // Prevents tree-shaking
-   <input type="text" use:model={[name, setName]} />;
-   ```
-
-   This is removed by bundlers like Terser, unlike a plain `model;` which may remain in the bundle.
-
-:::caution[Limitations]
-Directives only work with native HTML elements (HTML/SVG/MathML/Custom Elements).
-Directives are not forwarded and **won't work in user defined components**, such as `<MyComponent use:myinput={[..]}/>` [see also](https://github.com/solidjs/solid/discussions/722)
+:::note
+When using TypeScript, custom directives may require extending Solid's JSX directive typings.
 :::

From d992ace1087f0c3ecd28106d43c55555137b3f6f Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 15:15:09 -0700
Subject: [PATCH 19/88] update children

---
 .../reference/component-apis/children.mdx     | 28 ++++++++++---------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/src/routes/reference/component-apis/children.mdx b/src/routes/reference/component-apis/children.mdx
index 45b2a80c5..ee083ebb9 100644
--- a/src/routes/reference/component-apis/children.mdx
+++ b/src/routes/reference/component-apis/children.mdx
@@ -13,7 +13,7 @@ description: >-
   Resolve a component's `children` prop into a stable accessor.
 ---
 
-`children` resolves a component's `children` prop and returns an accessor for the resolved result.
+`children` resolves a component's `children` prop and returns a stable accessor for the resolved result.
 
 ## Import
 
@@ -24,10 +24,8 @@ import { children } from "solid-js";
 ## Type
 
 ```ts
-function children(fn: Accessor<JSX.Element>): ChildrenReturn;
-
-type ChildrenReturn = Accessor<ResolvedChildren> & {
-	toArray: () => ResolvedChildren[];
+function children(fn: Accessor<JSX.Element>): Accessor<JSX.Element> & {
+	toArray: () => JSX.Element[];
 };
 ```
 
@@ -42,16 +40,16 @@ Accessor that returns the component's `children` value.
 
 ## Return value
 
-- **Type:** `ChildrenReturn`
+- **Type:** `Accessor<JSX.Element> & { toArray: () => JSX.Element[] }`
 
 Returns an accessor for the resolved children.
 The accessor also exposes `toArray()`.
 
 ## Behavior
 
-- `children` resolves functions, arrays, fragments, and nested child structures.
-- The returned accessor reads the current resolved value of `props.children`.
-- `toArray()` returns a flattened array of resolved child elements.
+- 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`.
+- `toArray()` returns the resolved children as an array. It returns `[]` when the resolved value is `null` or `undefined`.
 
 ## Examples
 
@@ -63,7 +61,12 @@ import { children } from "solid-js";
 function Wrapper(props) {
 	const resolved = children(() => props.children);
 
-	return <div>{resolved()}</div>;
+	return (
+		<div>
+			<header>{resolved()}</header>
+			<div>{resolved()}</div>
+		</div>
+	);
 }
 ```
 
@@ -74,11 +77,10 @@ import { children } from "solid-js";
 
 function List(props) {
 	const resolved = children(() => props.children);
-	const items = resolved.toArray();
 
 	return (
 		<ul>
-			{items.map((child) => (
+			{resolved.toArray().map((child) => (
 				<li>{child}</li>
 			))}
 		</ul>
@@ -88,4 +90,4 @@ function List(props) {
 
 ## Related
 
-- [`createContext`](/reference/component-apis/create-context)
+- [Props](/concepts/components/props)

From 599b55c00cd5164f81e55d059befba83b8e5ad0f Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 15:19:52 -0700
Subject: [PATCH 20/88] update

---
 .../reference/component-apis/create-context.mdx  | 16 ++++++++++------
 .../reference/component-apis/use-context.mdx     | 10 ++++++----
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/src/routes/reference/component-apis/create-context.mdx b/src/routes/reference/component-apis/create-context.mdx
index 93fd78195..c6fa4e8be 100644
--- a/src/routes/reference/component-apis/create-context.mdx
+++ b/src/routes/reference/component-apis/create-context.mdx
@@ -16,7 +16,7 @@ description: >-
 ---
 
 `createContext` creates a context object.
-The returned object contains a `Provider` component and a `defaultValue`; [`useContext`](/reference/component-apis/use-context) reads the nearest matching provider value.
+The returned object contains a `Provider` component and an optional `defaultValue`; [`useContext`](/reference/component-apis/use-context) reads the nearest matching provider value.
 
 ## Import
 
@@ -37,6 +37,11 @@ function createContext<T>(
 	defaultValue?: undefined,
 	options?: { name?: string }
 ): Context<T | undefined>;
+
+function createContext<T>(
+	defaultValue: T,
+	options?: { name?: string }
+): Context<T>;
 ```
 
 ## Parameters
@@ -64,9 +69,8 @@ Returns a context object containing `id`, `Provider`, and `defaultValue`.
 ## Behavior
 
 - `Context.Provider` passes its `value` prop to descendant calls to [`useContext`](/reference/component-apis/use-context).
-- If no matching provider is found, `useContext` returns `defaultValue` when one was supplied.
-- If no matching provider is found and no default value was supplied, `useContext` returns `undefined`.
-- Calling `useContext` outside the owner tree of a matching provider also returns the default value or `undefined`.
+- `useContext` reads the nearest matching provider in the current owner tree.
+- If no matching provider is found, `useContext` returns `defaultValue` when one was supplied, or `undefined` otherwise.
 
 ## Notes
 
@@ -91,11 +95,11 @@ const ThemeContext = createContext<Theme>("light");
 ```tsx
 import { createContext } from "solid-js";
 
-const CounterContext = createContext<number>();
+const CounterContext = createContext<{ count: number }>();
 
 function CounterProvider(props) {
 	return (
-		<CounterContext.Provider value={1}>
+		<CounterContext.Provider value={{ count: 1 }}>
 			{props.children}
 		</CounterContext.Provider>
 	);
diff --git a/src/routes/reference/component-apis/use-context.mdx b/src/routes/reference/component-apis/use-context.mdx
index 255295d02..0f9be9aeb 100644
--- a/src/routes/reference/component-apis/use-context.mdx
+++ b/src/routes/reference/component-apis/use-context.mdx
@@ -14,7 +14,7 @@ description: >-
   Read the current value of a context object created by `createContext`.
 ---
 
-`useContext` returns the current value for a context object.
+`useContext` reads the nearest provider value for a context object in the current owner tree.
 
 ## Import
 
@@ -48,14 +48,14 @@ Context object created by [`createContext`](/reference/component-apis/create-con
 - **Type:** `T`
 
 Returns the value provided by the nearest matching `Context.Provider`.
+If the context was created without a default value, `T` can include `undefined`.
 If no provider is found, it returns the context's default value or `undefined`.
 
 ## Behavior
 
 - `useContext` reads the nearest matching provider in the current owner tree.
-- When no provider is found, it returns the default value from [`createContext`](/reference/component-apis/create-context).
-- When no provider is found and no default value was supplied, the result is `undefined`.
-- Calling `useContext` outside the owner tree of a matching provider returns the default value or `undefined`.
+- If no matching provider is found, it returns the default value from [`createContext`](/reference/component-apis/create-context), or `undefined` when no default value was supplied.
+- A provider value of `undefined` is treated the same as a missing provider and returns the default value or `undefined`.
 
 ## Examples
 
@@ -75,6 +75,8 @@ function CounterValue() {
 
 ### Throw when a provider is missing
 
+This example checks for `undefined` when the context was created without a default value.
+
 ```ts
 import { createContext, useContext } from "solid-js";
 

From 7c4ba3c7aa36e05474ce0f2efaf262b20e667643 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 15:24:54 -0700
Subject: [PATCH 21/88] update

---
 public/llms.txt                               |  5 ++
 .../reference/components/create-dynamic.mdx   | 74 +++++++++++++++++++
 src/routes/reference/components/data.json     |  1 +
 src/routes/reference/components/dynamic.mdx   | 54 +++-----------
 4 files changed, 91 insertions(+), 43 deletions(-)
 create mode 100644 src/routes/reference/components/create-dynamic.mdx

diff --git a/public/llms.txt b/public/llms.txt
index f0cd0ce39..fbff7eef6 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -103,6 +103,7 @@
 - [DEV](https://docs.solidjs.com/reference/rendering/dev)
 - [hydrate](https://docs.solidjs.com/reference/rendering/hydrate)
 - [hydrationScript](https://docs.solidjs.com/reference/rendering/hydration-script)
+- [isDev](https://docs.solidjs.com/reference/rendering/is-dev)
 - [isServer](https://docs.solidjs.com/reference/rendering/is-server)
 - [render](https://docs.solidjs.com/reference/rendering/render)
 - [renderToStream](https://docs.solidjs.com/reference/rendering/render-to-stream)
@@ -125,6 +126,7 @@
 
 - [Overview](https://docs.solidjs.com/solid-start/)
 - [Getting started](https://docs.solidjs.com/solid-start/getting-started)
+- [Migrating from v1](https://docs.solidjs.com/solid-start/migrating-from-v1)
 - [Routing](https://docs.solidjs.com/solid-start/building-your-application/routing)
 - [API routes](https://docs.solidjs.com/solid-start/building-your-application/api-routes)
 - [CSS and styling](https://docs.solidjs.com/solid-start/building-your-application/css-and-styling)
@@ -137,6 +139,7 @@
 - [Sessions](https://docs.solidjs.com/solid-start/advanced/session)
 - [Request events](https://docs.solidjs.com/solid-start/advanced/request-events)
 - [Returning responses](https://docs.solidjs.com/solid-start/advanced/return-responses)
+- [Serialization](https://docs.solidjs.com/solid-start/advanced/serialization)
 - [Auth](https://docs.solidjs.com/solid-start/advanced/auth)
 - [WebSocket endpoint](https://docs.solidjs.com/solid-start/advanced/websocket)
 - [Security](https://docs.solidjs.com/solid-start/guides/security)
@@ -182,6 +185,7 @@
 - [Revalidation](https://docs.solidjs.com/solid-router/data-fetching/revalidation)
 - [Preload data](https://docs.solidjs.com/solid-router/data-fetching/how-to/preload-data)
 - [Handle pending and error states](https://docs.solidjs.com/solid-router/data-fetching/how-to/handle-error-and-loading-states)
+- [Preloading](https://docs.solidjs.com/solid-router/advanced-concepts/preloading)
 - [Lazy loading](https://docs.solidjs.com/solid-router/advanced-concepts/lazy-loading)
 - [Migration from v0.9.x](https://docs.solidjs.com/solid-router/guides/migration)
 - [A](https://docs.solidjs.com/solid-router/reference/components/a)
@@ -225,3 +229,4 @@
 - [MetaProvider](https://docs.solidjs.com/solid-meta/reference/meta/metaprovider)
 - [Style](https://docs.solidjs.com/solid-meta/reference/meta/style)
 - [Title](https://docs.solidjs.com/solid-meta/reference/meta/title)
+- [useHead](https://docs.solidjs.com/solid-meta/reference/meta/use-head)
diff --git a/src/routes/reference/components/create-dynamic.mdx b/src/routes/reference/components/create-dynamic.mdx
new file mode 100644
index 000000000..6773febe8
--- /dev/null
+++ b/src/routes/reference/components/create-dynamic.mdx
@@ -0,0 +1,74 @@
+---
+title: createDynamic
+use_cases: >-
+  dynamic components, runtime component selection, polymorphic components,
+  lower-level rendering helpers, library components
+tags:
+  - dynamic
+  - components
+  - jsx
+  - polymorphic
+  - rendering
+version: "1.0"
+description: >-
+  Render a component or intrinsic element selected at runtime from an accessor.
+---
+
+`createDynamic` renders the value returned by its `component` accessor as either a custom component or an intrinsic element.
+
+## Import
+
+```ts
+import { createDynamic } from "solid-js/web";
+```
+
+## Type
+
+```ts
+type ValidComponent =
+	| keyof JSX.IntrinsicElements
+	| ((props: any) => JSX.Element);
+
+function createDynamic<T extends ValidComponent>(
+	component: () => T | undefined,
+	props: ComponentProps<T>
+): JSX.Element;
+```
+
+## Parameters
+
+### `component`
+
+- **Type:** `() => T | undefined`
+
+Accessor that returns the component or intrinsic element to render.
+
+### `props`
+
+- **Type:** props accepted by the rendered component or element
+
+Props passed to the rendered component or element.
+
+## Return value
+
+- **Type:** `JSX.Element`
+
+Returns the rendered component or element.
+
+## Behavior
+
+- If `component()` is `undefined`, nothing is rendered.
+
+## Example
+
+```tsx
+import { createDynamic } from "solid-js/web";
+
+function Example(props) {
+	return createDynamic(() => props.as, { type: "button", children: "Save" });
+}
+```
+
+## Related
+
+- [`<Dynamic>`](/reference/components/dynamic)
diff --git a/src/routes/reference/components/data.json b/src/routes/reference/components/data.json
index 716b071e6..18de882d2 100644
--- a/src/routes/reference/components/data.json
+++ b/src/routes/reference/components/data.json
@@ -1,6 +1,7 @@
 {
 	"title": "Components",
 	"pages": [
+		"create-dynamic.mdx",
 		"dynamic.mdx",
 		"error-boundary.mdx",
 		"for.mdx",
diff --git a/src/routes/reference/components/dynamic.mdx b/src/routes/reference/components/dynamic.mdx
index 8229c7e26..5fed38209 100644
--- a/src/routes/reference/components/dynamic.mdx
+++ b/src/routes/reference/components/dynamic.mdx
@@ -12,16 +12,15 @@ tags:
   - rendering
 version: "1.0"
 description: >-
-  Render a component or intrinsic element selected at runtime, and access the
-  lower-level `createDynamic` helper.
+  Render a component or intrinsic element selected at runtime.
 ---
 
-`<Dynamic>` renders the value of its `component` prop as either a custom component or an intrinsic element. `createDynamic` provides the same behavior as a function.
+`<Dynamic>` renders the value of its `component` prop as either a custom component or an intrinsic element.
 
 ## Import
 
 ```ts
-import { Dynamic, createDynamic } from "solid-js/web";
+import { Dynamic } from "solid-js/web";
 ```
 
 ## Type
@@ -31,14 +30,11 @@ type ValidComponent =
 	| keyof JSX.IntrinsicElements
 	| ((props: any) => JSX.Element);
 
-type DynamicProps<T extends ValidComponent> = {
+type DynamicProps<T extends ValidComponent, P = ComponentProps<T>> = {
+	[K in keyof P]: P[K];
+} & {
 	component: T | undefined;
-} & Record<string, unknown>;
-
-function createDynamic<T extends ValidComponent>(
-	component: () => T | undefined,
-	props: Record<string, unknown>
-): JSX.Element;
+};
 
 function Dynamic<T extends ValidComponent>(props: DynamicProps<T>): JSX.Element;
 ```
@@ -57,20 +53,6 @@ Component or intrinsic element to render.
 
 Props forwarded to the rendered value of `component`.
 
-## Parameters
-
-### `component`
-
-- **Type:** `() => T | undefined`
-
-Accessor that returns the component or intrinsic element to render.
-
-### `props`
-
-- **Type:** `Record<string, unknown>`
-
-Props passed to the rendered component or element.
-
 ## Return value
 
 - **Type:** `JSX.Element`
@@ -79,32 +61,18 @@ Returns the rendered component or element.
 
 ## Behavior
 
-- When `component` resolves to a function, Solid calls that component with the provided props.
-- When `component` resolves to a string, Solid creates an intrinsic element of that type and spreads the provided props onto it.
-- `<Dynamic>` calls `createDynamic(() => props.component, others)` internally after separating the `component` prop from the remaining props.
-
-## Examples
+- When `component` is `undefined`, nothing is rendered.
 
-### Basic usage
+## Example
 
 ```tsx
 import { Dynamic } from "solid-js/web";
 
 function Example(props) {
-	return <Dynamic component={props.as} value={props.value} />;
-}
-```
-
-### `createDynamic`
-
-```tsx
-import { createDynamic } from "solid-js/web";
-
-function Example(props) {
-	return createDynamic(() => props.as, { value: props.value });
+	return <Dynamic component={props.as} type="button" children="Save" />;
 }
 ```
 
 ## Related
 
-- [`<Portal>`](/reference/components/portal)
+- [`createDynamic`](/reference/components/create-dynamic)

From 78ba4881bdede9c204a8a22fa09b2b40811d5de8 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Fri, 3 Apr 2026 15:27:16 -0700
Subject: [PATCH 22/88] update

---
 src/routes/reference/components/error-boundary.mdx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/routes/reference/components/error-boundary.mdx b/src/routes/reference/components/error-boundary.mdx
index c222b6032..07a71d50d 100644
--- a/src/routes/reference/components/error-boundary.mdx
+++ b/src/routes/reference/components/error-boundary.mdx
@@ -50,9 +50,11 @@ Subtree wrapped by the boundary.
 
 - **Type:** `JSX.Element`
 
+Returns the rendered children or fallback content.
+
 ## Behavior
 
-- `<ErrorBoundary>` catches errors thrown while rendering JSX and while updating reactive computations in its subtree.
+- `<ErrorBoundary>` catches errors thrown while rendering JSX and while updating reactive computations in its subtree, including reactive async primitives when they surface through the same rendering or update flow.
 - Errors thrown from event handlers or from callbacks scheduled outside Solid's rendering and update flow are not caught by the boundary.
 - Function fallbacks receive `reset`, which clears the current error state and re-renders the children.
 - Errors thrown by the fallback itself can be caught by a parent error boundary.

From 6b391a0bede787aa0e297e9716b7141e1a3b1ae8 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 16:33:30 -0700
Subject: [PATCH 23/88] update

---
 src/routes/reference/components/for.mdx | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/src/routes/reference/components/for.mdx b/src/routes/reference/components/for.mdx
index 631b9a82d..ddbf554b2 100644
--- a/src/routes/reference/components/for.mdx
+++ b/src/routes/reference/components/for.mdx
@@ -49,7 +49,7 @@ Source list.
 
 - **Type:** `JSX.Element`
 
-Content rendered when `each` is empty or falsy.
+Content rendered when `each` is an empty array, `undefined`, `null`, or `false`.
 
 ### `children`
 
@@ -64,8 +64,8 @@ Child function. It receives the current item and an index accessor.
 ## Behavior
 
 - `<For>` maps items by value identity.
+- If the same item value appears at a new position, its rendered node can be moved instead of recreated.
 - The `index` argument is an accessor.
-- Reordering reuses rendered items whose source values are retained.
 - `<For>` uses [`mapArray`](/reference/reactive-utilities/map-array) internally.
 
 ## Examples
@@ -73,9 +73,7 @@ Child function. It receives the current item and an index accessor.
 ### Basic usage
 
 ```tsx
-import { For } from "solid-js";
-
-<For each={state.list} fallback={<div>No items</div>}>
+<For each={items()} fallback={<div>No items</div>}>
 	{(item) => <div>{item}</div>}
 </For>;
 ```
@@ -83,9 +81,7 @@ import { For } from "solid-js";
 ### Access the index
 
 ```tsx
-import { For } from "solid-js";
-
-<For each={state.list}>
+<For each={items()}>
 	{(item, index) => (
 		<div>
 			#{index()} {item}

From 2bda9b9c8f6e2fd218c9f2e86e4c29b855913a3e Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 17:20:38 -0700
Subject: [PATCH 24/88] update

---
 .../reference/component-apis/children.mdx     | 22 +++++++++++++++----
 .../reference/components/create-dynamic.mdx   | 18 +++++++++++----
 src/routes/reference/components/dynamic.mdx   | 18 +++++++++++----
 .../reference/components/error-boundary.mdx   |  2 --
 src/routes/reference/components/for.mdx       | 10 ++++++---
 .../reference/components/index-component.mdx  | 14 ++++++------
 6 files changed, 60 insertions(+), 24 deletions(-)

diff --git a/src/routes/reference/component-apis/children.mdx b/src/routes/reference/component-apis/children.mdx
index ee083ebb9..a820ef375 100644
--- a/src/routes/reference/component-apis/children.mdx
+++ b/src/routes/reference/component-apis/children.mdx
@@ -56,8 +56,6 @@ The accessor also exposes `toArray()`.
 ### Basic usage
 
 ```tsx
-import { children } from "solid-js";
-
 function Wrapper(props) {
 	const resolved = children(() => props.children);
 
@@ -68,13 +66,20 @@ function Wrapper(props) {
 		</div>
 	);
 }
+
+function Example() {
+	return (
+		<Wrapper>
+			<span>First</span>
+			<span>Second</span>
+		</Wrapper>
+	);
+}
 ```
 
 ### Flatten children into an array
 
 ```tsx
-import { children } from "solid-js";
-
 function List(props) {
 	const resolved = children(() => props.children);
 
@@ -86,6 +91,15 @@ function List(props) {
 		</ul>
 	);
 }
+
+function Example() {
+	return (
+		<List>
+			<span>Alpha</span>
+			<span>Beta</span>
+		</List>
+	);
+}
 ```
 
 ## Related
diff --git a/src/routes/reference/components/create-dynamic.mdx b/src/routes/reference/components/create-dynamic.mdx
index 6773febe8..323c8101a 100644
--- a/src/routes/reference/components/create-dynamic.mdx
+++ b/src/routes/reference/components/create-dynamic.mdx
@@ -62,11 +62,21 @@ Returns the rendered component or element.
 ## Example
 
 ```tsx
-import { createDynamic } from "solid-js/web";
+const views = {
+	red: () => <p style={{ color: "red" }}>Red</p>,
+	blue: () => <p style={{ color: "blue" }}>Blue</p>,
+};
+
+const [selected, setSelected] = createSignal<keyof typeof views>("red");
+
+	return (
+		<>
+			<button onClick={() => setSelected("red")}>Red</button>
+			<button onClick={() => setSelected("blue")}>Blue</button>
 
-function Example(props) {
-	return createDynamic(() => props.as, { type: "button", children: "Save" });
-}
+			<Dynamic component={views[selected()]} />
+		</>
+	);
 ```
 
 ## Related
diff --git a/src/routes/reference/components/dynamic.mdx b/src/routes/reference/components/dynamic.mdx
index 5fed38209..045fc4380 100644
--- a/src/routes/reference/components/dynamic.mdx
+++ b/src/routes/reference/components/dynamic.mdx
@@ -66,11 +66,21 @@ Returns the rendered component or element.
 ## Example
 
 ```tsx
-import { Dynamic } from "solid-js/web";
+const views = {
+	red: () => <p style={{ color: "red" }}>Red</p>,
+	blue: () => <p style={{ color: "blue" }}>Blue</p>,
+};
+
+const [selected, setSelected] = createSignal<keyof typeof views>("red");
+
+	return (
+		<>
+			<button onClick={() => setSelected("red")}>Red</button>
+			<button onClick={() => setSelected("blue")}>Blue</button>
 
-function Example(props) {
-	return <Dynamic component={props.as} type="button" children="Save" />;
-}
+			<Dynamic component={views[selected()]} />
+		</>
+	);
 ```
 
 ## Related
diff --git a/src/routes/reference/components/error-boundary.mdx b/src/routes/reference/components/error-boundary.mdx
index 07a71d50d..6936e22f2 100644
--- a/src/routes/reference/components/error-boundary.mdx
+++ b/src/routes/reference/components/error-boundary.mdx
@@ -64,8 +64,6 @@ Returns the rendered children or fallback content.
 ### Basic usage
 
 ```tsx
-import { ErrorBoundary } from "solid-js";
-
 <ErrorBoundary
 	fallback={(error, reset) => (
 		<div>
diff --git a/src/routes/reference/components/for.mdx b/src/routes/reference/components/for.mdx
index ddbf554b2..09dfc674e 100644
--- a/src/routes/reference/components/for.mdx
+++ b/src/routes/reference/components/for.mdx
@@ -73,7 +73,9 @@ Child function. It receives the current item and an index accessor.
 ### Basic usage
 
 ```tsx
-<For each={items()} fallback={<div>No items</div>}>
+const items = ["A", "B", "C"];
+
+<For each={items} fallback={<div>No items</div>}>
 	{(item) => <div>{item}</div>}
 </For>;
 ```
@@ -81,10 +83,12 @@ Child function. It receives the current item and an index accessor.
 ### Access the index
 
 ```tsx
-<For each={items()}>
+const items = ["A", "B", "C"];
+
+<For each={items}>
 	{(item, index) => (
 		<div>
-			#{index()} {item}
+			#{index} {item}
 		</div>
 	)}
 </For>;
diff --git a/src/routes/reference/components/index-component.mdx b/src/routes/reference/components/index-component.mdx
index 4ec170c1c..3a1fb7030 100644
--- a/src/routes/reference/components/index-component.mdx
+++ b/src/routes/reference/components/index-component.mdx
@@ -1,14 +1,13 @@
 ---
 title: <Index>
 use_cases: >-
-  primitive arrays, non-keyed lists, index-based rendering, static positions,
+  non-keyed lists, index-based rendering, fixed positions, changing values,
   simple lists
 tags:
   - lists
   - iteration
   - components
   - arrays
-  - primitives
   - index
 version: "1.0"
 description: >-
@@ -48,7 +47,7 @@ Source list.
 
 - **Type:** `JSX.Element`
 
-Content rendered when `each` is empty or falsy.
+Content rendered when `each` is an empty array, `undefined`, `null`, or `false`.
 
 ### `children`
 
@@ -66,6 +65,7 @@ Child function. It receives an accessor for the item at that index and the index
 - The `item` argument is an accessor.
 - The `index` argument is a number.
 - Updating a value at the same index updates the corresponding rendered item.
+- When the array is reordered, rendered positions stay tied to indexes, and `item()` updates to the current value at that index.
 - `<Index>` uses [`indexArray`](/reference/reactive-utilities/index-array) internally.
 
 ## Examples
@@ -73,9 +73,9 @@ Child function. It receives an accessor for the item at that index and the index
 ### Basic usage
 
 ```tsx
-import { Index } from "solid-js";
+const items = ["A", "B", "C"];
 
-<Index each={state.list} fallback={<div>No items</div>}>
+<Index each={items} fallback={<div>No items</div>}>
 	{(item) => <div>{item()}</div>}
 </Index>;
 ```
@@ -83,9 +83,9 @@ import { Index } from "solid-js";
 ### Access the index
 
 ```tsx
-import { Index } from "solid-js";
+const items = ["A", "B", "C"];
 
-<Index each={state.list}>
+<Index each={items}>
 	{(item, index) => (
 		<div>
 			#{index} {item()}

From d00622efd5611d343e0a085c83d13a9f936ccae8 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 17:21:48 -0700
Subject: [PATCH 25/88] update

---
 src/routes/reference/components/create-dynamic.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/components/create-dynamic.mdx b/src/routes/reference/components/create-dynamic.mdx
index 323c8101a..97edeb3e5 100644
--- a/src/routes/reference/components/create-dynamic.mdx
+++ b/src/routes/reference/components/create-dynamic.mdx
@@ -74,7 +74,7 @@ const [selected, setSelected] = createSignal<keyof typeof views>("red");
 			<button onClick={() => setSelected("red")}>Red</button>
 			<button onClick={() => setSelected("blue")}>Blue</button>
 
-			<Dynamic component={views[selected()]} />
+			{createDynamic(() => views[selected()], {})}
 		</>
 	);
 ```

From b25c82b95f74e9c3ef03d4d5d925a4a656188ed5 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 17:25:52 -0700
Subject: [PATCH 26/88] update

---
 src/routes/reference/components/no-hydration.mdx | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/src/routes/reference/components/no-hydration.mdx b/src/routes/reference/components/no-hydration.mdx
index 0064ddb96..c07cee268 100644
--- a/src/routes/reference/components/no-hydration.mdx
+++ b/src/routes/reference/components/no-hydration.mdx
@@ -39,11 +39,13 @@ Content inside the boundary.
 
 - **Type:** `JSX.Element`
 
+Returns the server-rendered children.
+
 ## Behavior
 
 - During server rendering, children inside `<NoHydration>` render normally.
-- During client hydration, Solid skips hydrating that subtree.
-- Event listeners and reactive updates are not attached to content inside the boundary during hydration.
+- During client hydration, Solid leaves the existing server-rendered DOM in place and does not hydrate that subtree.
+- Interactive behavior inside the boundary does not hydrate on the client.
 - Placing `<Hydration>` inside `<NoHydration>` does not override the no-hydration behavior.
 
 ## Examples
@@ -51,8 +53,6 @@ Content inside the boundary.
 ### Basic usage
 
 ```tsx
-import { NoHydration } from "solid-js/web";
-
 function Example() {
 	return (
 		<div>
@@ -64,7 +64,3 @@ function Example() {
 	);
 }
 ```
-
-## Related
-
-- [`<Portal>`](/reference/components/portal)

From 878aa466525174049e54f08b6c4d2a0dbc381e76 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 17:34:44 -0700
Subject: [PATCH 27/88] update

---
 src/routes/reference/components/portal.mdx | 38 ++++++++++++++++------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/src/routes/reference/components/portal.mdx b/src/routes/reference/components/portal.mdx
index 23c9b7449..ad85b150e 100644
--- a/src/routes/reference/components/portal.mdx
+++ b/src/routes/reference/components/portal.mdx
@@ -61,7 +61,7 @@ Creates an SVG `<g>` container instead of an HTML `<div>`.
 
 - **Type:** `HTMLDivElement | SVGGElement | ((el: HTMLDivElement | SVGGElement) => void)`
 
-Receives the portal container element.
+Receives the created portal container element. This is a `<div>` by default or a `<g>` when `isSVG` is `true`.
 
 ### `children`
 
@@ -80,6 +80,7 @@ Returns a marker node used to preserve the portal position in the component tree
 - `<Portal>` renders its children outside the parent DOM hierarchy, but events still propagate through the Solid component hierarchy.
 - When the mount target is not `document.head`, the portal creates a container element and appends it to the mount target.
 - When the mount target is `document.head`, the portal inserts its children without creating that container element.
+- During server rendering, `<Portal>` returns no output.
 - Portals render only on the client and are skipped during hydration.
 
 ## Examples
@@ -87,17 +88,34 @@ Returns a marker node used to preserve the portal position in the component tree
 ### Basic usage
 
 ```tsx
+import { createSignal, Show } from "solid-js";
 import { Portal } from "solid-js/web";
 
-function Example() {
-	return (
-		<Portal mount={document.getElementById("modal-root")!}>
-			<div>My Content</div>
-		</Portal>
+function App() {
+  const [open, setOpen] = createSignal(false);
+
+return (
+		<>
+			<button onClick={() => setOpen(true)}>Open</button>
+
+			<Show when={open()}>
+				<Portal>
+					<div
+						style={{
+							position: "fixed",
+							top: "2rem",
+							left: "2rem",
+							padding: "1rem",
+							background: "white",
+							border: "1px solid #ccc",
+						}}
+					>
+						<div>Popup</div>
+						<button onClick={() => setOpen(false)}>Close</button>
+					</div>
+				</Portal>
+			</Show>
+		</>
 	);
 }
 ```
-
-## Related
-
-- [`<Dynamic>`](/reference/components/dynamic)

From 8d5a5ae9becaa143b1b031a4ff8e298c6c4708f8 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 17:59:18 -0700
Subject: [PATCH 28/88] update

---
 .../reference/components/create-dynamic.mdx   | 12 +++++++----
 src/routes/reference/components/dynamic.mdx   | 12 +++++++----
 .../reference/components/error-boundary.mdx   |  6 +++++-
 src/routes/reference/components/for.mdx       |  2 +-
 .../reference/components/no-hydration.mdx     |  4 ++--
 src/routes/reference/components/portal.mdx    |  5 ++---
 src/routes/reference/components/show.mdx      | 21 ++++++++++---------
 7 files changed, 37 insertions(+), 25 deletions(-)

diff --git a/src/routes/reference/components/create-dynamic.mdx b/src/routes/reference/components/create-dynamic.mdx
index 97edeb3e5..4996cfe38 100644
--- a/src/routes/reference/components/create-dynamic.mdx
+++ b/src/routes/reference/components/create-dynamic.mdx
@@ -62,21 +62,25 @@ Returns the rendered component or element.
 ## Example
 
 ```tsx
+import { createSignal } from "solid-js";
+
 const views = {
-	red: () => <p style={{ color: "red" }}>Red</p>,
-	blue: () => <p style={{ color: "blue" }}>Blue</p>,
+	red: (props: { label: string }) => <p style={{ color: "red" }}>{props.label}</p>,
+	blue: (props: { label: string }) => <p style={{ color: "blue" }}>{props.label}</p>,
 };
 
-const [selected, setSelected] = createSignal<keyof typeof views>("red");
+function App() {
+	const [selected, setSelected] = createSignal<keyof typeof views>("red");
 
 	return (
 		<>
 			<button onClick={() => setSelected("red")}>Red</button>
 			<button onClick={() => setSelected("blue")}>Blue</button>
 
-			{createDynamic(() => views[selected()], {})}
+			{createDynamic(() => views[selected()], { label: "Selected view" })}
 		</>
 	);
+}
 ```
 
 ## Related
diff --git a/src/routes/reference/components/dynamic.mdx b/src/routes/reference/components/dynamic.mdx
index 045fc4380..90df187b5 100644
--- a/src/routes/reference/components/dynamic.mdx
+++ b/src/routes/reference/components/dynamic.mdx
@@ -66,21 +66,25 @@ Returns the rendered component or element.
 ## Example
 
 ```tsx
+import { createSignal } from "solid-js";
+
 const views = {
-	red: () => <p style={{ color: "red" }}>Red</p>,
-	blue: () => <p style={{ color: "blue" }}>Blue</p>,
+	red: (props: { label: string }) => <p style={{ color: "red" }}>{props.label}</p>,
+	blue: (props: { label: string }) => <p style={{ color: "blue" }}>{props.label}</p>,
 };
 
-const [selected, setSelected] = createSignal<keyof typeof views>("red");
+function App() {
+	const [selected, setSelected] = createSignal<keyof typeof views>("red");
 
 	return (
 		<>
 			<button onClick={() => setSelected("red")}>Red</button>
 			<button onClick={() => setSelected("blue")}>Blue</button>
 
-			<Dynamic component={views[selected()]} />
+			<Dynamic component={views[selected()]} label="Selected view" />
 		</>
 	);
+}
 ```
 
 ## Related
diff --git a/src/routes/reference/components/error-boundary.mdx b/src/routes/reference/components/error-boundary.mdx
index 6936e22f2..d91e14120 100644
--- a/src/routes/reference/components/error-boundary.mdx
+++ b/src/routes/reference/components/error-boundary.mdx
@@ -64,10 +64,14 @@ Returns the rendered children or fallback content.
 ### Basic usage
 
 ```tsx
+function ErrorProne() {
+	throw new Error("Broken");
+}
+
 <ErrorBoundary
 	fallback={(error, reset) => (
 		<div>
-			<p>{error.message}</p>
+			<p>{String(error)}</p>
 			<button onClick={reset}>Try Again</button>
 		</div>
 	)}
diff --git a/src/routes/reference/components/for.mdx b/src/routes/reference/components/for.mdx
index 09dfc674e..75ec4f86a 100644
--- a/src/routes/reference/components/for.mdx
+++ b/src/routes/reference/components/for.mdx
@@ -88,7 +88,7 @@ const items = ["A", "B", "C"];
 <For each={items}>
 	{(item, index) => (
 		<div>
-			#{index} {item}
+			#{index()} {item}
 		</div>
 	)}
 </For>;
diff --git a/src/routes/reference/components/no-hydration.mdx b/src/routes/reference/components/no-hydration.mdx
index c07cee268..49c6e0cff 100644
--- a/src/routes/reference/components/no-hydration.mdx
+++ b/src/routes/reference/components/no-hydration.mdx
@@ -56,9 +56,9 @@ Returns the server-rendered children.
 function Example() {
 	return (
 		<div>
-			<InteractiveComponent />
+			<button>Interactive button</button>
 			<NoHydration>
-				<StaticContent />
+				<div innerHTML={"<strong>Server-rendered only</strong>"} />
 			</NoHydration>
 		</div>
 	);
diff --git a/src/routes/reference/components/portal.mdx b/src/routes/reference/components/portal.mdx
index ad85b150e..432ae43a7 100644
--- a/src/routes/reference/components/portal.mdx
+++ b/src/routes/reference/components/portal.mdx
@@ -89,12 +89,11 @@ Returns a marker node used to preserve the portal position in the component tree
 
 ```tsx
 import { createSignal, Show } from "solid-js";
-import { Portal } from "solid-js/web";
 
 function App() {
-  const [open, setOpen] = createSignal(false);
+	const [open, setOpen] = createSignal(false);
 
-return (
+	return (
 		<>
 			<button onClick={() => setOpen(true)}>Open</button>
 
diff --git a/src/routes/reference/components/show.mdx b/src/routes/reference/components/show.mdx
index b5d843956..dd0cf37da 100644
--- a/src/routes/reference/components/show.mdx
+++ b/src/routes/reference/components/show.mdx
@@ -67,37 +67,38 @@ Content rendered when `when` is falsy.
 
 ### `children`
 
-- **Type:** `JSX.Element | ((item) => JSX.Element)`
+- **Type:** `JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element) | ((item: NonNullable<T>) => JSX.Element)`
 
-Content rendered when `when` is truthy. Function children receive an accessor or value based on `keyed`.
+Content rendered when `when` is truthy.
 
 ## Return value
 
 - **Type:** `JSX.Element`
 
+Returns the rendered children or `fallback` content.
+
 ## Behavior
 
-- With `keyed` omitted or `false`, `<Show>` re-renders only when the truthiness of `when` changes.
-- With `keyed={true}`, changes to the `when` value itself trigger a new render even when the value remains truthy.
+- With `keyed` omitted or `false`, `<Show>` updates only when the truthiness of `when` changes. Replacing one truthy value with another truthy value does not recreate the child block, and function children receive an accessor that can only be read while the condition remains truthy.
+- With `keyed={true}`, changes to the `when` value trigger a new render even when the value remains truthy, and function children receive the value directly.
 - Function children are wrapped in [`untrack`](/reference/reactive-utilities/untrack).
-- With `keyed={false}`, function children receive an accessor for the current non-nullish value; with `keyed={true}`, they receive the value directly.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-import { Show } from "solid-js";
+const loading = () => false;
 
-<Show when={value()} fallback={<div>Fallback Element</div>}>
-	<div>Child Element</div>
+<Show when={!loading()} fallback={<div>Loading...</div>}>
+	<div>Loaded</div>
 </Show>;
 ```
 
 ### Function child
 
 ```tsx
-import { Show } from "solid-js";
+const user = () => ({ name: "Ada" });
 
 <Show when={user()}>{(user) => <div>{user().name}</div>}</Show>;
 ```
@@ -105,7 +106,7 @@ import { Show } from "solid-js";
 ### Keyed function child
 
 ```tsx
-import { Show } from "solid-js";
+const user = () => ({ name: "Ada" });
 
 <Show when={user()} keyed>
 	{(user) => <div>{user.name}</div>}

From b310a1240f952c824ba31c10ca8d7fdae3be113c Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:01:01 -0700
Subject: [PATCH 29/88] update

---
 src/routes/reference/components/suspense-list.mdx | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/components/suspense-list.mdx b/src/routes/reference/components/suspense-list.mdx
index c46c47ffc..ec6bcffef 100644
--- a/src/routes/reference/components/suspense-list.mdx
+++ b/src/routes/reference/components/suspense-list.mdx
@@ -20,7 +20,7 @@ description: >-
 This is an experimental component
 :::
 
-`<SuspenseList>` coordinates nested suspense boundaries.
+`<SuspenseList>` coordinates how multiple child suspense boundaries reveal their content.
 
 ## Import
 
@@ -62,20 +62,25 @@ Controls fallback visibility for later items after the first still-pending item.
 
 - **Type:** `JSX.Element`
 
+Returns the coordinated suspense boundaries.
+
 ## Behavior
 
 - `revealOrder="forwards"` reveals items from first to last.
 - `revealOrder="backwards"` reveals items from last to first.
 - `revealOrder="together"` reveals all items only after all coordinated boundaries are ready.
-- With `tail="collapsed"`, later pending items can keep a fallback visible after the first pending item.
-- With `tail="hidden"`, later pending items hide their fallback after the first pending item.
+- With `tail="collapsed"`, the first still-pending item can keep its fallback visible, while later pending items hide theirs.
+- With `tail="hidden"`, pending items after the first still-pending item hide their fallbacks.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-import { Suspense, SuspenseList } from "solid-js";
+const resource = {
+	user: { name: "Ada" },
+	posts: ["First post"],
+};
 
 <SuspenseList revealOrder="forwards" tail="collapsed">
 	<Suspense fallback={<h2>Loading profile...</h2>}>

From cc371512cb8660fe080f446c74a1a45a3c26b58e Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:04:52 -0700
Subject: [PATCH 30/88] update

---
 src/routes/reference/components/suspense.mdx | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/src/routes/reference/components/suspense.mdx b/src/routes/reference/components/suspense.mdx
index c66a91041..ba08a2449 100644
--- a/src/routes/reference/components/suspense.mdx
+++ b/src/routes/reference/components/suspense.mdx
@@ -15,7 +15,7 @@ description: >-
   Render fallback content while resources read under the boundary are pending.
 ---
 
-`<Suspense>` tracks resources read under its boundary.
+`<Suspense>` renders `fallback` while resources read under its boundary are pending.
 
 ## Import
 
@@ -50,11 +50,13 @@ Subtree inside the suspense boundary.
 
 - **Type:** `JSX.Element`
 
+Returns the rendered subtree or `fallback` content depending on pending tracked resources.
+
 ## Behavior
 
 - `<Suspense>` is triggered when a resource is read inside the boundary.
 - The boundary waits until pending tracked resources resolve.
-- `<Suspense>` is non-blocking: the subtree still runs while the fallback is rendered.
+- `<Suspense>` is non-blocking: the subtree can continue running before the boundary reveals the resolved content in the DOM.
 - Nested suspense boundaries handle resources read under the nearest boundary.
 - `onMount` and `createEffect` inside the suspended subtree run after the boundary resolves.
 
@@ -63,8 +65,6 @@ Subtree inside the suspense boundary.
 ### Basic usage
 
 ```tsx
-import { Suspense } from "solid-js";
-
 <Suspense fallback={<LoadingSpinner />}>
 	<AsyncComponent />
 </Suspense>;
@@ -73,9 +73,7 @@ import { Suspense } from "solid-js";
 ### Nested suspense
 
 ```tsx
-import { Suspense } from "solid-js";
-
-<Suspense fallback={<div>Loading page</div>}>
+<Suspense fallback={<div>Loading page...</div>}>
 	<h1>{title()}</h1>
 	<Suspense fallback={<div>Loading details</div>}>
 		<DataComponent>{data()}</DataComponent>

From 4d7eb35cb2e0d31332a263bcddb0fe41dfcd3a22 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:05:59 -0700
Subject: [PATCH 31/88] update

---
 src/routes/reference/components/suspense.mdx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/routes/reference/components/suspense.mdx b/src/routes/reference/components/suspense.mdx
index ba08a2449..1d0bcb823 100644
--- a/src/routes/reference/components/suspense.mdx
+++ b/src/routes/reference/components/suspense.mdx
@@ -54,8 +54,7 @@ Returns the rendered subtree or `fallback` content depending on pending tracked
 
 ## Behavior
 
-- `<Suspense>` is triggered when a resource is read inside the boundary.
-- The boundary waits until pending tracked resources resolve.
+- When a resource is read inside the boundary, `<Suspense>` renders `fallback` until the pending tracked resources resolve.
 - `<Suspense>` is non-blocking: the subtree can continue running before the boundary reveals the resolved content in the DOM.
 - Nested suspense boundaries handle resources read under the nearest boundary.
 - `onMount` and `createEffect` inside the suspended subtree run after the boundary resolves.

From b94ffde7643fb44e649891038ced73ef6b9422a8 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:10:47 -0700
Subject: [PATCH 32/88] update

---
 .../reference/components/switch-and-match.mdx | 37 ++++++++-----------
 1 file changed, 15 insertions(+), 22 deletions(-)

diff --git a/src/routes/reference/components/switch-and-match.mdx b/src/routes/reference/components/switch-and-match.mdx
index e4e65de38..fa1da90f9 100644
--- a/src/routes/reference/components/switch-and-match.mdx
+++ b/src/routes/reference/components/switch-and-match.mdx
@@ -77,45 +77,38 @@ Controls whether function children receive the current value directly instead of
 
 ### `children`
 
-- **Type:** `JSX.Element | ((item) => JSX.Element)`
+- **Type:** `JSX.Element | ((item: Accessor<NonNullable<T>>) => JSX.Element) | ((item: NonNullable<T>) => JSX.Element)`
 
-Content rendered when the branch matches. Function children receive an accessor or value based on `keyed`.
+Content rendered when the branch matches.
 
 ## Return value
 
 - **Type:** `JSX.Element`
 
+Returns the selected branch or the `fallback` content.
+
 ## Behavior
 
-- `<Switch>` evaluates its child `<Match>` elements in order and renders the first truthy branch.
+- `<Switch>` evaluates its child `<Match>` elements in order and renders only the first truthy branch.
 - If no branch matches, `<Switch>` renders `fallback`.
-- Function children in `<Match>` follow the same keyed behavior as [`<Show>`](/reference/components/show): with `keyed={false}`, they receive an accessor; with `keyed={true}`, they receive the value directly.
+- With `keyed={false}`, function children in `<Match>` receive an accessor that can only be read while that branch remains selected. With `keyed={true}`, they receive the value directly.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-import { Match, Switch } from "solid-js";
-
-<Switch fallback={<div>Not Found</div>}>
-	<Match when={state.route === "home"}>
-		<Home />
+<Switch fallback={<p>Unknown status</p>}>
+	<Match when={state.status === "loading"}>
+		<p>Loading...</p>
 	</Match>
-	<Match when={state.route === "settings"}>
-		<Settings />
+	<Match when={state.status === "success"}>
+		<p>Saved</p>
 	</Match>
-</Switch>;
-```
-
-### Function child
-
-```tsx
-import { Match, Switch } from "solid-js";
-
-<Switch>
-	<Match when={user()}>{(user) => <div>{user().name}</div>}</Match>
-</Switch>;
+	<Match when={state.status === "error"}>
+		<p>Failed</p>
+	</Match>
+</Switch>
 ```
 
 ## Related

From a252fae1031101589f1d4dc1fc4710ab8c8d4e2e Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:12:16 -0700
Subject: [PATCH 33/88] update

---
 src/routes/reference/jsx-attributes/attr.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/attr.mdx b/src/routes/reference/jsx-attributes/attr.mdx
index 469f7a2c3..5775c4801 100644
--- a/src/routes/reference/jsx-attributes/attr.mdx
+++ b/src/routes/reference/jsx-attributes/attr.mdx
@@ -28,13 +28,13 @@ See the[TypeScript](/configuration/typescript#forcing-properties-and-custom-attr
 
 - **Type:** attribute value
 
-Value written to the attribute after the `attr:` prefix is removed.
+Value passed to normal attribute serialization after the `attr:` prefix is removed.
 
 ## Behavior
 
-- `attr:name={value}` writes the value to the `name` attribute.
-- The `attr:` prefix is removed before the attribute is written.
-- This is useful when an element expects data through attributes rather than DOM properties.
+- `attr:name={value}` writes the value to the `name` attribute after the `attr:` prefix is removed.
+- In the DOM runtime, `attr:name={undefined}` or `attr:name={null}` removes the attribute.
+- In SSR output, the stripped attribute name and escaped value are written as HTML.
 
 ## Examples
 

From ff0dcdb925a288af93d6eabb6ccfd24323756203 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:13:17 -0700
Subject: [PATCH 34/88] update

---
 src/routes/reference/jsx-attributes/bool.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/bool.mdx b/src/routes/reference/jsx-attributes/bool.mdx
index 3cfbb279b..6acd955b2 100644
--- a/src/routes/reference/jsx-attributes/bool.mdx
+++ b/src/routes/reference/jsx-attributes/bool.mdx
@@ -28,13 +28,13 @@ See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-att
 
 - **Type:** any truthy or falsy value
 
-Truthy values add the attribute. Falsy values remove it.
+Any JavaScript value is coerced by truthiness.
 
 ## Behavior
 
-- `bool:name={value}` adds `name` when `value` is truthy.
+- `bool:name={value}` writes `name=""` when `value` is truthy.
 - `bool:name={value}` removes `name` when `value` is falsy.
-- When present, the attribute is written as an empty string attribute.
+- SSR output follows the same presence-or-absence behavior.
 
 ## Examples
 

From d0217b0dda0ae4ff6fdbf099c2f41900ce94a811 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:14:55 -0700
Subject: [PATCH 35/88] update

---
 src/routes/reference/jsx-attributes/classlist.mdx | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/classlist.mdx b/src/routes/reference/jsx-attributes/classlist.mdx
index 07bc43364..16515a269 100644
--- a/src/routes/reference/jsx-attributes/classlist.mdx
+++ b/src/routes/reference/jsx-attributes/classlist.mdx
@@ -27,17 +27,19 @@ description: >-
 
 ## Value
 
-- **Type:** `Record<string, boolean | undefined | null>`
+- **Type:** `Record<string, boolean | undefined>`
 
 Object whose keys are class names and whose values control whether each class is present.
 
 ## Behavior
 
 - Each key is treated as a class name.
+- Keys can contain multiple space-separated class names, which are toggled individually.
 - Truthy values add the class and falsy values remove it.
 - Updates are applied per class rather than replacing the whole `class` attribute.
-- `classList` is a compile-time pseudo-attribute and does not work through prop spreads or `<Dynamic>`.
+- `classList` works through normal DOM prop assignment, including prop spreads and `<Dynamic>` when it renders an intrinsic element.
 - If both `class` and `classList` are reactive, updates to `class` can overwrite classes managed by `classList`.
+- SSR output merges `class`, `className`, and `classList` into the emitted `class` attribute.
 
 ## Examples
 
@@ -56,4 +58,8 @@ Object whose keys are class names and whose values control whether each class is
 
 ```tsx
 <div classList={{ [className()]: classOn() }} />
-```
\ No newline at end of file
+```
+
+## Related
+
+- [`class`](/reference/jsx-attributes/class)

From 0ef73e894af0dc3a7aa9105444409cfe1c390f0e Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:16:01 -0700
Subject: [PATCH 36/88] update

---
 src/routes/reference/jsx-attributes/innerhtml.mdx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/innerhtml.mdx b/src/routes/reference/jsx-attributes/innerhtml.mdx
index 7bd2a9ccc..313d60592 100644
--- a/src/routes/reference/jsx-attributes/innerhtml.mdx
+++ b/src/routes/reference/jsx-attributes/innerhtml.mdx
@@ -24,12 +24,14 @@ description: >-
 
 - **Type:** `string`
 
-HTML string parsed into the element.
+HTML string inserted as raw markup into the element.
 
 ## Behavior
 
 - Setting `innerHTML` replaces the element's existing children with nodes parsed from the string.
 - The value is written through the DOM `innerHTML` property.
+- In SSR output, the HTML string is emitted as child content without escaping.
+- Unlike [`textContent`](/reference/jsx-attributes/textcontent), `innerHTML` parses markup instead of inserting plain text.
 
 :::caution
 Using `innerHTML` with unsanitized user-supplied data can introduce security vulnerabilities.
@@ -40,7 +42,7 @@ Using `innerHTML` with unsanitized user-supplied data can introduce security vul
 ### Basic usage
 
 ```tsx
-<div innerHTML={markup} />
+<div innerHTML={"<strong>Hello</strong>"} />
 ```
 
 ## Related

From bf31ca0c617c2681c64f106f57fb6f984ba8acfe Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:17:19 -0700
Subject: [PATCH 37/88] update

---
 src/routes/reference/jsx-attributes/on.mdx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/routes/reference/jsx-attributes/on.mdx b/src/routes/reference/jsx-attributes/on.mdx
index b9c7d72d3..34b8340bb 100644
--- a/src/routes/reference/jsx-attributes/on.mdx
+++ b/src/routes/reference/jsx-attributes/on.mdx
@@ -33,7 +33,9 @@ Listener passed to `addEventListener`.
 - `on:name={handler}` attaches a listener for the event named `name`.
 - The listener is attached directly to the element instead of using Solid's delegated event system.
 - Event names keep the text after `on:` exactly as written.
+- When the value changes, Solid removes the previous direct listener and adds the new one.
 - Listener options such as `once`, `passive`, `capture`, and `signal` can be provided by passing an object that implements `handleEvent`.
+- `oncapture:*` remains available as a deprecated capture-specific form.
 
 ## Examples
 
@@ -65,4 +67,3 @@ The object-listener form was added in Solid 1.9.0.
 ## Related
 
 - [`on*`](/reference/jsx-attributes/on_)
-- [`oncapture:*`](/reference/jsx-attributes/on)

From 9515e10ecaf17147f81ccc7dd1f2fa31e946048a Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Sat, 4 Apr 2026 18:19:27 -0700
Subject: [PATCH 38/88] update

---
 src/routes/reference/jsx-attributes/on_.mdx | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/on_.mdx b/src/routes/reference/jsx-attributes/on_.mdx
index 0349efd54..dccfa80ca 100644
--- a/src/routes/reference/jsx-attributes/on_.mdx
+++ b/src/routes/reference/jsx-attributes/on_.mdx
@@ -30,10 +30,11 @@ Event handler, or a handler/data pair for delegated binding.
 
 ## Behavior
 
-- Common delegated events are handled at the document level instead of attaching one listener per element.
+- Events in Solid's delegated event set use document-level delegation; other `on*` handlers attach directly to the element.
 - Event names are mapped to lower case, so `onClick` listens to `click`.
 - The two-element array form passes the first item as bound data to the handler.
-- Delegated bindings are not reactive and are not rebound automatically.
+- Delegated bindings are not reactive and are not rebound automatically when the handler reference changes.
+- `onInput` uses the native input event, and `onChange` uses the native change event.
 - For direct element listeners, custom event casing, or listener options, use [`on:*`](/reference/jsx-attributes/on).
 
 ## Examples

From 05cfd3341c46a8851656f38c8a9698df17947acf Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:21:23 -0700
Subject: [PATCH 39/88] update

---
 src/routes/reference/jsx-attributes/once.mdx | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/once.mdx b/src/routes/reference/jsx-attributes/once.mdx
index 69b4f9f3e..2e110b5d6 100644
--- a/src/routes/reference/jsx-attributes/once.mdx
+++ b/src/routes/reference/jsx-attributes/once.mdx
@@ -9,10 +9,10 @@ tags:
   - optimization
 version: "1.0"
 description: >-
-  Mark a JSX expression so the compiler does not wrap it reactively.
+  Mark a JSX expression as static at compile time.
 ---
 
-`/*@once*/` marks a JSX expression so the compiler does not wrap it reactively.
+`/*@once*/` is a compiler marker comment that marks a JSX expression as static.
 
 ## Syntax
 
@@ -23,8 +23,9 @@ description: >-
 ## Behavior
 
 - `/*@once*/` applies to the expression that follows it.
-- It tells the compiler not to wrap that expression in reactive access machinery.
+- Marked expressions are compiled as static and do not update when reactive dependencies change.
 - It can be used in props and in children.
+- Some compiler transforms, including parts of `classList` and `style` handling, do not fully respect `/*@once*/`.
 
 ## Examples
 

From b0139d421c27e5c37bc319d2ead00067c511e7bf Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:23:01 -0700
Subject: [PATCH 40/88] update

---
 src/routes/reference/jsx-attributes/prop.mdx | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/prop.mdx b/src/routes/reference/jsx-attributes/prop.mdx
index a9c13ecec..f1265b830 100644
--- a/src/routes/reference/jsx-attributes/prop.mdx
+++ b/src/routes/reference/jsx-attributes/prop.mdx
@@ -30,20 +30,20 @@ See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-att
 
 - **Type:** property value
 
-Value assigned to the property after the `prop:` prefix is removed.
+Value assigned directly to the property after the `prop:` prefix is removed.
 
 ## Behavior
 
-- `prop:name={value}` assigns the value to the `name` property.
-- The `prop:` prefix is removed before the assignment happens.
-- This is useful when an element expects data through properties rather than attributes.
+- On the client, `prop:name={value}` strips the `prop:` prefix and assigns the value directly to the `name` property.
+- `prop:*` does not produce SSR output.
+- Use `prop:*` when a DOM property must receive the value directly. Solid can still assign some custom-element properties without `prop:*`.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-<div prop:scrollTop={props.scrollPos} />
+<input type="checkbox" prop:indeterminate={true} />
 ```
 
 ## Related

From 91b3aba9ea67a9156846e69eed37e324b8898689 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:24:27 -0700
Subject: [PATCH 41/88] update

---
 src/routes/reference/jsx-attributes/ref.mdx | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/ref.mdx b/src/routes/reference/jsx-attributes/ref.mdx
index 452a6f2cc..7434dff3b 100644
--- a/src/routes/reference/jsx-attributes/ref.mdx
+++ b/src/routes/reference/jsx-attributes/ref.mdx
@@ -24,14 +24,14 @@ description: >-
 
 - **Type:** variable binding or callback function
 
-Receives the rendered element or forwarded ref value.
+For DOM elements, variable refs are assigned during render and callback refs receive the element.
 
 ## Behavior
 
 - Refs are assigned during rendering before the element is connected to the DOM.
 - A variable ref assigns the rendered element to the referenced variable.
-- A callback ref is called with the rendered element.
-- Component refs work only when the component forwards the `ref` prop to an underlying element or child component.
+- A callback ref is called with the rendered element. When `ref` comes through a spread, functional refs are invoked from the spread handling path instead.
+- Component refs work only when the component uses or forwards the `ref` prop to an underlying element or child component.
 
 ## Examples
 
@@ -64,3 +64,7 @@ function App() {
 	return <MyComp ref={myDiv} />;
 }
 ```
+
+## Related
+
+- [`onMount`](/reference/lifecycle/on-mount)

From 4c2276e7e7ce285ce4cbeba86f30d29cbb533815 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:25:25 -0700
Subject: [PATCH 42/88] update

---
 src/routes/reference/jsx-attributes/textcontent.mdx | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/textcontent.mdx b/src/routes/reference/jsx-attributes/textcontent.mdx
index c7f2f1c3c..f90639b84 100644
--- a/src/routes/reference/jsx-attributes/textcontent.mdx
+++ b/src/routes/reference/jsx-attributes/textcontent.mdx
@@ -8,10 +8,10 @@ tags:
   - dom
 version: "1.0"
 description: >-
-  Set an element's `textContent` property from JSX.
+  Set an element's `textContent` property from JSX with plain text content.
 ---
 
-`textContent` sets an element's `textContent` property.
+`textContent` sets an element's `textContent` property with plain text content.
 
 ## Syntax
 
@@ -23,19 +23,19 @@ description: >-
 
 - **Type:** `string | number`
 
-Text written to the element.
+Text written to the element without parsing markup.
 
 ## Behavior
 
-- Setting `textContent` replaces the element's existing children with a single text node.
-- The value is written through the DOM `textContent` property.
+- `textContent` replaces the element's existing child content instead of merging with JSX children.
+- On the client, the value is written through the DOM `textContent` property. During SSR, it is emitted as escaped text instead of raw HTML.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-<div textContent={count()} />
+<div textContent={"<strong>Hello</strong>"} />
 ```
 
 ## Related

From 783dcd9adc469fe01281df052398c3a0703b9ab6 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:28:59 -0700
Subject: [PATCH 43/88] update

---
 src/routes/reference/jsx-attributes/use.mdx | 24 +++++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/use.mdx b/src/routes/reference/jsx-attributes/use.mdx
index 3dbbde30d..7d285e46b 100644
--- a/src/routes/reference/jsx-attributes/use.mdx
+++ b/src/routes/reference/jsx-attributes/use.mdx
@@ -25,21 +25,21 @@ description: >-
 ```ts
 type Accessor<T> = () => T;
 
-function directive(element: HTMLElement, accessor: Accessor<any>): void;
+function directive(element: Element, accessor: Accessor<any>): void;
 ```
 
 ## Value
 
 - **Type:** directive argument
 
-Value exposed to the directive through its accessor.
+Value exposed to the directive through an accessor.
+When no explicit value is passed, the accessor returns `true`.
 
 ## Behavior
 
-- `use:name={value}` calls the directive named `name` with the element and an accessor for `value`.
-- Directive functions run during rendering before the element is connected to the DOM.
-- Directives only work on native elements, including custom elements.
-- Directives are not forwarded through user-defined components.
+- The compiler lowers `use:name={value}` to a directive helper call with the element and an accessor for `value`. Without an explicit value, the accessor returns `true`.
+- The directive runs during rendering before the element is connected to the DOM.
+- `use:*` works only on native elements, including custom elements, and is not forwarded through user-defined components.
 
 ## Examples
 
@@ -58,5 +58,15 @@ const [name, setName] = createSignal("");
 ```
 
 :::note
-When using TypeScript, custom directives may require extending Solid's JSX directive typings.
+When using TypeScript, custom directives may require extending Solid's JSX directive typings:
+
+```ts
+declare module "solid-js" {
+	namespace JSX {
+		interface Directives {
+			model: [Accessor<string>, Setter<string>];
+		}
+	}
+}
+```
 :::

From 890f5bb9052963830aa23a3413441459d18b74a7 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:30:05 -0700
Subject: [PATCH 44/88] update

---
 src/routes/reference/lifecycle/on-cleanup.mdx | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/routes/reference/lifecycle/on-cleanup.mdx b/src/routes/reference/lifecycle/on-cleanup.mdx
index 79ee80fe0..71e2dc868 100644
--- a/src/routes/reference/lifecycle/on-cleanup.mdx
+++ b/src/routes/reference/lifecycle/on-cleanup.mdx
@@ -44,25 +44,24 @@ Cleanup function registered on the current reactive scope.
 
 - **Type:** `T`
 
-Returns the same function that was passed in.
+Returns `fn` unchanged.
 
 ## Behavior
 
 - 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.
-- On the server, cleanup also runs when server-side reactive branches are disposed.
+- On the server, cleanup also runs when server-side owners or reactive branches are disposed.
 
 ## Examples
 
 ### Remove an event listener
 
 ```tsx
-import { createSignal, onCleanup } from "solid-js";
+import { onCleanup } from "solid-js";
 
 const Component = () => {
-	const [count, setCount] = createSignal(0);
-	const handleClick = () => setCount((value) => value + 1);
+	const handleClick = () => console.log("clicked");
 
 	document.addEventListener("click", handleClick);
 
@@ -70,7 +69,7 @@ const Component = () => {
 		document.removeEventListener("click", handleClick);
 	});
 
-	return <main>Document has been clicked {count()} times</main>;
+	return <main>Listening for document clicks</main>;
 };
 ```
 

From 4045d1854357a3ad2055a38f21428e5041a8f717 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:31:23 -0700
Subject: [PATCH 45/88] update

---
 src/routes/reference/lifecycle/on-mount.mdx | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/lifecycle/on-mount.mdx b/src/routes/reference/lifecycle/on-mount.mdx
index fe5009af3..62b8a3181 100644
--- a/src/routes/reference/lifecycle/on-mount.mdx
+++ b/src/routes/reference/lifecycle/on-mount.mdx
@@ -37,7 +37,7 @@ function onMount(fn: () => void): void;
 - **Type:** `() => void`
 - **Required:** Yes
 
-Function executed once on mount.
+Non-tracking function executed once on mount.
 
 ## Return value
 
@@ -45,10 +45,10 @@ Function executed once on mount.
 
 ## Behavior
 
-- Runs once after the initial render.
-- Does not track reactive dependencies inside `fn`.
+- On the client, `onMount` runs once after the initial render. It does not run during server rendering.
+- `fn` does not track reactive dependencies.
 - Internally, `onMount(fn)` is equivalent to `createEffect(() => untrack(fn))`.
-- Runs after refs have been assigned.
+- By the time `onMount` runs, refs have already been assigned.
 
 ## Examples
 
@@ -75,6 +75,7 @@ import { onMount } from "solid-js";
 
 function Example() {
 	onMount(() => {
+		// Browser-only code
 		console.log(window.location.pathname);
 	});
 

From 63e122d76327afe2d62ec9035e119a2b85a020ad Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:43:29 -0700
Subject: [PATCH 46/88] update

---
 .../reference/reactive-utilities/batch.mdx    | 45 ++++++++-----------
 1 file changed, 18 insertions(+), 27 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/batch.mdx b/src/routes/reference/reactive-utilities/batch.mdx
index 2d1e8e54c..ab04ae9bd 100644
--- a/src/routes/reference/reactive-utilities/batch.mdx
+++ b/src/routes/reference/reactive-utilities/batch.mdx
@@ -49,7 +49,7 @@ Returns the value produced by `fn`.
 - Downstream computations are deferred until the batch completes.
 - Nested `batch` calls behave like a single larger batch.
 - If you read a stale memo or signal inside the batch, Solid updates it on demand before returning the value.
-- If `fn` is asynchronous, only the updates before the first `await` are batched.
+- If `fn` is asynchronous, batching applies only to updates before the first `await` or other async suspension point.
 
 ## Automatic batching
 
@@ -61,49 +61,40 @@ Solid automatically batches updates in several cases, including:
 
 ## Examples
 
-### Batch multiple signal updates
+### Basic usage
 
 ```ts
-import { batch, createEffect, createMemo, createSignal } from "solid-js";
+const [count, setCount] = createSignal(0);
+const [total, setTotal] = createSignal(0);
 
-const [up1, setUp1] = createSignal(1);
-const [up2, setUp2] = createSignal(2);
-const [up3, setUp3] = createSignal(3);
-
-const down = createMemo(() => up1() + up2() + up3());
-createEffect(() => console.log(down())); // outputs 6
+const summary = createMemo(() => `${count()} / ${total()}`);
+createEffect(() => console.log(summary())); // logs "0 / 0"
 ```
 
-Without `batch`, each setter can trigger downstream work:
+Outside `batch`:
 
 ```ts
-setUp1(4); // recomputes down, outputs 9
-setUp2(5); // recomputes down, outputs 12
-setUp3(6); // recomputes down, outputs 15
+setCount(1); // logs "1 / 0"
+setTotal(5); // logs "1 / 5"
 ```
 
-With `batch`, the memo recomputes once at the end:
+Inside `batch`:
 
 ```ts
 batch(() => {
-	setUp1(10); // doesn't update down yet
-	setUp2(10); // doesn't update down yet
-	setUp3(10); // doesn't update down yet
-}); // recomputes down, outputs 30
+	setCount(1);
+	setTotal(5);
+}); // logs "1 / 5"
 ```
 
-### Read a memo inside a batch
+### Read inside a batch
 
 ```ts
 batch(() => {
-	setUp1(11); // doesn't update down yet
-	setUp2(11); // doesn't update down yet
-	setUp3(11); // doesn't update down yet
-	console.log(down()); // recomputes down, outputs 33
-	setUp1(12); // doesn't update down yet
-	setUp2(12); // doesn't update down yet
-	setUp3(12); // doesn't update down yet
-}); // recomputes down, outputs 36
+	setCount(2);
+	console.log(summary()); // logs "2 / 5"
+	setTotal(10);
+}); // logs "2 / 10"
 ```
 
 ## Related

From 13744eba8c9a75b49b158d01acdd2f7ebc09a867 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:46:02 -0700
Subject: [PATCH 47/88] update

---
 src/routes/reference/reactive-utilities/catch-error.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/catch-error.mdx b/src/routes/reference/reactive-utilities/catch-error.mdx
index 4a500a6e2..b9b5b4c77 100644
--- a/src/routes/reference/reactive-utilities/catch-error.mdx
+++ b/src/routes/reference/reactive-utilities/catch-error.mdx
@@ -44,17 +44,17 @@ Function executed inside the error boundary.
 - **Type:** `(err: Error) => void`
 - **Required:** Yes
 
-Error handler invoked when an error is thrown inside descendant scopes.
+Error handler invoked when a thrown value reaches this boundary.
 
 ## Return value
 
 - **Type:** `T | undefined`
 
-Returns the value produced by `fn`.
-If `handler` handles a thrown error, the result is `undefined`.
+Returns the value produced by `fn`, or `undefined` when a thrown value is caught and handled.
 
 ## Behavior
 
+- While `fn` runs, `catchError` establishes an error boundary for reactive scopes created inside it.
 - Only the nearest matching error boundary handles a thrown error.
 - If `handler` throws, the next parent error boundary handles that error.
 

From caa87368205ca3ae2197dfbfb692995e3cf1f886 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:47:32 -0700
Subject: [PATCH 48/88] update

---
 src/routes/reference/reactive-utilities/from.mdx | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/from.mdx b/src/routes/reference/reactive-utilities/from.mdx
index 306d7a3d4..3ab41b721 100644
--- a/src/routes/reference/reactive-utilities/from.mdx
+++ b/src/routes/reference/reactive-utilities/from.mdx
@@ -62,8 +62,9 @@ Returns an accessor backed by the external source.
 ## Behavior
 
 - A producer function receives a Solid setter and returns a cleanup function.
-- A subscribable source must expose `subscribe()`.
-- Returned subscriptions are cleaned up with the owning Solid scope.
+- A subscribable source must expose `subscribe()`, and that subscription may return either a cleanup function or an object with `unsubscribe()`.
+- Emitted values are not deduplicated by equality.
+- Returned subscriptions are cleaned up with the current Solid owner when one exists.
 - When `initialValue` is omitted, the accessor can return `undefined`.
 
 ## Examples
@@ -73,7 +74,12 @@ Returns an accessor backed by the external source.
 ```ts
 import { from } from "solid-js";
 
-const signal = from(observableSource);
+const counter = from({
+	subscribe(next) {
+		const interval = setInterval(() => next(Date.now()), 1000);
+		return () => clearInterval(interval);
+	},
+});
 ```
 
 ### Create an accessor from a producer function

From ffede2d65f339584ba2c208978d057a8aba89cf1 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:48:56 -0700
Subject: [PATCH 49/88] update

---
 .../reference/reactive-utilities/get-owner.mdx      | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/get-owner.mdx b/src/routes/reference/reactive-utilities/get-owner.mdx
index 11ececd8a..ec0b22550 100644
--- a/src/routes/reference/reactive-utilities/get-owner.mdx
+++ b/src/routes/reference/reactive-utilities/get-owner.mdx
@@ -30,6 +30,8 @@ type Owner = unknown;
 function getOwner(): Owner | null;
 ```
 
+The concrete owner shape is internal and is primarily useful with [`runWithOwner`](/reference/reactive-utilities/run-with-owner).
+
 ## Parameters
 
 `getOwner` does not take any parameters.
@@ -42,6 +44,7 @@ Returns the current owner or `null` when no owner is active.
 
 ## Behavior
 
+- `getOwner` returns the current owner and does not create or modify ownership.
 - Owners determine cleanup and context lookup for descendant computations.
 - A computation created inside the current scope becomes part of the current owner tree unless ownership is overridden.
 - Components are not computations and do not create owner nodes themselves.
@@ -57,11 +60,13 @@ import { getOwner, runWithOwner } from "solid-js";
 
 const owner = getOwner();
 
-queueMicrotask(() => {
-	runWithOwner(owner, () => {
-		console.log("owner restored");
+if (owner) {
+	queueMicrotask(() => {
+		runWithOwner(owner, () => {
+			console.log("owner restored");
+		});
 	});
-});
+}
 ```
 
 ## Related

From a9755667e31bf732fdaaebb95d7e405bcd0cfa5b Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 6 Apr 2026 18:49:05 +0000
Subject: [PATCH 50/88] ci: apply automated fixes

---
 src/routes/reference/components/create-dynamic.mdx | 8 ++++++--
 src/routes/reference/components/dynamic.mdx        | 8 ++++++--
 src/routes/reference/components/suspense.mdx       | 4 ++--
 src/routes/reference/jsx-attributes/use.mdx        | 1 +
 4 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/src/routes/reference/components/create-dynamic.mdx b/src/routes/reference/components/create-dynamic.mdx
index 4996cfe38..9f6c63749 100644
--- a/src/routes/reference/components/create-dynamic.mdx
+++ b/src/routes/reference/components/create-dynamic.mdx
@@ -65,8 +65,12 @@ Returns the rendered component or element.
 import { createSignal } from "solid-js";
 
 const views = {
-	red: (props: { label: string }) => <p style={{ color: "red" }}>{props.label}</p>,
-	blue: (props: { label: string }) => <p style={{ color: "blue" }}>{props.label}</p>,
+	red: (props: { label: string }) => (
+		<p style={{ color: "red" }}>{props.label}</p>
+	),
+	blue: (props: { label: string }) => (
+		<p style={{ color: "blue" }}>{props.label}</p>
+	),
 };
 
 function App() {
diff --git a/src/routes/reference/components/dynamic.mdx b/src/routes/reference/components/dynamic.mdx
index 90df187b5..0b56f0d51 100644
--- a/src/routes/reference/components/dynamic.mdx
+++ b/src/routes/reference/components/dynamic.mdx
@@ -69,8 +69,12 @@ Returns the rendered component or element.
 import { createSignal } from "solid-js";
 
 const views = {
-	red: (props: { label: string }) => <p style={{ color: "red" }}>{props.label}</p>,
-	blue: (props: { label: string }) => <p style={{ color: "blue" }}>{props.label}</p>,
+	red: (props: { label: string }) => (
+		<p style={{ color: "red" }}>{props.label}</p>
+	),
+	blue: (props: { label: string }) => (
+		<p style={{ color: "blue" }}>{props.label}</p>
+	),
 };
 
 function App() {
diff --git a/src/routes/reference/components/suspense.mdx b/src/routes/reference/components/suspense.mdx
index 1d0bcb823..22a2e2bb0 100644
--- a/src/routes/reference/components/suspense.mdx
+++ b/src/routes/reference/components/suspense.mdx
@@ -66,7 +66,7 @@ Returns the rendered subtree or `fallback` content depending on pending tracked
 ```tsx
 <Suspense fallback={<LoadingSpinner />}>
 	<AsyncComponent />
-</Suspense>;
+</Suspense>
 ```
 
 ### Nested suspense
@@ -77,7 +77,7 @@ Returns the rendered subtree or `fallback` content depending on pending tracked
 	<Suspense fallback={<div>Loading details</div>}>
 		<DataComponent>{data()}</DataComponent>
 	</Suspense>
-</Suspense>;
+</Suspense>
 ```
 
 ## Related
diff --git a/src/routes/reference/jsx-attributes/use.mdx b/src/routes/reference/jsx-attributes/use.mdx
index 7d285e46b..e22097e7c 100644
--- a/src/routes/reference/jsx-attributes/use.mdx
+++ b/src/routes/reference/jsx-attributes/use.mdx
@@ -69,4 +69,5 @@ declare module "solid-js" {
 	}
 }
 ```
+
 :::

From cd3aa563ce8ef88663338a1b75035571ee3cfdf3 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:51:38 -0700
Subject: [PATCH 51/88] update

---
 src/routes/reference/reactive-utilities/index-array.mdx | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/index-array.mdx b/src/routes/reference/reactive-utilities/index-array.mdx
index 104209c90..f56435fd5 100644
--- a/src/routes/reference/reactive-utilities/index-array.mdx
+++ b/src/routes/reference/reactive-utilities/index-array.mdx
@@ -56,6 +56,7 @@ Mapping function for each index.
 - **Type:** `() => any`
 
 Fallback accessor used when the source array is empty or falsy.
+The mapped result becomes a single fallback entry.
 
 ## Return value
 
@@ -69,6 +70,7 @@ Returns an accessor for the mapped array.
 - The item argument is an accessor.
 - The index argument is a number.
 - Updating an item at the same index updates the corresponding mapped result.
+- Reordering the source array changes which item each index points to instead of moving mapped entries by identity.
 - This is the underlying helper for [`<Index>`](/reference/components/index-component).
 
 ## Examples
@@ -79,13 +81,13 @@ Returns an accessor for the mapped array.
 import { createSignal, indexArray } from "solid-js";
 
 const [source] = createSignal([
-	{ firstName: "Ada", lastName: "Lovelace" },
-	{ firstName: "Grace", lastName: "Hopper" },
+	{ status: "pending" },
+	{ status: "done" },
 ]);
 
 const mapped = indexArray(source, (item, index) => ({
 	index,
-	fullName: () => `${item().firstName} ${item().lastName}`,
+	status: () => item().status,
 }));
 ```
 

From 5d1467279f3d15a5f7dfadd1e89d9557811a31f3 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 6 Apr 2026 18:52:21 +0000
Subject: [PATCH 52/88] ci: apply automated fixes

---
 src/routes/reference/reactive-utilities/index-array.mdx | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/index-array.mdx b/src/routes/reference/reactive-utilities/index-array.mdx
index f56435fd5..43a0820f5 100644
--- a/src/routes/reference/reactive-utilities/index-array.mdx
+++ b/src/routes/reference/reactive-utilities/index-array.mdx
@@ -80,10 +80,7 @@ Returns an accessor for the mapped array.
 ```ts
 import { createSignal, indexArray } from "solid-js";
 
-const [source] = createSignal([
-	{ status: "pending" },
-	{ status: "done" },
-]);
+const [source] = createSignal([{ status: "pending" }, { status: "done" }]);
 
 const mapped = indexArray(source, (item, index) => ({
 	index,

From 8253297f597eb8134d340f35b6993d18a6243cbb Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:53:28 -0700
Subject: [PATCH 53/88] update

---
 .../reference/reactive-utilities/map-array.mdx     | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/map-array.mdx b/src/routes/reference/reactive-utilities/map-array.mdx
index 1c21f4dac..71014379a 100644
--- a/src/routes/reference/reactive-utilities/map-array.mdx
+++ b/src/routes/reference/reactive-utilities/map-array.mdx
@@ -55,7 +55,7 @@ Mapping function for each item.
 
 - **Type:** `() => any`
 
-Fallback accessor used when the source array is empty or falsy.
+Fallback accessor used when the source array is empty or falsy. The mapped result becomes a single fallback entry.
 
 ## Return value
 
@@ -67,8 +67,8 @@ Returns an accessor for the mapped array.
 
 - Items are cached by value identity.
 - The index argument is an accessor.
-- `mapFn` is not a tracking scope.
-- Reordering reuses existing mapped items when their source values are retained.
+- `mapFn` is not a tracking scope, so reads inside the callback do not track unless they happen inside nested JSX or another reactive scope.
+- Reordering reuses existing mapped items for retained source values and updates their index accessors.
 - This is the underlying helper for [`<For>`](/reference/components/for).
 
 ## Examples
@@ -79,14 +79,14 @@ Returns an accessor for the mapped array.
 import { createSignal, mapArray } from "solid-js";
 
 const [source] = createSignal([
-	{ id: 1, name: "A" },
-	{ id: 2, name: "B" },
+	{ id: 1, status: "pending" },
+	{ id: 2, status: "done" },
 ]);
 
 const mapped = mapArray(source, (item, index) => ({
 	id: item.id,
-	name: item.name,
-	position: index,
+	status: item.status,
+	position: () => index(),
 }));
 ```
 

From 5c821e005b7b86fbf5d920a3a63a8d91d50b7674 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:58:01 -0700
Subject: [PATCH 54/88] update

---
 .../reactive-utilities/merge-props.mdx        | 21 +++++++++----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/merge-props.mdx b/src/routes/reference/reactive-utilities/merge-props.mdx
index b804b7d7d..36d3e5025 100644
--- a/src/routes/reference/reactive-utilities/merge-props.mdx
+++ b/src/routes/reference/reactive-utilities/merge-props.mdx
@@ -28,7 +28,7 @@ import { mergeProps } from "solid-js";
 ```ts
 function mergeProps<T extends unknown[]>(
 	...sources: T
-): Record<string, unknown>;
+): MergeProps<T>;
 ```
 
 ## Parameters
@@ -41,13 +41,13 @@ Prop sources to merge.
 
 ## Return value
 
-- **Type:** `Record<string, unknown>`
+- **Type:** `MergeProps<T>`
 
-Returns an object that resolves each property from the last source that defines it.
+Returns a merged object with lazy reactive property resolution across the provided sources.
 
 ## Behavior
 
-- Later sources override earlier sources for the same property.
+- The last source with a non-`undefined` value for a property wins.
 - Function sources are wrapped so property reads stay reactive.
 - When reactive proxies are involved, the merged result uses proxy-backed property resolution.
 - Property lookups are resolved when read rather than copied eagerly from every source.
@@ -59,15 +59,14 @@ Returns an object that resolves each property from the last source that defines
 ```ts
 import { mergeProps } from "solid-js";
 
-const props = mergeProps({ name: "Smith" }, incomingProps);
-```
-
-### Clone props
+// default props
+props = mergeProps({ name: "Smith" }, props);
 
-```ts
-import { mergeProps } from "solid-js";
+// clone props
+newProps = mergeProps(props);
 
-const clonedProps = mergeProps(props);
+// merge props
+props = mergeProps(props, otherProps);
 ```
 
 ## Related

From f9b81409bad32b2cd1e8306a5c3729e5ad3d2d4a Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 6 Apr 2026 18:58:50 +0000
Subject: [PATCH 55/88] ci: apply automated fixes

---
 src/routes/reference/reactive-utilities/merge-props.mdx | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/merge-props.mdx b/src/routes/reference/reactive-utilities/merge-props.mdx
index 36d3e5025..0333f83b5 100644
--- a/src/routes/reference/reactive-utilities/merge-props.mdx
+++ b/src/routes/reference/reactive-utilities/merge-props.mdx
@@ -26,9 +26,7 @@ import { mergeProps } from "solid-js";
 ## Type
 
 ```ts
-function mergeProps<T extends unknown[]>(
-	...sources: T
-): MergeProps<T>;
+function mergeProps<T extends unknown[]>(...sources: T): MergeProps<T>;
 ```
 
 ## Parameters

From 31e5840ab0f14aa52c06bc0806bce8c4180d72c6 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 11:59:58 -0700
Subject: [PATCH 56/88] update

---
 src/routes/reference/reactive-utilities/observable.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/observable.mdx b/src/routes/reference/reactive-utilities/observable.mdx
index 6992d6110..e1203784d 100644
--- a/src/routes/reference/reactive-utilities/observable.mdx
+++ b/src/routes/reference/reactive-utilities/observable.mdx
@@ -42,13 +42,13 @@ Accessor used as the observable source.
 
 - **Type:** `Observable<T>`
 
-Returns an object with `subscribe()` and `[Symbol.observable]()`.
+Returns an object with `subscribe()` and `[Symbol.observable]()` that returns the same object.
 
 ## Behavior
 
-- The returned object is compatible with Observable interop based on `Symbol.observable`.
-- Subscriptions receive values from the accessor.
-- Observable libraries can consume the returned object through standard Observable interop.
+- `subscribe()` accepts either a function observer or an object observer with `next`.
+- Each subscription creates an effect over the accessor and returns an object with `unsubscribe()`.
+- If subscription happens inside an owned Solid scope, cleanup is also registered on that owner.
 
 ## Examples
 

From ff496a5863c49eb41381a0b7695dcab62de1db68 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:03:14 -0700
Subject: [PATCH 57/88] update

---
 .../reactive-utilities/run-with-owner.mdx     | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/run-with-owner.mdx b/src/routes/reference/reactive-utilities/run-with-owner.mdx
index 0cf133efa..8611a136d 100644
--- a/src/routes/reference/reactive-utilities/run-with-owner.mdx
+++ b/src/routes/reference/reactive-utilities/run-with-owner.mdx
@@ -52,14 +52,12 @@ Function executed under `owner`.
 
 - **Type:** `T | undefined`
 
-Returns the value produced by `fn`.
+Returns the value produced by `fn`, or `undefined` when an error is routed through Solid's error handling.
 
 ## Behavior
 
-- Computations created inside `fn` are attached to the provided owner.
-- Context lookup inside `fn` walks the provided owner tree.
-- Ownership affects cleanup and context resolution.
-- Ownership does not restore dependency tracking across asynchronous boundaries.
+- During the synchronous execution of `fn`, `runWithOwner` restores the provided owner for cleanup, context lookup, and descendant computations created inside `fn`.
+- `runWithOwner` does not restore dependency tracking because the current tracking listener is cleared while `fn` runs.
 - Code after the first `await` in an `async` function runs without reactive dependency tracking.
 
 ## Examples
@@ -71,15 +69,17 @@ import { createEffect, getOwner, runWithOwner, useContext } from "solid-js";
 
 const owner = getOwner();
 
-setTimeout(() => {
-	runWithOwner(owner, () => {
-		const value = useContext(FooContext);
+if (owner) {
+	setTimeout(() => {
+		runWithOwner(owner, () => {
+			const value = useContext(FooContext);
 
-		createEffect(() => {
-			console.log(value);
+			createEffect(() => {
+				console.log(value);
+			});
 		});
-	});
-}, 1000);
+	}, 1000);
+}
 ```
 
 ## Related

From ad3cd90ed5d3310da33947f750dace9f33650fa6 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:08:25 -0700
Subject: [PATCH 58/88] update

---
 src/routes/reference/reactive-utilities/split-props.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/split-props.mdx b/src/routes/reference/reactive-utilities/split-props.mdx
index 1f7e03fe9..7abd6cac2 100644
--- a/src/routes/reference/reactive-utilities/split-props.mdx
+++ b/src/routes/reference/reactive-utilities/split-props.mdx
@@ -29,7 +29,7 @@ import { splitProps } from "solid-js";
 function splitProps<T extends Record<string, unknown>>(
 	props: T,
 	...keys: (readonly (keyof T)[])[]
-): Record<string, unknown>[];
+): SplitProps<T, typeof keys>;
 ```
 
 ## Parameters
@@ -48,14 +48,14 @@ Arrays of keys that determine each returned subset.
 
 ## Return value
 
-- **Type:** `Record<string, unknown>[]`
+- **Type:** `SplitProps<T, typeof keys>`
 
-Returns one reactive object for each key array and a final object containing keys not assigned to any earlier group.
+Returns a tuple of reactive subsets followed by a reactive remainder object.
 
 ## Behavior
 
 - Each returned object preserves reactive property access.
-- Keys are assigned to the first matching group.
+- A key is assigned to the first matching group only.
 - The last returned object contains keys not included in the provided key arrays.
 - When the source props object is proxy-backed, the returned objects use proxy-backed property access.
 

From 799f08e301d90d61f74ecdbfbb45581a4debbbcb Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:09:51 -0700
Subject: [PATCH 59/88] update

---
 .../reference/reactive-utilities/start-transition.mdx       | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/start-transition.mdx b/src/routes/reference/reactive-utilities/start-transition.mdx
index 2f526b75f..58980749e 100644
--- a/src/routes/reference/reactive-utilities/start-transition.mdx
+++ b/src/routes/reference/reactive-utilities/start-transition.mdx
@@ -46,9 +46,9 @@ Resolves when the transition completes.
 
 ## Behavior
 
-- Updates scheduled inside `fn` run as a transition.
-- The returned promise resolves after transition work completes.
-- This API does not provide a pending-state accessor.
+- Updates scheduled inside `fn` run as a transition. Nested calls inside an active transition reuse that transition and return its existing promise, which resolves after transition work completes.
+- On the server, `startTransition(fn)` runs `fn()` synchronously.
+- `startTransition` is the transition-starting function exposed by [`useTransition`](/reference/reactive-utilities/use-transition), without the `pending` accessor.
 
 ## Examples
 

From acad60608db5b70b242d4313394477c1ebf6d81a Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:16:04 -0700
Subject: [PATCH 60/88] update

---
 src/routes/reference/reactive-utilities/untrack.mdx | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/untrack.mdx b/src/routes/reference/reactive-utilities/untrack.mdx
index 270c71f0c..63958a5e6 100644
--- a/src/routes/reference/reactive-utilities/untrack.mdx
+++ b/src/routes/reference/reactive-utilities/untrack.mdx
@@ -43,13 +43,12 @@ Function executed outside the current tracking context.
 
 - **Type:** `T`
 
-Returns the value produced by `fn`.
+Returns the value produced by `fn` unchanged.
 
 ## Behavior
 
-- Signals read inside `untrack` do not become dependencies of the surrounding computation.
-- `untrack` does not disable reactivity globally; it only affects reads inside the provided function.
-- Surrounding effects and memos do not subscribe to values read only inside `untrack`.
+- `untrack` only affects reads inside the provided function. Signals read there do not become dependencies of the surrounding computation.
+- On the server, `untrack` runs through the server runtime's `batch` implementation.
 
 ## Examples
 

From 9ef7a8d23680bf8ca64c0b841feb89ff4f282093 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:21:11 -0700
Subject: [PATCH 61/88] update

---
 .../reference/reactive-utilities/use-transition.mdx      | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/use-transition.mdx b/src/routes/reference/reactive-utilities/use-transition.mdx
index 749e1e605..57801f48d 100644
--- a/src/routes/reference/reactive-utilities/use-transition.mdx
+++ b/src/routes/reference/reactive-utilities/use-transition.mdx
@@ -47,9 +47,10 @@ Returns a tuple containing:
 
 ## Behavior
 
-- `start` schedules updates inside a transition.
-- `pending()` is `true` while the transition is pending.
+- `start` is the same transition-starting function exposed by [`startTransition`](/reference/reactive-utilities/start-transition).
+- `pending()` reflects whether that transition is still pending.
 - Transition state integrates with Suspense and resource reads under Suspense boundaries.
+- On the server, `pending()` is `false` and transitions run synchronously.
 
 ## Examples
 
@@ -65,8 +66,8 @@ function Example() {
 	return (
 		<>
 			<button
-				onClick={() => {
-					start(() => setValue("next"));
+				onClick={async () => {
+					await start(() => setValue("next"));
 				}}
 			>
 				Update

From 2b3e4f99d475456f0f61f88fb1d0e71606e334b0 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:21:38 -0700
Subject: [PATCH 62/88] update

---
 src/routes/reference/rendering/dev.mdx | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/rendering/dev.mdx b/src/routes/reference/rendering/dev.mdx
index 7d5e3209c..1a703612f 100644
--- a/src/routes/reference/rendering/dev.mdx
+++ b/src/routes/reference/rendering/dev.mdx
@@ -13,6 +13,7 @@ description: >-
 ---
 
 `DEV` is a development-only export from `solid-js`.
+It exposes Solid's development hooks and internals for development tooling and diagnostics.
 
 ## Import
 
@@ -43,8 +44,8 @@ const DEV:
 
 ## Behavior
 
-- In development builds, `DEV` is defined and exposes development hooks.
-- In production builds, `DEV` is `undefined`.
+- In the development browser bundle, `DEV` is defined and exposes development hooks.
+- In production and server bundles, `DEV` is `undefined`.
 
 ## Examples
 
@@ -54,7 +55,9 @@ const DEV:
 import { DEV } from "solid-js";
 
 if (DEV) {
-	console.log("development build");
+	DEV.hooks.afterUpdate = () => {
+		console.log("component graph updated");
+	};
 }
 ```
 

From 30e49f0ee3a8644b7f967f2dc172a55d5249fef6 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:24:18 -0700
Subject: [PATCH 63/88] update

---
 src/routes/reference/rendering/hydrate.mdx | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/rendering/hydrate.mdx b/src/routes/reference/rendering/hydrate.mdx
index fa26080a9..b787fed6a 100644
--- a/src/routes/reference/rendering/hydrate.mdx
+++ b/src/routes/reference/rendering/hydrate.mdx
@@ -58,13 +58,13 @@ DOM node that contains the server-rendered markup.
 
 - **Type:** `string`
 
-Hydration render identifier.
+Scopes hydration lookup to a specific rendered subtree.
 
 #### `owner`
 
 - **Type:** `unknown`
 
-Owner used for the hydration root.
+Owner used for the created hydration root.
 
 ## Return value
 
@@ -74,8 +74,8 @@ Dispose function for the hydrated root.
 
 ## Behavior
 
-- `hydrate` reuses existing DOM instead of creating a new subtree.
-- The target node is expected to contain server-rendered markup that matches the rendered output.
+- `hydrate` is a client-only API and throws in the server bundle.
+- `hydrate` reuses server-rendered DOM instead of creating a new subtree, locating nodes through Solid's hydration markers and optionally scoping that lookup with `renderId`.
 - The returned function disposes the hydrated root.
 
 ## Examples
@@ -85,6 +85,7 @@ Dispose function for the hydrated root.
 ```ts
 import { hydrate } from "solid-js/web";
 
+// #app already contains server-rendered Solid markup
 const dispose = hydrate(() => <App />, document.getElementById("app")!);
 ```
 

From de7692ae2835ad85c63d51262d8b2d3cacf4ac58 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:25:51 -0700
Subject: [PATCH 64/88] update

---
 src/routes/reference/rendering/hydration-script.mdx | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/routes/reference/rendering/hydration-script.mdx b/src/routes/reference/rendering/hydration-script.mdx
index 8c661378b..c52fdad8f 100644
--- a/src/routes/reference/rendering/hydration-script.mdx
+++ b/src/routes/reference/rendering/hydration-script.mdx
@@ -10,11 +10,11 @@ tags:
   - events
 version: "1.0"
 description: >-
-  Emit the hydration bootstrap script with `HydrationScript` or
+  Generate the SSR hydration bootstrap script with `HydrationScript` or
   `generateHydrationScript`.
 ---
 
-`HydrationScript` and `generateHydrationScript` emit Solid's hydration bootstrap script.
+`HydrationScript` and `generateHydrationScript` generate Solid's SSR hydration bootstrap script.
 
 ## Import
 
@@ -70,10 +70,10 @@ Delegated event names captured before client scripts load.
 
 ## Behavior
 
-- The hydration script bootstraps delegated event replay before the runtime loads.
-- `HydrationScript` returns JSX for server-rendered HTML output.
-- `generateHydrationScript` returns a string for manual HTML generation.
-- In browser-only bundles, these exports are no-op placeholders.
+- The generated script initializes `window._$HY` and bootstraps delegated event replay before the runtime loads.
+- The default captured delegated events are `"click"` and `"input"` unless `eventNames` is overridden.
+- `HydrationScript` returns JSX for server-rendered HTML output, and `generateHydrationScript` returns a string for manual HTML generation.
+- In browser bundles, these exports are placeholders that return `undefined`.
 
 ## Examples
 
@@ -82,6 +82,7 @@ Delegated event names captured before client scripts load.
 ```tsx
 import { HydrationScript } from "solid-js/web";
 
+// Use when generating HTML on the server
 <head>
 	<HydrationScript />
 </head>;

From 41afcb6985cf188972c38c6bfe8f9e611dc58fb1 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:32:47 -0700
Subject: [PATCH 65/88] update

---
 src/routes/reference/rendering/is-dev.mdx | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/rendering/is-dev.mdx b/src/routes/reference/rendering/is-dev.mdx
index 8c1305d4e..7ab4a7c20 100644
--- a/src/routes/reference/rendering/is-dev.mdx
+++ b/src/routes/reference/rendering/is-dev.mdx
@@ -10,7 +10,7 @@ tags:
   - conditional
 version: "1.0"
 description: >-
-  Read the development-mode boolean exported by `solid-js/web`.
+  Read the boolean that indicates whether the imported `solid-js/web` bundle is the development browser bundle.
 ---
 
 `isDev` is a constant boolean exported by `solid-js/web`.
@@ -29,8 +29,7 @@ const isDev: boolean;
 
 ## Behavior
 
-- `isDev` is `true` in the development browser bundle and `false` in production browser bundles.
-- `isDev` is `false` in the server bundle.
+- `isDev` is a bundle constant: it is `true` in the development browser bundle and `false` in production and server bundles. [`DEV`](/reference/rendering/dev) is a separate development-only export from `solid-js`.
 - Because it is exported as a constant, bundlers can eliminate unreachable branches.
 
 ## Examples
@@ -41,7 +40,7 @@ const isDev: boolean;
 import { isDev } from "solid-js/web";
 
 if (isDev) {
-	console.log("development browser bundle");
+	debugPanel.mount();
 }
 ```
 

From cb94434f7f3de231d79967007df274bfc531593e Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:41:59 -0700
Subject: [PATCH 66/88] update

---
 src/routes/reference/rendering/render-to-stream.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/rendering/render-to-stream.mdx b/src/routes/reference/rendering/render-to-stream.mdx
index d67a0ff05..79bfcd1bc 100644
--- a/src/routes/reference/rendering/render-to-stream.mdx
+++ b/src/routes/reference/rendering/render-to-stream.mdx
@@ -84,12 +84,12 @@ Callback invoked when a rendering error is encountered.
 
 - **Type:** `{ pipe: ..., pipeTo: ... }`
 
-Streaming controller with `pipe` and `pipeTo` methods.
+Streaming controller with `pipe` and `pipeTo` methods. The runtime implementation is also thenable and can resolve to the complete HTML string.
 
 ## Behavior
 
-- `renderToStream` writes the shell synchronously, including suspense fallback content.
-- Async content and serialized data continue streaming as resources resolve.
+- `renderToStream` is a server rendering API and is unsupported in browser bundles. It buffers the shell HTML, including suspense fallback content, and can flush it before later async fragments and serialized data stream as resources resolve.
+- `onCompleteShell` and `onCompleteAll` receive a `write()` helper for injecting additional output into the stream.
 - `pipe` writes to Node-style writable targets.
 - `pipeTo` writes to a `WritableStream`.
 

From 12320a7b7098264f103ccc16ee66a21146bedfd3 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:44:06 -0700
Subject: [PATCH 67/88] update

---
 src/routes/reference/rendering/render-to-string-async.mdx | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/rendering/render-to-string-async.mdx b/src/routes/reference/rendering/render-to-string-async.mdx
index b9602bf7b..334693593 100644
--- a/src/routes/reference/rendering/render-to-string-async.mdx
+++ b/src/routes/reference/rendering/render-to-string-async.mdx
@@ -50,7 +50,7 @@ Function that returns the root output to render.
 
 - **Type:** `number`
 
-Maximum wait time for suspense boundaries before the render resolves.
+Maximum wait time before the returned promise rejects.
 
 #### `nonce`
 
@@ -68,7 +68,7 @@ Identifier used to namespace the render output.
 
 - **Type:** `boolean`
 
-Disables script emission in the rendered output.
+Disables script emission, including serialized data used for hydration continuation.
 
 #### `onError`
 
@@ -84,7 +84,8 @@ Promise that resolves to the rendered HTML string.
 
 ## Behavior
 
-- `renderToStringAsync` waits for server suspense boundaries to settle before resolving.
+- `renderToStringAsync` is a server rendering API and is unsupported in browser bundles. It builds on [`renderToStream`](/reference/rendering/render-to-stream) and waits for the full stream result before resolving.
+- If the timeout elapses, the returned promise rejects instead of resolving partial HTML.
 - Resource data is serialized for client hydration unless scripts are disabled.
 - `renderId` namespaces the render output when multiple top-level roots are present.
 

From c6373b3dc4c92e841f0a4f2032dcdc2fabd57dbf Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:45:02 -0700
Subject: [PATCH 68/88] update

---
 src/routes/reference/rendering/render-to-string.mdx | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/routes/reference/rendering/render-to-string.mdx b/src/routes/reference/rendering/render-to-string.mdx
index 57e54e04f..b1e4de9fa 100644
--- a/src/routes/reference/rendering/render-to-string.mdx
+++ b/src/routes/reference/rendering/render-to-string.mdx
@@ -69,8 +69,9 @@ Rendered HTML string.
 
 ## Behavior
 
-- `renderToString` completes synchronously.
-- The output includes hydration data for progressive hydration.
+- `renderToString` is a server rendering API, is unsupported in browser bundles, and completes synchronously.
+- The output includes hydration markup. Inline serialized scripts are emitted only when serializer data is produced.
+- Registered assets are injected into the HTML output, typically before `</head>`.
 - `renderId` namespaces the render output when multiple top-level roots are present.
 
 ## Examples

From 943bf96616cc804e544285b7ed28f760998df190 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:46:45 -0700
Subject: [PATCH 69/88] update

---
 src/routes/reference/rendering/render.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/routes/reference/rendering/render.mdx b/src/routes/reference/rendering/render.mdx
index 0435ca714..9310d6890 100644
--- a/src/routes/reference/rendering/render.mdx
+++ b/src/routes/reference/rendering/render.mdx
@@ -55,9 +55,9 @@ Dispose function for the mounted root.
 
 ## Behavior
 
-- `render` creates a new root and appends its output to `element`.
+- `render` is a browser/client API and is unsupported in the server bundle. It creates a new root and appends its output to `element`. When `element` is `document`, it evaluates `code()` directly instead of using DOM insertion.
 - The first argument must be a function so Solid can establish the root before evaluating JSX.
-- The returned function disposes the root and removes the rendered content.
+- The returned function disposes the root and clears the mount container's content, so mounting into an empty container is safest.
 
 ## Examples
 

From 2b8579a8ea41771f80cf50185d93185718a79058 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:48:56 -0700
Subject: [PATCH 70/88] update

---
 .../reference/secondary-primitives/create-deferred.mdx   | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/secondary-primitives/create-deferred.mdx b/src/routes/reference/secondary-primitives/create-deferred.mdx
index 980b3b7da..b34dc10dd 100644
--- a/src/routes/reference/secondary-primitives/create-deferred.mdx
+++ b/src/routes/reference/secondary-primitives/create-deferred.mdx
@@ -11,8 +11,8 @@ tags:
   - updates
 version: "1.0"
 description: >-
-  Create a deferred accessor that updates when the browser is idle or when the
-  timeout is reached.
+  Create a deferred accessor whose updates are scheduled for later execution or
+  when the timeout is reached.
 ---
 
 `createDeferred` returns a deferred accessor for a source accessor.
@@ -75,9 +75,10 @@ Returns an accessor that exposes the deferred value.
 
 ## Behavior
 
-- The deferred accessor updates after the browser becomes idle or after `timeoutMs` is reached.
-- The returned accessor can lag behind the source accessor.
+- 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.
+- On the server, `createDeferred` returns the source accessor unchanged.
 
 ## Examples
 

From a40025dbc00853d7bebce52417736d44dfa5c2a5 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:51:25 -0700
Subject: [PATCH 71/88] update

---
 .../reference/secondary-primitives/create-reaction.mdx      | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/secondary-primitives/create-reaction.mdx b/src/routes/reference/secondary-primitives/create-reaction.mdx
index 9390c818e..7cfa6a092 100644
--- a/src/routes/reference/secondary-primitives/create-reaction.mdx
+++ b/src/routes/reference/secondary-primitives/create-reaction.mdx
@@ -56,9 +56,9 @@ Returns a function that executes `tracking` and records its dependencies for a s
 
 ## Behavior
 
-- The returned tracking function records dependencies read during `tracking`.
-- `onInvalidate` runs on the first change to any recorded dependency.
-- After invalidation, the reaction does not run again until the tracking function is called again.
+- Each call to the returned function records dependencies read during `tracking`.
+- `onInvalidate` runs untracked on the first change to any recorded dependency.
+- On the server, the returned function just executes `tracking`.
 
 ## Examples
 

From 8110eda3ae1464a1b83c529c45affb90c388ea12 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:53:08 -0700
Subject: [PATCH 72/88] update

---
 .../reference/secondary-primitives/create-selector.mdx | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/secondary-primitives/create-selector.mdx b/src/routes/reference/secondary-primitives/create-selector.mdx
index 205f0e94c..3b43ec360 100644
--- a/src/routes/reference/secondary-primitives/create-selector.mdx
+++ b/src/routes/reference/secondary-primitives/create-selector.mdx
@@ -62,13 +62,15 @@ Debug name used by development tooling.
 
 - **Type:** `(key: U) => boolean`
 
-Returns an accessor function that reports whether the provided key matches the current source value.
+Returns an accessor function that reports whether the provided key matches the current source value. Each subscriber tracks only its own key.
 
 ## Behavior
 
-- The returned function compares each key against the current source value.
-- With the default comparison, matching uses strict equality.
-- Subscribers update when their key starts or stops matching the source value.
+- The returned function compares each key against the current source value. With the default comparison, matching uses strict equality.
+- Solid tracks subscribers by key, so only subscribers whose key starts or stops matching need to update.
+- On the server, `createSelector` compares each key directly against `source()` without keyed subscriber bookkeeping.
+
+Compared with checking equality directly in every subscriber, `createSelector` keeps subscriptions keyed by the compared value.
 
 ## Examples
 

From 41550a3db0e6d9c360f54162d4eedb2ce6e37c40 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:54:19 -0700
Subject: [PATCH 73/88] update

---
 src/routes/reference/server-utilities/get-request-event.mdx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/server-utilities/get-request-event.mdx b/src/routes/reference/server-utilities/get-request-event.mdx
index 69b66bf81..1ccd67772 100644
--- a/src/routes/reference/server-utilities/get-request-event.mdx
+++ b/src/routes/reference/server-utilities/get-request-event.mdx
@@ -37,9 +37,9 @@ function getRequestEvent(): RequestEvent | undefined;
 
 ## Behavior
 
-- On the server, the returned event includes the current `Request`.
-- In the server declarations here, `RequestEvent` also includes `locals`.
-- If no request event is available, `getRequestEvent` returns `undefined`.
+- `getRequestEvent` is for managed server/request scope.
+- When available, the returned event includes the current `Request`. In the server type, it also includes `locals`.
+- If no current request event is available, including outside managed async scope, `getRequestEvent` returns `undefined`.
 
 ## Examples
 

From 1ba58f3b57ecf6a979b254acb13dc7b9b18a4cd8 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:55:18 -0700
Subject: [PATCH 74/88] update

---
 src/routes/reference/store-utilities/create-mutable.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/store-utilities/create-mutable.mdx b/src/routes/reference/store-utilities/create-mutable.mdx
index f518adcb8..142a727e9 100644
--- a/src/routes/reference/store-utilities/create-mutable.mdx
+++ b/src/routes/reference/store-utilities/create-mutable.mdx
@@ -24,7 +24,7 @@ import { createMutable } from "solid-js/store";
 ## Type
 
 ```ts
-function createMutable<T extends Record<PropertyKey, any>>(
+function createMutable<T extends StoreNode>(
 	state: T,
 	options?: { name?: string }
 ): T;
@@ -54,9 +54,9 @@ Mutable store proxy.
 
 ## Behavior
 
-- Property reads and writes go through a proxy.
-- Nested property access is reactive.
-- Mutations update the store in place.
+- `createMutable` creates mutable shared state through a reactive proxy. Property reads and writes go through that proxy, and nested property access is reactive.
+- Writes, deletes, and array mutator methods are batched through the proxy while updating the store in place.
+- This is primarily a client-side reactive proxy mechanism.
 - Getters and setters defined on the initial object remain available on the mutable store.
 
 ## Examples

From 1f10d226735e1e9bbf71bcf1d33fe7f51433a15f Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 12:56:10 -0700
Subject: [PATCH 75/88] update

---
 .../reference/store-utilities/create-store.mdx       | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/store-utilities/create-store.mdx b/src/routes/reference/store-utilities/create-store.mdx
index bb66d240e..eab1d560a 100644
--- a/src/routes/reference/store-utilities/create-store.mdx
+++ b/src/routes/reference/store-utilities/create-store.mdx
@@ -60,8 +60,8 @@ Tuple containing the store proxy and its setter.
 ## Behavior
 
 - The returned store is read through a proxy.
-- The setter can update the whole store or specific paths.
-- Object updates are shallowly merged by the setter.
+- The setter can replace the whole store or update nested paths.
+- Object updates shallow-merge by default, and setting a property to `undefined` deletes it.
 - Getters defined on the initial object remain available on the store.
 
 ## Examples
@@ -72,9 +72,13 @@ Tuple containing the store proxy and its setter.
 import { createStore } from "solid-js/store";
 
 const [state, setState] = createStore({
-	firstName: "John",
-	lastName: "Smith",
+	user: {
+		firstName: "John",
+		lastName: "Smith",
+	},
 });
+
+setStore("user", "firstName", "Jane");
 ```
 
 ### Getter

From 41c389db2f86917ed13b76298ed7fc5853d4795b Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 13:00:39 -0700
Subject: [PATCH 76/88] update

---
 src/routes/reference/store-utilities/modify-mutable.mdx | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/store-utilities/modify-mutable.mdx b/src/routes/reference/store-utilities/modify-mutable.mdx
index 1310ec05a..7673917de 100644
--- a/src/routes/reference/store-utilities/modify-mutable.mdx
+++ b/src/routes/reference/store-utilities/modify-mutable.mdx
@@ -38,7 +38,7 @@ Mutable store to modify.
 
 - **Type:** `(state: T) => T`
 
-Modifier applied to the mutable store.
+Modifier applied to the mutable store. For direct mutation-style modifiers, the return value is ignored.
 
 ## Return value
 
@@ -46,8 +46,7 @@ Modifier applied to the mutable store.
 
 ## Behavior
 
-- `modifyMutable` runs inside a [`batch`](/reference/reactive-utilities/batch).
-- Dependent computations update after the modifier completes.
+- `modifyMutable` runs inside a [`batch`](/reference/reactive-utilities/batch), so multiple changes notify dependents after the modifier completes, and the modifier receives the unwrapped underlying state object instead of the proxy.
 - The modifier can be a function returned by helpers such as [`reconcile`](/reference/store-utilities/reconcile) or [`produce`](/reference/store-utilities/produce).
 
 ## Examples

From e7d189e6f2b6d9221abed1d8b7e8773ffe83d7ac Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 13:02:21 -0700
Subject: [PATCH 77/88] update

---
 src/routes/reference/store-utilities/produce.mdx | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/routes/reference/store-utilities/produce.mdx b/src/routes/reference/store-utilities/produce.mdx
index fb035cc9b..efd55d775 100644
--- a/src/routes/reference/store-utilities/produce.mdx
+++ b/src/routes/reference/store-utilities/produce.mdx
@@ -8,10 +8,10 @@ tags:
   - mutations
 version: "1.0"
 description: >-
-  Create a store modifier that applies changes by mutating a draft value.
+  Create a store modifier that applies changes by mutating the current state through a helper proxy.
 ---
 
-`produce` creates a store modifier that applies changes by mutating a draft value.
+`produce` creates a store modifier that applies changes by mutating the current state through a helper proxy.
 
 ## Import
 
@@ -31,7 +31,7 @@ function produce<T>(fn: (state: T) => void): (state: T) => T;
 
 - **Type:** `(state: T) => void`
 
-Function that mutates the provided draft state.
+Function that mutates the provided proxy state.
 
 ## Return value
 
@@ -42,8 +42,8 @@ Store modifier function.
 ## Behavior
 
 - `produce` returns a function that can be passed to store setters or [`modifyMutable`](/reference/store-utilities/modify-mutable).
-- The modifier receives a mutable draft of the current state.
-- Nested properties can be changed inside the modifier.
+- The returned modifier mutates the passed state and returns that same state.
+- The helper is primarily for store objects and nested wrappable data.
 
 ## Examples
 

From b2b8a1b439a635760634440c8dd92e8822aa52b0 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 13:05:21 -0700
Subject: [PATCH 78/88] update

---
 src/routes/reference/store-utilities/reconcile.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/routes/reference/store-utilities/reconcile.mdx b/src/routes/reference/store-utilities/reconcile.mdx
index 769bb596a..000e7ffc4 100644
--- a/src/routes/reference/store-utilities/reconcile.mdx
+++ b/src/routes/reference/store-utilities/reconcile.mdx
@@ -61,10 +61,10 @@ Store modifier function.
 
 ## Behavior
 
-- `reconcile` performs a diff between the current state and `value`.
-- With the default `key`, array items are matched by `"id"`.
-- When `merge` is `false`, non-matching branches can be replaced.
-- When `merge` is `true`, reconciliation pushes updates deeper into the structure.
+- `reconcile` is for reconciling an incoming snapshot against existing store state.
+- With the default `key`, array items are matched by `"id"` where possible and otherwise fall back to positional or reference matching.
+- Non-wrappable values are replaced directly.
+- When `merge` is `false`, reconciliation prefers replacing non-matching branches. When `merge` is `true`, it pushes updates deeper into the structure.
 
 ## Examples
 

From cd19e355a0d21da892b1830b56e2cbc22fb31b6f Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 13:06:46 -0700
Subject: [PATCH 79/88] update

---
 src/routes/reference/store-utilities/unwrap.mdx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/routes/reference/store-utilities/unwrap.mdx b/src/routes/reference/store-utilities/unwrap.mdx
index 3a76907c5..bd7edf2d2 100644
--- a/src/routes/reference/store-utilities/unwrap.mdx
+++ b/src/routes/reference/store-utilities/unwrap.mdx
@@ -41,10 +41,12 @@ Unwrapped value.
 
 ## Behavior
 
-- Store proxies are removed recursively from returned objects and arrays.
-- Returned objects and arrays are plain values rather than reactive store proxies.
+- `unwrap` removes store proxies recursively and returns underlying plain data, reusing existing objects or arrays instead of cloning them when possible.
+- Frozen objects and arrays are shallow-copied before recursive unwrapping, while mutable ones are unwrapped in place.
 - Non-proxy input values are returned unchanged.
 
+Do not assume `unwrap` produces an isolated deep clone.
+
 ## Examples
 
 ### Basic usage

From b6c3f8746e72b1bffd8a7f76db7aae15df413f1b Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 13:09:31 -0700
Subject: [PATCH 80/88] update

---
 src/routes/reference/jsx-attributes/style.mdx | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/style.mdx b/src/routes/reference/jsx-attributes/style.mdx
index ead49483d..00be19ee8 100644
--- a/src/routes/reference/jsx-attributes/style.mdx
+++ b/src/routes/reference/jsx-attributes/style.mdx
@@ -31,9 +31,8 @@ CSS string or style object.
 ## Behavior
 
 - String values are written as inline CSS text.
-- Object values are applied property by property with `element.style.setProperty`.
-- Object keys should use lower-case, dash-separated CSS property names.
-- CSS custom properties can be set with keys such as `--my-color`.
+- Object values are applied property by property with `element.style.setProperty`, so keys should use lower-case, dash-separated CSS property names. CSS custom properties can use keys such as `--my-color`.
+- Nullish values in a style object remove that property, and falsy overall `style` values remove the `style` attribute.
 
 ## Examples
 
@@ -60,3 +59,8 @@ CSS string or style object.
 ```tsx
 <div style={{ "--my-custom-color": state.themeColor }} />
 ```
+
+## Related
+
+- [`class`](/reference/jsx-attributes/class)
+- [`classList`](/reference/jsx-attributes/classlist)

From ed5a2c7d98a4f553bad3c7c15c870e334f13f3ae Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 13:20:42 -0700
Subject: [PATCH 81/88] improve accuracy of docs

---
 .../reference/components/no-hydration.mdx     | 10 +--
 .../reference/components/suspense-list.mdx    | 25 ++++++--
 src/routes/reference/components/suspense.mdx  | 62 ++++++++++++++-----
 .../reference/components/switch-and-match.mdx | 39 ++++++++----
 4 files changed, 100 insertions(+), 36 deletions(-)

diff --git a/src/routes/reference/components/no-hydration.mdx b/src/routes/reference/components/no-hydration.mdx
index 49c6e0cff..94104e743 100644
--- a/src/routes/reference/components/no-hydration.mdx
+++ b/src/routes/reference/components/no-hydration.mdx
@@ -39,14 +39,14 @@ Content inside the boundary.
 
 - **Type:** `JSX.Element`
 
-Returns the server-rendered children.
+Returns the children during server and client-only rendering.
 
 ## Behavior
 
 - During server rendering, children inside `<NoHydration>` render normally.
 - During client hydration, Solid leaves the existing server-rendered DOM in place and does not hydrate that subtree.
+- In client-only rendering, `<NoHydration>` renders its children normally.
 - Interactive behavior inside the boundary does not hydrate on the client.
-- Placing `<Hydration>` inside `<NoHydration>` does not override the no-hydration behavior.
 
 ## Examples
 
@@ -56,9 +56,11 @@ Returns the server-rendered children.
 function Example() {
 	return (
 		<div>
-			<button>Interactive button</button>
+			<button onClick={() => console.log("hydrated")}>Hydrated button</button>
 			<NoHydration>
-				<div innerHTML={"<strong>Server-rendered only</strong>"} />
+				<div>
+					<strong>Rendered on the server without hydration</strong>
+				</div>
 			</NoHydration>
 		</div>
 	);
diff --git a/src/routes/reference/components/suspense-list.mdx b/src/routes/reference/components/suspense-list.mdx
index ec6bcffef..0be25dd8c 100644
--- a/src/routes/reference/components/suspense-list.mdx
+++ b/src/routes/reference/components/suspense-list.mdx
@@ -56,7 +56,7 @@ Order used to reveal child boundaries.
 
 - **Type:** `"collapsed" | "hidden"`
 
-Controls fallback visibility for later items after the first still-pending item.
+Controls fallback visibility for later items after the first still-pending item in ordered reveal modes.
 
 ## Return value
 
@@ -71,23 +71,36 @@ Returns the coordinated suspense boundaries.
 - `revealOrder="together"` reveals all items only after all coordinated boundaries are ready.
 - With `tail="collapsed"`, the first still-pending item can keep its fallback visible, while later pending items hide theirs.
 - With `tail="hidden"`, pending items after the first still-pending item hide their fallbacks.
+- `<SuspenseList>` coordinates child suspense boundaries. It does not suspend by itself.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-const resource = {
-	user: { name: "Ada" },
-	posts: ["First post"],
+import { createResource, Suspense } from "solid-js";
+
+const delayed = async <T,>(value: T, ms: number) => {
+	await new Promise((resolve) => setTimeout(resolve, ms));
+	return value;
 };
 
+function ProfileDetails() {
+	const [user] = createResource(() => delayed({ name: "Ada" }, 500));
+	return <h2>{user()?.name}</h2>;
+}
+
+function ProfileTimeline() {
+	const [posts] = createResource(() => delayed(["First post"], 1000));
+	return <ul>{posts()?.map((post) => <li>{post}</li>)}</ul>;
+}
+
 <SuspenseList revealOrder="forwards" tail="collapsed">
 	<Suspense fallback={<h2>Loading profile...</h2>}>
-		<ProfileDetails user={resource.user} />
+		<ProfileDetails />
 	</Suspense>
 	<Suspense fallback={<h2>Loading posts...</h2>}>
-		<ProfileTimeline posts={resource.posts} />
+		<ProfileTimeline />
 	</Suspense>
 </SuspenseList>;
 ```
diff --git a/src/routes/reference/components/suspense.mdx b/src/routes/reference/components/suspense.mdx
index 22a2e2bb0..a192b2cc8 100644
--- a/src/routes/reference/components/suspense.mdx
+++ b/src/routes/reference/components/suspense.mdx
@@ -12,10 +12,10 @@ tags:
   - components
 version: "1.0"
 description: >-
-  Render fallback content while resources read under the boundary are pending.
+  Render fallback content while suspense-tracked async dependencies under the boundary are pending.
 ---
 
-`<Suspense>` renders `fallback` while resources read under its boundary are pending.
+`<Suspense>` renders `fallback` while suspense-tracked async dependencies under its boundary are pending.
 
 ## Import
 
@@ -38,7 +38,7 @@ function Suspense(props: {
 
 - **Type:** `JSX.Element`
 
-Content rendered while tracked resources are pending.
+Content rendered while suspense-tracked async dependencies are pending.
 
 ### `children`
 
@@ -50,13 +50,13 @@ Subtree inside the suspense boundary.
 
 - **Type:** `JSX.Element`
 
-Returns the rendered subtree or `fallback` content depending on pending tracked resources.
+Returns the rendered subtree or `fallback` content depending on pending suspense-tracked async dependencies.
 
 ## Behavior
 
-- When a resource is read inside the boundary, `<Suspense>` renders `fallback` until the pending tracked resources resolve.
-- `<Suspense>` is non-blocking: the subtree can continue running before the boundary reveals the resolved content in the DOM.
-- Nested suspense boundaries handle resources read under the nearest boundary.
+- When a suspense-tracked async dependency is read inside the boundary, `<Suspense>` renders `fallback` until the pending work resolves.
+- `<Suspense>` is non-blocking: the subtree can continue running and create reactive owners before the boundary reveals the resolved content in the DOM.
+- Nested suspense boundaries handle suspense-tracked async dependencies under the nearest boundary.
 - `onMount` and `createEffect` inside the suspended subtree run after the boundary resolves.
 
 ## Examples
@@ -64,20 +64,54 @@ Returns the rendered subtree or `fallback` content depending on pending tracked
 ### Basic usage
 
 ```tsx
-<Suspense fallback={<LoadingSpinner />}>
-	<AsyncComponent />
-</Suspense>
+import { createResource } from "solid-js";
+
+const fetchMessage = async () => {
+	await new Promise((resolve) => setTimeout(resolve, 1000));
+	return "Loaded";
+};
+
+function AsyncMessage() {
+	const [message] = createResource(fetchMessage);
+	return <p>{message()}</p>;
+}
+
+<Suspense fallback={<p>Loading...</p>}>
+	<AsyncMessage />
+</Suspense>;
 ```
 
 ### Nested suspense
 
 ```tsx
+import { createResource } from "solid-js";
+
+const fetchTitle = async () => {
+	await new Promise((resolve) => setTimeout(resolve, 500));
+	return "Profile";
+};
+
+const fetchDetails = async () => {
+	await new Promise((resolve) => setTimeout(resolve, 1000));
+	return "Details loaded";
+};
+
+function Title() {
+	const [title] = createResource(fetchTitle);
+	return <h1>{title()}</h1>;
+}
+
+function Details() {
+	const [details] = createResource(fetchDetails);
+	return <p>{details()}</p>;
+}
+
 <Suspense fallback={<div>Loading page...</div>}>
-	<h1>{title()}</h1>
-	<Suspense fallback={<div>Loading details</div>}>
-		<DataComponent>{data()}</DataComponent>
+	<Title />
+	<Suspense fallback={<div>Loading details...</div>}>
+		<Details />
 	</Suspense>
-</Suspense>
+</Suspense>;
 ```
 
 ## Related
diff --git a/src/routes/reference/components/switch-and-match.mdx b/src/routes/reference/components/switch-and-match.mdx
index fa1da90f9..cbcb1384b 100644
--- a/src/routes/reference/components/switch-and-match.mdx
+++ b/src/routes/reference/components/switch-and-match.mdx
@@ -91,26 +91,41 @@ Returns the selected branch or the `fallback` content.
 
 - `<Switch>` evaluates its child `<Match>` elements in order and renders only the first truthy branch.
 - If no branch matches, `<Switch>` renders `fallback`.
-- With `keyed={false}`, function children in `<Match>` receive an accessor that can only be read while that branch remains selected. With `keyed={true}`, they receive the value directly.
+- Function children in `<Match>` are wrapped in [`untrack`](/reference/reactive-utilities/untrack).
+- With `keyed={false}`, function children in `<Match>` receive an accessor that can only be read while that branch remains selected. Replacing one truthy value with another truthy value does not recreate the child block.
+- With `keyed={true}`, function children receive the current value directly, and changing the `when` value recreates the child block even when it remains truthy.
 
 ## Examples
 
 ### Basic usage
 
 ```tsx
-<Switch fallback={<p>Unknown status</p>}>
-	<Match when={state.status === "loading"}>
-		<p>Loading...</p>
-	</Match>
-	<Match when={state.status === "success"}>
-		<p>Saved</p>
-	</Match>
-	<Match when={state.status === "error"}>
-		<p>Failed</p>
-	</Match>
-</Switch>
+import { createSignal } from "solid-js";
+
+const [status, setStatus] = createSignal<"loading" | "success" | "error">(
+	"loading"
+);
+
+<>
+	<button onClick={() => setStatus("loading")}>Loading</button>
+	<button onClick={() => setStatus("success")}>Success</button>
+	<button onClick={() => setStatus("error")}>Error</button>
+
+	<Switch fallback={<p>Unknown status</p>}>
+		<Match when={status() === "loading"}>
+			<p>Loading...</p>
+		</Match>
+		<Match when={status() === "success"}>
+			<p>Saved</p>
+		</Match>
+		<Match when={status() === "error"}>
+			<p>Failed</p>
+		</Match>
+	</Switch>
+</>;
 ```
 
 ## Related
 
 - [`<Show>`](/reference/components/show)
+- [`untrack`](/reference/reactive-utilities/untrack)

From 431f2f2c95592bbc20fd39dc6ee88f6d17027941 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Mon, 6 Apr 2026 20:21:28 +0000
Subject: [PATCH 82/88] ci: apply automated fixes

---
 src/routes/reference/components/suspense-list.mdx | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/routes/reference/components/suspense-list.mdx b/src/routes/reference/components/suspense-list.mdx
index 0be25dd8c..68604cca2 100644
--- a/src/routes/reference/components/suspense-list.mdx
+++ b/src/routes/reference/components/suspense-list.mdx
@@ -92,7 +92,13 @@ function ProfileDetails() {
 
 function ProfileTimeline() {
 	const [posts] = createResource(() => delayed(["First post"], 1000));
-	return <ul>{posts()?.map((post) => <li>{post}</li>)}</ul>;
+	return (
+		<ul>
+			{posts()?.map((post) => (
+				<li>{post}</li>
+			))}
+		</ul>
+	);
 }
 
 <SuspenseList revealOrder="forwards" tail="collapsed">

From 666143c1fbba9f528afcc182c6ee80da1cccd84a Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 13:53:08 -0700
Subject: [PATCH 83/88] update docs for accuracy

---
 src/routes/reference/jsx-attributes/on.mdx    | 34 ++++++++++++++-----
 src/routes/reference/jsx-attributes/style.mdx |  5 +--
 src/routes/reference/jsx-attributes/use.mdx   | 15 ++++----
 3 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/src/routes/reference/jsx-attributes/on.mdx b/src/routes/reference/jsx-attributes/on.mdx
index 34b8340bb..23a55ab7d 100644
--- a/src/routes/reference/jsx-attributes/on.mdx
+++ b/src/routes/reference/jsx-attributes/on.mdx
@@ -24,7 +24,7 @@ description: >-
 
 ## Value
 
-- **Type:** event handler function or `EventListenerObject & AddEventListenerOptions`
+- **Type:** event handler function or object with `handleEvent` and optional `AddEventListenerOptions`
 
 Listener passed to `addEventListener`.
 
@@ -33,6 +33,7 @@ Listener passed to `addEventListener`.
 - `on:name={handler}` attaches a listener for the event named `name`.
 - The listener is attached directly to the element instead of using Solid's delegated event system.
 - Event names keep the text after `on:` exactly as written.
+- Use `on:*` when you need exact event casing, such as case-sensitive custom events.
 - When the value changes, Solid removes the previous direct listener and adds the new one.
 - Listener options such as `once`, `passive`, `capture`, and `signal` can be provided by passing an object that implements `handleEvent`.
 - `oncapture:*` remains available as a deprecated capture-specific form.
@@ -42,26 +43,43 @@ Listener passed to `addEventListener`.
 ### Basic usage
 
 ```tsx
-<div on:DOMContentLoaded={(e) => console.log("Welcome!", e)} />
+const [message, setMessage] = createSignal("Waiting");
+let el;
+
+<>
+	<button
+		onClick={() =>
+			el.dispatchEvent(new CustomEvent("MyEvent", { detail: "Hello" }))
+		}
+	>
+		Dispatch event
+	</button>
+
+	<div on:MyEvent={(e) => setMessage(e.detail)} ref={el} />
+	<p>{message()}</p>
+</>;
 ```
 
 ### Listener options
 
 ```tsx
+const [count, setCount] = createSignal(0);
+
 const handler = {
-	handleEvent(e) {
-		console.log(e);
+	handleEvent() {
+		setCount((count) => count + 1);
 	},
 	once: true,
-	passive: false,
-	capture: true,
 };
 
-<div on:wheel={handler} />;
+<>
+	<button on:click={handler}>Click me</button>
+	<p>Clicked {count()} time(s)</p>
+</>;
 ```
 
 :::note
-The object-listener form was added in Solid 1.9.0.
+The object-listener form was added in Solid 1.9.0. It is useful when you need options such as `once`, `passive`, `capture`, or `signal`.
 :::
 
 ## Related
diff --git a/src/routes/reference/jsx-attributes/style.mdx b/src/routes/reference/jsx-attributes/style.mdx
index 00be19ee8..d9e8db82e 100644
--- a/src/routes/reference/jsx-attributes/style.mdx
+++ b/src/routes/reference/jsx-attributes/style.mdx
@@ -24,15 +24,16 @@ description: >-
 
 ## Value
 
-- **Type:** `string | Record<string, string | undefined | null>`
+- **Type:** `string | CSSProperties`
 
 CSS string or style object.
 
 ## Behavior
 
 - String values are written as inline CSS text.
-- Object values are applied property by property with `element.style.setProperty`, so keys should use lower-case, dash-separated CSS property names. CSS custom properties can use keys such as `--my-color`.
+- Object values are applied property by property with `element.style.setProperty`, so keys should use lower-case, dash-separated CSS property names instead of camelCase. CSS custom properties can use keys such as `--my-color`.
 - Nullish values in a style object remove that property, and falsy overall `style` values remove the `style` attribute.
+- In SSR output, object values are serialized into the emitted `style` attribute.
 
 ## Examples
 
diff --git a/src/routes/reference/jsx-attributes/use.mdx b/src/routes/reference/jsx-attributes/use.mdx
index e22097e7c..4f7e80cc4 100644
--- a/src/routes/reference/jsx-attributes/use.mdx
+++ b/src/routes/reference/jsx-attributes/use.mdx
@@ -25,20 +25,20 @@ description: >-
 ```ts
 type Accessor<T> = () => T;
 
-function directive(element: Element, accessor: Accessor<any>): void;
+function directive(element: Element, accessor?: Accessor<any>): void;
 ```
 
 ## Value
 
 - **Type:** directive argument
 
-Value exposed to the directive through an accessor.
-When no explicit value is passed, the accessor returns `true`.
+The directive reads the value through an accessor. Without an explicit value, the accessor returns `true`.
 
 ## Behavior
 
-- The compiler lowers `use:name={value}` to a directive helper call with the element and an accessor for `value`. Without an explicit value, the accessor returns `true`.
-- The directive runs during rendering before the element is connected to the DOM.
+- `use:name={value}` passes the element and an accessor for `value` to the directive.
+- Without an explicit value, the accessor returns `true`.
+- The directive runs during rendering in the current owner, before the element is connected to the DOM, so it can create effects and register cleanup.
 - `use:*` works only on native elements, including custom elements, and is not forwarded through user-defined components.
 
 ## Examples
@@ -48,8 +48,11 @@ When no explicit value is passed, the accessor returns `true`.
 ```tsx
 function model(element, value) {
 	const [field, setField] = value();
+	const onInput = ({ currentTarget }) => setField(currentTarget.value);
+
 	createRenderEffect(() => (element.value = field()));
-	element.addEventListener("input", ({ target }) => setField(target.value));
+	element.addEventListener("input", onInput);
+	onCleanup(() => element.removeEventListener("input", onInput));
 }
 
 const [name, setName] = createSignal("");

From e0f4812525a0eb7a38bf1db3862020ed7811b860 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 14:05:16 -0700
Subject: [PATCH 84/88] update docs for accuracy

---
 .../reference/component-apis/children.mdx     | 11 ++-
 src/routes/reference/lifecycle/on-cleanup.mdx |  1 +
 src/routes/reference/lifecycle/on-mount.mdx   |  1 +
 .../secondary-primitives/create-deferred.mdx  |  1 +
 .../create-render-effect.mdx                  | 80 +++++--------------
 5 files changed, 30 insertions(+), 64 deletions(-)

diff --git a/src/routes/reference/component-apis/children.mdx b/src/routes/reference/component-apis/children.mdx
index a820ef375..54da34705 100644
--- a/src/routes/reference/component-apis/children.mdx
+++ b/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,7 +43,7 @@ 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()`.
@@ -48,7 +51,7 @@ 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
diff --git a/src/routes/reference/lifecycle/on-cleanup.mdx b/src/routes/reference/lifecycle/on-cleanup.mdx
index 71e2dc868..954a582d5 100644
--- a/src/routes/reference/lifecycle/on-cleanup.mdx
+++ b/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
diff --git a/src/routes/reference/lifecycle/on-mount.mdx b/src/routes/reference/lifecycle/on-mount.mdx
index 62b8a3181..2ead251c2 100644
--- a/src/routes/reference/lifecycle/on-mount.mdx
+++ b/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
 
diff --git a/src/routes/reference/secondary-primitives/create-deferred.mdx b/src/routes/reference/secondary-primitives/create-deferred.mdx
index b34dc10dd..5dfb8bc09 100644
--- a/src/routes/reference/secondary-primitives/create-deferred.mdx
+++ b/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
diff --git a/src/routes/reference/secondary-primitives/create-render-effect.mdx b/src/routes/reference/secondary-primitives/create-render-effect.mdx
index 03ba5016b..aac6df1a1 100644
--- a/src/routes/reference/secondary-primitives/create-render-effect.mdx
+++ b/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

From 1e410e6198ec34bf80b545ebc47b0bff23f73d7d Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 14:27:01 -0700
Subject: [PATCH 85/88] update docs for accuracy

---
 public/llms.txt                               |  1 +
 .../component-apis/create-unique-id.mdx       | 22 ++++++--
 src/routes/reference/component-apis/lazy.mdx  | 49 +++++++++-------
 .../secondary-primitives/create-computed.mdx  | 56 +++++++++----------
 .../server-utilities/get-request-event.mdx    | 16 +++---
 5 files changed, 83 insertions(+), 61 deletions(-)

diff --git a/public/llms.txt b/public/llms.txt
index fbff7eef6..052c911fe 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -71,6 +71,7 @@
 - [<Suspense>](https://docs.solidjs.com/reference/components/suspense)
 - [<SuspenseList>](https://docs.solidjs.com/reference/components/suspense-list)
 - [<Switch> / <Match>](https://docs.solidjs.com/reference/components/switch-and-match)
+- [createDynamic](https://docs.solidjs.com/reference/components/create-dynamic)
 - [@once](https://docs.solidjs.com/reference/jsx-attributes/once)
 - [attr:*](https://docs.solidjs.com/reference/jsx-attributes/attr)
 - [bool:*](https://docs.solidjs.com/reference/jsx-attributes/bool)
diff --git a/src/routes/reference/component-apis/create-unique-id.mdx b/src/routes/reference/component-apis/create-unique-id.mdx
index fbc2bdeab..a2de7d756 100644
--- a/src/routes/reference/component-apis/create-unique-id.mdx
+++ b/src/routes/reference/component-apis/create-unique-id.mdx
@@ -11,12 +11,11 @@ tags:
   - utilities
 version: "1.0"
 description: >-
-  Generate unique IDs that are stable across server and client with
-  createUniqueId. Essential for accessible forms and SSR-compatible components.
+  Generate a unique string for the current render or hydration context.
 ---
 
-The `createUniqueId` function generates a unique ID that remains consistent across both server and client renders.
-It is commonly used with HTML `id` and `for` attributes to ensure stable hydration.
+`createUniqueId` generates a unique string for the current render or hydration context.
+During hydration, matching server and client call order produces matching IDs.
 
 `createUniqueId` does _not_ generate a cryptographically secure ID and is not suitable for security-sensitive data.
 Additionally, it should not be used in scenarios that require uniqueness across a distributed system.
@@ -48,6 +47,11 @@ This function does not take any parameters.
 
 `createUniqueId` returns a unique `string` that is stable across server and client renders.
 
+## Behavior
+
+- During hydration, IDs come from the current hydration context, so matching call order produces matching server and client IDs.
+- Outside hydration context, client-side IDs use a local counter and are unique only within the current Solid runtime instance.
+
 ## Examples
 
 ### Basic Usage
@@ -57,9 +61,17 @@ import { createUniqueId } from "solid-js";
 
 type InputProps = {
 	id?: string;
+	label: string;
 };
 
 function Input(props: InputProps) {
-	return <input id={props.id ?? createUniqueId()} />;
+	const inputId = props.id ?? createUniqueId();
+
+	return (
+		<>
+			<label for={inputId}>{props.label}</label>
+			<input id={inputId} />
+		</>
+	);
 }
 ```
diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index 87c5ba0b7..970d510fd 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -12,12 +12,11 @@ tags:
   - imports
 version: "1.0"
 description: >-
-  Lazy load components with code splitting to reduce bundle size and improve
-  performance. Components load on-demand and integrate with Suspense.
+  Create a component that loads its module lazily from a dynamic import.
 ---
 
-The `lazy` helper wraps a dynamic import and returns a component that loads on demand.
-Lazy components accept the same props as their eager counterparts and integrate with `<Suspense>` boundaries.
+`lazy` wraps a dynamic import and returns a component that loads its module on demand.
+The returned component accepts the same props as the loaded component and exposes `preload()`.
 
 ## Import
 
@@ -27,10 +26,10 @@ import { lazy } from "solid-js";
 
 ## Type
 
-```tsx
+```ts
 function lazy<T extends Component<any>>(
 	fn: () => Promise<{ default: T }>
-): T & { preload: () => Promise<T> };
+): T & { preload: () => Promise<{ default: T }> };
 ```
 
 ## Parameters
@@ -44,32 +43,42 @@ Dynamic import that resolves to the component module, exposing the component as
 
 ## Return value
 
-`lazy` returns a renderable component compatible with `T`.
-The component exposes a `preload()` method that resolves the underlying module.
+- **Type:** `T & { preload: () => Promise<{ default: T }> }`
+
+Returns a renderable component compatible with `T`.
+The returned component also exposes `preload()`.
+
+`preload()` starts loading the module without rendering the component and returns the resolved module.
 
-| Property  | Type               | Description                                                            |
-| --------- | ------------------ | ---------------------------------------------------------------------- |
-| `preload` | `() => Promise<T>` | Loads the module without rendering and returns the resolved component. |
+## Behavior
+
+- Rendering a lazy component starts loading its module if it has not already been loaded.
+- Inside a [`<Suspense>`](/reference/components/suspense) boundary, the boundary shows its fallback while the module is loading.
+- Without a suspense boundary, the lazy component renders an empty string until the module resolves.
+- `preload()` starts the same module request without rendering the component.
 
 ## Examples
 
 ### Basic usage
 
-```tsx title="app.tsx"
-import { lazy } from "solid-js";
+```tsx
+import { lazy, Suspense } from "solid-js";
 
 const ComponentA = lazy(() => import("./ComponentA"));
 
 function App(props: { title: string }) {
-	return <ComponentA title={props.title} />;
+	return (
+		<Suspense fallback={<p>Loading...</p>}>
+			<ComponentA title={props.title} />
+		</Suspense>
+	);
 }
 ```
 
 ### Preloading nested lazy components
 
 ```tsx
-import { lazy } from "solid-js";
-import type { Component } from "solid-js";
+import { createSignal, lazy, Show, Suspense } from "solid-js";
 
 const Nested = lazy(() => import("./Nested"));
 
@@ -85,14 +94,16 @@ const ComponentWithPreload = () => {
 				Preload Nested Component
 			</button>
 			<Show when={showNested()}>
-				<Nested />
+				<Suspense fallback={<p>Loading nested component...</p>}>
+					<Nested />
+				</Suspense>
 			</Show>
 		</div>
 	);
 };
 ```
 
-## See also
+## Related
 
-- [`Suspense`](https://docs.solidjs.com/reference/components/suspense)
+- [`Suspense`](/reference/components/suspense)
 - [Router preloading guide](/solid-router/advanced-concepts/preloading)
diff --git a/src/routes/reference/secondary-primitives/create-computed.mdx b/src/routes/reference/secondary-primitives/create-computed.mdx
index 84da443c4..624067c1f 100644
--- a/src/routes/reference/secondary-primitives/create-computed.mdx
+++ b/src/routes/reference/secondary-primitives/create-computed.mdx
@@ -11,12 +11,12 @@ tags:
   - tracking
 version: "1.0"
 description: >-
-  Create immediate reactive computations with createComputed. Build custom
-  primitives and handle side effects that respond to dependencies.
+  Create an immediate reactive computation that runs synchronously when created
+  and whenever its dependencies change.
 ---
 
-The `createComputed` function creates a reactive computation that runs _before_ the rendering phase.
-It is primarily used to synchronize state before rendering begins.
+`createComputed` creates an immediate reactive computation.
+It runs synchronously in the current execution context when created, then re-runs whenever its tracked dependencies change.
 
 ## Import
 
@@ -83,41 +83,39 @@ It is used for identification in debugging tools like the [Solid Debugger](https
 
 `createComputed` does not return a value.
 
+## Behavior
+
+- `createComputed` runs immediately when it is created.
+- It tracks reactive reads inside `fn` and re-runs synchronously when those dependencies change.
+- Unlike [`createMemo`](/reference/basic-reactivity/create-memo), it does not expose a derived accessor.
+- `createComputed` is primarily used to build reactive primitives. Application code that derives state usually wants [`createMemo`](/reference/basic-reactivity/create-memo) instead.
+
 ## Examples
 
-### Basic usage
+### Build a writable derived signal
 
 ```tsx
-import { createComputed } from "solid-js";
-import { createStore } from "solid-js/store";
+import { createComputed, createSignal } from "solid-js";
 
-type User = {
-	name?: string;
-};
+function createWritableMemo<T>(fn: () => T) {
+	const [value, setValue] = createSignal(fn());
 
-type UserEditorProps = {
-	user: User;
-};
-
-function UserEditor(props: UserEditorProps) {
-	const [formData, setFormData] = createStore<User>({
-		name: "",
-	});
-
-	// Update the store synchronously when props change.
-	// This prevents a second render cycle.
 	createComputed(() => {
-		setFormData("name", props.user.name);
+		setValue(fn());
 	});
 
+	return value;
+}
+
+function Counter() {
+	const [count, setCount] = createSignal(1);
+	const double = createWritableMemo(() => count() * 2);
+
 	return (
-		<form>
-			<h1>Editing: {formData.name}</h1>
-			<input
-				value={formData.name}
-				onInput={(e) => setFormData("name", e.currentTarget.value)}
-			/>
-		</form>
+		<>
+			<p>{double()}</p>
+			<button onClick={() => setCount((value) => value + 1)}>Increment</button>
+		</>
 	);
 }
 ```
diff --git a/src/routes/reference/server-utilities/get-request-event.mdx b/src/routes/reference/server-utilities/get-request-event.mdx
index 1ccd67772..37a00c6fb 100644
--- a/src/routes/reference/server-utilities/get-request-event.mdx
+++ b/src/routes/reference/server-utilities/get-request-event.mdx
@@ -23,10 +23,7 @@ import { getRequestEvent } from "solid-js/web";
 ## Type
 
 ```ts
-interface RequestEvent {
-	request: Request;
-	locals?: Record<string | number | symbol, any>;
-}
+import type { RequestEvent } from "solid-js/web";
 
 function getRequestEvent(): RequestEvent | undefined;
 ```
@@ -38,7 +35,8 @@ function getRequestEvent(): RequestEvent | undefined;
 ## Behavior
 
 - `getRequestEvent` is for managed server/request scope.
-- When available, the returned event includes the current `Request`. In the server type, it also includes `locals`.
+- When available, the returned event includes the current `Request` as `event.request`.
+- Depending on the server integration, the event can also expose request-scoped fields such as `response`, `locals`, or router state.
 - If no current request event is available, including outside managed async scope, `getRequestEvent` returns `undefined`.
 
 ## Examples
@@ -48,9 +46,11 @@ function getRequestEvent(): RequestEvent | undefined;
 ```ts
 import { getRequestEvent } from "solid-js/web";
 
-const event = getRequestEvent();
+function readAuthorizationHeader() {
+	const event = getRequestEvent();
 
-if (event) {
-	const auth = event.request.headers.get("Authorization");
+	return event?.request.headers.get("Authorization") ?? null;
 }
 ```
+
+This example reads the event during request-scoped server execution.

From b7a9c9d9902c2582259b138640be2f59d130be98 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 14:36:55 -0700
Subject: [PATCH 86/88] update docs for accuracy

---
 src/routes/reference/store-utilities/create-mutable.mdx | 6 ++++--
 src/routes/reference/store-utilities/create-store.mdx   | 9 +++++----
 src/routes/reference/store-utilities/unwrap.mdx         | 3 +++
 3 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/src/routes/reference/store-utilities/create-mutable.mdx b/src/routes/reference/store-utilities/create-mutable.mdx
index 142a727e9..d04ae0900 100644
--- a/src/routes/reference/store-utilities/create-mutable.mdx
+++ b/src/routes/reference/store-utilities/create-mutable.mdx
@@ -56,7 +56,7 @@ Mutable store proxy.
 
 - `createMutable` creates mutable shared state through a reactive proxy. Property reads and writes go through that proxy, and nested property access is reactive.
 - Writes, deletes, and array mutator methods are batched through the proxy while updating the store in place.
-- This is primarily a client-side reactive proxy mechanism.
+- `createMutable` exposes reads and writes through the same proxy instead of separating them into a getter and setter.
 - Getters and setters defined on the initial object remain available on the mutable store.
 
 ## Examples
@@ -86,10 +86,12 @@ const user = createMutable({
 	get fullName() {
 		return `${this.firstName} ${this.lastName}`;
 	},
-	set setFullName(value) {
+	set fullName(value) {
 		[this.firstName, this.lastName] = value.split(" ");
 	},
 });
+
+user.fullName = "Jane Doe";
 ```
 
 ## Related
diff --git a/src/routes/reference/store-utilities/create-store.mdx b/src/routes/reference/store-utilities/create-store.mdx
index eab1d560a..180b7ddd0 100644
--- a/src/routes/reference/store-utilities/create-store.mdx
+++ b/src/routes/reference/store-utilities/create-store.mdx
@@ -27,6 +27,7 @@ type Store<T> = T;
 
 interface SetStoreFunction<T> {
 	(setter: T | Partial<T> | ((prev: T) => T | Partial<T>)): void;
+	(...path: unknown[]): void;
 }
 
 function createStore<T extends object = {}>(
@@ -59,9 +60,9 @@ Tuple containing the store proxy and its setter.
 
 ## Behavior
 
-- The returned store is read through a proxy.
-- The setter can replace the whole store or update nested paths.
-- Object updates shallow-merge by default, and setting a property to `undefined` deletes it.
+- The returned store is read through a proxy, and property reads track at the property level.
+- The setter supports both top-level updates and path syntax for nested updates.
+- Object updates shallow-merge by default, while single-array updates replace array contents. Setting a property to `undefined` deletes it.
 - Getters defined on the initial object remain available on the store.
 
 ## Examples
@@ -78,7 +79,7 @@ const [state, setState] = createStore({
 	},
 });
 
-setStore("user", "firstName", "Jane");
+setState("user", "firstName", "Jane");
 ```
 
 ### Getter
diff --git a/src/routes/reference/store-utilities/unwrap.mdx b/src/routes/reference/store-utilities/unwrap.mdx
index bd7edf2d2..551e26acf 100644
--- a/src/routes/reference/store-utilities/unwrap.mdx
+++ b/src/routes/reference/store-utilities/unwrap.mdx
@@ -44,6 +44,7 @@ Unwrapped value.
 - `unwrap` removes store proxies recursively and returns underlying plain data, reusing existing objects or arrays instead of cloning them when possible.
 - Frozen objects and arrays are shallow-copied before recursive unwrapping, while mutable ones are unwrapped in place.
 - Non-proxy input values are returned unchanged.
+- Mutating the returned value can mutate the underlying store data.
 
 Do not assume `unwrap` produces an isolated deep clone.
 
@@ -56,6 +57,8 @@ import { createStore, unwrap } from "solid-js/store";
 
 const [state] = createStore({ user: { name: "John" } });
 const user = unwrap(state.user);
+
+user.name = "Jane";
 ```
 
 ## Related

From 44fe189545b4ea195e47236dba0a1544bc73e93d Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 14:44:57 -0700
Subject: [PATCH 87/88] update docs for accuracy

---
 .../reference/reactive-utilities/from.mdx     | 46 +++++++++++++------
 .../reactive-utilities/get-owner.mdx          | 20 ++++----
 .../reactive-utilities/merge-props.mdx        | 18 ++++----
 .../reactive-utilities/run-with-owner.mdx     | 29 ++++++------
 .../reactive-utilities/split-props.mdx        |  9 ++--
 .../reactive-utilities/start-transition.mdx   | 29 +++++++++---
 .../reference/reactive-utilities/untrack.mdx  | 18 +++++---
 .../reactive-utilities/use-transition.mdx     | 23 ++++++++--
 8 files changed, 125 insertions(+), 67 deletions(-)

diff --git a/src/routes/reference/reactive-utilities/from.mdx b/src/routes/reference/reactive-utilities/from.mdx
index 3ab41b721..07a28c0c6 100644
--- a/src/routes/reference/reactive-utilities/from.mdx
+++ b/src/routes/reference/reactive-utilities/from.mdx
@@ -61,39 +61,55 @@ Returns an accessor backed by the external source.
 
 ## Behavior
 
+- `from` subscribes to the producer immediately when it runs.
 - A producer function receives a Solid setter and returns a cleanup function.
 - A subscribable source must expose `subscribe()`, and that subscription may return either a cleanup function or an object with `unsubscribe()`.
 - Emitted values are not deduplicated by equality.
-- Returned subscriptions are cleaned up with the current Solid owner when one exists.
+- Cleanup is registered on the current Solid owner when one exists.
+- When `from` runs without an owner, the subscription still starts but is not cleaned up automatically.
 - When `initialValue` is omitted, the accessor can return `undefined`.
 
 ## Examples
 
 ### Create an accessor from a subscribable source
 
-```ts
+```tsx
 import { from } from "solid-js";
 
-const counter = from({
-	subscribe(next) {
-		const interval = setInterval(() => next(Date.now()), 1000);
-		return () => clearInterval(interval);
-	},
-});
+function Clock() {
+	const time = from(
+		{
+			subscribe(next) {
+				const interval = setInterval(
+					() => next(new Date().toLocaleTimeString()),
+					1000
+				);
+				return () => clearInterval(interval);
+			},
+		},
+		""
+	);
+
+	return <div>{time()}</div>;
+}
 ```
 
 ### Create an accessor from a producer function
 
-```ts
+```tsx
 import { from } from "solid-js";
 
-const clock = from((set) => {
-	const interval = setInterval(() => {
-		set((value) => value + 1);
-	}, 1000);
+function Counter() {
+	const count = from((set) => {
+		const interval = setInterval(() => {
+			set((value = 0) => value + 1);
+		}, 1000);
+
+		return () => clearInterval(interval);
+	}, 0);
 
-	return () => clearInterval(interval);
-}, 0);
+	return <div>{count()}</div>;
+}
 ```
 
 ## Related
diff --git a/src/routes/reference/reactive-utilities/get-owner.mdx b/src/routes/reference/reactive-utilities/get-owner.mdx
index ec0b22550..506b962d6 100644
--- a/src/routes/reference/reactive-utilities/get-owner.mdx
+++ b/src/routes/reference/reactive-utilities/get-owner.mdx
@@ -30,7 +30,7 @@ type Owner = unknown;
 function getOwner(): Owner | null;
 ```
 
-The concrete owner shape is internal and is primarily useful with [`runWithOwner`](/reference/reactive-utilities/run-with-owner).
+The `Owner` interface is public, but its concrete shape is mostly useful for advanced interop such as [`runWithOwner`](/reference/reactive-utilities/run-with-owner).
 
 ## Parameters
 
@@ -47,7 +47,7 @@ Returns the current owner or `null` when no owner is active.
 - `getOwner` returns the current owner and does not create or modify ownership.
 - Owners determine cleanup and context lookup for descendant computations.
 - A computation created inside the current scope becomes part of the current owner tree unless ownership is overridden.
-- Components are not computations and do not create owner nodes themselves.
+- Component functions run under an owner created for that subtree.
 - Calling `getOwner` inside component code returns the owner responsible for rendering and disposing that component subtree.
 - Turning off tracking with [`untrack`](/reference/reactive-utilities/untrack) does not create a new owner.
 
@@ -55,17 +55,21 @@ Returns the current owner or `null` when no owner is active.
 
 ### Capture an owner for later use
 
-```ts
+```tsx
 import { getOwner, runWithOwner } from "solid-js";
 
-const owner = getOwner();
+function Example() {
+	const owner = getOwner();
 
-if (owner) {
 	queueMicrotask(() => {
-		runWithOwner(owner, () => {
-			console.log("owner restored");
-		});
+		if (owner) {
+			runWithOwner(owner, () => {
+				console.log("owner restored");
+			});
+		}
 	});
+
+	return null;
 }
 ```
 
diff --git a/src/routes/reference/reactive-utilities/merge-props.mdx b/src/routes/reference/reactive-utilities/merge-props.mdx
index 0333f83b5..26099a905 100644
--- a/src/routes/reference/reactive-utilities/merge-props.mdx
+++ b/src/routes/reference/reactive-utilities/merge-props.mdx
@@ -45,6 +45,7 @@ Returns a merged object with lazy reactive property resolution across the provid
 
 ## Behavior
 
+- `mergeProps` is shallow.
 - The last source with a non-`undefined` value for a property wins.
 - Function sources are wrapped so property reads stay reactive.
 - When reactive proxies are involved, the merged result uses proxy-backed property resolution.
@@ -54,17 +55,18 @@ Returns a merged object with lazy reactive property resolution across the provid
 
 ### Basic usage
 
-```ts
+```tsx
 import { mergeProps } from "solid-js";
 
-// default props
-props = mergeProps({ name: "Smith" }, props);
-
-// clone props
-newProps = mergeProps(props);
+function Greeting(props) {
+	const merged = mergeProps({ greeting: "Hello", name: "Smith" }, props);
 
-// merge props
-props = mergeProps(props, otherProps);
+	return (
+		<div>
+			{merged.greeting} {merged.name}
+		</div>
+	);
+}
 ```
 
 ## Related
diff --git a/src/routes/reference/reactive-utilities/run-with-owner.mdx b/src/routes/reference/reactive-utilities/run-with-owner.mdx
index 8611a136d..9d52709a3 100644
--- a/src/routes/reference/reactive-utilities/run-with-owner.mdx
+++ b/src/routes/reference/reactive-utilities/run-with-owner.mdx
@@ -58,32 +58,33 @@ Returns the value produced by `fn`, or `undefined` when an error is routed throu
 
 - During the synchronous execution of `fn`, `runWithOwner` restores the provided owner for cleanup, context lookup, and descendant computations created inside `fn`.
 - `runWithOwner` does not restore dependency tracking because the current tracking listener is cleared while `fn` runs.
-- Code after the first `await` in an `async` function runs without reactive dependency tracking.
+- Code after the first `await` in an `async` function runs without the restored owner or reactive dependency tracking.
 
 ## Examples
 
 ### Restore an owner in a callback
 
-```ts
-import { createEffect, getOwner, runWithOwner, useContext } from "solid-js";
-
-const owner = getOwner();
+```tsx
+import { createEffect, getOwner, runWithOwner } from "solid-js";
 
-if (owner) {
-	setTimeout(() => {
-		runWithOwner(owner, () => {
-			const value = useContext(FooContext);
+function Example() {
+	const owner = getOwner();
 
-			createEffect(() => {
-				console.log(value);
+	queueMicrotask(() => {
+		if (owner) {
+			runWithOwner(owner, () => {
+				createEffect(() => {
+					console.log("effect created under the captured owner");
+				});
 			});
-		});
-	}, 1000);
+		}
+	});
+
+	return null;
 }
 ```
 
 ## Related
 
 - [`getOwner`](/reference/reactive-utilities/get-owner)
-- [`useContext`](/reference/component-apis/use-context)
 - [`onCleanup`](/reference/lifecycle/on-cleanup)
diff --git a/src/routes/reference/reactive-utilities/split-props.mdx b/src/routes/reference/reactive-utilities/split-props.mdx
index 7abd6cac2..a6b8d4496 100644
--- a/src/routes/reference/reactive-utilities/split-props.mdx
+++ b/src/routes/reference/reactive-utilities/split-props.mdx
@@ -26,10 +26,10 @@ import { splitProps } from "solid-js";
 ## Type
 
 ```ts
-function splitProps<T extends Record<string, unknown>>(
-	props: T,
-	...keys: (readonly (keyof T)[])[]
-): SplitProps<T, typeof keys>;
+function splitProps<
+	T extends Record<any, any>,
+	K extends [readonly (keyof T)[], ...(readonly (keyof T)[])[]],
+>(props: T, ...keys: K): SplitProps<T, K>;
 ```
 
 ## Parameters
@@ -58,6 +58,7 @@ Returns a tuple of reactive subsets followed by a reactive remainder object.
 - A key is assigned to the first matching group only.
 - The last returned object contains keys not included in the provided key arrays.
 - When the source props object is proxy-backed, the returned objects use proxy-backed property access.
+- `splitProps` separates props into groups without destructuring them into non-reactive locals.
 
 ## Examples
 
diff --git a/src/routes/reference/reactive-utilities/start-transition.mdx b/src/routes/reference/reactive-utilities/start-transition.mdx
index 58980749e..1aa7e1c1d 100644
--- a/src/routes/reference/reactive-utilities/start-transition.mdx
+++ b/src/routes/reference/reactive-utilities/start-transition.mdx
@@ -46,7 +46,8 @@ Resolves when the transition completes.
 
 ## Behavior
 
-- Updates scheduled inside `fn` run as a transition. Nested calls inside an active transition reuse that transition and return its existing promise, which resolves after transition work completes.
+- On the client, `fn` runs asynchronously in a microtask and its updates run as a transition.
+- Nested calls inside an active transition reuse that transition and return its existing promise, which resolves after transition work completes.
 - On the server, `startTransition(fn)` runs `fn()` synchronously.
 - `startTransition` is the transition-starting function exposed by [`useTransition`](/reference/reactive-utilities/use-transition), without the `pending` accessor.
 
@@ -55,18 +56,34 @@ Resolves when the transition completes.
 ### Basic usage
 
 ```tsx
-import { createSignal, startTransition } from "solid-js";
+import {
+	Suspense,
+	createResource,
+	createSignal,
+	startTransition,
+} from "solid-js";
 
 function Example() {
-	const [value, setValue] = createSignal("");
+	const [userId, setUserId] = createSignal(1);
+	const [user] = createResource(userId, async (id) => {
+		const response = await fetch(`/api/users/${id}`);
+		return response.json();
+	});
 
-	async function update(next: string) {
+	async function showNextUser() {
 		await startTransition(() => {
-			setValue(next);
+			setUserId(2);
 		});
 	}
 
-	return <button onClick={() => update("next")}>{value()}</button>;
+	return (
+		<>
+			<button onClick={showNextUser}>Load next user</button>
+			<Suspense fallback={<p>Loading user...</p>}>
+				<pre>{JSON.stringify(user(), null, 2)}</pre>
+			</Suspense>
+		</>
+	);
 }
 ```
 
diff --git a/src/routes/reference/reactive-utilities/untrack.mdx b/src/routes/reference/reactive-utilities/untrack.mdx
index 63958a5e6..4c9cfbbe0 100644
--- a/src/routes/reference/reactive-utilities/untrack.mdx
+++ b/src/routes/reference/reactive-utilities/untrack.mdx
@@ -48,19 +48,24 @@ Returns the value produced by `fn` unchanged.
 ## Behavior
 
 - `untrack` only affects reads inside the provided function. Signals read there do not become dependencies of the surrounding computation.
-- On the server, `untrack` runs through the server runtime's `batch` implementation.
+- `untrack` does not create or restore an owner.
 
 ## Examples
 
-### Read a prop without tracking
+### Read part of an effect without tracking
 
 ```tsx
-import { untrack } from "solid-js";
+import { createEffect, untrack } from "solid-js";
 
 export function Component(props) {
-	const value = untrack(() => props.value);
+	createEffect(() => {
+		console.log(
+			props.id,
+			untrack(() => props.label)
+		);
+	});
 
-	return <div>{value}</div>;
+	return <div>{props.id}</div>;
 }
 ```
 
@@ -86,8 +91,7 @@ function Example() {
 
 ## Notes
 
-Default and initial prop values can be read directly when initializing a signal.
-This pattern commonly appears with names such as `initialName` and `defaultName`.
+Default and initial prop values can be read directly when initializing a signal. This pattern commonly appears with names such as `initialName` and `defaultName`.
 
 ```tsx tab title="initialValue" {5}
 import { createSignal } from "solid-js";
diff --git a/src/routes/reference/reactive-utilities/use-transition.mdx b/src/routes/reference/reactive-utilities/use-transition.mdx
index 57801f48d..c43d10842 100644
--- a/src/routes/reference/reactive-utilities/use-transition.mdx
+++ b/src/routes/reference/reactive-utilities/use-transition.mdx
@@ -48,6 +48,7 @@ Returns a tuple containing:
 ## Behavior
 
 - `start` is the same transition-starting function exposed by [`startTransition`](/reference/reactive-utilities/start-transition).
+- On the client, `start` schedules its callback asynchronously in a microtask.
 - `pending()` reflects whether that transition is still pending.
 - Transition state integrates with Suspense and resource reads under Suspense boundaries.
 - On the server, `pending()` is `false` and transitions run synchronously.
@@ -57,22 +58,34 @@ Returns a tuple containing:
 ### Basic usage
 
 ```tsx
-import { createSignal, useTransition } from "solid-js";
+import {
+	Suspense,
+	createResource,
+	createSignal,
+	useTransition,
+} from "solid-js";
 
 function Example() {
-	const [value, setValue] = createSignal("");
+	const [userId, setUserId] = createSignal(1);
+	const [user] = createResource(userId, async (id) => {
+		const response = await fetch(`/api/users/${id}`);
+		return response.json();
+	});
 	const [pending, start] = useTransition();
 
 	return (
 		<>
 			<button
 				onClick={async () => {
-					await start(() => setValue("next"));
+					await start(() => setUserId(2));
 				}}
 			>
-				Update
+				Load next user
 			</button>
-			<div>{pending() ? "pending" : value()}</div>
+			<div>{pending() ? "Loading transition..." : "Ready"}</div>
+			<Suspense fallback={<p>Loading user...</p>}>
+				<pre>{JSON.stringify(user(), null, 2)}</pre>
+			</Suspense>
 		</>
 	);
 }

From 27a34a2fe7095b272bac9b71f35ff2c704fd017e Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <gerrardsarah@gmail.com>
Date: Mon, 6 Apr 2026 14:49:45 -0700
Subject: [PATCH 88/88] update docs for accuracy

---
 src/routes/reference/rendering/dev.mdx        |  7 +++---
 src/routes/reference/rendering/hydrate.mdx    |  7 +++---
 .../reference/rendering/hydration-script.mdx  | 18 +++++++++++----
 .../reference/rendering/render-to-stream.mdx  | 20 ++++++----------
 .../rendering/render-to-string-async.mdx      | 23 ++++---------------
 .../reference/rendering/render-to-string.mdx  | 10 ++------
 src/routes/reference/rendering/render.mdx     |  2 +-
 7 files changed, 35 insertions(+), 52 deletions(-)

diff --git a/src/routes/reference/rendering/dev.mdx b/src/routes/reference/rendering/dev.mdx
index 1a703612f..f019ecf69 100644
--- a/src/routes/reference/rendering/dev.mdx
+++ b/src/routes/reference/rendering/dev.mdx
@@ -44,8 +44,9 @@ const DEV:
 
 ## Behavior
 
-- In the development browser bundle, `DEV` is defined and exposes development hooks.
+- In the development browser bundle, `DEV` is defined and exposes development hooks and internals.
 - In production and server bundles, `DEV` is `undefined`.
+- `DEV` is intended for tooling, diagnostics, and library code that needs development-only behavior.
 
 ## Examples
 
@@ -55,9 +56,7 @@ const DEV:
 import { DEV } from "solid-js";
 
 if (DEV) {
-	DEV.hooks.afterUpdate = () => {
-		console.log("component graph updated");
-	};
+	console.warn("development-only check");
 }
 ```
 
diff --git a/src/routes/reference/rendering/hydrate.mdx b/src/routes/reference/rendering/hydrate.mdx
index b787fed6a..0a57d5858 100644
--- a/src/routes/reference/rendering/hydrate.mdx
+++ b/src/routes/reference/rendering/hydrate.mdx
@@ -74,15 +74,16 @@ Dispose function for the hydrated root.
 
 ## Behavior
 
-- `hydrate` is a client-only API and throws in the server bundle.
-- `hydrate` reuses server-rendered DOM instead of creating a new subtree, locating nodes through Solid's hydration markers and optionally scoping that lookup with `renderId`.
+- `hydrate` is a client-only API.
+- `hydrate` reuses DOM produced by Solid's server renderer instead of creating a new subtree, locating nodes through Solid's hydration markers and optionally scoping that lookup with `renderId`.
+- The hydrated DOM and the JSX returned by `fn` must match the server output for hydration to succeed.
 - The returned function disposes the hydrated root.
 
 ## Examples
 
 ### Basic usage
 
-```ts
+```tsx
 import { hydrate } from "solid-js/web";
 
 // #app already contains server-rendered Solid markup
diff --git a/src/routes/reference/rendering/hydration-script.mdx b/src/routes/reference/rendering/hydration-script.mdx
index c52fdad8f..33225c728 100644
--- a/src/routes/reference/rendering/hydration-script.mdx
+++ b/src/routes/reference/rendering/hydration-script.mdx
@@ -72,6 +72,7 @@ Delegated event names captured before client scripts load.
 
 - The generated script initializes `window._$HY` and bootstraps delegated event replay before the runtime loads.
 - The default captured delegated events are `"click"` and `"input"` unless `eventNames` is overridden.
+- Place the generated script once in the server-rendered document when the page will hydrate on the client.
 - `HydrationScript` returns JSX for server-rendered HTML output, and `generateHydrationScript` returns a string for manual HTML generation.
 - In browser bundles, these exports are placeholders that return `undefined`.
 
@@ -81,11 +82,18 @@ Delegated event names captured before client scripts load.
 
 ```tsx
 import { HydrationScript } from "solid-js/web";
-
-// Use when generating HTML on the server
-<head>
-	<HydrationScript />
-</head>;
+import type { JSX } from "solid-js";
+
+function Html(props: { children: JSX.Element }) {
+	return (
+		<html lang="en">
+			<head>
+				<HydrationScript />
+			</head>
+			<body>{props.children}</body>
+		</html>
+	);
+}
 ```
 
 ### `generateHydrationScript`
diff --git a/src/routes/reference/rendering/render-to-stream.mdx b/src/routes/reference/rendering/render-to-stream.mdx
index 79bfcd1bc..7ea469481 100644
--- a/src/routes/reference/rendering/render-to-stream.mdx
+++ b/src/routes/reference/rendering/render-to-stream.mdx
@@ -32,11 +32,10 @@ function renderToStream<T>(
 		renderId?: string;
 		onCompleteShell?: (info: { write: (v: string) => void }) => void;
 		onCompleteAll?: (info: { write: (v: string) => void }) => void;
-		onError?: (err: any) => void;
 	}
 ): {
 	pipe: (writable: { write: (v: string) => void }) => void;
-	pipeTo: (writable: WritableStream) => Promise<void>;
+	pipeTo: (writable: WritableStream) => void;
 };
 ```
 
@@ -74,21 +73,16 @@ Callback invoked when the shell is ready to flush.
 
 Callback invoked after all server suspense boundaries have settled.
 
-#### `onError`
-
-- **Type:** `(err: any) => void`
-
-Callback invoked when a rendering error is encountered.
-
 ## Return value
 
 - **Type:** `{ pipe: ..., pipeTo: ... }`
 
-Streaming controller with `pipe` and `pipeTo` methods. The runtime implementation is also thenable and can resolve to the complete HTML string.
+Streaming controller with `pipe` and `pipeTo` methods.
 
 ## Behavior
 
-- `renderToStream` is a server rendering API and is unsupported in browser bundles. It buffers the shell HTML, including suspense fallback content, and can flush it before later async fragments and serialized data stream as resources resolve.
+- `renderToStream` is a server rendering API and is unsupported in browser bundles.
+- It renders the shell first, including suspense fallback content, and can flush that output before later async fragments and serialized data stream as resources resolve.
 - `onCompleteShell` and `onCompleteAll` receive a `write()` helper for injecting additional output into the stream.
 - `pipe` writes to Node-style writable targets.
 - `pipeTo` writes to a `WritableStream`.
@@ -97,7 +91,7 @@ Streaming controller with `pipe` and `pipeTo` methods. The runtime implementatio
 
 ### `pipe`
 
-```ts
+```tsx
 import { renderToStream } from "solid-js/web";
 
 renderToStream(() => <App />).pipe(response);
@@ -105,11 +99,11 @@ renderToStream(() => <App />).pipe(response);
 
 ### `pipeTo`
 
-```ts
+```tsx
 import { renderToStream } from "solid-js/web";
 
 const { writable } = new TransformStream();
-await renderToStream(() => <App />).pipeTo(writable);
+renderToStream(() => <App />).pipeTo(writable);
 ```
 
 ## Related
diff --git a/src/routes/reference/rendering/render-to-string-async.mdx b/src/routes/reference/rendering/render-to-string-async.mdx
index 334693593..b6fcf3ad1 100644
--- a/src/routes/reference/rendering/render-to-string-async.mdx
+++ b/src/routes/reference/rendering/render-to-string-async.mdx
@@ -30,8 +30,6 @@ function renderToStringAsync<T>(
 		timeoutMs?: number;
 		nonce?: string;
 		renderId?: string;
-		noScripts?: boolean;
-		onError?: (err: any) => void;
 	}
 ): Promise<string>;
 ```
@@ -64,18 +62,6 @@ Nonce applied to inline scripts emitted during rendering.
 
 Identifier used to namespace the render output.
 
-#### `noScripts`
-
-- **Type:** `boolean`
-
-Disables script emission, including serialized data used for hydration continuation.
-
-#### `onError`
-
-- **Type:** `(err: any) => void`
-
-Callback invoked when a rendering error is encountered.
-
 ## Return value
 
 - **Type:** `Promise<string>`
@@ -84,16 +70,17 @@ Promise that resolves to the rendered HTML string.
 
 ## Behavior
 
-- `renderToStringAsync` is a server rendering API and is unsupported in browser bundles. It builds on [`renderToStream`](/reference/rendering/render-to-stream) and waits for the full stream result before resolving.
-- If the timeout elapses, the returned promise rejects instead of resolving partial HTML.
-- Resource data is serialized for client hydration unless scripts are disabled.
+- `renderToStringAsync` is a server rendering API and is unsupported in browser bundles.
+- It waits for server suspense boundaries to settle before resolving the final HTML string.
+- `timeoutMs` limits how long the render waits for async suspense work to finish.
+- Resource data is serialized for client hydration.
 - `renderId` namespaces the render output when multiple top-level roots are present.
 
 ## Examples
 
 ### Basic usage
 
-```ts
+```tsx
 import { renderToStringAsync } from "solid-js/web";
 
 const html = await renderToStringAsync(() => <App />);
diff --git a/src/routes/reference/rendering/render-to-string.mdx b/src/routes/reference/rendering/render-to-string.mdx
index b1e4de9fa..3ce5667ca 100644
--- a/src/routes/reference/rendering/render-to-string.mdx
+++ b/src/routes/reference/rendering/render-to-string.mdx
@@ -28,7 +28,6 @@ function renderToString<T>(
 	options?: {
 		nonce?: string;
 		renderId?: string;
-		onError?: (err: any) => void;
 	}
 ): string;
 ```
@@ -55,12 +54,6 @@ Nonce applied to inline scripts emitted during rendering.
 
 Identifier used to namespace the render output.
 
-#### `onError`
-
-- **Type:** `(err: any) => void`
-
-Callback invoked when a rendering error is encountered.
-
 ## Return value
 
 - **Type:** `string`
@@ -70,6 +63,7 @@ Rendered HTML string.
 ## Behavior
 
 - `renderToString` is a server rendering API, is unsupported in browser bundles, and completes synchronously.
+- It returns the current render output without waiting for async suspense boundaries to settle.
 - The output includes hydration markup. Inline serialized scripts are emitted only when serializer data is produced.
 - Registered assets are injected into the HTML output, typically before `</head>`.
 - `renderId` namespaces the render output when multiple top-level roots are present.
@@ -78,7 +72,7 @@ Rendered HTML string.
 
 ### Basic usage
 
-```ts
+```tsx
 import { renderToString } from "solid-js/web";
 
 const html = renderToString(() => <App />);
diff --git a/src/routes/reference/rendering/render.mdx b/src/routes/reference/rendering/render.mdx
index 9310d6890..b78314e51 100644
--- a/src/routes/reference/rendering/render.mdx
+++ b/src/routes/reference/rendering/render.mdx
@@ -63,7 +63,7 @@ Dispose function for the mounted root.
 
 ### Basic usage
 
-```ts
+```tsx
 import { render } from "solid-js/web";
 
 const dispose = render(() => <App />, document.getElementById("app")!);