@picked/client 0.0.64-next.3 → 0.0.64-next.5

package/dist/docs/content/pages.mdx

@@ -0,0 +1,67 @@
+---
+layout: docs
+---
+
+import { Screenshot } from '../../../components/Screenshot'
+
+# Pages
+
+A Page is a standalone, server-rendered experience backed by CMS content, built for SEO-critical landing pages.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences"
+  alt="The experiences list, where Pages and Flows are created on the Picked dashboard"
+/>
+
+## Pages vs flows
+
+Picked has two kinds of experience:
+
+| Experience | What it is | Use it for |
+| --- | --- | --- |
+| **Page** | A standalone experience rendered on your server, backed by a Content Entry. | SEO-critical landing pages, campaign pages, content the crawler must see. |
+| **Flow** | A multi-step, interactive experience rendered in the browser. | Quizzes, surveys, product finders, multi-step onboarding. |
+
+Reach for a **Page** when the content must appear in the server HTML for search engines and social unfurls. Reach for a **Flow** when the value is in the interaction, and client-side rendering is fine. See [Experiences](/experiences) for the wider model.
+
+## How a page fits together
+
+Four pieces back every Page:
+
+1. A **Page Layout** defines the shape: the fields a page can hold. See [Page & Step Layouts](/content/layouts).
+2. A **Content Entry** fills that shape with real data. See [Content Entries](/content/content-entries).
+3. A **Page** binds one entry so the SDK can render it.
+4. The **SDK** fetches the entry and renders it on your server. See [Server-Side Rendering](/sdk/ssr).
+
+A layout defines the shape, a content entry fills it with data, a Page binds an entry so the SDK can render it. Step Layouts do the same for individual Steps inside a Flow.
+
+```
+Author (dashboard) -> Publish -> Delivery API (config + content)
+  -> serialize() on server -> Provider seeds client -> ExperienceSlot renders -> hydrate
+```
+
+## Create a page
+
+1. Open your project and select a workspace.
+2. Click **Experiences** in the sidebar.
+3. Click **New Experience** and choose the **Page** type.
+4. Pick a **Page Layout**. The layout determines which fields the page holds.
+5. Click **Create**.
+
+A Content Entry is created and linked to the page on its first save, so the page always has somewhere to store its data.
+
+## Edit page content
+
+The Page editor has a **Properties** tab for the page's content and a **Settings** tab for its name, condition, and layout. Fill in the fields on the **Properties** tab. The inspector on the right edits the selected field, and the preview panel shows the page as it fills in.
+
+## Change or remove the layout
+
+Use the change-layout control on the **Settings** tab to switch the page to a different Page Layout. Unlinking a layout detaches the Content Entry from the page. The entry is not deleted, but the page no longer has content to render until you bind a layout again.
+
+## Validate and publish
+
+Invalid fields surface inline as per-field errors while you edit, so you can fix them before publishing. When the page is valid, publish the workspace to make it live. Publishing produces the version the Delivery API serves to anonymous readers.
+
+## Render a page
+
+A published Page is rendered by the SDK on your server. See the [Build a Personalized Page](/guides/build-a-personalized-page) guide for the end-to-end walkthrough, and [Server-Side Rendering](/sdk/ssr) for the SDK reference.

package/dist/docs/content/sections.mdx

@@ -0,0 +1,33 @@
+---
+layout: docs
+---
+
+import { Screenshot } from '../../../components/Screenshot'
+
+# Sections
+
+Sections are reusable schema fragments you embed inside layouts, so common structures such as a hero or a feature list are defined once.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/blocks"
+  alt="The sections list in the schema builder on the Picked dashboard"
+/>
+
+## What a section is
+
+A Section is a reusable fragment of schema with its own **Key**. Where a [layout](/content/layouts) backs a whole Page or Step, a Section is a piece you compose into one or more layouts. Define the shape once, reuse it everywhere.
+
+## Create a section
+
+1. Open your workspace and click **Sections** in the sidebar.
+2. Click **New Section**.
+3. Enter a name and a **Key**. The Key is a unique, stable identifier used in SDK code and API references.
+4. Add fields and save.
+
+## Use a section in a layout
+
+Add a **Section** field to a Page or Step Layout and point it at the Section you want to embed. The layout then carries the Section's fields wherever that field appears. A Content Entry built from the layout fills the Section's fields like any others.
+
+## Changing a section
+
+Editing a Section does not automatically migrate the entries that already use it. After changing a Section, revalidate the affected [Content Entries](/content/content-entries) and resolve any per-field errors before publishing.

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

@@ -0,0 +1,85 @@
+---
+layout: docs
+---
+
+# Experience Content Endpoint
+
+Fetch the Content Entries that back a single experience's steps.
+
+## Request
+
+```
+GET /api/v1/projects/:projectId/experiences/:id/content
+```
+
+| Parameter | In | Description |
+| --- | --- | --- |
+| `projectId` | path | The project the experience belongs to. |
+| `id` | path | The experience to fetch content for. |
+| `preview_token` | query | Optional. Returns preview (unpublished) content when present. |
+
+## Response
+
+```json
+{
+  "experienceId": "exp_123",
+  "versionId": "ver_456",
+  "content": [
+    {
+      "id": "entry_789",
+      "contentModelKey": "page-hero",
+      "data": { "title": "Spring sale", "body": "..." }
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `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, matching the layout schema. |
+
+## HTML asset inlining
+
+When the layout has an [HTML asset](/content/asset-library) field, its value arrives inlined. The reference is rewritten to `{ id, content }`, where `content` is the uploaded HTML as a string (or `null` when it cannot be resolved):
+
+```json
+{
+  "id": "entry_789",
+  "contentModelKey": "page-hero",
+  "data": {
+    "markup": { "id": "asset_42", "content": "<section>...</section>" }
+  }
+}
+```
+
+The SDK renders the inlined HTML directly, with no extra storage fetch.
+
+## Status codes
+
+| Code | Meaning |
+| --- | --- |
+| `200` | Success. |
+| `401` | Invalid `preview_token`. |
+| `404` | The experience has no published content. |
+
+## Example
+
+```bash
+curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
+```
+
+```json
+{
+  "experienceId": "exp_123",
+  "versionId": "ver_456",
+  "content": [
+    { "id": "entry_789", "contentModelKey": "page-hero", "data": { "title": "Spring sale" } }
+  ]
+}
+```
+
+See [Project Config](/delivery-api/project-config) for the endpoint that links steps to entries, [Asset Library](/content/asset-library) for HTML assets, and [Server Snapshot](/sdk/ssr/serialize) for how the SDK consumes this content.

package/dist/docs/delivery-api/index.md

@@ -0,0 +1,46 @@
+---
+layout: docs
+---
+
+# Delivery API
+
+The Delivery API is a public, read-only REST API that serves your published project config and page content. It is separate from the GraphQL management API.
+
+## Delivery API vs the management API
+
+Picked has two HTTP APIs. Use the one that fits the job:
+
+| | Delivery API | Management API |
+| --- | --- | --- |
+| Style | REST | GraphQL |
+| Access | Public, anonymous | Authenticated |
+| Operations | Read-only | Read and write |
+| Use for | Serving published config and content to your app | Managing projects, experiences, and content |
+
+The management API is documented under [API Reference](/api). This section covers the Delivery API.
+
+## Base URL and versioning
+
+All Delivery API routes are versioned under `/api/v1`:
+
+```
+https://api.picked.app/api/v1
+```
+
+## Published vs preview
+
+Each endpoint serves two surfaces:
+
+- **Published** content is anonymous. Anyone can read your published config and content.
+- **Preview** content is gated by a `preview_token` query parameter, so you can render unpublished drafts before going live.
+
+A workspace's preview token is available as the `previewToken` field on the workspace in the management API, and the dashboard preview action issues one for you.
+
+## Endpoints
+
+| Endpoint | Description |
+| --- | --- |
+| [Project Config](/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published project config, including each step's content link. |
+| [Experience Content](/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries that back an experience. |
+
+For the operational details shared by both endpoints, see [Preview, Caching & Crawling](/delivery-api/preview-caching-crawling).

package/dist/docs/delivery-api/preview-caching-crawling.md

@@ -0,0 +1,59 @@
+---
+layout: docs
+---
+
+# Preview, Caching & Crawling
+
+The operational surface shared by both Delivery API endpoints: preview tokens, caching, CORS, and crawling.
+
+## Preview tokens
+
+Pass `?preview_token=<token>` to read unpublished content. Both endpoints accept it, and both return `versionId: null` on the preview surface. An invalid token returns `401`.
+
+```bash
+curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
+```
+
+A workspace's preview token is available as the `previewToken` field on the workspace in the [management API](/api), and the dashboard preview action issues one for you. Use the same token for the project config and the experience content requests so both come from the same preview surface.
+
+## Caching
+
+Caching depends on the surface and the requesting client. The SDK sends a `Picked-Client: sdk` request header:
+
+| Request | `Cache-Control` |
+| --- | --- |
+| Published, `Picked-Client: sdk` | `public, s-maxage=60, stale-while-revalidate=86400` |
+| Published, other clients | `private, no-store` |
+| Preview | `no-store` |
+
+Cacheable published responses also send `Vary: Picked-Client`, so a shared cache keys on the client header and never serves an SDK-cached body to a non-SDK request.
+
+## CORS
+
+Both endpoints are cross-origin readable. An `OPTIONS` preflight returns `204` with the CORS headers:
+
+| Header | Value |
+| --- | --- |
+| `Access-Control-Allow-Origin` | `*` |
+| `Access-Control-Allow-Methods` | `GET, OPTIONS` |
+| `Access-Control-Allow-Headers` | `Content-Type, Picked-Client, Picked-Version, traceparent, tracestate` |
+
+## Crawling and SEO
+
+Both endpoints are crawlable so search engines can read your published content. Preview URLs are disallowed, so drafts never reach the index. The `robots.txt` rules:
+
+```
+User-agent: *
+
+# Allow crawling of the public project config and experience content endpoints
+Allow: /api/v1/projects
+Allow: /api/v1/projects/*/experiences/*/content
+
+# Keep preview (draft) responses out of crawlers
+Disallow: /api/v1/projects/*preview_token=
+
+# Everything else (GraphQL, MCP, internal, ping) stays disallowed
+Disallow: /
+```
+
+See [Project Config](/delivery-api/project-config) and [Experience Content](/delivery-api/experience-content) for the endpoints themselves.

package/dist/docs/delivery-api/project-config.md

@@ -0,0 +1,56 @@
+---
+layout: docs
+---
+
+# Project Config Endpoint
+
+Fetch a project's published configuration: its experiences, steps, and the link from each step to the Content Entry that backs it.
+
+## Request
+
+```
+GET /api/v1/projects/:projectId
+```
+
+| Parameter | In | Description |
+| --- | --- | --- |
+| `projectId` | path | The project to fetch config for. |
+| `preview_token` | query | Optional. Returns the preview (unpublished) config when present. |
+
+## Response
+
+The response carries the project's experiences and steps. Each step includes `layoutContentId`, the reference to the Content Entry that backs that step's layout. Use it to know which experiences have content to fetch from the [Experience Content](/delivery-api/experience-content) endpoint.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The project id. |
+| `versionId` | `string \| null` | The published version id, or `null` on preview. |
+| `steps[].layoutContentId` | `string \| null` | The Content Entry backing this step, or `null` when the step has no content. |
+
+## Published vs preview
+
+On the published surface, `versionId` is the published version id. On the preview surface (`?preview_token=...`), `versionId` is `null` because there is no published version. See [Preview, Caching & Crawling](/delivery-api/preview-caching-crawling).
+
+## Example
+
+```bash
+curl https://api.picked.app/api/v1/projects/proj_123
+```
+
+```json
+{
+  "id": "proj_123",
+  "versionId": "ver_456",
+  "steps": [
+    {
+      "id": "step_1",
+      "key": "hero",
+      "name": "Hero",
+      "layoutName": "HeroLayout",
+      "layoutContentId": "entry_789"
+    }
+  ]
+}
+```
+
+Pass the config to `serialize()` on your server to produce an SSR snapshot. See [Server Snapshot](/sdk/ssr/serialize).

package/dist/docs/experiences.mdx

@@ -6,7 +6,9 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Experiences
 
-An experience is a personalized UI flow delivered to visitors on your site. Each experience maps to a component registered in your application.
+An experience is a personalized experience delivered to visitors on your site. Each experience maps to a component registered in your application.
+
+Picked has two kinds of experience. A **Flow** is a multi-step, interactive experience rendered in the browser, covered on this page. A **Page** is a standalone, server-rendered experience backed by CMS content, built for SEO-critical landing pages. See [Pages](/content/pages) for that kind.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences"

package/dist/docs/fields.mdx

@@ -8,6 +8,8 @@ import { Screenshot } from '../../components/Screenshot'
 
 A field is a data input shown to visitors inside a step. Fields collect information like names, email addresses, preferences, or selections.
 
+These are experience Fields, which collect visitor input. They are distinct from the Content Fields that make up a CMS layout's schema, covered in [Page & Step Layouts](/content/layouts).
+
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
   alt="The fields list for a workspace on the Picked dashboard"

package/dist/docs/guides/build-a-personalized-page.mdx

@@ -0,0 +1,143 @@
+---
+layout: docs
+---
+
+import { Screenshot } from '../../../components/Screenshot'
+
+# Build a Personalized Page
+
+Build a personalized landing page with Picked: model it in the dashboard, publish it, and render it server-side in your app.
+
+## What you will build
+
+A standalone, SEO-critical landing page whose content lives in Picked's CMS and renders on your server. You model the page's shape once, fill it with content, publish it, then fetch and render it in React or Svelte. The lifecycle from authoring to a hydrated page:
+
+```
+Author (dashboard) -> Publish -> Delivery API (config + content)
+  -> serialize() on server -> Provider seeds client -> ExperienceSlot renders -> hydrate
+```
+
+## Model a page layout
+
+A [Page Layout](/content/layouts) defines the fields your page can hold.
+
+1. Open your workspace and click **Models** in the sidebar.
+2. Click **New Model** and choose **Page Layout**.
+3. Enter a name and a **Key**, for example `page-hero`. The Key is a unique, stable identifier you use in SDK code and API references.
+4. Add a few fields: a **Single-line text** field `title`, a **Markdown** field `body`, and an **Asset** field `image`.
+5. Save the layout.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
+  alt="A page layout in the schema builder on the Picked dashboard"
+/>
+
+See [Page & Step Layouts](/content/layouts) for every field type.
+
+## Create and fill the page
+
+1. Click **Experiences** in the sidebar, then **New Experience**.
+2. Choose the **Page** type and pick your `page-hero` layout.
+3. On the **Properties** tab, fill in `title`, `body`, and `image`. A [Content Entry](/content/content-entries) is created and linked on first save.
+4. Fix any per-field validation errors.
+5. Publish the workspace to make the page live.
+
+See [Pages](/content/pages) for the full editor reference.
+
+## Fetch the config and content
+
+Your server fetches two things from the [Delivery API](/delivery-api): the project config (which experiences and steps exist) and the content for the matching experience.
+
+```bash
+# 1. Project config: find the steps and their content links
+curl https://api.picked.app/api/v1/projects/proj_123
+
+# 2. Experience content: the entry data backing the page
+curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
+```
+
+In practice you fetch the config, then let `serialize()` fetch the content for you. See [Project Config](/delivery-api/project-config) and [Experience Content](/delivery-api/experience-content).
+
+## Render server-side and hydrate
+
+On the server, create a per-request client, call `serialize()` to produce a snapshot, render your app, and embed the snapshot. On the client, seed from the snapshot and hydrate.
+
+```ts
+// server.ts
+import { createClient } from '@picked/client'
+import { serialize } from '@picked/client/server'
+
+const client = createClient(options)
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: url.pathname } },
+})
+// Render your app, then embed `snapshot` in the HTML response.
+```
+
+Render `<ExperienceSlot name="page" />` inside the provider, and register the component the Page maps to (here, `CMSPage`):
+
+:::code-group
+
+```tsx [React]
+import type { CreateClientOptions } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
+import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
+import { useStepContent } from '@picked/react/hooks'
+
+function CMSPage() {
+  const content = useStepContent()
+  const title = typeof content?.title === 'string' ? content.title : ''
+  return <h1>{title}</h1>
+}
+
+const options = {
+  projectId: 'proj_123',
+  components: { CMSPage: adaptReactComponent(CMSPage) },
+  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+} satisfies CreateClientOptions
+
+export function Page({ snapshot }) {
+  return (
+    <PickedProvider options={options} snapshot={snapshot}>
+      <ExperienceSlot name="page" />
+    </PickedProvider>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import type { CreateClientOptions } from '@picked/client'
+  import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+  import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
+  import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
+  import CMSPage from './CMSPage.svelte'
+
+  const { snapshot } = $props()
+
+  const options = {
+    projectId: 'proj_123',
+    components: { CMSPage: adaptSvelteComponent(CMSPage) },
+    plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
+  } satisfies CreateClientOptions
+
+  setPickedContext({ options, snapshot })
+</script>
+
+<ExperienceSlot name="page" />
+```
+
+:::
+
+The provider seeds synchronously, so the server HTML and the client's first paint match, then the SDK hydrates. See [Server-Side Rendering](/sdk/ssr) for the full reference.
+
+## Verify SEO
+
+Confirm the page is crawlable end to end:
+
+1. View the server response (for example with `curl` or your browser's view-source) and check the rendered HTML contains your `title` and `body`, not an empty shell.
+2. Confirm the content endpoint is reachable anonymously and returns your entry data.
+
+Published Delivery API responses are crawlable; preview URLs are disallowed. See [Preview, Caching & Crawling](/delivery-api/preview-caching-crawling).

package/dist/docs/sdk/experiences.md

@@ -6,6 +6,8 @@ layout: docs
 
 Define experiences in code with `createExperience()`, or load them from the dashboard at runtime with the [Dynamic Experiences Plugin](./plugins/dynamic-experiences).
 
+The execution flow below targets a DOM selector and renders into it. A Page experience instead renders through a named slot: target it to `.picked-slot-<name>` and render `<ExperienceSlot name="<name>" />` on your server. Use the slot path for SEO-critical, server-rendered Pages; use the selector path for browser-rendered Flows. See [Server-Side Rendering](/sdk/ssr) and [Slots & Placements](/sdk/ssr/slots-and-placements).
+
 ## Creating experiences
 
 ```ts

package/dist/docs/sdk/index.md

@@ -28,11 +28,21 @@ picked.init()
 ```
 
 ```ts [Server]
-Coming Soon...
+import { createClient } from '@picked/client'
+import { serialize } from '@picked/client/server'
+
+const client = createClient({ projectId: 'your-project-id' })
+
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: '/promo' } },
+})
 ```
 
 :::
 
+The `@picked/client/server` entry holds the server-only helpers, such as `serialize()`, that produce an SSR snapshot. It is a separate entry point so browser bundles never include it. See [Server-Side Rendering](/sdk/ssr).
+
 :::tip
 If you’re running Picked in a browser environment, access the Picked client in the console with `window.Picked`
 :::

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

@@ -0,0 +1,62 @@
+---
+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.
+
+## 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 flow
+
+```
+projectConfig (Delivery API)
+  -> serialize(client, params) on the server -> PickedSnapshot
+  -> embed snapshot in HTML
+  -> client seeds from snapshot -> renders the same markup -> hydrates
+```
+
+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).
+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).
+
+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.
+
+## React vs Svelte at a glance
+
+:::code-group
+
+```tsx [React]
+import { PickedProvider, ExperienceSlot } from '@picked/react'
+
+<PickedProvider options={options} snapshot={snapshot}>
+  <ExperienceSlot name="page" />
+</PickedProvider>
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
+
+  setPickedContext({ options, snapshot })
+</script>
+
+<ExperienceSlot name="page" />
+```
+
+:::
+
+## The server entry point
+
+The server helpers live in a dedicated entry so browser bundles never pull them in:
+
+```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).