@picked/client 0.0.70-next.5 → 0.0.70

package/dist/docs/sdk/ssr/index.md

@@ -4,11 +4,17 @@ layout: docs
 
 # Server-Side Rendering
 
-Render Picked Pages on your server for SEO, then hydrate them on the client. This page shows the end-to-end shape; the following pages cover each piece.
+Render a Picked Page on your server so that search engines can read it. Then hydrate
+the page on the client. This page shows the whole shape. The pages after it cover
+each part.
 
 ## Why server-side rendering
 
-Pages are SEO-critical, so their content must be in the HTML your server returns. Crawlers and social unfurls read that HTML directly and do not wait for client-side JavaScript. Rendering a Page on the server puts its content in the initial response, then the client takes over.
+The search rank of a Page matters, so the HTML that your server returns must hold the
+content of that Page. A crawler and a social preview both read that HTML directly.
+Neither waits for the JavaScript in the browser. A Page that the server renders
+therefore has its content in the first response, and the client takes over after
+that.
 
 ## The flow
 
@@ -20,13 +26,19 @@ projectConfig (Delivery API)
 ```
 
 1. Fetch your published `projectConfig` from the [Delivery API](/delivery-api).
-2. Call `serialize()` on the server. It evaluates which experiences match the URL, fetches their content, and returns a plain-JSON `PickedSnapshot`. See [Server Snapshot](/sdk/ssr/serialize).
+2. Call `serialize()` on the server. It finds which experiences match the URL, reads
+   their content, and returns a `PickedSnapshot` as plain JSON. See
+   [Server Snapshot](/sdk/ssr/serialize).
 3. Embed the snapshot in your HTML payload.
-4. On the client, seed a Picked client from the snapshot so the first paint matches the server markup, then hydrate. See [Rendering & Hydration](/sdk/ssr/rendering-and-hydration).
+4. On the client, seed a Picked client from the snapshot. The first paint then
+   matches the markup from the server. Hydrate after that. See
+   [Rendering and Hydration](/sdk/ssr/rendering-and-hydration).
 
-Because the snapshot carries the exact config the server selected with and the memoized condition results, the client's first render reuses the server's decisions instead of re-evaluating them.
+The snapshot carries the exact options that the server chose with, and the condition
+results that it kept. The first render on the client therefore reuses the decisions
+of the server. It does not evaluate them again.
 
-## React vs Svelte at a glance
+## React and Svelte side by side
 
 :::code-group
 
@@ -52,11 +64,16 @@ import { PickedProvider, ExperienceSlot } from '@picked/react'
 
 ## The server entry point
 
-The server helpers live in a dedicated entry so browser bundles never pull them in:
+The server helpers live in a dedicated entry point, so a browser bundle never holds
+them:
 
 ```ts
 import { serialize, registerProjectConfig } from '@picked/client/server'
 import type { PickedSnapshot } from '@picked/client/server'
 ```
 
-Continue to [Server Snapshot](/sdk/ssr/serialize) for the `serialize()` reference, [Rendering & Hydration](/sdk/ssr/rendering-and-hydration) for wiring React and Svelte, and [Slots & Placements](/sdk/ssr/slots-and-placements) for how a slot selects experiences. New to the SDK? Start with [Installation](/sdk).
+Go to [Server Snapshot](/sdk/ssr/serialize) for the `serialize()` reference. Go to
+[Rendering and Hydration](/sdk/ssr/rendering-and-hydration) to connect React and
+Svelte. Go to [Slots and Placements](/sdk/ssr/slots-and-placements) for how a slot
+chooses an experience. If the SDK is new to you, read
+[Installation](/sdk) first.

package/dist/docs/sdk/ssr/rendering-and-hydration.md

@@ -2,20 +2,25 @@
 layout: docs
 ---
 
-# Rendering & Hydration
+# Rendering and Hydration
 
-Seed a Picked client from the server snapshot, render your slots, and hydrate. React and Svelte below.
+Seed a Picked client from the server snapshot, render your slots, and hydrate. This
+page covers React and Svelte.
 
-## React: PickedProvider
+## React: `PickedProvider`
 
-`PickedProvider` supplies a client to descendant components. Its props are a union of two construction modes:
+`PickedProvider` gives a client to each component below it. Its props are a union of
+two modes:
 
 | Props | Mode | Description |
 | --- | --- | --- |
-| `{ options, snapshot? }` | Create | The provider calls `createClient(options)` and hydrates it from the snapshot. |
-| `{ client, snapshot? }` | Adopt | The provider uses an existing client, such as an app-wide global, and optionally seeds it from the snapshot. |
+| `{ options, snapshot? }` | Create | The provider calls `createClient(options)` and hydrates the client from the snapshot. |
+| `{ client, snapshot? }` | Adopt | The provider uses a client that is there already, such as a global one for the whole application. It can also seed that client from the snapshot. |
 
-The provider seeds synchronously, so the server render and the client's first paint produce the same markup. In the browser it calls `client.start()` from an effect; `start()` is idempotent, so an already-started client is left untouched.
+The provider seeds the client at once, so the server and the first paint on the
+client give the same markup. In the browser the provider calls `client.start()` from
+an effect. `start()` is idempotent, so it changes nothing on a client that already
+started.
 
 ```tsx
 import { PickedProvider, ExperienceSlot } from '@picked/react'
@@ -25,9 +30,11 @@ import { PickedProvider, ExperienceSlot } from '@picked/react'
 </PickedProvider>
 ```
 
-## Svelte: setPickedContext
+## Svelte: `setPickedContext`
 
-`setPickedContext` is the Svelte-idiomatic equivalent. Call it once at the top of a component's `<script>`. It takes the same two modes, `{ options, snapshot? }` or `{ client, snapshot? }`, and returns the client.
+`setPickedContext` does the same work in the Svelte style. Call it one time at the
+top of the `<script>` block of a component. It takes the same two modes,
+`{ options, snapshot? }` or `{ client, snapshot? }`, and it returns the client.
 
 ```svelte
 <script lang="ts">
@@ -39,13 +46,20 @@ import { PickedProvider, ExperienceSlot } from '@picked/react'
 <ExperienceSlot name="page" />
 ```
 
-## Placing the slot
+## Place the slot
 
-Drop `<ExperienceSlot name="page" />` where the Page should render. The slot renders every experience that targets it and whose condition is active. See [Slots & Placements](/sdk/ssr/slots-and-placements) for how a slot selects and orders experiences.
+Put `<ExperienceSlot name="page" />` where the Page must render. The slot renders
+every experience that points at it and whose condition is active. See
+[Slots and Placements](/sdk/ssr/slots-and-placements) for how a slot chooses and
+orders your experiences.
 
-## Rendering the page component
+## Render the page component
 
-The SDK does not map content to components. You own the component a Page renders and register it under the name the Page uses, which is the same name the dashboard Page Layout maps to. The component reads the resolved entry data through the content hook: `useStepContent()` in React and `getStepContent()` in Svelte.
+The SDK does not connect content to a component. You own the component that a Page
+renders. Register it under the name that the Page uses. The Page Layout in the dashboard
+points at that same name. The component reads the resolved entry data
+through a content hook: `useStepContent()` in React, and `getStepContent()` in
+Svelte.
 
 :::code-group
 
@@ -85,11 +99,15 @@ export function CMSPage() {
 
 :::
 
-`useStepContent()` returns the entry's `data` object directly, or `null` while no content is registered. `getStepContent()` returns a store you read with `$content`.
+`useStepContent()` returns the `data` object of the entry directly. It returns `null`
+while no content is registered. `getStepContent()` returns a store, and you read it
+with `$content`.
 
 ## Full example
 
-This is the verified page-slot wiring. The page client fetches the project config and renders whichever Page experience targets `.picked-slot-page` and matches the current URL.
+This is the page-slot setup that we tested. The page client reads the project options
+and renders the Page experience that points at `.picked-slot-page` and matches the
+current URL.
 
 :::code-group
 
@@ -138,4 +156,7 @@ export function PageSlot({ snapshot }: { snapshot?: PickedSnapshot }) {
 
 :::
 
-For the end-to-end version with the server snapshot, see [Build a Personalized Page](/guides/build-a-personalized-page). For the snapshot reference, see [Server Snapshot](/sdk/ssr/serialize). For how experiences register, see [SDK Experiences](/sdk/experiences).
+For the full version with the server snapshot, see
+[Build a Personalized Page](/guides/build-a-personalized-page). For the snapshot
+reference, see [Server Snapshot](/sdk/ssr/serialize). For how an experience
+registers, see [SDK Experiences](/sdk/experiences).

package/dist/docs/sdk/ssr/serialize.md

@@ -4,9 +4,11 @@ layout: docs
 
 # Server Snapshot
 
-`serialize()` evaluates which experiences match a URL and fetches their content on the server, returning a plain-JSON snapshot you pass to the client.
+`serialize()` finds which experiences match a URL and reads their content on the
+server. It returns a snapshot as plain JSON, and you pass that snapshot to the
+client.
 
-## serialize(client, params)
+## The `serialize(client, params)` function
 
 ```ts
 import { createClient } from '@picked/client'
@@ -20,7 +22,14 @@ const snapshot = await serialize(client, {
 })
 ```
 
-`serialize()` registers the project config on the client synchronously, evaluates each experience's condition against `attributes.location`, fetches content for the experiences whose steps reference layout content, dedupes the content blobs by id, and returns a `PickedSnapshot`. It expects a per-request client; concurrent calls on a single client are not supported.
+`serialize()` does this. It registers the project options on the client at once. It
+evaluates the condition of each experience against `attributes.location`. It reads
+the content for each experience whose steps point at layout content. It removes the
+duplicate content blobs, which it finds by their IDs. It then returns a
+`PickedSnapshot`.
+
+Give `serialize()` one client for each request. It does not support two calls at the
+same time on one client.
 
 ```ts
 serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
@@ -30,13 +39,15 @@ serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `projectConfig` | `ProjectConfig` | required | The published or preview config to register and select against. |
-| `attributes.location` | `Partial<SerializeLocation>` | none | URL fields injected into the selection context, such as `pathname`. |
-| `getContent` | `SerializeGetContent` | runtime API | A custom content fetcher used in place of the runtime API. |
-| `previewToken` | `string` | none | Forwarded to the content fetch so preview content resolves during preview SSR. |
-| `timeoutMs` | `number` | `10000` | Per-content-fetch timeout. On timeout the blob is skipped and the render proceeds. |
+| `projectConfig` | `ProjectConfig` | required | The published options, or the preview options, to register and choose against. |
+| `attributes.location` | `Partial<SerializeLocation>` | none | The URL fields that go into the selection context, such as `pathname`. |
+| `getContent` | `SerializeGetContent` | runtime API | Your own function to read content, in place of the runtime API. |
+| `previewToken` | `string` | none | The SDK sends this with the content request, so that preview content resolves during a preview render. |
+| `timeoutMs` | `number` | `10000` | The limit for each content request. After the limit, the SDK skips that blob and continues. |
 
-`SerializeLocation` carries the plain URL fields `href`, `pathname`, `search`, `hostname`, `origin`, `protocol`, `port`, `host`, and `hash`. Pass only the ones your conditions read.
+`SerializeLocation` carries the URL fields `href`, `pathname`, `search`, `hostname`,
+`origin`, `protocol`, `port`, `host`, and `hash`. Pass only the fields that your
+conditions read.
 
 ## The snapshot
 
@@ -51,16 +62,18 @@ interface PickedSnapshot {
 
 | Field | Description |
 | --- | --- |
-| `versionId` | The project version the snapshot was selected against, or `null` when unknown (for example on preview). |
-| `projectConfig` | The config the server selected with. It travels so the client renders against the exact same config. |
-| `content` | The deduped content blobs for the selected experiences. |
-| `conditionResults` | The memoized condition results, keyed by rule hash, so the client reuses the server's selection. |
+| `versionId` | The project version that the snapshot was chosen against. It is `null` when the version is not known, for example in a preview. |
+| `projectConfig` | The options that the server chose with. They travel to the client, so that the client renders against exactly the same options. |
+| `content` | The content blobs for the chosen experiences, with the duplicates removed. |
+| `conditionResults` | The condition results that the server kept, under a key made from the rule hash. The client then reuses the choice of the server. |
 
-The snapshot is plain JSON. Serialize it into your HTML response with `JSON.stringify` and read it back on the client.
+The snapshot is plain JSON. Write it into your HTML response with `JSON.stringify`
+and read it back on the client.
 
-## Passing the snapshot to the client
+## Pass the snapshot to the client
 
-Embed the snapshot in your HTML payload, then hand it to the provider (React) or context (Svelte):
+Embed the snapshot in your HTML payload. Then give it to the provider in React, or to
+the context in Svelte:
 
 ```ts
 const html = `
@@ -69,11 +82,14 @@ const html = `
 `
 ```
 
-On the client, read `window.__PICKED__` and pass it as the `snapshot` prop. See [Rendering & Hydration](/sdk/ssr/rendering-and-hydration).
+On the client, read `window.__PICKED__` and pass it as the `snapshot` prop. See
+[Rendering and Hydration](/sdk/ssr/rendering-and-hydration).
 
-## Preview rendering
+## Render a preview
 
-Pass `previewToken` so unpublished content resolves during preview SSR. The server has no access to the request's query string, so the token cannot be recovered any other way:
+Pass `previewToken`, so that unpublished content resolves during a preview render.
+The server cannot read the query string of the request, so there is no other way to
+give it the token:
 
 ```ts
 const snapshot = await serialize(client, {
@@ -83,4 +99,6 @@ const snapshot = await serialize(client, {
 })
 ```
 
-Use the same token when you fetch `projectConfig` from the [Delivery API](/delivery-api), so the config and the content come from the same preview surface.
+Use the same token when you read `projectConfig` from the
+[Delivery API](/delivery-api). The options and the content then come from the same
+preview.

package/dist/docs/sdk/ssr/slots-and-placements.md

@@ -2,34 +2,52 @@
 layout: docs
 ---
 
-# Slots & Placements
+# Slots and Placements
 
-A slot is a named mount point. `<ExperienceSlot name="page" />` renders every experience that targets that slot and whose condition matches.
+A slot is a named mount point. `<ExperienceSlot name="page" />` renders every
+experience that points at that slot and whose condition matches.
 
 ## What a slot is
 
-A slot's `name` maps to the `.picked-slot-<name>` selector. `<ExperienceSlot name="page" />` renders every experience whose target selector is `.picked-slot-page` and whose condition is active. The slot reads each experience's active state from the seeded snapshot, so it renders synchronously during server-side rendering and the hydration first paint.
+The `name` of a slot points at the `.picked-slot-<name>` selector. So
+`<ExperienceSlot name="page" />` renders every experience with the target selector
+`.picked-slot-page`, when the condition of that experience is active.
+
+The slot reads the active state of each experience from the seeded snapshot. It
+therefore renders at once, both in server-side rendering and at the first paint of
+the hydration.
 
 ```tsx
 <ExperienceSlot name="page" />
 ```
 
-## Targeting an experience to a slot
+## Point an experience at a slot
 
-Set the experience's target selector to `.picked-slot-<name>`. An experience targeting `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The slot name and the selector suffix must match.
+Set the target selector of the experience to `.picked-slot-<name>`. An experience
+that points at `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The
+name of the slot and the end of the selector must match.
 
 ## Placement order
 
-When several experiences target the same slot, they render in placement precedence:
+When more than one experience points at the same slot, they render in this placement
+order:
 
 ```
 replace -> before -> prepend -> append -> after
 ```
 
-`replace` wins. If an active experience uses the `replace` placement, it renders alone and replaces every other match in the slot. Otherwise every active experience renders, in placement order.
+`replace` wins. An active experience with the `replace` placement renders alone, and
+it replaces every other match in the slot. In every other case each active experience
+renders, in placement order.
 
-## Multiple experiences in one slot
+## More than one experience in one slot
 
-The slot collects each experience that targets its selector, drops any whose condition is not active, and sorts the rest by placement. If a `replace` experience is among the active ones, only that experience renders. With no active `replace`, the slot renders all active experiences in `before, prepend, append, after` order.
+The slot collects each experience that points at its selector. It drops each one
+whose condition is not active. It then sorts the rest into placement order. When a `replace`
+experience is among the active ones, only that experience renders. With no active
+`replace`, the slot renders every active experience in the order `before`, `prepend`,
+`append`, `after`.
 
-This lets one Page take over a slot with `replace`, while other slots can stack several experiences by using the non-`replace` placements. Conditions decide which experiences are active; see [Conditions](/conditions).
+One Page can therefore take a whole slot with `replace`, while another slot holds
+several experiences that use the other placements. A condition decides which
+experiences are active. See [Conditions](/conditions).

package/dist/docs/sdk/steps.md

@@ -4,23 +4,33 @@ layout: docs
 
 # Steps
 
-Render steps with `<StepRouter>` and `<Step>` from `@picked/react` or `@picked/svelte`, and access the active step through `useStep()` / `getStep()`.
+Render your steps with `<StepRouter>` and `<Step>` from `@picked/react` or
+`@picked/svelte`. Reach the active step through `useStep()` or `getStep()`.
 
 ## How steps work
 
-When an experience starts, its steps are connected in a directed node graph. The SDK traverses this graph to determine which step to display:
-
-1. **Initialization**: When the experience opens, the SDK starts at the origin node and traverses the graph to find the first step
-2. **Step Entry**: The active step is set and a `step_enter` event is emitted on the event bus
-3. **Field Evaluation**: The step's fields are evaluated — fields with conditions are shown or hidden based on the current state
-4. **User Input**: The user interacts with the step's fields. Client-side validation runs on blur and on submit
-5. **Step Submission**: When the user submits, a `step_submit` event fires and field responses are committed to the client state
-6. **Navigation**: The SDK follows the edge from the current step node to the next, traversing any conditionals or actions before arriving at the next step
-7. **Completion**: When no further steps exist, the experience flow is complete
+When an experience starts, its steps form a directed graph of nodes. The SDK walks
+this graph to find which step to show:
+
+1. **Initialization**: when the experience opens, the SDK starts at the origin node.
+   It walks the graph to find the first step.
+2. **Step entry**: the SDK sets the active step. It sends a `step_enter` event on the
+   event bus.
+3. **Field evaluation**: the SDK evaluates the fields of the step. It shows or hides
+   a field with a condition, and the current state decides which.
+4. **User input**: the user fills in the fields of the step. Validation runs in the
+   browser on blur and on submit.
+5. **Step submission**: when the user submits, a `step_submit` event fires. The SDK
+   commits the field responses to the client state.
+6. **Navigation**: the SDK follows the edge from the current step node to the next
+   one. It walks through each condition and action on the way.
+7. **Completion**: when no step remains, the experience flow is complete.
 
 ## Step routing
 
-`StepRouter` listens to the experience's current step state and activates the matching `Step` by its `id`. Each `Step` registers itself on mount and unregisters on unmount, so lazy-rendered tabs or drawers work automatically.
+`StepRouter` watches the current step state of the experience. It activates the
+`Step` whose `id` matches. Each `Step` registers itself on mount and unregisters on
+unmount, so a tab or a drawer that renders lazily works with no extra code.
 
 :::code-group
 
@@ -69,12 +79,12 @@ function MyExperience() {
 :::
 
 :::note
-All Steps must be wrapped in a router, even if it is a single Step
+A router must hold every Step, even when there is only one Step.
 :::
 
 ### Lazy-loaded steps
 
-For large experiences, steps can be lazily loaded using dynamic imports:
+For a large experience, load a step lazily with a dynamic import:
 
 :::code-group
 
@@ -98,11 +108,13 @@ const WelcomeScreen = lazy(() => import('./WelcomeScreen'))
 
 :::
 
-The `component` prop accepts a `Promise<Component>` — the step's content is not loaded until it becomes active.
+The `component` prop takes a `Promise<Component>`. The SDK does not load the content
+of the step until that step becomes active.
 
-## Accessing step context
+## Reach the step context
 
-Inside a `Step` component (or any component rendered within one), call `getStep()` / `useStep()` to access the step's reactive context:
+Inside a `Step` component, or inside any component that a `Step` renders, call
+`getStep()` or `useStep()` to reach the reactive context of the step:
 
 :::code-group
 
@@ -161,24 +173,29 @@ function ContactForm() {
 
 :::
 
-`getStep()` (Svelte) / `useStep()` (React) returns a `StepContext` with the following properties:
+`getStep()` in Svelte, and `useStep()` in React, return a `StepContext` with these
+properties:
 
 | Property   | Type                                          | Description                                                                    |
 | ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
-| `step`     | `Store<ExperienceStep>`                       | Reactive store containing the step's `id` and `label`                          |
-| `fields`   | `Store<FormField[]>`                          | Reactive store of fields with their current values, errors, and event handlers |
-| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether this step is currently active in the router                            |
-| `form`     | Object                                        | Form submission handlers (see [Forms](#forms))                                 |
+| `step`     | `Store<ExperienceStep>`                       | A reactive store that holds the `id` and the `label` of the step                |
+| `fields`   | `Store<FormField[]>`                          | A reactive store of the fields, with their current values, errors, and handlers |
+| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether the router holds this step as the active one                            |
+| `form`     | Object                                        | The handlers for a form submission. See [Forms](#forms).                        |
 
 ## Forms
 
-When a step has fields, `getStep()` / `useStep()` provides a `form` object for handling submission, validation, and navigation.
+When a step has fields, `getStep()` and `useStep()` give you a `form` object. Use it
+for the submission, the validation, and the move to the next step.
 
-Both accept an optional callbacks object — `getStep({ onSuccess })` / `useStep({ onSuccess })` — which is the recommended way to react to submission. The available slots are `onBeforeSubmit`, `onSuccess` and `onError`, all covered below.
+Both take an optional object of callbacks, as in `getStep({ onSuccess })` or
+`useStep({ onSuccess })`. This is the recommended way to act on a submission. The
+slots are `onBeforeSubmit`, `onSuccess`, and `onError`. This page covers each one
+below.
 
-### Handling submission
+### Handle a submission
 
-Bind `form.props` to your `<form>` element's `onsubmit` handler:
+Bind `form.props` to the `onsubmit` handler of your `<form>` element:
 
 :::code-group
 
@@ -242,19 +259,22 @@ function StepForm() {
 
 :::
 
-Submitting the form:
+When you submit the form, the SDK does this:
 
-1. Collects field values from the HTML form
-2. Runs `onBeforeSubmit` transform callbacks in series — a throw here aborts the submit before anything is committed
-3. Validates all required fields and field validation rules
-4. Commits the responses to the experience state
-5. Fires `form_submit_success` or `form_submit_error` on the event bus
-6. Runs your `onSuccess` or `onError` callbacks
-7. Navigates to the next step (unless `stopNavigation` is called, and regardless of whether a callback in step 6 failed)
+1. It collects the field values from the HTML form.
+2. It runs each `onBeforeSubmit` callback, one after another. A throw here aborts the
+   submit and commits nothing.
+3. It checks each required field and each validation rule.
+4. It commits the responses to the experience state.
+5. It fires `form_submit_success` or `form_submit_error` on the event bus.
+6. It runs your `onSuccess` or `onError` callback.
+7. It moves to the next step. A call to `stopNavigation` stops this. A callback that
+   failed in step 6 does not stop it.
 
-### Transforming data before submission
+### Transform data before a submission
 
-Use `onBeforeSubmit` to intercept and transform field data before it is committed. Callbacks run in series, each receiving the output of the previous:
+Use `onBeforeSubmit` to intercept and transform the field data before the SDK stores it. The callbacks run one after another. Each one takes the output of the one before
+it:
 
 :::code-group
 
@@ -264,7 +284,7 @@ Use `onBeforeSubmit` to intercept and transform field data before it is committe
 
   const { form } = getStep({
     onBeforeSubmit: async (data) => {
-      // Normalize email to lowercase before committing
+      // Normalize the email address to lowercase first.
       return {
         ...data,
         'email-address': String(data['email-address']).toLowerCase(),
@@ -282,7 +302,7 @@ import { useStep } from '@picked/react/hooks'
 function ContactStep() {
   const { form } = useStep({
     onBeforeSubmit: async (data) => {
-      // Normalize email to lowercase before committing
+      // Normalize the email address to lowercase first.
       return {
         ...data,
         'email-address': String(data['email-address']).toLowerCase(),
@@ -297,12 +317,16 @@ function ContactStep() {
 :::
 
 :::warning
-If an `onBeforeSubmit` callback throws, the submit is aborted before anything is committed and the step does not advance. This is deliberate — committing a half-transformed payload would persist wrong-but-plausible data. Use it for transforms and validation, and put side effects such as analytics or backend calls in `onSuccess` instead.
+When an `onBeforeSubmit` callback throws, the SDK aborts the submit before it commits
+anything, and the step does not advance. This is deliberate. A payload that is only
+part transformed would store data that looks correct but is wrong. Use
+`onBeforeSubmit` for a transform and for a validation check. Put a side effect, such as an
+analytics call or a backend call, in `onSuccess`.
 :::
 
 ### Success and error callbacks
 
-Pass `onSuccess` and `onError` to react to submission outcomes:
+Pass `onSuccess` and `onError` to act on the outcome of a submission:
 
 :::code-group
 
@@ -342,13 +366,20 @@ function ContactStep() {
 
 :::
 
-Callbacks are scoped to the component that passes them, and are cleaned up automatically when that component unmounts — no manual teardown is needed. Passing a new inline function on a re-render replaces the previous one rather than adding another, so a single submit runs each callback exactly once.
+A callback belongs to the component that passes it. The SDK releases the callback
+when that component unmounts, so you write no teardown code. A new inline function on
+a re-render replaces the earlier one and does not add a second one. One submit
+therefore runs each callback exactly one time.
 
-A throwing or rejecting `onSuccess`/`onError` callback cannot block the flow: the step still advances, and the failure is reported on the client event bus as `form_submit_callback_error` so it stays observable.
+An `onSuccess` or `onError` callback that throws or rejects cannot stop the flow. The
+step still advances, and the SDK reports the failure on the client event bus as
+`form_submit_callback_error`, so the failure stays observable.
 
-#### Registering callbacks imperatively
+#### Register a callback in code
 
-`form.onSuccess`, `form.onError` and `form.onBeforeSubmit` are also available as an escape hatch, for cases where a callback has to be attached conditionally. They return nothing — cleanup is automatic, as above.
+`form.onSuccess`, `form.onError`, and `form.onBeforeSubmit` are an escape hatch, for
+a callback that you must attach only when a condition holds. They return nothing. The
+SDK releases them for you, as above.
 
 ```tsx [React]
 function ContactStep({ trackConversions }: { trackConversions: boolean }) {
@@ -363,12 +394,17 @@ function ContactStep({ trackConversions }: { trackConversions: boolean }) {
 ```
 
 :::warning
-Register from the component body, not from an event handler. A registration made inside a click handler is added each time the handler runs and is only released when the component unmounts, so it accumulates. Prefer the options object above wherever you can.
+Register from the body of the component, and not from an event handler. A
+registration inside a click handler is added each time the handler runs, and the SDK
+releases it only when the component unmounts. The registrations therefore accumulate.
+Use the options object above where you can.
 :::
 
-### Preventing navigation on success
+### Stop the move to the next step
 
-By default, the experience advances to the next step after a successful submission. Call `stopNavigation()` inside `onSuccess` to prevent this, for example when you need to handle navigation manually:
+By default the experience advances to the next step after a successful submission.
+Call `stopNavigation()` inside `onSuccess` to stop this. Do it when you must choose
+the next step yourself:
 
 :::code-group
 
@@ -383,7 +419,7 @@ By default, the experience advances to the next step after a successful submissi
     onSuccess: ({ data, stopNavigation }) => {
       stopNavigation()
 
-      // Navigate to step based on submitted data
+      // Choose the next step from the data that the user sent.
       if (data['plan-type'] === 'enterprise') {
         experience.goToStepById('enterprise-contact')
       } else {
@@ -407,7 +443,7 @@ function PlanStep() {
     onSuccess: ({ data, stopNavigation }) => {
       stopNavigation()
 
-      // Decide the next step based on submitted data
+      // Choose the next step from the data that the user sent.
       if (data['plan-type'] === 'enterprise') {
         experience.goToStepById('enterprise-contact')
       } else {
@@ -422,13 +458,22 @@ function PlanStep() {
 
 :::
 
-Navigate by step `id` with `goToStepById('<step-id>')`, or by the step's semantic `key` with `goToStepByKey('<step-key>')`. Both jump straight to the matching step node; if no step matches, the call is a no-op.
+Move by step `id` with `goToStepById('<step-id>')`, or by the `key` of the step with
+`goToStepByKey('<step-key>')`. Both jump directly to the step node that matches. When
+no step matches, the call does nothing.
 
 ## Best practices
 
-- **Give steps meaningful labels**: The `label` is used in analytics events and the dashboard — prefer descriptive names like `"Contact Details"` over `"Step 2"`
-- **Keep steps focused**: Each step should collect a small, related set of information. Prefer more steps over longer forms to reduce abandonment
-- **Use conditionals for branching**: Avoid duplicating steps — model branching logic with `nextConditional()` so shared steps can be reused
-- **Use `stopNavigation` sparingly**: Automatic navigation after submit is the expected behavior. Only disable it when you need explicit control over the next destination
-- **Validate eagerly on blur, not on change**: The SDK follows this pattern automatically — fields show errors after the user leaves them, not as they type
-- **Lazy-load large step components**: Use the `component` prop on `<Step>` with a dynamic import for content that is only shown to a subset of users
+- **Give each step a meaningful label**: analytics events and the dashboard both show
+  the `label`. Use a name that says what the step does, such as `"Contact Details"`
+  and not `"Step 2"`.
+- **Keep each step small**: each step must collect one small set of related
+  information. More steps with fewer fields each reduce the number of users who leave.
+- **Use a condition to take a branch**: do not make a second copy of a step. Write the
+  branch with `nextConditional()`, so that you can reuse a shared step.
+- **Use `stopNavigation` only when you must**: an automatic move after a submit is
+  what a user expects. Stop it only when you must choose the next step yourself.
+- **Check a field on blur, not on change**: the SDK does this for you. A field shows
+  an error after the user leaves it, and not while the user types.
+- **Load a large step component lazily**: use the `component` prop on `<Step>` with a
+  dynamic import, for content that only some users see.