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

package/dist/docs/sdk/features.md

@@ -2,13 +2,42 @@
 layout: docs
 ---
 
-# Features
+# Feature flags
 
-Define feature flags with a `decide` function that resolves to a bucket value, access results through framework hooks, and invalidate cached decisions by bumping the version.
+A feature flag lets you run an A/B test and roll a change out in stages. Control a
+feature flag from the dashboard, or define it in SDK code when you need your own decision
+rules.
 
-## Defining features
+## Where feature flags come from
 
-Define features when creating the Picked client by passing a `features` object. Each feature requires a unique identifier, a versioning key, a human-readable name, and a `decide` function:
+You control most feature flags from the dashboard. The
+[dynamic experiences plugin](/sdk/plugins/dynamic-experiences) reads the options of
+your project at runtime and registers every feature flag for you. You declare no feature flag in
+code.
+
+For a feature flag that you control from the dashboard, the SDK makes the definition:
+
+| Field | Value |
+| --- | --- |
+| `id` | The dashboard key of the feature flag |
+| `key` | `v{version}`, for example `v3` |
+| `name` | The dashboard name of the feature flag |
+| `enabled` | The dashboard **Enabled** toggle |
+| `weight` | The dashboard **Weight**, 0 to 100 |
+| `storage` | `local`, or `session` in [preview mode](/sdk/feature-allocation#preview-mode) |
+| `decide` | Made by the SDK. It compares the stable value of the visitor for this feature flag against `weight`. |
+
+The `decide` function that the SDK makes derives from the visitor ID, the ID of the
+feature flag, and the weight. A feature flag that you control from the dashboard
+therefore cannot use the data of your application. Define the feature flag in SDK code
+when you need that.
+
+## Define a feature flag in SDK code
+
+Define your feature flags when you create the Picked client. Pass a `features` object. Use
+this when a decision needs data that only your application holds. Each feature flag needs a
+unique identifier, a version key, a name that a person can read, and a `decide`
+function:
 
 ```ts
 import { createClient } from '@picked/client'
@@ -17,20 +46,20 @@ const client = createClient({
   projectId: 'your-project-id',
   features: {
     'summer-sale': {
-      key: 'summer-sale-v1', // Version key - change to invalidate cache
-      name: 'Summer Sale Experiment', // Human-readable name for analytics
+      key: 'summer-sale-v1', // The version key. Change it to invalidate the cache.
+      name: 'Summer Sale Experiment', // A name for analytics that a person can read.
       decide: async () => {
-        // Your decision logic here
+        // Put your decision rules here.
         const isEligible = await checkUserEligibility()
-        return isEligible // Returns boolean
+        return isEligible // Returns a boolean.
       },
-      storage: 'local', // Optional: 'local' (default) or 'session'
+      storage: 'local', // Optional: 'local' is the default, or 'session'.
     },
     'homepage-variant': {
       key: 'homepage-test-v2',
       name: 'Homepage A/B Test',
       decide: async () => {
-        // Return string for multi-variant tests
+        // Return a string for a test of more than two variants.
         return Math.random() < 0.5 ? 'variant-a' : 'variant-b'
       },
     },
@@ -38,7 +67,8 @@ const client = createClient({
 })
 ```
 
-Features can also be defined as factory functions for lazy initialization:
+A feature flag can also be a factory function, which starts the feature flag only when it is
+first needed:
 
 ```ts
 features: {
@@ -50,25 +80,35 @@ features: {
 }
 ```
 
-## How features work
+## How feature flags work
+
+After you register a feature flag, the SDK follows this order:
 
-When a feature is registered, the SDK follows this execution order:
+1. **Registration** — the client registers each feature flag at startup. A registration
+   allocates nobody.
+2. **Cache check** — the SDK looks in browser storage for a decision from an earlier
+   visit. The cache key holds the feature flag `id` and `key`. When an entry is there, the
+   feature flag starts in a resolved state. This is why Picked allocates a visitor who
+   returns before anything reads the feature flag.
+3. **Lazy evaluation** — with no cached decision, `decide` runs the first time that
+   something reads the bucket.
+4. **Storage** — the SDK writes the resolved bucket to browser storage.
+5. **Event emission** — the SDK sends a `feature_decide` event, but only for a
+   decision that it makes during this page view. A decision that step 2 restores
+   sends nothing.
 
-1. **Registration**: Features are registered to the Picked client during initialization
-2. **Cache Check**: The SDK checks browser storage (localStorage or sessionStorage) for a previously resolved value using the feature `id` and `key`
-3. **Lazy Evaluation**: If no cached value exists, the `decide` function will be called the first time the feature is accessed
-4. **Storage**: Once resolved, the bucket value is persisted to browser storage for consistency across page loads
-5. **Event Emission**: A `feature_decide` event is fired on the event bus when a feature is resolved for the first time
+See [Allocation and exposure](/sdk/feature-allocation) for what this means when you
+track an exposure.
 
-## URL-based overrides
+## Overrides in the URL
 
-You can override feature decisions via URL search parameters for testing purposes:
+You can override a feature flag decision from the URL search parameters, for a test:
 
 ```
 https://example.com?picked-feature=my-feature:true
 ```
 
-Multiple overrides can be specified:
+You can give more than one override value:
 
 ```
 https://example.com?picked-feature=my-feature:true&picked-feature=homepage-variant:variant-a
@@ -76,11 +116,15 @@ https://example.com?picked-feature=my-feature:true&picked-feature=homepage-varia
 
 The format is `?picked-feature=<feature-id>:<bucket-value>`.
 
-This is useful for QA testing specific feature variants without modifying code. The override is persisted in session storage and will be cleared when the browser tab is closed.
+This is useful for QA, because you can test one bucket value and change no code. The
+SDK keeps the override value in session storage. The browser clears it when you close
+the tab.
 
-## Accessing features
+## Read a feature flag
 
-Once features are defined, you can access their resolved bucket values in your application code. The SDK provides framework-specific hooks and a framework-agnostic event bus for subscribing to feature decisions.
+After you define your feature flags, your application code can read the resolved
+bucket value of each one. The SDK gives you a hook for each framework, and an event
+bus that works with any framework.
 
 :::code-group
 
@@ -88,66 +132,89 @@ Once features are defined, you can access their resolved bucket values in your a
 import { createClient } from '@picked/client'
 
 const client = createClient({
-  /* Create client options here */
+  /* Put your client options here. */
 })
 
-client.eventBus.subscribe('feature_decide', ({ feature }) => {
-  if (feature.id === 'my-feature') {
-    console.log(feature) // { id: 'my-feature', bucket: 'control' }
+client.eventBus.watch((event) => {
+  if (event.type === 'feature_decide' && event.feature.id === 'my-feature') {
+    console.log(event.feature) // { id: 'my-feature', key: 'v1', bucket: 'control' }
   }
 })
 ```
 
-```ts [Svelte]
+```svelte [Svelte]
 <script lang="ts">
-  import { getFeature } from '@picked/svelte/hooks'
-  // Returns an Effector store containing the feature resolver
-  const myFeature = getFeature('my-feature')
+  import { getFeatureResult } from '@picked/svelte/hooks'
+
+  // A store that holds { id, bucket }, or undefined until the feature flag resolves.
+  const result = getFeatureResult('my-feature')
 </script>
-<!-- $myFeature is a reactive Effector store (see Effector docs for details) -->
-{#if $myFeature()}
-  <p>My feature is enabled</p>
-{:else}
-  <p>My feature is disabled</p>
+
+{#if $result?.bucket === 'control'}
+  <p>Control</p>
+{:else if $result?.bucket === 'variant-a'}
+  <p>Variant A</p>
 {/if}
 ```
 
-```ts [React]
-import { useFeature } from '@picked/react/hooks'
+```tsx [React]
+import { useFeatureResult } from '@picked/react/hooks'
 
 function MyComponent() {
-  // Returns the resolved bucket value for 'my-feature'
-  const myFeature = useFeature('my-feature')
+  // { id, bucket }, or undefined until the feature flag resolves.
+  const result = useFeatureResult('my-feature')
 
   return (
     <div>
-      {myFeature === 'control' && <p>Control variant</p>}
-      {myFeature === 'variant-a' && <p>Variant A</p>}
+      {result?.bucket === 'control' && <p>Control</p>}
+      {result?.bucket === 'variant-a' && <p>Variant A</p>}
     </div>
   )
 }
-
 ```
 
 :::
 
-## Using features in experience conditions
+### Choose an accessor
+
+Each accessor returns a different value. They also differ in whether a read resolves
+the feature flag. A read that resolves the feature flag commits the visitor to a bucket and reports
+the decision. See [Allocation and exposure](/sdk/feature-allocation).
+
+| API | Returns | Does a read resolve the feature flag? |
+| --- | --- | --- |
+| `useFeature` / `getFeature` | `() => Promise<bucket>` | Only when you call the function that it returns |
+| `useFeatureResult` / `getFeatureResult` | `{ id, bucket }`, and `undefined` until it resolves | Yes, as soon as the component renders |
+| `useFeatureEnabled` / `getFeatureEnabled` | `boolean \| undefined`, the dashboard **Enabled** toggle | No |
+| `client.features.listStore` | Every registered feature flag, each with an `isResolved` feature flag | No |
+| `client.features.getById(id)` | A store that holds one feature flag | No |
+
+:::warning
+`useFeatureResult` and `getFeatureResult` resolve the feature flag as soon as the component
+renders. They commit the visitor to a bucket at that moment.
+
+Some decisions must wait for data that you do not have yet, such as a cart, a quote,
+or a profile of a signed-in user. For those, use `useFeature` or `getFeature`. Call
+the function that they return after the data arrives.
+:::
+
+## Use a feature flag in an experience condition
 
-Features can be used with experience conditions via JSON logic:
+You can use a feature flag in an experience condition through JSON logic:
 
 ```ts
 const myExperience = createExperience({
-  // ... other config
+  // The other options go here.
   condition: {
     and: [
       {
         '==': [
           {
             invoke: {
-              var: 'features.summer-sale', // Reference feature by ID
+              var: 'features.summer-sale', // Point at the feature flag by its ID.
             },
           },
-          true, // Check if bucket equals true
+          true, // Check that the bucket equals true.
         ],
       },
     ],
@@ -155,16 +222,25 @@ const myExperience = createExperience({
 })
 ```
 
-## Listening to feature decisions
+The ID in `features.<id>` is the **Key** of the feature flag from the dashboard. It is the
+same value that the detail page of the feature flag shows.
+
+An evaluation of a condition reads the bucket. Picked therefore allocates a visitor
+to a feature flag when the condition that points at it runs.
+
+## Watch for feature flag decisions
 
-Subscribe to the `feature_decide` event to track when features are resolved:
+Subscribe to the `feature_decide` event to track when a feature flag resolves:
 
 ```ts
-client.eventBus.subscribe('feature_decide', ({ feature }) => {
-  console.log(`Feature "${feature.id}" resolved to bucket:`, feature.bucket)
-  // Example output: Feature "summer-sale" resolved to bucket: true
+client.eventBus.watch((event) => {
+  if (event.type !== 'feature_decide') return
 
-  // Send to analytics
+  const { feature } = event
+  console.log(`Flag "${feature.id}" resolved to bucket:`, feature.bucket)
+  // Example output: the feature flag resolved to the bucket true.
+
+  // Send the decision to your analytics.
   analytics.track('Feature Decision', {
     featureId: feature.id,
     bucket: feature.bucket,
@@ -172,41 +248,73 @@ client.eventBus.subscribe('feature_decide', ({ feature }) => {
 })
 ```
 
-## Versioning and cache invalidation
+## Versions and cache invalidation
+
+The SDK caches a feature flag decision in browser storage. It uses `localStorage`, or
+`sessionStorage` in a preview. The cache key derives from the feature flag ID and the version,
+so a visitor keeps the same decision across page loads.
 
-Feature decisions are cached in browser storage (localStorage or sessionStorage) using a key derived from the feature ID and version. This ensures visitors see a consistent experience across page loads.
+:::warning
+The SDK does not yet restore a string bucket value, such as `'variant-a'`, correctly
+from storage. It treats the visitor as unallocated on the next page load. A boolean
+bucket value is correct, and that includes every feature flag that you control from the
+dashboard. See PICK-1574.
+:::
 
-### How versioning works
+### How versions work
 
-When you create a feature in the dashboard, it starts at version 1. The SDK uses the version to build the cache key — for example, a feature at version 3 uses the key `v3`. This version is also included in the allocation hash, so it directly affects which variant a visitor is assigned to.
+A feature flag that you create in the dashboard starts at version 1. The SDK uses the
+version to build the cache key. A feature flag at version 3 caches under `v3`.
 
-### What happens when the version is incremented
+The version affects **the cache only**. It is not part of the allocation. For a feature flag
+that you control from the dashboard, the allocation derives from the visitor ID and
+the weight of the feature flag.
 
-When you increment a feature's version in the dashboard:
+### What happens when you increment the version
 
-1. **Cache keys change.** The old cache entry (e.g., `v3`) no longer matches the new key (`v4`), so the SDK treats the feature as undecided.
-2. **All visitors are re-allocated.** The allocation hash includes the version, so every visitor gets a new hash value and may be assigned to a different variant.
-3. **The `decide` function runs again.** On the next page load, the SDK calls `decide()` fresh and caches the new result.
+When you increment the version of a feature flag in the dashboard:
 
-> **Warning:** Incrementing the version re-allocates all visitors, not just new ones. This is irreversible. Only increment when you intentionally want to reset all assignments — for example, after changing traffic allocation weights.
+1. **The cache key changes.** The old entry, `v3`, no longer matches the new key,
+   `v4`. The SDK therefore treats the feature flag as undecided.
+2. **The `decide` function runs again.** On the next page load, the SDK calls
+   `decide()` again and caches the new result.
+3. **Picked evaluates each visitor again and moves nobody.** For a feature flag that you
+   control from the dashboard the allocation is deterministic. The same visitor
+   against an unchanged weight gives the same bucket.
+
+:::note
+The new version clears the cached decisions and runs the allocation again. It moves
+no visitor between groups. With an unchanged weight, everybody lands where they were.
+Increment the version after you change a weight, so that Picked evaluates a visitor
+with a cached decision against the new weight.
+:::
 
-### SDK `key` vs dashboard version
+### The SDK `key` and the dashboard version
 
-If you define features statically in the SDK (not loaded from the dashboard), use the `key` field for manual versioning:
+For a feature flag that you define in SDK code, use the `key` field to set the version
+yourself. This applies when you do not read the feature flag from the dashboard:
 
 ```ts
 features: {
   'summer-sale': {
-    key: 'summer-sale-v2', // Change to invalidate cache
-    // ...
+    key: 'summer-sale-v2', // Change this to invalidate the cache.
+    // The other options go here.
   },
 }
 ```
 
-For features managed through the dashboard, versioning is handled automatically — the dashboard appends the version number to the cache key used by the SDK.
+For a feature flag that you control from the dashboard, Picked sets the version for you. The
+dashboard adds the version number to the end of the cache key that the SDK uses.
 
 ## Best practices
 
-- **Use `session` storage for temporary tests**: Set `storage: 'session'` for short-lived experiments that shouldn't persist across browser sessions
-- **Keep `decide` functions fast**: The function blocks experience rendering, so avoid heavy computations or slow network calls
-- **Return consistent types**: Don't mix boolean and string returns for the same feature - pick one type and stick with it
+- **Use `session` storage for a short test**: set `storage: 'session'` for an
+  experiment that must not stay across browser sessions.
+- **Keep each `decide` function fast**: everything that waits for the feature flag waits for
+  `decide` to finish. This includes an experience condition and a component that
+  reads the result. Do not make a slow network call inside it.
+- **Allocate when the decision matters**: read a feature flag only after the data that it
+  needs arrives. Do not read every feature flag at startup. See
+  [Allocation and exposure](/sdk/feature-allocation).
+- **Return one type**: do not return a boolean from a feature flag one time and a string the
+  next. Choose one type and keep it.

package/dist/docs/sdk/fields.md

@@ -4,16 +4,19 @@ layout: docs
 
 # Fields
 
-Define fields in code with `createField()`, validate input with JSON Logic, and read submitted values through step context.
+Define your fields in code with `createField()`. Check the input with JSON Logic.
+Read the values that a user sends through the step context.
 
-## Defining fields
+## Define a field
 
-Define fields using `createField()` from the `@picked/client/plugins/create-experience` package. Each field requires a unique identifier, name, type, label, and cardinality:
+Define a field with `createField()` from the
+`@picked/client/plugins/create-experience` package. Each field needs a unique
+identifier, a name, a type, a label, and a count of the values that it takes:
 
 ```ts
 import { createField } from '@picked/client/plugins/create-experience'
 
-// Required text input
+// A text input that the user must fill in.
 export const emailField = createField({
   id: 'email-address',
   name: 'email-address',
@@ -24,7 +27,7 @@ export const emailField = createField({
   placeholder: 'you@example.com',
 })
 
-// Multi-select dropdown with static options
+// A dropdown that takes more than one choice, with fixed options.
 export const communicationMethods = createField({
   id: 'communication-methods',
   name: 'communication-methods',
@@ -54,21 +57,28 @@ export const communicationMethods = createField({
 
 ## How fields work
 
-When a field is registered and used in an experience:
-
-1. **Registration**: Fields are registered to the experience during step creation via `.addField()`
-2. **Condition Evaluation**: If the field has a `condition`, it's evaluated against the current context to determine visibility
-3. **Rendering**: Visible fields are rendered in the experience UI with their label, placeholder, and options
-4. **User Input**: User enters or selects a value, triggering client-side validation if specified
-5. **Storage**: Valid responses are stored in the experience state under `responses[field.name]`
-6. **Reference**: Field values can be referenced in subsequent field conditions, step conditions, or experience logic via `{ var: 'responses.field-name' }`
+After you register a field and an experience uses it:
+
+1. **Registration**: you register a field on the experience while you create the
+   step, with `.addField()`.
+2. **Condition evaluation**: when the field has a `condition`, the SDK evaluates it
+   against the current context. The result decides whether the field is visible.
+3. **Rendering**: the SDK renders each visible field in the experience UI, with its
+   label, its placeholder, and its options.
+4. **User input**: the user enters or chooses a value. Validation then runs in the
+   browser, when you set a rule.
+5. **Storage**: the SDK stores a valid response in the experience state, under
+   `responses[field.name]`.
+6. **Reference**: a later condition can point at the value with
+   `{ var: 'responses.field-name' }`. This works in a field condition, in a step
+   condition, and in the logic of an experience.
 
 ## Field types
 
-Fields support four primitive types, `text`, `number`, `boolean` and `object`:
+A field has one of four basic types: `text`, `number`, `boolean`, or `object`.
 
 ```ts
-// Single text input
+// One text input.
 const nameField = createField({
   type: 'text',
   multiple: false,
@@ -76,7 +86,7 @@ const nameField = createField({
 })
 ```
 
-Provide an `options` array to allow multiple select:
+Give an `options` array to let the user choose more than one value:
 
 ```ts
 const nameField = createField({
@@ -104,7 +114,7 @@ const nameField = createField({
 
 ## Conditions
 
-Fields and field options are compatible with condition logic:
+A field and a field option both work with condition logic:
 
 ```ts
 const conditionalField = createField({
@@ -131,7 +141,8 @@ const conditionalField = createField({
 
 ## Field validation
 
-Validate user input using JSON Logic rules. The `$input` variable contains the current field value:
+Check the input of a user with a JSON Logic rule. The `$input` variable holds the
+current value of the field:
 
 ```ts
 const quantityField = createField({
@@ -147,7 +158,7 @@ const quantityField = createField({
         {
           and: [
             {
-              // Input value is above 0
+              // The input value is above 0.
               '>': [
                 {
                   var: '$input',
@@ -156,7 +167,7 @@ const quantityField = createField({
               ],
             },
             {
-              // Input value is equal or below 999
+              // The input value is 999 or below.
               '<=': [
                 {
                   var: '$input',
@@ -176,12 +187,13 @@ const quantityField = createField({
 ```
 
 :::tip
-The `catch`/`throw` pattern in JSON Logic validates that the condition evaluates to `true`. If it doesn't, the `throw` message is displayed to the user.
+The `catch` and `throw` pattern in JSON Logic checks that the condition gives `true`.
+When it does not, the SDK shows the `throw` message to the user.
 :::
 
 ## Field policies
 
-Control how field data is tracked and stored using privacy policies:
+Use a privacy policy to control how Picked tracks and stores the data of a field:
 
 ```ts
 const sensitiveField = createField({
@@ -192,22 +204,25 @@ const sensitiveField = createField({
   multiple: false,
   required: true,
   policies: {
-    doNotTrackValue: true, // Don't send value to analytics
-    doNotStoreValue: true, // Don't persist value to browser storage
+    doNotTrackValue: true, // Do not send the value to analytics.
+    doNotStoreValue: true, // Do not keep the value in browser storage.
   },
 })
 ```
 
 **Privacy policies**:
 
-- `doNotTrackValue`: Excludes field value from analytics events (only field ID is tracked)
-- `doNotStoreValue`: Prevents field value from being persisted to browser storage
+- `doNotTrackValue`: keeps the value of the field out of your analytics events. The
+  events carry the field ID only.
+- `doNotStoreValue`: stops the SDK, so that it does not put the value in browser
+  storage.
 
-Use these policies for sensitive data like SSNs, credit cards, or passwords that should only exist client-side.
+Use these policies for sensitive data such as a tax number, a credit card number, or
+a password. That data must stay in the browser.
 
 ## Field metadata
 
-Enhance user experience with additional descriptive text:
+Add more text to help the user:
 
 ```ts
 const passwordField = createField({
@@ -225,18 +240,19 @@ const passwordField = createField({
 
 **Metadata fields**:
 
-- `placeholder`: Hint text displayed in empty input fields
-- `description`: Brief explanation shown below the label
-- `helpText`: Additional guidance or requirements displayed near the field
+- `placeholder`: the hint text that an empty input shows.
+- `description`: a short explanation below the label.
+- `helpText`: more guidance, or the requirements, next to the field.
 
-## Accessing field values
+## Read a field value
 
-Field responses are stored in the experience state and can be accessed via the `responses` object:
+The SDK stores each field response in the experience state. Read a response through
+the `responses` object:
 
 :::code-group
 
 ```ts [In Conditions]
-// Reference in subsequent field conditions
+// Point at the value from a later field condition.
 const sensitiveField = createField({
   condition: {
     '==': [
@@ -253,11 +269,19 @@ const sensitiveField = createField({
 
 ## Best practices
 
-- **Use semantic IDs and names**: Name fields descriptively (e.g., `email-address` not `field1`) for easier debugging and analytics
-- **Match type to data**: Use `number` for numeric values, not `text`, to enable proper validation and comparison
-- **Set appropriate `required` flags**: Only mark fields as required when truly necessary to reduce form abandonment
-- **Keep validation messages clear**: Error messages should tell users exactly how to fix the input
-- **Use conditional fields for progressive disclosure**: Show fields only when relevant based on prior responses
-- **Apply privacy policies to sensitive data**: Use `doNotTrackValue` and `doNotStoreValue` for PII, passwords, or financial data
-- **Provide helpful metadata**: Add `placeholder` and `description` to guide users, especially for complex or formatted inputs
-- **Keep option lists scannable**: For more than 5 options, consider providing search/filter functionality or breaking into multiple steps
+- **Give each field a name that says what it holds**: use `email-address` and not
+  `field1`. It is then easier to debug the flow and to read your analytics.
+- **Match the type to the data**: use `number` for a numeric value, and not `text`.
+  The SDK can then check and compare the value correctly.
+- **Mark a field as required only when it is**: fewer required fields means fewer
+  users who leave the form.
+- **Keep each validation message clear**: an error message must tell the user exactly
+  how to correct the input.
+- **Show a field only when it is relevant**: use a condition on the field, and decide
+  it from the earlier responses.
+- **Apply a privacy policy to sensitive data**: use `doNotTrackValue` and
+  `doNotStoreValue` for personal information, a password, or financial data.
+- **Give helpful metadata**: add a `placeholder` and a `description` to help the
+  user, above all for an input with a format.
+- **Keep an option list easy to read**: for more than 5 options, add a search or
+  break the field into more than one step.