@picked/client 0.0.101-next.1 → 0.0.101-next.3

package/dist/docs/_root.css

@@ -1,101 +0,0 @@
-/*
- * Site font. Vocs 2 has no `font` config option, so Inter is declared here.
- */
-@import url('https://fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap');
-
-:root {
-  --vocs-fontFamily-default: 'Inter', sans-serif;
-}
-
-/*
- * Embed mode — activated by the ?embed query param.
- * Hides site chrome (gutters, top nav, sidebar, outline, footer) so the docs
- * content can be displayed inside an iframe in the dashboard's docs panel.
- *
- * Every selector targets a `data-v-*` attribute. These are the hooks Vocs
- * publishes for styling its layout, and they are what this file must use:
- * matching on class names instead would bind to generated Tailwind utilities
- * that carry no compatibility promise, and a rename would break the dashboard's
- * docs panel silently — build and tests stay green while the panel renders with
- * a sidebar and a top nav inside it.
- *
- * Nothing automated covers the visual result. After any Vocs upgrade, open the
- * dashboard docs panel and look at it.
- */
-
-/*
- * Hide the gutters. These hold the top nav, the sidebar and the outline, so
- * hiding them removes the chrome in one step.
- *
- * Do NOT add `[data-v-sidebar]` or `[data-v-topnav]` here. Those sit on the
- * layout root as flags describing which regions the layout has — the root
- * carries both — so hiding them blanks the entire page, content included.
- */
-.vocs-embed [data-v-gutter-top],
-.vocs-embed [data-v-gutter-top-left],
-.vocs-embed [data-v-gutter-left],
-.vocs-embed [data-v-gutter-right],
-.vocs-embed [data-v-gutter-logo],
-.vocs-embed [data-v-mobile-nav] {
-  display: none !important;
-}
-
-/* Hide the sidebar's own container and the curtains behind it */
-.vocs-embed [data-v-sidebar-container],
-.vocs-embed [data-v-sidebar-curtain],
-.vocs-embed [data-v-sidebar-footer-curtain] {
-  display: none !important;
-}
-
-/*
- * Hide the surface layer that paints the sidebar and top-nav backgrounds.
- * It sits behind the chrome rather than inside it, so hiding the gutters alone
- * leaves its fill behind as a ghost panel down the left edge.
- */
-.vocs-embed [data-v-surface-bg] {
-  display: none !important;
-}
-
-/*
- * Hide the "Ask AI" prompt. The dashboard embeds these pages beside its own
- * agent, so a second assistant entry point inside the panel competes with it.
- */
-.vocs-embed [data-v-ask-ai-container] {
-  display: none !important;
-}
-
-/*
- * Hide the mobile outline trigger, the footer, the skip link and the bottom
- * observer. The outline and footer render on the client rather than into the
- * prerendered HTML, so they are covered here even though a static build of this
- * site does not emit them.
- */
-.vocs-embed [data-v-outline],
-.vocs-embed [data-v-outline-mobile],
-.vocs-embed [data-v-footer],
-.vocs-embed [data-v-skip-to-content],
-.vocs-embed [data-bottom-observer],
-.vocs-embed footer {
-  display: none !important;
-}
-
-/* Reclaim the space the hidden gutters and top nav were holding */
-.vocs-embed [data-v-main] {
-  margin-left: 0 !important;
-  padding-top: 0 !important;
-}
-
-/* Expand content to fill the embed viewport */
-.vocs-embed [data-v-content] {
-  max-width: 100% !important;
-  margin-left: auto !important;
-  margin-right: auto !important;
-  padding-left: 1.25rem !important;
-  padding-right: 1.25rem !important;
-}
-
-/* Remove the top margin on the first child so there is no gap at the panel top */
-.vocs-embed article > :first-child,
-.vocs-embed [data-v-content] > :first-child {
-  margin-top: 0 !important;
-}

package/dist/docs/explanation/conditions-and-the-logic-engine.md

@@ -1,94 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About conditions and the logic engine
-
-A condition decides whether a visitor sees something. One rule format covers every one of
-those decisions, both in the dashboard and in code. This page covers why there is one
-engine, and what it can reach.
-
-## One rule format, many places
-
-The dashboard uses the visual condition builder in four places, and the SDK evaluates the
-same rules in each:
-
-- **Condition nodes** decide which branch a flow takes.
-- **Experience conditions** decide whether an experience starts for a visitor.
-- **Initialize-open conditions** decide whether an experience opens by itself.
-- **Field option conditions** show or hide one option in a field.
-
-One format means one model to learn. Learn how a rule reads in the flow builder, and you
-can read the rule that gates an experience.
-
-## What a rule looks like below
-
-A rule is JSON Logic. The visual builder writes it for you, and you can also write it
-directly in SDK code:
-
-```ts
-{
-  '==': [{ var: 'responses.country' }, 'US']
-}
-```
-
-Rules sit in groups, and each group is an **AND** or an **OR**. Put a group inside another
-group to build a larger rule.
-
-The format is data, and not code. That is the point. A rule travels from the dashboard to
-the browser inside the published snapshot. A function cannot travel that way.
-
-## What a rule can read
-
-| Source | What it holds |
-| --- | --- |
-| **Responses** | The values your visitors send through the fields of the current experience. |
-| **Actions** | The actions that ran during the flow. |
-| **Feature flags** | Whether Picked allocates this visitor to a flag. |
-| **Location** | The parts of the current URL: pathname, search parameters, hostname, and hash. |
-
-Each one is state the SDK already holds, which is why a rule evaluates without a network
-request.
-
-## Predicates are the escape hatch
-
-The four sources above cover what Picked knows. They do not cover what *your application*
-knows: a cart total, an account level, or the profile of a signed-in user.
-
-A **predicate** gives you that. It is a function that you register on the client, and a
-rule invokes it by name:
-
-```ts
-{ invoke: { var: 'predicates.has-items-in-cart' } }
-```
-
-The predicate receives a frozen state snapshot and returns a boolean, a string, an array
-of strings, or `undefined`. Because a rule can invoke one, the visual builder in the
-dashboard reaches your application data, and nobody writes JSON Logic by hand.
-
-A predicate must stay pure and fast. The SDK can invoke it many times while it evaluates a
-flow, and everything that waits on the rule waits on the predicate.
-
-## Why a precondition is not a condition
-
-The client takes two gates, and they answer different questions:
-
-| Gate | Question |
-| --- | --- |
-| Precondition | Must Picked start at all? |
-| Condition | Is this visitor eligible? |
-
-A precondition runs at startup, and that has a result which catches people out. A
-precondition that points at a feature flag reads the bucket of that flag, and a read is
-what allocates the visitor. Every visitor is therefore allocated to that flag before
-anything else happens, and that includes a visitor who never reaches the experience the
-flag controls. See
-[About feature flag allocation](/explanation/feature-flag-allocation).
-
-## Related
-
-- [Condition builder](/reference/dashboard/flow-builder/condition-builder) — the visual
-  editor.
-- [SDK conditions](/reference/sdk/conditions) — the JSON Logic shapes.
-- [Predicates](/reference/sdk/predicates) — the state snapshot and the return types.

package/dist/docs/explanation/content-references.md

@@ -1,99 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About content references
-
-A [Reference field](/reference/dashboard/content/models#reference-fields) points one
-content entry at another. Why a pointer, when Picked can put the content into the entry
-that needs it?
-
-## A pointer keeps one fact in one place
-
-A product points at its category. Ten products can point at the same category.
-
-A copy makes ten categories. Correct the name of the category and you must correct it ten
-times. The copy that you do not correct is now wrong.
-
-A pointer makes one category. Correct the name one time, and every product that points at
-it is correct.
-
-This is the same reason that Blocks exist, one level up. A Block shares a *shape* between
-entries. A reference shares an *entry* between entries.
-
-## The target travels beside the content
-
-Picked sends the entries of your steps in `content`. It sends the entries that a
-reference reaches in `references`. Both go into the same content index in the SDK, keyed
-by the id.
-
-Picked can put the target inside the field instead, and it did so before. Three things
-count against that.
-
-A shared target costs one blob, and not one blob for each entry that points at it. Ten
-products with the same category send the category one time.
-
-A separate entry has an id. Your code reads it with `useContent(id)`, and live preview
-updates it while you edit. A target inside a field has no id, so an update finds nothing
-to change.
-
-The reader chooses how deep to go. A component that shows a category reads the category.
-A component that shows a card reads the product only, and it costs nothing more.
-
-## Picked stops a chain at a depth of five
-
-Content can point at content that points at content. Such a chain has no end of its own.
-A cycle has none at all. Two entries that point at each other keep the chain open for as
-long as something asks.
-
-Picked therefore resolves a chain to a depth of five. It counts the depth from the
-entries that your steps point at. It also keeps the entries that it saw, so that a cycle
-stops.
-
-Five is a choice, and not a rule of the system. It is deep enough for the shapes that
-content takes, such as a product, its category, and the owner of that category. It is
-also small enough that one page cannot pull a whole workspace over the wire.
-
-## A missing entry is how Picked says "no such entry"
-
-Picked sends no blob for a pointer whose target it cannot resolve. The entry is absent
-from `references`.
-
-The other option is a blob with no data. That reads as an entry that exists and is empty,
-which is a different fact from an entry that is not there.
-
-Your code cannot tell one from the other. The empty record also goes into the content
-index under an id that resolves. A missing entry looks like nothing else.
-
-## A delete stops while a reference is live
-
-Picked does not delete an entry that another entry points at. It does not delete a Model
-that a Reference field holds as its target.
-
-The other option is a pointer at nothing. Picked must then choose what the field holds,
-and every answer is wrong. It can give your component an empty value that the component
-does not expect. It can also remove content that somebody wrote, with no report.
-
-A stop costs you one step. Clear the reference, then delete the target. In return, a
-field that holds a pointer always points at something that exists.
-
-## A reference stays inside its workspace
-
-A field cannot point at an entry in another workspace. Picked reports such a target as
-unknown.
-
-A workspace is one version of the configuration of a project, and you publish it whole. A
-pointer that leaves the workspace resolves against content that this workspace never
-sent. The two sides can then go live at different times.
-
-The delivery surface applies the same rule on a read, so a target outside the workspace
-never reaches a visitor.
-
-## Related
-
-- [Models](/reference/dashboard/content/models) — the field and its options.
-- [Content entries](/reference/dashboard/content/content-entries) — the editor and the delete rules.
-- [Content](/reference/sdk/content) — how your code resolves a pointer.
-- [Experience content endpoint](/reference/delivery-api/experience-content) — the wire shape.
-- [About the content model](/explanation/the-content-model) — why a schema and its data are separate.

package/dist/docs/explanation/feature-flag-allocation.md

@@ -1,218 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About feature flag allocation
-
-When does a visitor enter a test, and what decides the group they land in? The answer is
-not "when you create the feature flag" and not "when the page loads". It is the moment something
-reads the bucket, and that moment is yours to choose.
-
-## A registration is not a decision
-
-The SDK loads every feature flag in your project at startup. It allocates nobody 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 the bucket records an exposure
-
-The first read is the decision, so it is also the moment the visitor enters the test. If
-you read every feature flag at startup, every visitor counts as exposed to every test. That
-includes a test the visitor never reached.
-
-Read a feature flag where the decision matters: after the cart loads, after the quote returns, or
-after you know who the visitor is. A feature flag that you read before that point puts a visitor in
-a test they never saw, and the uplift number then means nothing.
-
-## A condition reads the bucket, so a condition allocates
-
-Most reads are not calls that you write. They come from a condition. A condition that
-points at a feature flag with `invoke: { var: 'features.<id>' }` must have the bucket
-before it can compare it. That read allocates the visitor, exactly as a call in your own
-code does.
-
-Where the condition sits therefore decides who enters the test:
-
-| The condition is | It runs | Who enters the test |
-| --- | --- | --- |
-| An experience condition | When Picked evaluates that experience | Only a visitor who reaches the experience |
-| A precondition | At startup, before anything else | Every visitor who loads the page |
-
-A precondition that points at a feature flag allocates every visitor on your site, and it
-does so before the visitor sees anything. Keep a feature flag out of a precondition unless
-it truly controls whether Picked starts at all.
-
-Keep each `decide` function fast for the same reason. Everything that waits for the
-condition waits for `decide`, and that includes the experience itself. A network call
-inside `decide` delays what the visitor sees.
-
-## How Picked chooses
-
-For a feature flag you control from the dashboard the choice is deterministic. Picked
-gives each visitor a stable value for each feature flag. It derives that value from the
-visitor ID and from the ID of the feature flag, and it compares the value against the
-weight. Picked allocates the visitor when the value is below the weight.
-
-The same visitor gets the same result for one feature flag on every visit, while the
-weight stays the same.
-
-That is also why a feature flag you control from the dashboard cannot use the data of
-your application in its decision. The value comes from the visitor ID, the feature flag
-ID, and the weight, and from nothing else. Define the feature flag in SDK code when the
-decision needs a cart, a quote, or a profile.
-
-## More than two groups
-
-A Text feature flag has a table of variants, and each variant is one group. Picked
-allocates a visitor to exactly one of them, and the control group is one of the rows.
-
-The two types decide by different routes, and the difference matters if you compare them:
-
-| Type | Picked compares | Against |
-| --- | --- | --- |
-| Boolean | The stable value of the visitor, out of 100 | The weight |
-| Text | One stable value for each variant | The weight of that variant |
-
-A Text feature flag gives each variant a score. Picked makes the score from the visitor
-ID, the feature flag ID, and the key of the variant. The weight of the variant then scales
-that score. The variant with the best score receives the visitor.
-
-The weight of a variant therefore changes the score of that variant alone. No other
-variant moves because of it.
-
-A Boolean feature flag makes the same comparison it always has. A feature flag that you
-made before variants existed therefore keeps every visitor where it put them.
-
-Picked derives the stable value from the visitor ID and from the ID of the feature flag,
-for both types. The two types are therefore independent of each other in the same way that
-two feature flags are.
-
-**The order of the rows has no effect.** Picked scores each variant from its key, and the
-key of a variant never changes. Move a row in the dashboard and the
-visitors stay where they are. The order that you see is the order that you chose to read
-them in, and nothing more.
-
-Rename a variant and nothing changes. The name travels no further than the dashboard.
-
-Change the string that a variant serves and the visitors stay in the same group, but your
-site and your reports receive the new string. A visitor with a decision in browser storage
-keeps the old string until you increment the version.
-
-## Each feature flag is independent
-
-Picked builds that value from the visitor ID together with the ID of the feature flag.
-Each feature flag therefore gets its own value, and tests that run at the same time are
-independent of each other.
-
-Two feature flags, both at weight 50, split your visitors into four equal parts:
-allocated to both, to one, to the other, or to neither. Three feature flags at weight 50
-give eight groups of 12.5%. Add a feature flag and the groups divide again.
-
-This is what lets you read two experiments separately. Give every feature flag the same
-value, and two feature flags at weight 50 hold exactly the same visitors. Your analytics
-then never sees the mixed groups that tell one result from the other.
-
-## The allocation ratchets
-
-The ratchet applies to both types of feature flag. Inside one feature flag, a larger
-weight only adds visitors. Everybody allocated at
-weight 30 is still allocated at weight 50. The allocation is a **ratchet**: it turns one
-way, and a larger weight never moves a visitor back out.
-
-That property is what makes a staged release safe. A visitor who sees the change at 10%
-still sees it at 20%. A smaller weight is the reverse turn. It removes visitors from the
-top of the range, and every visitor below the new weight keeps what they had.
-
-A Text feature flag has the same ratchet, one variant at a time. A larger weight on one variant only
-adds visitors to that variant. A smaller weight only removes them. Two variants that you
-do not change never exchange visitors with each other.
-
-## A disabled feature flag records nothing
-
-A disabled feature flag allocates nobody, and the difference from a weight of 0
-matters for your reports. At weight 0 the visitor is in the test, and in the
-control group. When the feature flag is disabled, the visitor is not in the test at all.
-
-The SDK does not evaluate a disabled feature flag. It writes no decision to browser
-storage and it reports no decision. The feature flag is also absent from the feature
-list on every analytics event. Expect a step change in your reports when you disable
-one: fewer feature flags for each visitor, and fewer decision events.
-
-This state is temporary. A visitor allocated before you disabled the feature flag keeps
-that bucket in the browser. When you enable the feature flag again, that visitor continues
-in the same group.
-
-## What a version does, and what it does not
-
-Each feature flag carries a version, and it starts at 1. The SDK caches the bucket in
-browser storage under a key that holds the feature flag ID and the version. A visitor
-therefore keeps the same bucket across page loads.
-
-Change a weight and leave the version as it is, and that cache decides the result. A
-visitor who has a cached bucket keeps it. The new weight reaches only a visitor who has no
-cache. Your reports then hold two groups of visitors at the same time, one measured
-against the old weight and one against the new.
-
-Increment the version and the old cache key no longer matches. The feature flag counts as
-undecided, `decide` runs again on the next page load, and every visitor is measured
-against the new weight. Increment it after each weight change, unless you intend the
-change to reach new visitors only.
-
-**The version affects the cache only. It is not part of the allocation.** The ratchet
-still holds after you increment the version: a visitor allocated at weight 30 is allocated
-again at weight 50. You cannot decrement a version.
-
-## When the SDK reports a decision
-
-The SDK sends `feature_decide` the first time that it allocates a visitor to a bucket,
-and only then. On a later page load it restores that bucket from browser storage and sends
-nothing. A visitor who returns therefore produces no `feature_decide` event, although that
-visitor is still in the group they went into the first time.
-
-An integration that listens only for `feature_decide` under-reports every visitor who
-returns. Choose the source that matches your question:
-
-| Question | Source |
-| --- | --- |
-| Which bucket is this visitor in now? | [`client.features.listStore`](/how-to/read-a-feature-flag#1-choose-an-accessor) |
-| Did the SDK allocate a visitor now? | [`feature_decide` on `client.eventBus`](/reference/sdk/features#watch-for-feature-flag-decisions) |
-| Which allocations happened before I subscribed? | [`client.events`](/reference/sdk/features#read-the-events-that-already-happened) |
-
-`listStore` updates each time that a feature flag resolves. It does this whether the SDK
-restored the bucket from storage or allocated the visitor now. A watch on it therefore
-always gives the current state.
-Use `feature_decide` only when you need to know that Picked allocated a visitor at that
-moment.
-
-## What Picked reports for you
-
-Every Picked analytics event carries a `feature_list` context, and a report of your own
-can use it. The context describes each feature flag that this visitor resolved: the
-feature flag ID, the name, the version key, and the bucket. Only a resolved feature flag
-appears there, so the context shows what the visitor was exposed to at the time when the
-event fired.
-
-The optional [Sentry plugin](https://www.npmjs.com/package/@picked/sentry) also tags each
-allocation onto the Sentry scope as `picked.feature.<id>`, with the bucket as the value.
-You can then filter your errors by the variant.
-
-## Preview mode
-
-In preview mode the SDK stores the bucket in session storage and not in local storage. The
-bucket 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.
-
-A feature flag that you define in SDK code can ask for the same thing in production with
-`storage: 'session'`. Use it for a short test that must not last across browser sessions.
-
-## Related
-
-- [How to read a feature flag](/how-to/read-a-feature-flag) — the accessors, and which
-  ones resolve the feature flag.
-- [Feature flags](/reference/dashboard/features) — the dashboard controls.
-- [SDK feature flags](/reference/sdk/features) — the definition shape and the accessor
-  table.

package/dist/docs/explanation/how-picked-works.md

@@ -1,124 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About how Picked works
-
-What happens between the moment an editor clicks **Publish** and the moment a visitor
-sees the result? This page follows one change through the whole system.
-
-## The shape of it
-
-Picked splits into two parts that meet at a published snapshot.
-
-```
-Author (dashboard) -> Publish -> Delivery API (config + content)
-  -> SDK reads it -> conditions decide -> component renders
-```
-
-On the left, an editor works in a workspace. Nothing they do reaches a visitor. On the
-right, the SDK in your application reads what was published and renders it. The snapshot
-between them is immutable, so each part moves at its own speed. An editor publishes with
-no deployment, and you deploy with no change to the content.
-
-## What happens when you publish
-
-Picked takes the current workspace and makes an immutable snapshot of it. The result is a
-version, and a project serves exactly one version at a time, the live one. Nothing in a
-published version can change later. A roll-back moves the live pointer of the project to
-an earlier version, and it changes no data.
-
-That is why the dashboard has a draft state at all. The workspace holds the work that is
-still in progress. The version holds what your visitors get.
-
-## What the SDK does at startup
-
-`createClient()` builds the client, and `client.start()` runs it. Between those two calls
-nothing happens yet.
-
-1. **Options resolve.** The dynamic experiences plugin reads the configuration of your
-   project from the source that its `mode` names. That is the data in your bundle, or a
-   request to the Delivery API. A preview token replaces both.
-2. **Everything registers.** The plugin registers every feature flag, condition, field,
-   step, and experience from that configuration. You declare none of them in code.
-3. **Preconditions run.** A precondition asks whether Picked should start at all. A
-   condition asks whether this visitor is eligible.
-4. **Experiences resolve.** Each experience evaluates its condition and looks for its
-   target element in the page.
-5. **Components render.** An experience whose condition is true, and whose target exists,
-   renders the component you registered under its component name.
-
-Step 1 is why the [Vite plugin](/reference/tools/vite-plugin) exists: it embeds the
-options at build time, so production makes no request at startup.
-
-## Why the browser and the server can read from different places
-
-The two ends of a server-rendered page want different things. Your server wants a new
-version to reach visitors at once. That needs a request to the API. The browser wants no
-request at all. That needs the data in your bundle.
-
-The `mode` option belongs to one end only, so you can have both. Give `'api'` to your
-server and `'bundle'` to your browser.
-
-Each end stays consistent with itself. The configuration and the content that one end
-reads always come from the same source. Picked gives them the same version.
-
-The two ends can still hold different versions. An editor publishes a workspace between
-your build and the request, which moves the server to a newer version than the bundle.
-The snapshot from the server then wins. The browser keeps it, and drops the configuration
-that it read.
-
-The reason is that the server made the page from that snapshot. To register a different
-configuration over the top makes the page and the client show different data. One
-version behind is the safer of the two results. The client records the two version IDs on
-`client.versionSkew`, and the [devtools](/reference/tools/chrome-extension) show them.
-
-## Why the flow is a graph
-
-An experience is not a list of screens. It is a directed graph, and the SDK walks it.
-
-The origin node is the entry point. From there each edge leads to a step, an action, or a
-condition. A step waits for the visitor. An action runs a side effect and does not
-interrupt them. A condition evaluates a rule and sends the flow down one of two paths.
-
-The walk is what makes a branch cost so little. To show a different screen to a different
-visitor you add a condition node, and not a second copy of the flow. The same step can
-appear in several flows, because a step belongs to the project and the graph only
-points at it.
-
-## How an action decides which way to go
-
-An action node can carry a success branch and a failure branch, and the SDK picks between
-them from the outcome of your handler:
-
-- The handler **throws**, or its promise rejects: the flow takes the failure branch.
-- The handler **resolves** to any value at all, and that includes `false`: the flow takes
-  the success branch.
-
-This difference matters more than it looks. A valid negative result is not a failure. An
-endpoint that answers `200` with `{ serviced: false }` succeeded — it told you something
-true. Record that value as a response and branch on it with a condition. Keep the failure
-branch for a request that did not complete.
-
-Get this wrong and your failure branch holds two different things at once: a network
-error, and a visitor who lives outside your service area.
-
-## Where content comes in
-
-A flow renders in the browser. A page renders on your server, from content held in the
-Picked CMS, so a search engine reads it in the first response. Both are experiences, and
-both go through the same publish.
-
-The difference is only the place where each one renders, and that follows from what the
-content is for. See [About pages and flows](/explanation/pages-and-flows) and
-[About server-side rendering](/explanation/why-server-side-rendering).
-
-## Related
-
-- [Add Picked to your application](/tutorials/first-experience) — the whole path, in
-  practice.
-- [About workspaces and versions](/explanation/workspaces-and-versions) — draft, live,
-  and roll-back.
-- [Delivery API](/reference/delivery-api) — what the published snapshot looks like on the
-  wire.