@picked/client 0.0.1-dev.1785287094311 → 0.0.1-dev.1785826066660

package/dist/docs/sdk/actions.md

@@ -4,11 +4,13 @@ layout: docs
 
 # Actions
 
-Register action handlers on the Picked client so the SDK can invoke them when an experience flow reaches an action node.
+Register an action handler on the Picked client. The SDK then invokes the handler
+when an experience flow reaches an action node.
 
-## Registering actions
+## Register an action
 
-Register actions when creating the Picked client. Each key in the `actions` object must match an action key defined in the dashboard:
+Register your actions when you create the Picked client. Each key in the `actions`
+object must match an action key from the dashboard:
 
 ```ts
 import { createClient } from '@picked/client'
@@ -26,41 +28,55 @@ const picked = createClient({
 })
 ```
 
-Each action is a function that receives optional parameters and usually runs a side effect. When the flow reaches an action node, the SDK calls the matching function and branches on whether it succeeds or throws (see [Success and failure branching](#success-and-failure-branching)).
+Each action is a function. It takes optional parameters and it usually runs a side
+effect. When the flow reaches an action node, the SDK calls the function that
+matches. The SDK then takes a branch, which depends on whether the function succeeds
+or throws. See [Success and failure branches](#success-and-failure-branches).
 
 ## How actions work
 
-1. **Registration**: Actions are registered to the Picked client during initialization
-2. **Flow traversal**: When the SDK traverses the experience flow and reaches an action node, it looks up the action by its key
-3. **Execution**: The matching function is called and awaited. The SDK then continues to the next node based on the action's outcome
-4. **Non-blocking**: Actions don't interrupt the visitor's experience. The current step stays on screen while an async action runs
+1. **Registration**: you register each action on the Picked client at startup.
+2. **Flow traversal**: the SDK walks the experience flow. When it reaches an action
+   node, it finds the action by its key.
+3. **Execution**: the SDK calls the function that matches and awaits it. The outcome
+   then decides which node comes next.
+4. **No block**: an action does not interrupt your visitor. The current step
+   stays on the screen while an async action runs.
 
-## Success and failure branching
+## Success and failure branches
 
-An action node can have separate **success** and **failure** branches. The SDK selects the branch from the action's outcome:
+An action node can have a **success** branch and a **failure** branch. The SDK
+chooses the branch from the outcome of the action:
 
-- **Failure** — the action throws (or its promise rejects). The flow follows the failure (`onFail`) branch.
-- **Success** — the action resolves to any value (`void`, `true`, `false`, or a string). A resolved `false` is a valid response, not a failure. The flow follows the success (`onSuccess`) branch.
+- **Failure** — the action throws, or its promise rejects. The flow takes the failure
+  branch, `onFail`.
+- **Success** — the action resolves to any value: `void`, `true`, `false`, or a
+  string. A resolved `false` is a valid response and not a failure. The flow takes
+  the success branch, `onSuccess`.
 
-Reserve the failure branch for genuine errors — throw on the failure case, since a returned value never routes to `onFail`:
+Keep the failure branch for a true error. Throw on the failure case, because a
+returned value never takes the `onFail` branch:
 
 ```ts
 'check-eligibility': async () => {
   const response = await fetch('/api/eligibility')
-  // Throw only when the request itself fails — that takes the failure branch.
+  // Throw only when the request itself fails. That takes the failure branch.
   if (!response.ok) throw new Error('Eligibility request failed')
 }
 ```
 
-A valid negative result is not a failure. An API that returns `200` with a "no" (for example `{ serviced: false }`) should record that value as a response and branch on it with a condition, rather than throw:
+A valid negative result is not a failure. An API can return `200` with a "no", for
+example `{ serviced: false }`. Record that value as a response and branch on it with
+a condition. Do not throw:
 
 ```ts
 'check-serviced-area': async ({ client, responses }) => {
   const postcode = responses.find((r) => r.fieldKey === 'postcode')?.value
   const { serviced } = await fetch(`/api/serviced?postcode=${postcode}`).then((r) => r.json())
-  // Commit the outcome as a response; a downstream condition routes the flow.
+  // Store the outcome as a response. A later condition then takes the branch.
   client.responses.register('is-serviced', serviced)
 }
 ```
 
-If an action node has only a single plain connection (no explicit success or failure branch), the flow continues through it on either outcome.
+An action node can also have one plain connection, with no success or failure branch.
+The flow then continues through it on either outcome.

package/dist/docs/sdk/conditions.md

@@ -4,11 +4,13 @@ layout: docs
 
 # Conditions
 
-Conditions use JSON Logic to evaluate client state. Use them to gate experience activation, branch step navigation, and control field visibility.
+A condition uses JSON Logic to evaluate the client state. Use a condition to control
+when an experience starts, to choose the next step, and to show or hide a field.
 
 ## Conditions in experiences
 
-A common pattern is using conditions between steps to branch the flow based on form responses:
+A common pattern puts a condition between two steps. The flow then takes a branch
+that the form responses decide:
 
 ```ts
 import { createExperience } from '@picked/client/plugins/create-experience'
@@ -47,12 +49,13 @@ isSigningUpForNewsletter.addFalse(userDoesNotWantNewsletter)
 
 ## Conditional fields
 
-Fields can be shown or hidden based on previous responses or [predicates](./predicates) using JSON Logic conditions:
+A JSON Logic condition can show or hide a field. The condition can read an earlier
+response or a [predicate](./predicates):
 
 ```ts
 import { createField } from '@picked/client/plugins/create-experience'
 
-// Show email field only if user selected "email" as a contact method
+// Show the email field only when the user chose "email" as a contact method.
 export const emailField = createField({
   id: 'email-input',
   name: 'email-input',
@@ -70,7 +73,7 @@ export const emailField = createField({
   },
 })
 
-// Show field based on predicate
+// Show the field when the predicate returns true.
 export const mailingAddressField = createField({
   id: 'mailing-address',
   name: 'mailing-address',

package/dist/docs/sdk/content-security-policy.md

@@ -4,15 +4,16 @@ layout: docs
 
 # Content Security Policy
 
-The Picked SDK loads resources from the following domains. Add each to the matching CSP directive.
+The Picked SDK loads resources from the domains below. Add each domain to the CSP
+directive that the table gives.
 
 ## Required domains
 
 | Domain | Directive | Purpose |
 | --- | --- | --- |
-| `api.picked.app` | `connect-src` | API requests, project configuration, experiences, session tracking |
-| `evnts.pckd.dev` | `connect-src` | Analytics event collection (Snowplow) |
-| `img.picked-content.com` | `img-src` | Optimised images served via the [image optimisation service](../image-optimisation-service.md) |
+| `api.picked.app` | `connect-src` | API requests, project options, experiences, and the record of each session |
+| `evnts.pckd.dev` | `connect-src` | Analytics events, which Snowplow collects |
+| `img.picked-content.com` | `img-src` | Optimised images, which the [image optimisation service](../image-optimisation-service.md) serves |
 
 ## Configuration
 

package/dist/docs/sdk/experiences.md

@@ -4,11 +4,18 @@ layout: docs
 
 # Experiences
 
-Define experiences in code with `createExperience()`, or load them from the dashboard at runtime with the [Dynamic Experiences Plugin](./plugins/dynamic-experiences).
+Define an experience in code with `createExperience()`. You can also load an
+experience 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).
+The flow below points at a DOM selector and renders into it. A Page experience
+renders through a named slot instead. Point it at `.picked-slot-<name>` and render
+`<ExperienceSlot name="<name>" />` on your server. Use the slot path for a Page that
+the server renders and that search engines must read. Use the selector path for a
+Flow that the browser renders. See [Server-Side Rendering](/sdk/ssr) and
+[Slots and Placements](/sdk/ssr/slots-and-placements).
 
-## Creating experiences
+## Create an experience
 
 ```ts
 import { createExperience } from '@picked/client/plugins/create-experience'
@@ -32,15 +39,26 @@ export const productPageExperience = createExperience({
 })
 ```
 
-Register experiences using the [Create Experience Plugin](./plugins/create-experience) for code-defined experiences, or the [Dynamic Experiences Plugin](./plugins/dynamic-experiences) to fetch and manage them from the dashboard at runtime.
+To register an experience that you define in code, use the
+[Create Experience Plugin](./plugins/create-experience). To read an experience from
+the dashboard at runtime and control it there, use the
+[Dynamic Experiences Plugin](./plugins/dynamic-experiences).
 
 ## How experiences work
 
-When an experience is registered, the SDK follows this execution flow:
+After you register an experience, the SDK follows this flow:
 
-1. **Registration**: Experiences are registered to the Picked client using [createExperiencePlugin](./plugins/create-experience) for code-defined experiences, or [dynamicExperiencesPlugin](./plugins/dynamic-experiences) for dashboard-managed experiences
-2. **Condition evaluation**: The SDK evaluates the experience's `condition` using the logic engine to determine if it should be shown
-3. **Target resolution**: The SDK searches the DOM for elements matching the `targets` selectors (e.g., `body`, `.product-page`, `#checkout`)
-4. **Initialization**: If the condition evaluates to `true` and at least one target element exists, the experience is initialized
-5. **Component rendering**: The experience's component is rendered and injected into the DOM at the specified target location and placement (before, after, append, prepend, or replace)
-6. **Flow execution**: If the experience contains steps, fields, and conditionals, users can progress through the multi-step flow with validation and branching logic
+1. **Registration**: You register the experience on the Picked client. Use
+   `createExperiencePlugin` for an experience that you define in code. Use
+   `dynamicExperiencesPlugin` for one that you control from the dashboard.
+2. **Condition evaluation**: The SDK evaluates the `condition` of the experience with
+   the logic engine. The result decides whether a visitor sees it.
+3. **Target resolution**: The SDK searches the DOM for an element that matches a
+   selector in `targets`. Examples are `body`, `.product-page`, and `#checkout`.
+4. **Initialization**: The SDK starts the experience when the condition is `true` and
+   at least one target element is there.
+5. **Component rendering**: The SDK renders the component of the experience. It puts
+   the component into the DOM at the target and the placement that you set. A
+   placement is `before`, `after`, `append`, `prepend`, or `replace`.
+6. **Flow execution**: An experience can hold steps, fields, and conditions. A user
+   then moves through the flow. The flow checks each answer and takes a branch.

package/dist/docs/sdk/feature-allocation.md

@@ -0,0 +1,161 @@
+---
+layout: docs
+---
+
+# Allocation and exposure
+
+A read of the bucket of a feature flag is what allocates a visitor to that feature flag. This
+page covers when that happens and how to watch it. It also covers how to be sure that
+Picked allocates a visitor before you report on that visitor.
+
+## A registration is not a decision
+
+The SDK loads every feature flag in your project at startup, but it allocates no visitor
+then. A feature flag stays undecided until something reads its bucket. The first read runs the
+`decide` function, stores the result, and reports the decision.
+
+You therefore choose when Picked commits a visitor to a feature flag. You choose it by the
+point at which you read the feature flag.
+
+## A read of a bucket records an exposure
+
+The first read is the decision, so a read of a bucket is the moment when the visitor
+enters the test. If you read every feature flag at startup, every visitor counts as exposed
+to every test. This includes a test that the visitor never reached.
+
+:::warning
+Do not loop over every feature flag at startup to read its bucket. That commits every visitor
+to every test immediately. You then have no way to wait for the data that a decision
+needs.
+:::
+
+Read a feature flag at the point where the decision matters. That is after the cart loads,
+after the quote returns, or after you know who the visitor is.
+
+## Check a feature flag without a decision
+
+`client.features.listStore` holds every registered feature flag. Each entry reports whether
+the feature flag is decided yet, so you can check a feature flag and commit nobody:
+
+```ts
+for (const feature flag of client.features.listStore.getState()) {
+  console.log(feature flag.id, feature flag.isResolved)
+}
+```
+
+`getBucket()` behaves differently for each state:
+
+- **Resolved** — it returns `{ id, bucket }` at once. The read changes nothing.
+- **Not resolved** — it returns a promise. An `await` runs `decide` and commits the
+  visitor.
+
+`await` works for both states, so you can treat them the same way when you do intend
+to decide.
+
+## When `feature_decide` fires
+
+The SDK sends a `feature_decide` event the first time that it decides a feature flag for a
+visitor, and only then.
+
+:::warning
+On a later page load the SDK restores the decision from browser storage, and it
+sends **no event**. A visitor who returns produces no `feature_decide` event at all,
+although Picked still allocates that visitor.
+
+An integration that reads only `feature_decide` therefore reports nothing for a
+visitor who returns.
+:::
+
+Use the correct source for your question:
+
+| Question | Use |
+| --- | --- |
+| What is this visitor allocated to now? | `client.features.listStore` |
+| Did the SDK make a new decision? | `feature_decide` on `client.eventBus` |
+| Which decisions happened before I subscribed? | `client.events` |
+
+## Watch for decisions
+
+`listStore` updates each time that a feature flag resolves. It does this whether the SDK
+restored the feature flag from storage or decided it now. A watch on `listStore` therefore
+always gives you the current state:
+
+```ts
+const buckets = new Map<string, string | boolean>()
+
+client.features.listStore.watch((feature flags) => {
+  for (const feature flag of feature flags) {
+    if (!feature flag.isResolved) continue
+    buckets.set(feature flag.id, feature flag.getBucket().bucket)
+  }
+})
+```
+
+Use `feature_decide` when you need to know that the SDK *made* a decision, and not
+what the current value is. An example is your own exposure event:
+
+```ts
+client.eventBus.watch((event) => {
+  if (event.type !== 'feature_decide') return
+  analytics.track('Experiment exposure', {
+    feature flag: event.feature.id,
+    bucket: event.feature.bucket,
+  })
+})
+```
+
+An earlier event is still available when you subscribe after startup. `client.events`
+holds every event since the client started:
+
+```ts
+const earlier = client.events
+  .getState()
+  .filter((entry) => entry.payload.type === 'feature_decide')
+```
+
+## Decide before you report
+
+To be sure that the SDK decides a feature flag before a later event fires, `await` the feature flag
+first:
+
+```ts
+const feature flag = client.features.getById('quote-experiment').getState()
+
+if (feature flag) {
+  const { bucket } = await feature flag.getBucket()
+  trackViewQuote({ experiment: bucket })
+}
+```
+
+An `await` on `getBucket()` resolves the feature flag when it is undecided, and returns the
+stored value when it is decided. In both cases the bucket is known before the next
+line runs.
+
+## What Picked reports for you
+
+Read this before you build a report of your own.
+
+Every Picked analytics event carries a `feature_list` context. The context describes
+each feature flag that this visitor resolved:
+
+| Field | Description |
+| --- | --- |
+| `ab_feature` | The feature flag ID |
+| `ab_name` | The feature flag name |
+| `ab_key` | The version key, such as `v3` |
+| `ab_bucket` | The resolved bucket |
+
+Only a resolved feature flag appears there. The context therefore shows what the visitor was
+exposed to at the time when the event fired.
+
+The [Sentry plugin](https://www.npmjs.com/package/@picked/sentry) is optional. When
+it is installed, each decision also tags the Sentry scope as
+`picked.feature.<feature flag-id>`, with the bucket as the value. You can then filter your
+errors by the variant.
+
+## Preview mode
+
+In [preview mode](/workspaces#preview) the SDK stores a decision in session storage
+and not in local storage. The decision does not stay after you close the tab, and
+Picked can allocate a preview visitor differently from a production visitor. Treat a
+preview allocation as disposable.