@picked/client 0.0.72-next.1 → 0.0.72-next.3

package/dist/docs/reference/dashboard/content/models.mdx

@@ -0,0 +1,108 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Models
+
+A Model is a reusable schema. It sets which fields a piece of content can hold, and it holds no data itself.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
+  alt="The models list in the schema builder on the Picked dashboard"
+/>
+
+## Where a Model appears
+
+**CMS** in the sidebar holds **Models**, and that list shows every Model in the
+workspace. The list shows the **Key** below the name, because the key is the value that
+a schema holds.
+
+Two shortcuts open a filtered subset of the same list. **Flows** holds **Step Layouts**,
+and **Pages** holds **Page Layouts**.
+
+## Category
+
+A category gives a Model a role. It decides where the Model appears, and what renders an
+entry that comes from it.
+
+| Category | It gives its shape to | What renders it |
+| --- | --- | --- |
+| **Page layout** | A standalone [Page](/reference/dashboard/content/pages). | The SDK renders the entry on your server. |
+| **Step layout** | One [Step](/reference/dashboard/steps) inside a Flow. | The Step renders the entry in the browser. |
+| **None (general content)** | Content with no layout role. | Nothing renders it directly. A [reference field](#reference-fields) reaches it. |
+
+A Model with no category holds content that other content points at, such as a product
+or a category. It appears under **CMS** only.
+
+:::warning
+The category is fixed when you create the Model. You cannot change it later.
+:::
+
+## Field types
+
+A Model is built from fields. Each field has a type. The type decides the editor for the
+field, and the shape of the value that the field holds.
+
+| Type | Holds | Use it for |
+| --- | --- | --- |
+| **Single line text** | A short string. | A title, a label, or a short headline. |
+| **Multi-line text** | A longer plain string. | A description, or a paragraph with no format marks. |
+| **Markdown** | A Markdown string. | Body copy with format marks. |
+| **Slug** | A URL-safe string. | A part of a path, or an identifier. |
+| **Number** | A numeric value. | A price, a count, or a rating. |
+| **Boolean** | A true or false value. | A toggle or a flag. |
+| **Date** | A date value. | A publish date or a deadline. |
+| **Color** | A color value. | A theme accent or a swatch. |
+| **JSON** | Any JSON value. | Structured data with no editor of its own. |
+| **Group** | An object of fields inside the Model. | A set of related fields, held together. |
+| **Content block** | A [Block](/reference/dashboard/content/blocks) schema inside the Model. | A shared schema fragment that you reuse. |
+| **Page Sections** | A repeatable Content block field, limited to the Section category. | The section list of a page. |
+| **Reference** | A pointer at another [content entry](/reference/dashboard/content/content-entries). | A product that points at its category. |
+| **Asset** | A link to an [Asset Library](/reference/dashboard/content/asset-library) item. | An image, a video, or a document. |
+| **HTML** | A link to a `.html` file in your library. | HTML that you wrote before, held inside the content. |
+
+## Reference fields
+
+A **Reference** field points at another content entry. The entry that you point at keeps
+its own data, and many fields can point at the same entry.
+
+| Option | Values | What it does |
+| --- | --- | --- |
+| **Target Model** | A Model, or **Any Model** | Limits which entries an editor can choose. |
+| **Repeatable** | On or off | On gives an ordered list of entries. Off gives one entry. |
+
+**Target Model** holds the `key` of the Model, and not its id. A duplicate of the
+workspace therefore keeps the constraint.
+
+A reference stays inside one workspace. A field cannot point at an entry in another
+workspace, and Picked reports such a target as unknown.
+
+## Repeatable and grouped fields
+
+You can make any field **repeatable**. It then shows as a sortable list of values, and
+not as one value. Use it for a gallery, for a list of features, or for any collection.
+
+A **Group** field holds a set of fields under one key, and it gives a structured object.
+Make a group repeatable to describe a list of objects, such as a list of feature cards.
+
+## Delete rules
+
+Picked does not delete a Model while something still needs it.
+
+| Condition | Result |
+| --- | --- |
+| Content entries still belong to the Model | The delete stops. |
+| A Reference field still holds the Model as its **Target Model** | The delete stops. |
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why a schema change does not
+  migrate your data.
+- [About content references](/explanation/content-references) — why a reference is a pointer.
+- [How to define a page layout](/how-to/define-a-page-layout)
+- [How to create a content entry](/how-to/create-a-content-entry)
+- [How to point one entry at another](/how-to/point-one-entry-at-another)
+- [Blocks](/reference/dashboard/content/blocks)

package/dist/docs/reference/dashboard/content/pages.mdx

@@ -24,12 +24,13 @@ choose, and the preview panel shows the page while it fills in.
 ## Change or remove the layout
 
 Use the change-layout control on the **Settings** tab to move the page to another
-Page Layout. When you unlink a layout, Picked separates the Content Entry from the
-page. It deletes no entry, but the page then has no content to render until you
-attach a layout again.
+[Page Layout](/reference/dashboard/content/models#category). When you unlink a layout,
+Picked separates the content entry from the page. It deletes no entry, but the page then
+has no content to render until you attach a layout again.
 
 ## Related
 
 - [About pages and flows](/explanation/pages-and-flows) — when to choose a Page.
 - [How to fill and publish a page](/how-to/fill-and-publish-a-page)
 - [How to server-render a page](/how-to/server-render-a-page)
+- [Models](/reference/dashboard/content/models) — the schema behind a Page.

package/dist/docs/reference/dashboard/fields.mdx

@@ -12,7 +12,7 @@ information such as a name, an email address, a preference, or a choice.
 
 This page covers the experience field, which collects visitor input. An experience
 field is not the same as a content field. A content field is part of the schema of a
-CMS layout. See [Page and Step Layouts](/reference/dashboard/content/layouts) for those.
+CMS layout. See [Models](/reference/dashboard/content/models) for those.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"

package/dist/docs/reference/dashboard/steps.mdx

@@ -26,7 +26,7 @@ visitors do not see it.
 are `card`, `modal`, and `fullscreen`.
 
 A step can also carry a **Step Layout**. A step layout is a reusable CMS schema, and
-it gives the step a Content Entry. See [Page and Step Layouts](/reference/dashboard/content/layouts).
+it gives the step a Content Entry. See [Models](/reference/dashboard/content/models).
 
 ## Related
 
@@ -34,4 +34,4 @@ it gives the step a Content Entry. See [Page and Step Layouts](/reference/dashbo
 
 - [How to build a flow](/how-to/build-a-flow) — add a step and assign fields to it.
 - [How to reuse a step, a field, or an action](/how-to/reuse-a-step-field-or-action)
-- [Page and step layouts](/reference/dashboard/content/layouts) — the step layout schema.
+- [Models](/reference/dashboard/content/models) — the step layout schema.

package/dist/docs/reference/delivery-api/experience-content.md

@@ -5,7 +5,7 @@ layout: docs
 
 # Experience Content Endpoint
 
-Fetch the Content Entries that back a single experience's steps.
+Fetch the content entries that back the steps of a single experience.
 
 ## Request
 
@@ -29,7 +29,17 @@ GET /api/v1/projects/:projectId/experiences/:id/content
     {
       "id": "entry_789",
       "contentModelKey": "page-hero",
-      "data": { "title": "Spring sale", "body": "..." }
+      "data": {
+        "title": "Spring sale",
+        "category": { "contentEntryId": "entry_42", "contentModelKey": "category" }
+      }
+    }
+  ],
+  "references": [
+    {
+      "id": "entry_42",
+      "contentModelKey": "category",
+      "data": { "name": "Outerwear" }
     }
   ]
 }
@@ -39,14 +49,59 @@ GET /api/v1/projects/:projectId/experiences/:id/content
 | --- | --- | --- |
 | `experienceId` | `string` | The experience the content belongs to. |
 | `versionId` | `string \| null` | The published version id, or `null` on preview. |
-| `content[].id` | `string` | The Content Entry id. |
-| `content[].contentModelKey` | `string \| null` | The layout's Key, or `null` when it cannot be resolved. |
-| `content[].data` | `object` | The entry data. It matches the layout schema. |
+| `content[]` | `array` | The entries that the steps of the experience point at. |
+| `content[].id` | `string` | The content entry id. |
+| `content[].contentModelKey` | `string \| null` | The Key of the Model, or `null` when it cannot be resolved. |
+| `content[].data` | `object` | The entry data. It matches the schema of the Model. |
+| `references[]` | `array` | Every entry that a `reference` field reaches, in the same blob shape as `content[]`. |
+
+The published response and the preview response hold the same fields, and the same
+values, for the same content.
+
+## A reference field points at a separate blob
+
+A [Reference field](/reference/dashboard/content/models#reference-fields) arrives as a
+pointer, and not as the entry:
+
+```json
+{ "contentEntryId": "entry_42", "contentModelKey": "category" }
+```
+
+A repeatable Reference field arrives as an array of such pointers.
+
+The entry itself arrives in `references[]` under its own `id`. Look the pointer up
+there. The SDK does this for you, through
+[`useReference` and `getReference`](/reference/sdk/content).
+
+`references[]` holds each entry one time, for any number of fields that point at it. It
+omits the entries that are in `content[]` already.
+
+### What `references[]` omits
+
+Picked resolves a chain of references to a maximum depth of 5. It counts the depth from
+the entries in `content[]`. An entry is absent from `references[]` when Picked cannot
+resolve it:
+
+| Cause | Result |
+| --- | --- |
+| The target was deleted | The pointer stays. The entry is absent. |
+| The target is in another workspace | The pointer stays. The entry is absent. |
+| The chain makes a cycle | The pointer stays. The entry is absent. |
+| The chain is deeper than 5 | The pointer stays, with its `contentModelKey`. The entry is absent. |
+
+A pointer with no entry in `references[]` means that there is no such entry. Picked sends
+no empty blob for it.
+
+:::warning
+A reference pointer also carries a `data` field with the content of the target inlined.
+This is for the SDK versions that came before `references[]`. Read `references[]`
+instead. A later release removes the inline copy.
+:::
 
 ## An HTML asset comes back in the response
 
-A layout can have an [HTML asset](/reference/dashboard/content/asset-library) field. The value of that
-field arrives inside the response. The endpoint changes the reference to
+A Model can have an [HTML asset](/reference/dashboard/content/asset-library) field. The
+value of that field arrives inside the response. The endpoint changes the reference to
 `{ id, content }`. There, `content` holds the HTML that you uploaded, as a string. It
 is `null` when the endpoint cannot resolve it:
 
@@ -82,16 +137,16 @@ curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
   "versionId": "ver_456",
   "content": [
     { "id": "entry_789", "contentModelKey": "page-hero", "data": { "title": "Spring sale" } }
-  ]
+  ],
+  "references": []
 }
 ```
 
-See [Project Config](/reference/delivery-api/project-config) for the endpoint that links a step
-to an entry. See [Asset Library](/reference/dashboard/content/asset-library) for an HTML asset. See
-[Server Snapshot](/reference/sdk/ssr/serialize) for how the SDK reads this content.
-
 ## Related
 
 - [About the two APIs](/explanation/the-two-apis)
-- [Project config](/reference/delivery-api/project-config)
+- [About content references](/explanation/content-references) — why a reference is a pointer.
+- [Content](/reference/sdk/content) — how the SDK resolves a pointer.
+- [Project config](/reference/delivery-api/project-config) — the endpoint that links a step to an entry.
+- [Server Snapshot](/reference/sdk/ssr/serialize) — how the SDK reads this content.
 - [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling)

package/dist/docs/reference/glossary.md

@@ -74,14 +74,21 @@ documentation uses, and it names the others.
 
 | Term | What it is |
 | --- | --- |
-| **Page layout** | A reusable schema that sets which fields a Page can hold. The API type is `ContentModel`, and the dashboard list page is titled **Models**. |
-| **Step layout** | The same, for one Step inside a Flow. |
-| **Section** | A reusable schema fragment that you put inside one or more layouts. The API type is `ContentBlock`, and the dashboard list page is titled **Blocks**. |
-| **Content entry** | One instance of a layout, filled with real values. The dashboard list page is titled **Content**. |
+| **Model** | A reusable schema that sets which fields a piece of content can hold. The API type is `ContentModel`. The dashboard lists them under **CMS**, at **Models**. |
+| **Block** | A reusable schema fragment that you put inside one or more Models. The API type is `ContentBlock`. The dashboard lists them under **CMS**, at **Blocks**. |
+| **Content entry** | One instance of a Model, filled with real values. The dashboard lists them under **CMS**, at **Content entries**. |
+| **Category** | The role of a Model or a Block. It is fixed when you create the record. |
+| **Page layout** | A Model with the Page layout category. It sets which fields a Page can hold. |
+| **Step layout** | A Model with the Step layout category. It sets which fields one Step inside a Flow can hold. |
+| **Section** | A Block with the Section category. A **Page Sections** field accepts it. |
+| **General content** | A Model or a Block with no category. It has no layout role, and nothing renders its entries directly. |
+| **Reference** | A field that points one content entry at another. The pointer holds the id of the target, and not a copy of it. |
+| **Target Model** | The Model whose entries a Reference field accepts. It holds a Key. **Any Model** sets no limit. |
+| **Entry title** | The name that the entries list shows. It is the first single-line text field of the entry, and it falls back to the entry id. |
 | **Asset** | A file that your content points at: an image, a video, a document, or HTML. |
 | **Asset library** | The project-level store that holds your assets. |
 | **Design system** | A set of shared design decisions for a project. |
-| **Content schema** | The set of fields that a layout or a section defines. |
+| **Content schema** | The set of fields that a Model or a Block defines. |
 | **Asset version** | One file that somebody uploaded for an asset. The library keeps the earlier versions. |
 | **Validation error** | A report that one field in a content entry does not match its schema. It carries the path to the exact field. |
 
@@ -96,6 +103,7 @@ documentation uses, and it names the others.
 | **Slot** | A named mount point, rendered by `<ExperienceSlot name="…" />`. It maps to the `.picked-slot-<name>` selector. |
 | **Placement** | Where an experience renders against its target: `replace`, `before`, `prepend`, `append`, or `after`. |
 | **Target selector** | The selector that an experience renders into. |
+| **Content index** | The store of every content record that the client holds, keyed by id. `useContent(id)` and `useReference()` read it. |
 | **Snapshot** | The plain JSON that `serialize()` returns on your server, and that seeds the client in the browser. |
 | **Precondition** | A gate that decides whether Picked starts at all. |
 | **Visitor** | The person on your site. Picked gives each one a stable ID. A visitor is not a user. |

package/dist/docs/reference/management-api/error-handling.md

@@ -46,7 +46,7 @@ operation, or MFA. They match the `AuthErrorCode` enum in the schema.
 | Code | Description |
 |------|-------------|
 | `INVALID_CREDENTIALS` | The email address and the password do not match. |
-| `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/reference/management-api/authentication#verify-an-email-address). |
+| `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/reference/management-api/authentication#the-mutations). |
 | `USER_NOT_FOUND` | There is no account with that email address. |
 | `USER_ALREADY_EXISTS` | An account with that email address is there already. The API returns this when you create an account. |
 | `WEAK_PASSWORD` | The password is not strong enough. |
@@ -199,7 +199,7 @@ if (result.errors) {
 ### Refresh a token that expired
 
 A request can return `UNAUTHORIZED` while the caller holds a refresh token. Try a
-[session refresh](/reference/management-api/authentication#refresh-a-session) first. Do not treat it as a
+[session refresh](/reference/management-api/authentication#the-mutations) first. Do not treat it as a
 failure to sign in:
 
 ```javascript

package/dist/docs/reference/sdk/content.md

@@ -0,0 +1,216 @@
+---
+type: reference
+layout: docs
+---
+
+# Content
+
+The client holds every content record in one index, keyed by the id. The hooks on this
+page read that index.
+
+## The content record
+
+```ts
+interface Content {
+  id: string
+  contentModelKey?: string | null
+  data: Record<string, unknown>
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The content entry id. |
+| `contentModelKey` | `string \| null` | The Key of the [Model](/reference/dashboard/content/models) that the entry belongs to. |
+| `data` | `Record<string, unknown>` | The field values, keyed by the field key from the schema. |
+
+The client registers the `content` array and the `references` array of the
+[experience content response](/reference/delivery-api/experience-content) into the same
+index. Your code can therefore read a referenced entry by its own id.
+
+## Read the content of a step
+
+`useStepContent()` in React, and `getStepContent()` in Svelte, give the `data` of the
+entry that the current step points at.
+
+:::code-group
+
+```tsx [React]
+import { useStepContent } from '@picked/react/hooks'
+
+export function Hero() {
+  const content = useStepContent()
+
+  return <h1>{String(content?.headline ?? '')}</h1>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+</script>
+
+<h1>{$content?.headline ?? ''}</h1>
+```
+
+:::
+
+`useStepContent()` returns the data, and React re-renders the component when the data
+changes. `getStepContent()` returns a store, which you read with the `$` prefix.
+
+## Read a record by id
+
+`useContent(id)` and `getContent(id)` return a store of one record. The store holds
+`null` until the client registers that record.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useContent } from '@picked/react/hooks'
+
+export function Banner() {
+  const banner = useUnit(useContent('entry_42'))
+
+  return <h1>{String(banner?.data.headline ?? '')}</h1>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getContent } from '@picked/svelte/hooks'
+
+  const banner = getContent('entry_42')
+</script>
+
+<h1>{$banner?.data.headline ?? ''}</h1>
+```
+
+:::
+
+## Resolve a reference field
+
+A [Reference field](/reference/dashboard/content/models#reference-fields) holds a pointer,
+and not the record. `useReference()` and `getReference()` resolve the pointer against the
+index.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReference, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategory() {
+  const content = useStepContent()
+  const category = useUnit(useReference(content?.category))
+
+  return <span>{String(category?.data.name ?? '')}</span>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReference } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const category = getReference(content.map((c) => c?.category ?? null, { skipVoid: false }))
+</script>
+
+<span>{$category?.data.name ?? ''}</span>
+```
+
+:::
+
+For a repeatable Reference field, use `useReferences()` and `getReferences()`. They give
+a list in field order.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReferences, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategories() {
+  const content = useStepContent()
+  const categories = useUnit(useReferences(content?.categories))
+
+  return (
+    <ul>
+      {categories.map((category) => (
+        <li key={category.id}>{String(category.data.name ?? '')}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReferences } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const categories = getReferences(content.map((c) => c?.categories ?? null, { skipVoid: false }))
+</script>
+
+<ul>
+  {#each $categories as category (category.id)}
+    <li>{category.data.name ?? ''}</li>
+  {/each}
+</ul>
+```
+
+:::
+
+The list holds no empty places. A pointer that Picked cannot resolve is absent from the
+list, so each item is a record.
+
+:::note
+The Svelte helpers accept a store, and the examples pass one. Content arrives after the
+component starts. A plain value therefore holds the result at "not set".
+:::
+
+## Reference hooks
+
+| Hook | Returns | When the target is absent |
+| --- | --- | --- |
+| `useReference(value)` | `Store<Content \| null>` | `null` |
+| `useReferences(value)` | `Store<Content[]>` | The item is absent from the list. |
+| `getReference(value)` | `Store<Content \| null>` | `null` |
+| `getReferences(value)` | `Store<Content[]>` | The item is absent from the list. |
+
+Each one accepts the raw field value, or a store of it. A single value that goes to
+`useReferences()` or `getReferences()` gives a list of one.
+
+A target is absent for three reasons. Somebody deleted the entry, the entry belongs to
+another workspace, or the chain of references is deeper than the limit. See
+[About content references](/explanation/content-references).
+
+## Read a pointer directly
+
+`@picked/client` gives you the readers behind the hooks, for the code that runs outside
+React and Svelte.
+
+| Export | Returns | Description |
+| --- | --- | --- |
+| `isContentReference(value)` | `boolean` | Whether the value is a pointer. |
+| `readReferenceId(value)` | `string \| null` | The target id of a single pointer. |
+| `readReferenceIds(value)` | `string[]` | Every target id, for a repeatable field. |
+| `deriveReference(contents, value)` | `Store<Content \| null>` | The store behind `useReference` and `getReference`. |
+| `deriveReferences(contents, value)` | `Store<Content[]>` | The store behind `useReferences` and `getReferences`. |
+
+```ts
+import { createClient, readReferenceIds } from '@picked/client'
+
+const client = createClient({ projectId: 'proj_123' })
+const content = client.contents.getById('entry_789').getState()
+const categoryIds = readReferenceIds(content?.data.categories)
+```
+
+## Related
+
+- [About content references](/explanation/content-references) — why a reference is a pointer.
+- [How to read a referenced entry](/how-to/read-a-referenced-entry)
+- [Experience content endpoint](/reference/delivery-api/experience-content) — the wire shape.
+- [Server snapshot](/reference/sdk/ssr/serialize) — content on a server render.

package/dist/docs/reference/sdk/plugins/dynamic-experiences.md

@@ -9,16 +9,64 @@ This plugin reads the configuration of your project from the Picked API at runti
 therefore control your experiences, feature flags, steps, fields, and conditions from
 the [dashboard](/reference/dashboard/experiences) alone.
 
+The plugin reads the configuration of your project and the CMS content of your
+experiences from one source. It does not mix them. Picked gives a configuration and its
+content the same version.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `'bundle' \| 'api'` | see below | Where to read the configuration and the content from. |
+| `apiUrl` | `string` | `https://api.picked.app` | Your own API URL, for a self-hosted or local API. |
+| `projectConfig` | `ProjectConfig` | none | A configuration that you give. The plugin makes no request for it. |
+| `getContent` | `function` | none | A function that you give. The plugin calls it for each experience that uses CMS content. |
+
+### mode
+
+| Value | Source | Use it when |
+| --- | --- | --- |
+| `'bundle'` | The data that the [Vite plugin](/reference/tools/vite-plugin) puts in your build | You want no API request when the page loads. |
+| `'api'` | The Picked API, read when the client starts | You want a workspace publish to reach users without a new deployment. |
+
+:::code-group
+
+```ts [app.ts]
+import { createClient } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [dynamicExperiencesPlugin({ mode: 'bundle' })],
+})
+
+client.start()
+```
+
+:::
+
+If you do not set `mode`, the plugin uses the build data when the Vite plugin gave it
+some. In every other case it uses the API.
+
+### projectConfig and getContent
+
+These two replace the source for you. Keep the configuration and the content at the same
+version when you use them. The plugin cannot make that check for you.
+
 ## Preview mode
 
-After you [enter preview mode from the dashboard](/reference/dashboard/workspaces#preview), the SDK
+After you [enter preview mode from the dashboard](/how-to/preview-a-workspace), the SDK
 receives a preview token and starts preview mode:
 
-- The plugin reads fresh options from the API with that token. It bypasses the
-  build-time configuration and the cached options.
+- The plugin reads fresh options from the API with that token, for any value of `mode`.
+  It does not read the build-time configuration, a `projectConfig` that you give, or the
+  cached options.
 - A feature flag decision uses session storage. The decision resets when you close
   the tab.
 
+A `getContent` function keeps its place in a preview session, and it receives the token.
+You therefore decide what a preview means for your own content.
+
 ## Related
 
 - [About how Picked works](/explanation/how-picked-works) — how the plugin resolves your

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

@@ -26,8 +26,10 @@ const snapshot = await serialize(client, {
 `serialize()` does this. It registers the project configuration 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`.
+duplicate content blobs, which it finds by their IDs. It then returns a `PickedSnapshot`.
+
+The content that it reads holds the entries of the steps. It also holds the entries that
+a [reference field](/reference/dashboard/content/models#reference-fields) reaches.
 
 Give `serialize()` one client for each request. It does not support two calls at the
 same time on one client.
@@ -65,7 +67,7 @@ interface PickedSnapshot {
 | --- | --- |
 | `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. |
+| `content` | The content blobs for the chosen experiences, with the duplicates removed. It holds the entries of the steps, and every entry that a reference field reaches. The server render and the first paint in the browser therefore resolve the same pointers. |
 | `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. Write it into your HTML response with `JSON.stringify`
@@ -75,3 +77,4 @@ and read it back on the client.
 
 - [How to server-render a page](/how-to/server-render-a-page)
 - [How to render an unpublished preview](/how-to/render-an-unpublished-preview)
+- [Content](/reference/sdk/content) — how to read a content record in a component.