update docs for accuracy

LadyBluenotes · LadyBluenotes · commit 27a34a2fe709 · 2026-04-06T14:49:45.000-07:00
diff --git 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
@@ -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
@@ -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
@@ -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,19 +91,19 @@ Streaming controller with `pipe` and `pipeTo` methods. The runtime implementatio
 
 ### `pipe`
 
-```ts
+```tsx
 import { renderToStream } from "solid-js/web";
 
 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
@@ -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
@@ -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
@@ -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")!);
