@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785908062293

package/dist/docs/sdk/predicates.md

@@ -1,112 +0,0 @@
----
-layout: docs
----
-
-# Predicates
-
-Predicates enable reusable condition logic based on current application state. Each predicate is a pure function that receives a state snapshot containing responses, fields, browser context, and optional arguments.
-
-## Defining Predicates
-
-Define predicates when creating the Picked client by passing a `predicates` object. Each predicate requires a unique identifier and a function that receives a state snapshot:
-
-```ts
-import { createClient } from '@picked/client'
-
-const client = createClient({
-  projectId: 'your-project-id',
-  predicates: {
-    'is-example-page': ({ location }) => {
-      return location?.pathname === '/example'
-    },
-    'get-account-tier': async () => {
-      const data = await fetch('/api/get-account-tier').then((r) => r.json())
-      return data.result // returns "trial"
-    },
-  },
-})
-```
-
-## How Predicates Work
-
-When a predicate is registered and used in conditions, the SDK follows this execution flow:
-
-1. **Registration**: Predicates are registered to the Picked client during initialization
-2. **State Snapshot Creation**: When invoked, predicates receive a frozen state snapshot containing current responses, fields, and browser context
-3. **Condition Evaluation**: Experience conditions invoke predicates with a fresh snapshot whenever called
-4. **Return Flexibility**: Predicates can return boolean, string, string array, undefined, or promises that resolve to these types
-
-## Using Predicates in Conditions
-
-Predicates are most commonly used within condition logic via the `invoke` operator:
-
-```ts
-const myExperience = createExperience({
-  // ... other config
-  condition: {
-    and: [
-      {
-        '==': [
-          {
-            invoke: {
-              var: 'predicates.is-example-page', // Reference predicate that calls user endpoint
-            },
-          },
-          true, // Check if return value is true
-        ],
-      },
-      {
-        '==': [
-          {
-            invoke: {
-              var: 'predicates.account-tier',
-            },
-          },
-          '/trial', // If string matches, evaluate to true
-        ],
-      },
-    ],
-  },
-})
-```
-
-:::tip
-Predicates can also be used in `validation` logic
-:::
-
-## Using the State Snapshot
-
-Each predicate receives a `StateSnapshot` object with the following properties:
-
-```ts
-interface StateSnapshot {
-  client: Picked // The Picked client instance
-  responses?: Array<{
-    // All user responses
-    fieldId: string
-    value: FieldValue | undefined
-  }>
-  args?: unknown[]
-  fields?: Field[] // All registered fields
-  location?: Location // Browser location (URL, pathname, search, etc.)
-  document?: Document // Browser document object
-  sessionStorage?: Storage // Browser sessionStorage API
-  localStorage?: Storage // Browser localStorage API
-}
-```
-
-:::warning
-In server-side rendering or non-browser environments, `location`, `document`, `sessionStorage`,
-and `localStorage` will be `undefined`.
-:::
-
-## Best Practices
-
-- **Keep predicates pure**: Predicates should be deterministic and side-effect free. Given the same snapshot, they should always return the same result
-- **Handle missing data gracefully**: Always check if responses or fields exist before accessing their values. Return `undefined` when data is unavailable rather than throwing errors
-- **Avoid heavy computations**: Predicates may be invoked frequently. Keep logic lightweight and fast
-- **Use async sparingly**: While async predicates are supported, they can delay experience rendering. Prefer synchronous logic when possible
-- **Return consistent types**: Don't mix return types (e.g., sometimes boolean, sometimes string) for the same predicate
-- **Use meaningful names**: Predicate IDs should clearly describe what they evaluate (e.g., `is-premium-user`, `has-items-in-cart`)
-- **Consider caching expensive operations**: If a predicate needs to perform expensive operations, consider caching the result in `localStorage` or `sessionStorage` within the predicate logic
-- **Don't mutate the snapshot**: The state snapshot is frozen. Any attempt to modify it will throw an error in strict mode

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

@@ -1,62 +0,0 @@
----
-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).

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

@@ -1,141 +0,0 @@
----
-layout: docs
----
-
-# Rendering & Hydration
-
-Seed a Picked client from the server snapshot, render your slots, and hydrate. React and Svelte below.
-
-## React: PickedProvider
-
-`PickedProvider` supplies a client to descendant components. Its props are a union of two construction 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. |
-
-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.
-
-```tsx
-import { PickedProvider, ExperienceSlot } from '@picked/react'
-
-<PickedProvider options={options} snapshot={snapshot}>
-  <ExperienceSlot name="page" />
-</PickedProvider>
-```
-
-## 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.
-
-```svelte
-<script lang="ts">
-  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-## Placing 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.
-
-## Rendering 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.
-
-:::code-group
-
-```tsx [React]
-import { useStepContent } from '@picked/react/hooks'
-
-export function CMSPage() {
-  const content = useStepContent()
-  if (!content) {
-    return <p>Loading page content…</p>
-  }
-
-  const title = typeof content.title === 'string' ? content.title : ''
-  return (
-    <article>
-      <h1>{title}</h1>
-    </article>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-</script>
-
-{#if $content}
-  <article>
-    <h1>{typeof $content.title === 'string' ? $content.title : ''}</h1>
-  </article>
-{:else}
-  <p>Loading page content…</p>
-{/if}
-```
-
-:::
-
-`useStepContent()` returns the entry's `data` object directly, or `null` while no content is registered. `getStepContent()` returns a store you read 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.
-
-:::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" />
-```
-
-:::
-
-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).

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

@@ -1,86 +0,0 @@
----
-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(client, params)
-
-```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: '/promo' } },
-})
-```
-
-`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.
-
-```ts
-serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
-```
-
-## Parameters
-
-| 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. |
-
-`SerializeLocation` carries the plain URL fields `href`, `pathname`, `search`, `hostname`, `origin`, `protocol`, `port`, `host`, and `hash`. Pass only the ones your conditions read.
-
-## The snapshot
-
-```ts
-interface PickedSnapshot {
-  versionId: string | null
-  projectConfig: ProjectConfig
-  content: ContentBlob[]
-  conditionResults: Record<string, boolean>
-}
-```
-
-| 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. |
-
-The snapshot is plain JSON. Serialize it into your HTML response with `JSON.stringify` and read it back on the client.
-
-## Passing the snapshot to the client
-
-Embed the snapshot in your HTML payload, then hand it to the provider (React) or context (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 & Hydration](/sdk/ssr/rendering-and-hydration).
-
-## Preview rendering
-
-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:
-
-```ts
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: '/promo' } },
-  previewToken,
-})
-```
-
-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.

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

@@ -1,35 +0,0 @@
----
-layout: docs
----
-
-# Slots & Placements
-
-A slot is a named mount point. `<ExperienceSlot name="page" />` renders every experience that targets 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.
-
-```tsx
-<ExperienceSlot name="page" />
-```
-
-## Targeting an experience to 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.
-
-## Placement order
-
-When several experiences target the same slot, they render in placement precedence:
-
-```
-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.
-
-## Multiple experiences 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.
-
-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).