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

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

@@ -0,0 +1,176 @@
+---
+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.
+
+## 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
+
+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 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

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

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

@@ -0,0 +1,76 @@
+---
+type: explanation
+layout: docs
+---
+
+# About PickedQL
+
+PickedQL is SQL over your Picked analytics data, but it is not only SQL. It expands what
+you write before it runs. Why add a layer at all, and not give you the tables?
+
+## The problem it answers
+
+An A/B test question is short to ask, and the SQL behind it is not. Take one question:
+"How many users are in the control group?" It needs four things. It needs a filter on the
+variant, a count of distinct users, a join to each dimension in the group, and a tenant
+filter.
+
+Write that by hand for every question, and most of each query is the same text again.
+
+PickedQL lets you write the short version:
+
+```sql
+SELECT control_users(), variant_users()
+FROM metrics
+WHERE project_id = 'your-project-id'
+```
+
+## What it expands
+
+**Virtual tables.** A name such as `metrics` maps to the real tables below it. You name
+the thing that you ask about, and not the storage.
+
+**Virtual functions.** `control_users()` expands to a full aggregate expression. The
+definition lives in one place, so every report that counts control users counts them the
+same way.
+
+**Automatic joins.** Point at a dimension column such as `device_category` or
+`country_code` and PickedQL adds the `LEFT JOIN` for you. This gives you the most: a
+dimension that you did not join is the most common reason for a wrong answer that looks
+correct.
+
+**SQL passthrough.** Standard SQL still works next to a virtual function, and that
+includes `CASE WHEN`, window functions, and subqueries. The layer adds; it does not
+restrict.
+
+## Why every query must carry a tenant filter
+
+Every query must carry a tenant filter in its `WHERE` clause. That filter is `project_id`
+for most tables. The `projects` table uses `id` instead, because there the row ID *is* the
+project ID.
+
+PickedQL reads that filter and checks your permission for that project. The filter is
+therefore not a convention that you can forget. Without one, the query does not run.
+The isolation is a property of the language, and not of each author.
+
+## Which table to reach for
+
+| Table | Use it for |
+| --- | --- |
+| `metrics` | A dashboard. The data is aggregated first, so it is much faster than raw events. |
+| `events` | Anything deeper. Raw events let you build any breakdown or funnel. |
+| `experience_journey` | A sankey or a funnel chart. One line of SQL returns `source, target, users`. |
+
+Note what `experience_journey` does for you. It builds the eight common table expressions
+that a path analysis needs. Those remove the duplicates, rank the top paths, and call
+`lagInFrame`. You pass your parameters in the `WHERE` clause.
+
+Some reference columns are free on `events`. `step_title`, `experience_title`, and
+`project_name` come from reference tables that PickedQL joins for you.
+
+## Related
+
+- [PickedQL](/reference/pickedql) — the language surface.
+- [Data sources](/reference/pickedql/data-sources) — every table.
+- [Virtual functions](/reference/pickedql/virtual-functions) — every function.
+- [How to run an analytics query](/how-to/analytics) — worked examples.

package/dist/docs/explanation/pages-and-flows.md

@@ -0,0 +1,64 @@
+---
+type: explanation
+layout: docs
+---
+
+# About pages and flows
+
+An experience has two kinds, and the dashboard makes you choose
+between them when you create one. Why two, and how do you know which one a piece of work needs?
+
+## The two kinds
+
+| | Page | Flow |
+| --- | --- | --- |
+| What it is | A standalone experience that your server renders from a content entry. | An interactive experience of more than one step, which the browser renders. |
+| Use it for | A landing page or a campaign page where the search rank matters. | A quiz, a survey, a product finder, onboarding of more than one step. |
+
+The split is not about how complex the content is. It is about **who has to read it**.
+
+## Why the split exists
+
+A crawler and a social preview read the HTML your server returns. Neither waits for
+JavaScript in the browser. Content that a search engine must find is therefore
+content that must be in the first response. Only a server render puts it there.
+
+A flow has the reverse constraint. Its value is in the interaction: a visitor answers,
+the flow branches, the next screen depends on what came before. None of that can be in the
+first response, because none of it exists until the visitor acts.
+
+Choose a Page when the content must reach a search engine. Choose a Flow when the value is
+in the interaction and a browser render is acceptable.
+
+## What backs a page
+
+Four pieces sit behind every Page, and they are separate on purpose:
+
+1. A **page layout** sets the shape: which fields the page can hold.
+2. A **content entry** fills that shape with real data.
+3. A **Page** binds one entry, so the SDK can render it.
+4. The **SDK** reads the entry and renders it on your server.
+
+Layout and entry are separate because one layout backs many entries. Describe a campaign
+page one time, then make many pages from it. Change the layout and you must check every
+entry again. That is why the dashboard reports an invalid entry and does not serve it.
+
+A step layout does the same thing for one step inside a flow. The parts behave the same
+way. Only the thing that they give shape to is different.
+
+## They meet at the same publish
+
+Both kinds are experiences. Both live in a workspace, both go into the same immutable
+version, and both come out of the same Delivery API. The SDK decides where to render each
+one, and every step before that treats them the same way.
+
+This matters, because it means a project mixes them freely. A server-rendered
+landing page can carry a browser-rendered quiz inside it.
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — the path that both kinds take.
+- [About server-side rendering](/explanation/why-server-side-rendering) — how a Page
+  reaches the browser.
+- [Pages](/reference/dashboard/content/pages) — the page editor.
+- [Experiences](/reference/dashboard/experiences) — the flow options.

package/dist/docs/explanation/the-content-model.md

@@ -0,0 +1,77 @@
+---
+type: explanation
+layout: docs
+---
+
+# About the content model
+
+Picked splits your content into three pieces: a layout, a section, and a content entry.
+Why three, when a page editor needs only one?
+
+## Schema and data are separate
+
+A **layout** is a schema. It sets which fields a piece of content can hold, and it holds
+no data itself. A **content entry** is one instance of that schema, filled with real
+values.
+
+One layout backs many entries. Describe a campaign page one time, then make many pages
+from it. Each entry carries its own title, its own body, and its own image, but they all
+share the shape.
+
+That split is also what lets your code depend on content that it never saw. Your component
+reads `content.title` because the layout promises a `title`. It works for every entry that
+comes from that layout.
+
+## A layout has a fixed category
+
+Each layout is a **page layout** or a **step layout**, and you choose which when you
+create it. The category cannot change later.
+
+| Layout | It gives shape to | Who renders it |
+| --- | --- | --- |
+| Page layout | A standalone [Page](/reference/dashboard/content/pages). | The SDK renders the entry on your server. |
+| Step layout | One [Step](/reference/dashboard/steps) inside a Flow. | The Step renders the entry in the browser. |
+
+The category is fixed because it decides where the SDK renders the entry. That is not a
+property you can change under an entry that exists already. See
+[About pages and flows](/explanation/pages-and-flows).
+
+## A section is a schema fragment
+
+A layout gives shape to a whole page or a whole step. A **section** is a part that you put
+inside one or more layouts.
+
+Define a hero one time as a section, then point at it from every page layout that needs
+one. Change the section and every layout that holds it changes with it.
+
+This is the reason sections exist at all. Without them you must describe a common
+structure again in each layout, and the copies then become different. It is the same
+argument for one fact in one place that runs through the rest of this documentation.
+
+## Why a schema change does not migrate your data
+
+Change a layout or a section, and Picked does not rewrite the entries behind it. An entry
+that no longer matches its schema becomes invalid, and the dashboard shows an error on
+each field that does not fit.
+
+That is deliberate. An automatic change must decide what a new required field holds for
+every entry that came before it. Any value that it chooses is content that nobody wrote.
+Picked reports the error instead, and you correct it.
+
+The cost is real. After a schema change, check every entry that uses that layout and fix
+each error before you publish. Picked serves valid content only, so an entry with an error
+does not reach a visitor.
+
+## An error points at the exact field
+
+A validation error carries a path in JSON style, such as `sections[0].data.title`. The
+path holds through nested groups, repeated fields, and sections. An error inside a
+repeated group therefore tells you which item in that group holds it.
+
+## Related
+
+- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
+- [Sections](/reference/dashboard/content/sections) — the reusable fragments.
+- [Content entries](/reference/dashboard/content/content-entries) — the editor and the
+  validation.
+- [About pages and flows](/explanation/pages-and-flows) — which layout category you need.

package/dist/docs/explanation/the-two-apis.md

@@ -0,0 +1,68 @@
+---
+type: explanation
+layout: docs
+---
+
+# About the two APIs
+
+Picked has two HTTP APIs, and a new reader often reaches for the wrong one. This page
+covers which is which and why they are separate.
+
+## The split
+
+| | Delivery API | Management API |
+| --- | --- | --- |
+| Style | REST | GraphQL |
+| Access | Public, anonymous | Authenticated |
+| Operations | Read-only | Read and write |
+| Base | `https://api.picked.app/api/v1` | `POST https://api.picked.app/api/graphql` |
+| Use it to | Serve published configuration and content to your application | Control your projects, experiences, and content |
+
+The short rule is this: **the Delivery API serves your visitors, and the management API
+serves you.**
+
+## Why they are not one API
+
+Three properties of the delivery path make it a different kind of API.
+
+**It is anonymous.** A crawler must read your published page content with no credential at
+all. An API that requires a token cannot serve a search engine, and an API that serves a
+search engine cannot require one.
+
+**It is cacheable.** A published response is the same for every reader, so a shared cache
+can hold it. The Delivery API sends `s-maxage` for an SDK request, and it sends
+`Vary: Picked-Client`. A GraphQL endpoint that takes any query over a `POST` has none of
+those properties.
+
+**It is read-only.** Nothing that a reader reaches without a credential can change your
+data. Every write stays on a separate authenticated surface, so that property holds by
+design.
+
+## What the Delivery API serves
+
+Two endpoints, and the SDK calls both:
+
+- **Project config** returns the published configuration of a project: its experiences and
+  steps, and the content link on each step.
+- **Experience content** returns the content entries behind an experience.
+
+Your server usually calls the first and lets `serialize()` call the second. See
+[About server-side rendering](/explanation/why-server-side-rendering).
+
+## How a preview stays out of the search index
+
+A preview needs unpublished content, and by the definition of it that content is not
+public. The Delivery API takes a `preview_token` query parameter for exactly that. It then
+treats the result differently. `versionId` comes back `null`, the response is `no-store`,
+and `robots.txt` does not allow the preview path.
+
+That last part matters more than it looks. A draft that anybody can read over an anonymous
+URL is a draft that a search engine can find. A campaign page that is only part complete
+can then appear in the search results of a customer.
+
+## Related
+
+- [Delivery API](/reference/delivery-api) — the endpoints and their responses.
+- [Management API](/reference/management-api/authentication) — authentication and scopes.
+- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — the
+  exact cache rules and `robots.txt` rules.

package/dist/docs/explanation/why-server-side-rendering.md

@@ -0,0 +1,76 @@
+---
+type: explanation
+layout: docs
+---
+
+# About server-side rendering
+
+Why does a Page need a snapshot, when the SDK can fetch its content in the browser?
+Because the reader that matters most does not run JavaScript.
+
+## The constraint
+
+A crawler and a social preview read the HTML your server returns, and they do not wait for
+the browser to fetch anything. If the content of a Page arrives after the first response,
+those readers never see it.
+
+So the content has to be in the HTML. That means your server has to know, before it
+answers, which experiences match this URL and what their content is.
+
+## What the snapshot is for
+
+`serialize()` answers that question on the server. It registers your project configuration and
+evaluates each experience condition against the URL. It then reads the content for each
+experience that matches, and returns a `PickedSnapshot` as plain JSON.
+
+```
+projectConfig (Delivery API)
+  -> serialize(client, params) on the server -> PickedSnapshot
+  -> embed snapshot in HTML
+  -> client seeds from snapshot -> renders the same markup -> hydrates
+```
+
+The snapshot carries the exact options the server chose with, and the condition results it
+reached. The first render in the browser therefore reuses the decisions of the server. It
+does not evaluate them a second time.
+
+That last point is the whole reason the snapshot holds condition results and not only
+content. A browser that evaluates the conditions itself can reach a different answer. A different URL shape, a
+different time, or a different flag value each give a different result. The markup then does not
+match what the server sent, and hydration discards the server HTML. That failure is the
+one server-side rendering exists to prevent.
+
+## Why a slot instead of a selector
+
+A browser-rendered flow points at a DOM selector, and the SDK inserts the component next
+to the element that it finds. That cannot work on a server, because a server has no DOM
+to search.
+
+A slot reverses that. `<ExperienceSlot name="page" />` is a mount point that you place in
+your own markup. An experience joins it when its target selector is `.picked-slot-<name>`.
+Your component tree decides where the content goes, so the server renders it in one pass.
+
+## Why placements have an order
+
+More than one experience can point at the same slot, so the slot needs a rule. The order
+is:
+
+```
+replace -> before -> prepend -> append -> after
+```
+
+`replace` wins: an active experience with that placement renders alone. Every other active
+experience renders in the order above.
+
+The rule exists so the outcome does not depend on which experience came first. Two editors
+can add an experience to the same slot on the same day. The result then follows from the
+placements, and not from the database.
+
+## Related
+
+- [Your first server-rendered page](/tutorials/first-server-rendered-page) — the whole
+  path, in practice.
+- [Server snapshot](/reference/sdk/ssr/serialize) — every `serialize()` parameter.
+- [Slots and placements](/reference/sdk/ssr/slots-and-placements) — the exact rules for
+  the order.
+- [About pages and flows](/explanation/pages-and-flows) — which kind you need.