@picked/client 0.0.70 → 0.0.71-next.2

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

@@ -0,0 +1,43 @@
+---
+type: reference
+layout: docs
+---
+
+# Predicates
+
+A predicate holds reusable condition logic that reads the current state of your
+application. Each predicate is a pure function. It takes a state snapshot, and that
+snapshot holds the responses, the fields, the browser context, and optional
+arguments.
+
+## Use the state snapshot
+
+Each predicate takes a `StateSnapshot` object with these properties:
+
+```ts
+interface StateSnapshot {
+  client: Picked // The Picked client.
+  responses?: Array<{
+    // Every response from the user.
+    fieldId: string
+    value: FieldValue | undefined
+  }>
+  args?: unknown[]
+  fields?: Field[] // Every registered field.
+  location?: Location // The browser location: URL, pathname, search, and more.
+  document?: Document // The browser document object.
+  sessionStorage?: Storage // The browser sessionStorage API.
+  localStorage?: Storage // The browser localStorage API.
+}
+```
+
+:::warning
+In server-side rendering, and in any environment that is not a browser, `location`,
+`document`, `sessionStorage`, and `localStorage` are `undefined`.
+:::
+
+## Related
+
+- [How to write a predicate](/how-to/write-a-predicate)
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  why predicates exist.

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

@@ -0,0 +1,33 @@
+---
+type: reference
+layout: docs
+---
+
+# Server-Side Rendering
+
+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.
+
+## The server entry point
+
+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'
+```
+
+Go to [Server Snapshot](/reference/sdk/ssr/serialize) for the `serialize()` reference. Go to
+[Rendering and Hydration](/reference/sdk/ssr/rendering-and-hydration) to connect React and
+Svelte. Go to [Slots and Placements](/reference/sdk/ssr/slots-and-placements) for how a slot
+chooses an experience. If the SDK is new to you, read
+[Installation](/reference/sdk) first.
+
+## Related
+
+- [About server-side rendering](/explanation/why-server-side-rendering) — why the snapshot
+  exists.
+- [How to server-render a page](/how-to/server-render-a-page)
+- [Server snapshot](/reference/sdk/ssr/serialize)

package/dist/docs/{sdk → reference/sdk}/ssr/rendering-and-hydration.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -46,13 +47,6 @@ top of the `<script>` block of a component. It takes the same two modes,
 <ExperienceSlot name="page" />
 ```
 
-## Place the slot
-
-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.
-
 ## Render the page component
 
 The SDK does not connect content to a component. You own the component that a Page
@@ -103,60 +97,7 @@ export function CMSPage() {
 while no content is registered. `getStepContent()` returns a store, and you read it
 with `$content`.
 
-## Full example
-
-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
-
-```tsx [React]
-import type { CreateClientOptions } from '@picked/client'
-import type { PickedSnapshot } from '@picked/client/server'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-import { CMSPage } from './CMSPage'
-
-const options = {
-  projectId: 'sdk-cvly-x',
-  components: { CMSPage: adaptReactComponent(CMSPage) },
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-} satisfies CreateClientOptions
-
-export function PageSlot({ snapshot }: { snapshot?: PickedSnapshot }) {
-  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 options = {
-    projectId: 'sdk-cvly-x',
-    components: { CMSPage: adaptSvelteComponent(CMSPage) },
-    plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-  } satisfies CreateClientOptions
-
-  setPickedContext({ options })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-:::
+## Related
 
-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).
+- [How to server-render a page](/how-to/server-render-a-page) — the full example.
+- [Slots and placements](/reference/sdk/ssr/slots-and-placements)

package/dist/docs/{sdk → reference/sdk}/ssr/serialize.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -22,7 +23,7 @@ const snapshot = await serialize(client, {
 })
 ```
 
-`serialize()` does this. It registers the project options on the client at once. It
+`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
@@ -39,7 +40,7 @@ serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `projectConfig` | `ProjectConfig` | required | The published options, or the preview options, to register and choose against. |
+| `projectConfig` | `ProjectConfig` | required | The published configuration, or the preview configuration, 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. |
@@ -70,35 +71,7 @@ interface PickedSnapshot {
 The snapshot is plain JSON. Write it into your HTML response with `JSON.stringify`
 and read it back on the client.
 
-## Pass the snapshot to the client
+## Related
 
-Embed the snapshot in your HTML payload. Then give it to the provider in React, or to
-the context in Svelte:
-
-```ts
-const html = `
-  <div id="root">${appHtml}</div>
-  <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
-`
-```
-
-On the client, read `window.__PICKED__` and pass it as the `snapshot` prop. See
-[Rendering and Hydration](/sdk/ssr/rendering-and-hydration).
-
-## Render a preview
-
-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, {
-  projectConfig,
-  attributes: { location: { pathname: '/promo' } },
-  previewToken,
-})
-```
-
-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.
+- [How to server-render a page](/how-to/server-render-a-page)
+- [How to render an unpublished preview](/how-to/render-an-unpublished-preview)

package/dist/docs/{sdk → reference/sdk}/ssr/slots-and-placements.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -50,4 +51,9 @@ experience is among the active ones, only that experience renders. With no activ
 
 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).
+experiences are active. See [Conditions](/reference/dashboard/conditions).
+
+## Related
+
+- [About server-side rendering](/explanation/why-server-side-rendering) — why placements
+  have an order.

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

@@ -0,0 +1,87 @@
+---
+type: reference
+layout: docs
+---
+
+# Steps
+
+Render your steps with `<StepRouter>` and `<Step>` from `@picked/react` or
+`@picked/svelte`. Reach the active step through `useStep()` or `getStep()`.
+
+## Reach the step 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
+
+```tsx [React]
+import { useStep } from '@picked/react/hooks'
+import { useUnit } from 'effector-react'
+
+function ContactForm() {
+  const { step, fields } = useStep()
+  const currentStep = useUnit(step)
+  const currentFields = useUnit(fields)
+
+  return (
+    <>
+      <h1>{currentStep.label}</h1>
+
+      {currentFields.map((field) => (
+        <div key={field.id}>
+          <label>{field.label}</label>
+          <input
+            name={field.id}
+            value={field.value ?? ''}
+            onChange={field.onChange}
+            onBlur={field.onBlur}
+          />
+          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
+        </div>
+      ))}
+    </>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStep } from '@picked/svelte/hooks'
+
+  const { step, fields } = getStep()
+</script>
+
+<h1>{$step.label}</h1>
+
+{#each $fields as field}
+  <label>{field.label}</label>
+  <input
+    name={field.id}
+    value={field.value ?? ''}
+    onchange={field.onChange}
+    onblur={field.onBlur}
+  />
+  {#if field.error && field.touched}
+    <p class="error">{field.error.userMessage}</p>
+  {/if}
+{/each}
+```
+
+:::
+
+`getStep()` in Svelte, and `useStep()` in React, return a `StepContext` with these
+properties:
+
+| Property   | Type                                          | Description                                                                    |
+| ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
+| `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).                        |
+
+## Related
+
+- [How to render a step form](/how-to/render-a-step-form)
+- [How to run code on a form submission](/how-to/run-code-on-a-form-submission)
+- [About how Picked works](/explanation/how-picked-works) — why a flow is a graph.

package/dist/docs/reference/tools/chrome-extension.md

@@ -0,0 +1,16 @@
+---
+type: reference
+layout: docs
+---
+
+# Chrome Extension
+
+The extension for the Picked Developer Tools adds a Picked panel to Chrome DevTools.
+Use the panel to check and debug your Picked integration on any page that runs the
+SDK.
+
+![Picked Developer Tools](/chrome-extension-screenshot.jpg)
+
+## Related
+
+- [How to debug with the Chrome extension](/how-to/debug-with-the-chrome-extension)

package/dist/docs/{image-optimisation-service.md → reference/tools/image-optimisation-service.md}

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -94,3 +95,10 @@ that time.
   (`default-src *; script-src 'none'; sandbox;`). A compromised source therefore
   cannot run a script in the browser that shows the image.
 - The response uses `Content-Disposition: inline`, and never `attachment`.
+
+## Related
+
+- [Asset library](/reference/dashboard/content/asset-library) — where the images come
+  from.
+- [Content Security Policy](/reference/sdk/content-security-policy) — the `img-src`
+  entry this service needs.

package/dist/docs/{mcp.md → reference/tools/mcp.md}

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -7,51 +8,6 @@ layout: docs
 Control your Picked workspace from an AI tool that writes code, with the Model
 Context Protocol (MCP).
 
-## Connect
-
-The server URL is `https://api.picked.app/mcp`.
-
-### Claude Desktop
-
-1. Open **Settings > Connectors > Add custom connector**.
-2. Set **Name** to `Picked` and **URL** to `https://api.picked.app/mcp`.
-3. Click **Connect** and answer the authorization prompt.
-
-### Project configuration in `.mcp.json`
-
-Add this file to the root of your repository. It works with Claude Code, Cursor,
-Windsurf, and other tools that support MCP.
-
-:::code-group
-
-```json [.mcp.json]
-{
-  "mcpServers": {
-    "picked": {
-      "type": "http",
-      "url": "https://api.picked.app/mcp"
-    }
-  }
-}
-```
-
-:::
-
-### Cursor
-
-Add this file to `.cursor/mcp.json` in the root of your project:
-
-```json
-{
-  "mcpServers": {
-    "picked": {
-      "type": "http",
-      "url": "https://api.picked.app/mcp"
-    }
-  }
-}
-```
-
 ## Tools
 
 ### Discovery
@@ -126,3 +82,7 @@ functions, and the dimension columns before you write a query.
   is correct.
 - Ask your agent to run a PickedQL query on your analytics data. The agent can read
   the schema, write the SQL, and explain the rows.
+
+## Related
+
+- [How to connect the MCP server](/how-to/connect-the-mcp-server)

package/dist/docs/{vite-plugin.md → reference/tools/vite-plugin.md}

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -10,52 +11,17 @@ option, so the SDK makes no API request at runtime. In development it also serve
 launcher page. On that page you can see a preview of an experience with your own
 feature flag values.
 
-## Installation
-
-:::code-group
-
-```bash [npm]
-npm install @picked/vite-plugin-picked
-```
-
-```bash [pnpm]
-pnpm add @picked/vite-plugin-picked
-```
-
-```bash [yarn]
-yarn add @picked/vite-plugin-picked
-```
-
-:::
-
-## Setup
-
-Add the plugin to your `vite.config.ts`:
-
-```typescript
-import { defineConfig } from 'vite'
-import { picked } from '@picked/vite-plugin-picked'
-
-export default defineConfig({
-  plugins: [
-    picked({
-      projectId: 'your-project-id',
-    }),
-  ],
-})
-```
-
 ## How it works
 
 ### Build-time config injection
 
 When Vite starts, in both `dev` and `build`, the plugin does this:
 
-1. It reads the options of your project from the Picked API.
+1. It reads the configuration of your project from the Picked API.
 2. It embeds those options in your bundle.
-3. The SDK reads the embedded options at runtime and makes no network request.
+3. The SDK reads the embedded configuration at runtime and makes no network request.
 
-When a preview token is there at runtime, the SDK ignores the embedded options and
+When a preview token is there at runtime, the SDK ignores the embedded configuration and
 reads fresh data from the API.
 
 ### Dev launcher
@@ -87,3 +53,7 @@ After the dev server starts, the launcher URL appears next to the Vite output:
 For a production build, `vite build`, the plugin writes an `index.html` file that
 holds the launcher page. Set `disableLauncher` to stop this. The file lets you deploy
 the launcher next to your application, so that a stakeholder can see a preview.
+
+## Related
+
+- [How to install the Vite plugin](/how-to/install-the-vite-plugin)

package/dist/docs/{api/index.md → tutorials/first-api-call.md}

@@ -1,16 +1,24 @@
 ---
+type: tutorial
 layout: docs
 ---
 
-# Start here
+# Your first API call
 
-This guide takes you through your first calls to the Picked GraphQL API. It starts
-with a ping and ends with an authenticated query and mutation.
+In this tutorial we make your first calls to the Picked management API. We start with a
+ping, then authenticate, then read your user and make an organization.
+
+At the end you have an access token and two answers from the API.
+
+## Before you start
+
+- A Picked account, with an email address and a password.
+- `curl`, or any HTTP client.
 
 :::note
-This reference covers the GraphQL API that needs authentication. To serve your
-published options and page content to your application, use the public
-[Delivery API](/delivery-api), which is read-only.
+This tutorial covers the GraphQL management API, which needs authentication. To serve
+published configuration and page content to your application, use the read-only
+[Delivery API](/reference/delivery-api) instead.
 :::
 
 ## Playground
@@ -107,10 +115,10 @@ A successful response returns a `Session` with an `accessToken` and a
 ```
 
 When `requiresMfa` is `true`, you must complete the MFA challenge before you receive
-a session. See the [Authentication](./authentication.md) guide.
+a session. See the [Authentication](/reference/management-api/authentication) guide.
 
 For a server-to-server integration, use
-[API key authentication](/api/authentication#api-key-authentication) and not a
+[API key authentication](/reference/management-api/authentication#api-key-authentication) and not a
 session token.
 
 ## Make an authenticated query
@@ -202,15 +210,19 @@ When something goes wrong, the API returns the errors in the standard GraphQL
 ```
 
 Read the `extensions.code` field. It holds an error code that your code can act on.
-See the [Errors](./error-handling.md) guide for the full list of codes.
+See the [Errors](/reference/management-api/error-handling) guide for the full list of codes.
+
+## What you built
 
-## Next steps
+You authenticated against the management API, read your own user, and created an
+organization. Every other operation follows the same shape: a `POST` to one endpoint,
+with your token in the `Authorization` header.
 
-You can now authenticate and make a request. These guides go into more detail:
+## Where to go next
 
-- [Authentication](./authentication.md) — an email address and a password, OAuth,
+- [Authentication](/reference/management-api/authentication) — an email address and a password, OAuth,
   magic links, MFA, API keys, and how to control a session.
-- [Authorization and Scopes](./authorization-and-scopes.md) — what each role can
+- [Authorization and Scopes](/reference/management-api/authorization-and-scopes) — what each role can
   reach, and how a scope controls a permission.
-- [Pagination](./pagination.md) — how to move through a large result with a cursor.
-- [Errors](./error-handling.md) — every error code that the API can return.
+- [Pagination](/reference/management-api/pagination) — how to move through a large result with a cursor.
+- [Errors](/reference/management-api/error-handling) — every error code that the API can return.