@picked/client 0.0.70-next.5 → 0.0.70

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.

package/dist/docs/sdk/index.md

@@ -4,13 +4,15 @@ layout: docs
 
 # Picked SDK
 
-The Picked SDK enables you to add dynamic, personalized experiences to your web applications with minimal code.
+The Picked SDK lets you add a dynamic, personalized experience to your web
+application with very little code.
 
 :::tip
-The SDK is framework-agnostic and works with React, Svelte, Vue, and vanilla JavaScript.
+The SDK is framework-agnostic. It works with React, Svelte, Vue, and plain
+JavaScript.
 :::
 
-## Quick Start
+## Quick start
 
 :::code-group
 
@@ -41,18 +43,20 @@ const snapshot = await serialize(client, {
 
 :::
 
-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).
+The `@picked/client/server` entry holds the helpers that run only on a server, such
+as `serialize()`. Those helpers make an SSR snapshot. It is a separate entry point,
+so a browser bundle never holds 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`
+In a browser, you can reach the Picked client from the console with `window.Picked`.
 :::
 
-## Precondition & Condition
+## Precondition and condition
 
 | Category     | Question               | Description                                                                                   |
 | ------------ | ---------------------- | --------------------------------------------------------------------------------------------- |
-| Precondition | Should Picked start?   | Use for environment checks, page filtering, or feature flags that completely disable the SDK. |
-| Condition    | Is this user eligible? | Use for user segmentation, A/B test enrollment, or targeting specific user groups.            |
+| Precondition | Must Picked start?     | Use it to check the environment, to filter by page, or for a feature flag that turns the SDK off completely. |
+| Condition    | Is this user eligible? | Use it to divide your users into groups, to enter a user into an A/B test, or to reach one group of users. |
 
 ```ts
 const picked = createClient({
@@ -76,14 +80,19 @@ const picked = createClient({
       var: 'features.convincely-enabled',
     },
   },
-  // rest of picked config
+  // The rest of the Picked options go here.
 })
 ```
 
 :::warning
-A precondition or condition that references a flag reads its bucket, which allocates the visitor at that moment. Preconditions run at startup, so a flag referenced there is allocated for every visitor before anything else happens — including visitors who never reach the experience it gates.
-
-See [Allocation and exposure](/sdk/feature-allocation) before referencing a flag in a precondition.
+A precondition or a condition that points at a flag reads the bucket of that flag,
+and that allocates the visitor at that moment. A precondition runs at startup.
+Picked therefore allocates every visitor to a flag that a precondition points at,
+before anything else happens. This includes a visitor who never reaches the
+experience that the flag controls.
+
+See [Allocation and exposure](/sdk/feature-allocation) before you point a
+precondition at a flag.
 :::
 
-See [conditions](./conditions.md) for more detail
+See [conditions](./conditions.md) for more detail.

package/dist/docs/sdk/plugins/create-experience.md

@@ -4,9 +4,9 @@ layout: docs
 
 # Create Experience Plugin
 
-A plugin to register an array of experiences to the Picked client.
+This plugin registers an array of experiences on the Picked client.
 
-## Setup Plugin
+## Set the plugin up
 
 :::code-group
 
@@ -26,14 +26,15 @@ const client = createClient({
 
 :::
 
-## Defining Steps
+## Define a step
 
-Steps are defined using `createStep()`. They are added directly to an experience using `experience.addStep()`.
+Define a step with `createStep()`. Add it directly to an experience with
+`experience.addStep()`.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'
 
-// Define standalone steps
+// Define the steps on their own.
 const welcomeStep = createStep({
   id: 'welcome',
   name: 'Welcome',
@@ -44,7 +45,7 @@ const contactStep = createStep({
   name: 'Contact Details',
 })
 
-// Define the experience and add steps to build the flow
+// Define the experience, then add the steps to build the flow.
 const onboardingExperience = createExperience({
   id: 'onboarding',
   name: 'User Onboarding',
@@ -55,13 +56,14 @@ onboardingExperience.addStep(welcomeStep)
 onboardingExperience.addStep(contactStep)
 ```
 
-Each step requires a `name` that identifies it in analytics events. An `id` is optional — one will be generated automatically if omitted.
+Each step needs a `name`, and your analytics events use that name to identify the
+step. An `id` is optional. Picked makes one for you when you give none.
 
-Steps can be used on multiple experiences.
+You can use the same step on more than one experience.
 
-### Adding Fields to Steps
+### Add a field to a step
 
-Fields are defined with `createField()`.
+Define a field with `createField()`.
 
 ```ts
 import { createStep, createField } from '@picked/client/plugins/create-experience'
@@ -77,7 +79,8 @@ const emailField = createField({
 })
 ```
 
-Fields are added to a step with `step.addField()`, or an array of `fieldIds` when creating a step:
+Add a field to a step with `step.addField()`. You can also pass an array of
+`fieldIds` when you create the step:
 
 ```ts
 const contactStep = createStep({
@@ -87,7 +90,7 @@ const contactStep = createStep({
 
 contactStep.addField(emailField)
 
-//Or
+// Or:
 
 const contactStep = createStep({
   id: 'contact',
@@ -96,9 +99,9 @@ const contactStep = createStep({
 })
 ```
 
-## Using conditions in an experience
+## Use a condition in an experience
 
-[Conditions](../conditions) are used to define when an experience will become active for the user.
+A [condition](../conditions) defines when an experience becomes active for the user.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'
@@ -125,7 +128,7 @@ const productPageFunnel = createExperience({
 })
 ```
 
-Navigation between steps is handled with [conditions](../conditions). Use the `create`
+A [condition](../conditions) also controls the move from one step to the next.
 
 ```ts
 import { createExperience, createStep } from '@picked/client/plugins/create-experience'

package/dist/docs/sdk/plugins/dynamic-experiences.md

@@ -4,9 +4,11 @@ layout: docs
 
 # Dynamic Experiences Plugin
 
-A plugin that fetches your project configuration from the Picked API at runtime, letting you manage experiences, feature flags, steps, fields, and conditions entirely from the [dashboard](/experiences).
+This plugin reads the options of your project from the Picked API at runtime. You can
+therefore control your experiences, feature flags, steps, fields, and conditions from
+the [dashboard](/experiences) alone.
 
-## Setup Plugin
+## Set the plugin up
 
 :::code-group
 
@@ -25,34 +27,58 @@ client.start()
 :::
 
 :::tip
-Unlike [createExperiencePlugin](./create-experience.md), you do not define experiences, steps, or fields in code. All configuration is managed from the [Picked dashboard](/experiences).
+With [`createExperiencePlugin`](./create-experience.md) you define an experience, a
+step, and a field in code. With this plugin you do not. You control every option from
+the [Picked dashboard](/experiences).
 :::
 
-## How It Works
+## How it works
 
-When the client starts, the plugin resolves your project configuration using a three-tier strategy:
+When the client starts, the plugin resolves the options of your project. It tries
+three sources, in this order:
 
-1. **Preview mode** — When you [enter preview mode from the dashboard](/workspaces#preview), the plugin fetches fresh config from the API. Feature flag decisions use session storage so they are not persisted beyond the current tab.
+1. **Preview mode** — after you [enter preview mode from the dashboard](/workspaces#preview),
+   the plugin reads fresh options from the API. A feature flag decision then uses
+   session storage, so it does not stay after you close the tab.
 
-2. **Build-time config** — If `projectConfig` was passed as a plugin option, or the [Vite Plugin](/vite-plugin) injected config at build time, the plugin uses that config with no network request.
+2. **Build-time options** — the plugin uses the options that it has already, and
+   makes no network request. This applies in two cases. You pass `projectConfig` as a
+   plugin option, or the [Vite Plugin](/vite-plugin) injects the options at build
+   time.
 
-3. **Runtime fetch** — Otherwise, the plugin fetches config from the API when the client starts.
+3. **Runtime read** — in every other case, the plugin reads the options from the API
+   when the client starts.
 
-Once resolved, the plugin registers all feature flags, conditions, fields, steps, and experiences with the client. Experiences then initialize according to their [conditions](/sdk/conditions) and [target selectors](/sdk/experiences).
+After the options resolve, the plugin registers every feature flag, condition, field,
+step, and experience on the client. Each experience then starts, and its
+[conditions](/sdk/conditions) and [target selectors](/sdk/experiences) decide
+whether it does.
 
 :::note
-The [Vite Plugin](/vite-plugin) eliminates the runtime API request in production by embedding your project config at build time. This is the recommended setup for Vite-based applications.
+The [Vite Plugin](/vite-plugin) embeds the options of your project at build time. In
+production there is therefore no API request at runtime. This is the recommended
+setup for an application that uses Vite.
 :::
 
 ## Feature flag allocation
 
-Each [feature flag](/sdk/features) in your project has an `enabled` state and a `weight` (0–100) that controls the percentage of traffic allocated to it. The plugin uses a deterministic hash of the user's session ID to produce a stable allocation value. A user whose value falls below the flag's weight is allocated to that flag — the same user always gets the same result.
+Each [feature flag](/sdk/features) in your project has an `enabled` state and a
+`weight` from 0 to 100. The weight controls what percentage of your traffic Picked
+allocates to the flag.
 
-Feature flag decisions are cached in `localStorage` by default, or `sessionStorage` when in [preview mode](#preview-mode).
+The plugin makes a deterministic hash from the session ID of the user, and that gives
+a stable allocation value. Picked allocates a user whose value is below the weight of
+the flag. The same user always gets the same result.
 
-## Preview Mode
+The plugin caches a feature flag decision in `localStorage` by default. In
+[preview mode](#preview-mode) it uses `sessionStorage`.
 
-When you [enter preview mode from the dashboard](/workspaces#preview), the SDK receives a preview token and activates preview mode:
+## Preview mode
 
-- The plugin fetches fresh config from the API using the token, bypassing any build-time or cached config
-- Feature flag decisions use session storage, so closing the tab resets them
+After you [enter preview mode from the dashboard](/workspaces#preview), the SDK
+receives a preview token and starts preview mode:
+
+- The plugin reads fresh options from the API with that token. It bypasses the
+  build-time options and the cached options.
+- A feature flag decision uses session storage. The decision resets when you close
+  the tab.

package/dist/docs/sdk/predicates.md

@@ -4,11 +4,15 @@ 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.
+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.
 
-## Defining Predicates
+## Define a predicate
 
-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:
+Define your predicates when you create the Picked client. Pass a `predicates` object.
+Each predicate needs a unique identifier and a function that takes a state snapshot:
 
 ```ts
 import { createClient } from '@picked/client'
@@ -21,24 +25,28 @@ const client = createClient({
     },
     'get-account-tier': async () => {
       const data = await fetch('/api/get-account-tier').then((r) => r.json())
-      return data.result // returns "trial"
+      return data.result // Returns "trial".
     },
   },
 })
 ```
 
-## How Predicates Work
+## How predicates work
 
-When a predicate is registered and used in conditions, the SDK follows this execution flow:
+After you register a predicate and a condition uses it, the SDK follows this 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
+1. **Registration**: you register each predicate on the Picked client at startup.
+2. **State snapshot**: the SDK gives the predicate a frozen state snapshot. The
+   snapshot holds the current responses, the fields, and the browser context.
+3. **Condition evaluation**: an experience condition invokes the predicate with a
+   fresh snapshot on each call.
+4. **Return types**: a predicate can return a boolean, a string, an array of
+   strings, or `undefined`. It can also return a promise that resolves to one of
+   those.
 
-## Using Predicates in Conditions
+## Use a predicate in a condition
 
-Predicates are most commonly used within condition logic via the `invoke` operator:
+Most predicates are used inside condition logic, through the `invoke` operator:
 
 ```ts
 const myExperience = createExperience({
@@ -49,10 +57,10 @@ const myExperience = createExperience({
         '==': [
           {
             invoke: {
-              var: 'predicates.is-example-page', // Reference predicate that calls user endpoint
+              var: 'predicates.is-example-page', // Points at a predicate that calls your endpoint.
             },
           },
-          true, // Check if return value is true
+          true, // Check that the return value is true.
         ],
       },
       {
@@ -62,7 +70,7 @@ const myExperience = createExperience({
               var: 'predicates.account-tier',
             },
           },
-          '/trial', // If string matches, evaluate to true
+          '/trial', // The condition is true when the string matches.
         ],
       },
     ],
@@ -71,42 +79,50 @@ const myExperience = createExperience({
 ```
 
 :::tip
-Predicates can also be used in `validation` logic
+You can also use a predicate in `validation` logic.
 :::
 
-## Using the State Snapshot
+## Use the state snapshot
 
-Each predicate receives a `StateSnapshot` object with the following properties:
+Each predicate takes a `StateSnapshot` object with these properties:
 
 ```ts
 interface StateSnapshot {
-  client: Picked // The Picked client instance
+  client: Picked // The Picked client.
   responses?: Array<{
-    // All user responses
+    // Every response from the user.
     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
+  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 or non-browser environments, `location`, `document`, `sessionStorage`,
-and `localStorage` will be `undefined`.
+In server-side rendering, and in any environment that is not a browser, `location`,
+`document`, `sessionStorage`, and `localStorage` are `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
+## Best practices
+
+- **Keep each predicate pure**: a predicate must be deterministic and free of side
+  effects. The same snapshot must always give the same result.
+- **Handle missing data**: check that a response or a field is there before you read
+  its value. Return `undefined` when the data is not available. Do not throw.
+- **Do not do heavy work**: the SDK can invoke a predicate many times. Keep the logic
+  small and fast.
+- **Use an async predicate only when you must**: the SDK supports one, but it can
+  make the experience slow to appear. Use synchronous logic where you can.
+- **Return one type**: do not return a boolean from a predicate one time and a string
+  the next.
+- **Use a meaningful name**: a predicate ID must say what the predicate evaluates,
+  such as `is-premium-user` or `has-items-in-cart`.
+- **Keep the result of expensive work**: when a predicate must do expensive work, put
+  the result in `localStorage` or `sessionStorage` inside the predicate.
+- **Do not change the snapshot**: the state snapshot is frozen. A change to it throws
+  an error in strict mode.