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

package/dist/docs/chrome-extension.md

@@ -1,68 +0,0 @@
----
-layout: docs
----
-
-# Chrome Extension
-
-The extension for the Picked Developer Tools adds a Picked panel to Chrome DevTools.
-Use the panel to check and debug your Picked integration on any page that runs the
-SDK.
-
-![Picked Developer Tools](/chrome-extension-screenshot.jpg)
-
-## Installation
-
-Install the extension from the
-[Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
-
-## Setup
-
-Add the `svelteDevtoolsPlugin` to your Picked client. The extension then connects to
-the SDK.
-
-```typescript
-import { createPicked } from '@picked/client'
-import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
-
-const picked = createPicked({
-  projectId: 'your-project-id',
-  plugins: [
-    svelteDevtoolsPlugin(),
-  ],
-})
-```
-
-## Custom Tools
-
-You can extend the Developer Tools with your own tools for one project. They appear
-under a **Custom Tools** tab.
-
-Each tool is a framework-adapted component. Write it with the same
-`adaptReactComponent` or `adaptSvelteComponent` helper that you already use. You can
-therefore build the tool in the framework of your application.
-
-The tool receives the live Picked client, exactly as an experience component does. In
-React, use `usePicked()`. In Svelte, use `getPicked()`. A tool can read client state
-and call client methods.
-
-```typescript
-import { createPicked } from '@picked/client'
-import { adaptReactComponent } from '@picked/react'
-import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
-import MyTool from './MyTool'
-
-const picked = createPicked({
-  projectId: 'your-project-id',
-  plugins: [
-    svelteDevtoolsPlugin({
-      customTools: [{ id: 'my-tool', label: 'My Tool', component: adaptReactComponent(MyTool) }],
-    }),
-  ],
-})
-```
-
-Svelte renders the Developer Tools shell, so you must also register the framework of
-your tool on the client. A React application needs `reactFrameworkPlugin` for the
-tool, together with the Svelte framework and `svelteDevtoolsPlugin` for the shell.
-When the framework of a tool is not registered, the tab of that tool shows a warning
-and no content.

package/dist/docs/conditions.mdx

@@ -1,72 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Conditions
-
-A condition evaluates a rule and splits the flow into two paths. One path is for a
-true result, the other for a false result.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/conditions"
-  alt="The conditions list for a workspace on the Picked dashboard"
-/>
-
-## Create a condition
-
-1. Open your project.
-2. Click **Conditions** in the sidebar.
-3. Click **New Condition**.
-4. Enter a name and a key.
-5. Click **Create**.
-
-## Set up a condition
-
-**Name**: The name that the dashboard shows. Your visitors do not see it.
-
-**Key**: The identifier for your application. You set it once and you cannot change
-it. Your visitors do not see it.
-
-## Define the rule
-
-Choose a condition node in the flow builder to open its inspector. The **Logic**
-section holds a visual [condition builder](/flow-builder/condition-builder).
-
-The condition builder lets you write a rule with AND groups and OR groups. Each rule
-compares a data source against an operator and a value.
-
-### Data sources
-
-**Responses** — the values that your visitors send through form fields. An example is
-a check of whether a visitor entered one email domain, or chose one option.
-
-**Actions** — the actions that ran during the flow.
-
-**Feature flags** — the state of each feature flag in your project. Branch on whether
-Picked allocates a visitor to a flag.
-
-**Location** — the parts of the current page URL of the visitor. These are the
-pathname, the search parameters, the hostname, and the hash. An example is content
-that changes with the page that the visitor is on.
-
-### Example
-
-To take a branch on the country that a visitor chooses:
-
-1. Add a rule: **Responses → country** equals `US`.
-2. The green path, for a true result, handles a visitor in the US. The red path, for
-   a false result, handles every other visitor.
-
-To join more than one rule, create an AND group or an OR group and add the rules
-inside it.
-
-## Branches
-
-In the flow builder, a condition node has two output handles. The green handle, for a
-true result, leads to the path for a match. The red handle, for a false result, leads
-to the other path.
-
-You can chain conditions. Connect the output of one condition to the input of another
-to build a decision tree.

package/dist/docs/content/asset-library.mdx

@@ -1,124 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Asset Library
-
-The Asset Library holds the files that your content points at. These are images,
-video, documents, and HTML.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/assets"
-  alt="The asset library on the Picked dashboard"
-/>
-
-## Upload and control your assets
-
-The Asset Library is a project-level store. Upload a file, then point at it from any
-Content Entry in the project.
-
-- **Size limit:** 50 MB for each file.
-- **Allowed types:** an image in PNG, JPEG, WebP, AVIF, GIF, or SVG. A video in MP4
-  or WebM. A common document format. HTML, as `text/html`.
-
-Picked rejects a file of another type. It also rejects a file above the size limit.
-
-## Reference an asset from a field
-
-Two field types point at an item in the library:
-
-- An **Asset** field points at an image, a video, or a document.
-- An **HTML asset** field takes a `.html` file from your library.
-
-Add the field to a [layout](/content/layouts). Then choose an item from the library
-when you fill in the [Content Entry](/content/content-entries).
-
-## Pick an asset
-
-Every Asset field opens the same picker. Click **Choose file** to open it. On a field
-with a value already, click **Replace**. The modal has two tabs: **Library**, where
-you browse the assets that are there, and **Upload**, where you add a new file.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/design-systems/new"
-  wait='button:has-text("Upload file")'
-  click='button:has-text("Upload file")'
-  selector="[role=dialog]"
-  alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort by menu"
-  renderWidth={1072}
-  renderHeight={790}
-/>
-
-### Search, filter, and sort
-
-The Library tab has three controls that make a large asset list smaller. The server
-applies each one across the whole library, and not only across the assets that it
-loaded already:
-
-- **Search:** narrows the list by file name while you type.
-- **Type filter:** narrows the list to one media type. The choices are All types,
-  Images, Video, Audio, Documents, and Archive files.
-- **Sort by:** orders the list by the Name or by the Date uploaded, each one
-  ascending or descending.
-
-:::note
-The results come one page at a time. Click **Load more** at the bottom of the list to
-read the next page.
-:::
-
-### Choose one asset or several
-
-The picker changes with the number of assets that the field takes:
-
-- A field that holds one asset shows a **radio** indicator next to each row. The
-  Asset field of a layout and the guidance file of a design system both do this. A
-  new choice replaces the current asset.
-- A place that takes several assets at once shows a **checkbox** indicator. The
-  detail panel then also shows a count of what you chose. The Files tab of a
-  workbench does this.
-
-The detail panel on the right shows the kind, the dimensions, the size, and the
-upload date of the asset that you chose.
-
-### Open an asset in a new tab
-
-Each row has an **Open in new tab** control, and so does the detail panel of the
-asset that you chose. It links to the full detail page of the asset, and your choice
-in the picker stays as it is.
-
-:::tip
-Use this to check an asset again before you choose it. You can see the full-size
-preview and every version that somebody uploaded.
-:::
-
-## HTML assets
-
-Upload a `.html` file and point at it from an **HTML asset** field. Picked then scans
-the file. The scan is advisory: it helps you, and it never stops you. It
-reports findings about speed, about search rank, and about accessibility, so that you
-can improve the file before you publish it:
-
-- **File size:** a warning at 100 KB, and a stronger one at 250 KB.
-- **Inline images:** a note when inline `base64` image data adds about 50 KB or more.
-- **Image dimensions:** an image with no width and no height. Such an image can move
-  the content around it while the page loads.
-- **Lazy load:** an image with no `loading="lazy"` attribute.
-- **Link safety:** an external link with `target="_blank"` and no `rel="noopener"`.
-- **Link search rank:** an external link with no `rel="nofollow"`.
-- **Accessibility:** a pass by `axe-core`. It covers alt text, heading order,
-  contrast, and more.
-
-Every finding is advisory. You can always upload the file as it is.
-
-## How assets are served
-
-Picked serves each asset from a sandboxed storage origin. That origin is separate
-from the trusted origin of your application. HTML therefore comes from its own
-origin, so a document that you upload runs in isolation and cannot reach the page
-that holds it.
-
-An [Experience Content](/delivery-api/experience-content) response can hold an HTML
-asset. The response then carries the content of that asset, and the SDK renders it
-with no second request to storage.

package/dist/docs/content/pages.mdx

@@ -1,82 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Pages
-
-A Page is a standalone, server-rendered experience backed by CMS content, built for SEO-critical landing pages.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences"
-  alt="The experiences list, where Pages and Flows are created on the Picked dashboard"
-/>
-
-## Pages and flows
-
-Picked has two experience kinds:
-
-| Experience | What it is | Use it for |
-| --- | --- | --- |
-| **Page** | A standalone experience that your server renders from a Content Entry. | A landing page or a campaign page where the search rank matters, and any content that a crawler must see. |
-| **Flow** | An interactive experience of more than one step, which the browser renders. | A quiz, a survey, a product finder, and onboarding of more than one step. |
-
-Choose a **Page** when the content must be in the HTML from your server, for a search
-engine and for a social preview. Choose a **Flow** when the value is in the
-interaction, and a browser render is acceptable. See
-[Experiences](/experiences) for the wider picture.
-
-## How a page fits together
-
-Four pieces back every Page:
-
-1. A **Page Layout** defines the shape: the fields a page can hold. See [Page & Step Layouts](/content/layouts).
-2. A **Content Entry** fills that shape with real data. See [Content Entries](/content/content-entries).
-3. A **Page** binds one entry so the SDK can render it.
-4. The **SDK** fetches the entry and renders it on your server. See [Server-Side Rendering](/sdk/ssr).
-
-A layout defines the shape, a content entry fills it with data, a Page binds an entry so the SDK can render it. Step Layouts do the same for individual Steps inside a Flow.
-
-```
-Author (dashboard) -> Publish -> Delivery API (config + content)
-  -> serialize() on server -> Provider seeds client -> ExperienceSlot renders -> hydrate
-```
-
-## Create a page
-
-1. Open your project.
-2. Choose a workspace.
-3. Click **Experiences** in the sidebar.
-4. Click **New Experience**.
-5. Choose the **Page** type.
-6. Choose a **Page Layout**. The layout sets which fields the page holds.
-7. Click **Create**.
-
-A Content Entry is created and linked to the page on its first save, so the page always has somewhere to store its data.
-
-## Edit page content
-
-The Page editor has two tabs. The **Properties** tab holds the content of the page.
-The **Settings** tab holds its name, its condition, and its layout. Fill in the
-fields on the **Properties** tab. The inspector on the right edits the field that you
-choose, and the preview panel shows the page while it fills in.
-
-## Change or remove the layout
-
-Use the change-layout control on the **Settings** tab to move the page to another
-Page Layout. When you unlink a layout, Picked separates the Content Entry from the
-page. It deletes no entry, but the page then has no content to render until you
-attach a layout again.
-
-## Validate and publish
-
-An invalid field shows an error next to it while you edit, so that you can correct it
-before you publish. When the page is valid, publish the workspace to make it live.
-That makes the version that the Delivery API serves to an anonymous reader.
-
-## Render a page
-
-The SDK renders a published Page on your server. See the
-[Build a Personalized Page](/guides/build-a-personalized-page) guide for the full
-steps, and [Server-Side Rendering](/sdk/ssr) for the SDK reference.

package/dist/docs/content/sections.mdx

@@ -1,44 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Sections
-
-Sections are reusable schema fragments you embed inside layouts, so common structures such as a hero or a feature list are defined once.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/blocks"
-  alt="The sections list in the schema builder on the Picked dashboard"
-/>
-
-## What a section is
-
-A Section is a reusable schema fragment with its own **Key**. A
-[layout](/content/layouts) gives its shape to a whole Page or Step. A Section is a
-part that you put into one or more layouts. Define the shape one time, then reuse it
-everywhere.
-
-## Create a section
-
-1. Open your workspace.
-2. Click **Sections** in the sidebar.
-3. Click **New Section**.
-4. Enter a name and a **Key**. The Key is a unique, stable identifier. Your SDK code
-   and your API calls both use it.
-5. Add your fields.
-6. Save.
-
-## Use a section in a layout
-
-Add a **Section** field to a Page Layout or a Step Layout. Point that field at the
-Section that you want. The layout then carries the fields of the Section at every
-place where that field appears. A Content Entry from the layout fills in the fields
-of the Section in the same way as every other field.
-
-## Change a section
-
-An edit to a Section does not migrate the entries that use it. After you change a
-Section, check each affected [Content Entry](/content/content-entries) again. Correct
-every field error before you publish.

package/dist/docs/delivery-api/index.md

@@ -1,53 +0,0 @@
----
-layout: docs
----
-
-# Delivery API
-
-The Delivery API is a public REST API. It is read-only, and it serves the published
-options of your project together with your page content. It is separate from the
-GraphQL management API.
-
-## The Delivery API and the management API
-
-Picked has two HTTP APIs. Use the one that fits your work:
-
-| | Delivery API | Management API |
-| --- | --- | --- |
-| Style | REST | GraphQL |
-| Access | Public, anonymous | Authenticated |
-| Operations | Read-only | Read and write |
-| Use it to | Serve published options and content to your application | Control your projects, experiences, and content |
-
-The [API Reference](/api) covers the management API. This section covers the Delivery
-API.
-
-## Base URL and versioning
-
-All Delivery API routes are versioned under `/api/v1`:
-
-```
-https://api.picked.app/api/v1
-```
-
-## Published content and preview content
-
-Each endpoint serves two surfaces:
-
-- **Published** content is anonymous. Anybody can read your published options and
-  your published content.
-- **Preview** content needs a `preview_token` query parameter. With it you can render
-  an unpublished draft before you make it live.
-
-The management API holds the preview token of a workspace in the `previewToken`
-field. The preview action in the dashboard also makes one for you.
-
-## Endpoints
-
-| Endpoint | Description |
-| --- | --- |
-| [Project Config](/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published options of the project, with the content link of each step. |
-| [Experience Content](/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries of an experience. |
-
-Both endpoints share some behaviour. See
-[Preview, cache, and crawlers](/delivery-api/preview-caching-crawling).

package/dist/docs/guides/build-a-personalized-page.mdx

@@ -1,161 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Build a Personalized Page
-
-Build a personalized landing page with Picked: model it in the dashboard, publish it, and render it server-side in your app.
-
-## What you will build
-
-A standalone landing page where the search rank matters. Its content lives in the
-Picked CMS, and your server renders it. You describe the shape of the page one time,
-fill it with content, and publish it. Your server then reads it and renders it in
-React or in Svelte. These are the stages, from the first draft to a hydrated page:
-
-```
-Author (dashboard) -> Publish -> Delivery API (config + content)
-  -> serialize() on server -> Provider seeds client -> ExperienceSlot renders -> hydrate
-```
-
-## Model a page layout
-
-A [Page Layout](/content/layouts) defines the fields your page can hold.
-
-1. Open your workspace.
-2. Click **Models** in the sidebar.
-3. Click **New Model**.
-4. Choose **Page Layout**.
-5. Enter a name and a **Key**, for example `page-hero`. The Key is a unique, stable
-   identifier. Your SDK code and your API calls both use it.
-6. Add three fields: a **Single-line text** field `title`, a **Markdown** field
-   `body`, and an **Asset** field `image`.
-7. Save the layout.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
-  alt="A page layout in the schema builder on the Picked dashboard"
-/>
-
-See [Page & Step Layouts](/content/layouts) for every field type.
-
-## Create and fill the page
-
-1. Click **Experiences** in the sidebar.
-2. Click **New Experience**.
-3. Choose the **Page** type.
-4. Choose your `page-hero` layout.
-5. On the **Properties** tab, fill in `title`, `body`, and `image`. On the first save,
-   Picked creates a [Content Entry](/content/content-entries) and links it to the
-   page.
-6. Correct every field error.
-7. Publish the workspace to make the page live.
-
-See [Pages](/content/pages) for the full editor reference.
-
-## Fetch the config and content
-
-Your server reads two things from the [Delivery API](/delivery-api). The first is the
-options of the project, which give the experiences and the steps. The second is the
-content of the experience that matches.
-
-```bash
-# 1. The project options: find the steps and their content links.
-curl https://api.picked.app/api/v1/projects/proj_123
-
-# 2. The experience content: the entry data of the page.
-curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
-```
-
-In practice you fetch the config, then let `serialize()` fetch the content for you. See [Project Config](/delivery-api/project-config) and [Experience Content](/delivery-api/experience-content).
-
-## Render server-side and hydrate
-
-On the server, create a per-request client, call `serialize()` to produce a snapshot, render your app, and embed the snapshot. On the client, seed from the snapshot and hydrate.
-
-```ts
-// `server.ts`
-import { createClient } from '@picked/client'
-import { serialize } from '@picked/client/server'
-
-const client = createClient(options)
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: url.pathname } },
-})
-// Render your app, then embed `snapshot` in the HTML response.
-```
-
-Render `<ExperienceSlot name="page" />` inside the provider, and register the component the Page maps to (here, `CMSPage`):
-
-:::code-group
-
-```tsx [React]
-import type { CreateClientOptions } from '@picked/client'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-import { useStepContent } from '@picked/react/hooks'
-
-function CMSPage() {
-  const content = useStepContent()
-  const title = typeof content?.title === 'string' ? content.title : ''
-  return <h1>{title}</h1>
-}
-
-const options = {
-  projectId: 'proj_123',
-  components: { CMSPage: adaptReactComponent(CMSPage) },
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-} satisfies CreateClientOptions
-
-export function Page({ snapshot }) {
-  return (
-    <PickedProvider options={options} snapshot={snapshot}>
-      <ExperienceSlot name="page" />
-    </PickedProvider>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import type { CreateClientOptions } from '@picked/client'
-  import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-  import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
-  import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
-  import CMSPage from './CMSPage.svelte'
-
-  const { snapshot } = $props()
-
-  const options = {
-    projectId: 'proj_123',
-    components: { CMSPage: adaptSvelteComponent(CMSPage) },
-    plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-  } satisfies CreateClientOptions
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-:::
-
-The provider seeds synchronously, so the server HTML and the client's first paint match, then the SDK hydrates. See [Server-Side Rendering](/sdk/ssr) for the full reference.
-
-## Verify SEO
-
-Confirm the page is crawlable end to end:
-
-1. Read the response from your server. Use `curl`, or the view-source command of
-   your browser.
-2. Check that the HTML holds your `title` and your `body`, and that it is not an
-   empty shell.
-3. Check that the content endpoint answers an anonymous request.
-4. Check that it returns your entry data.
-
-A crawler can read a published Delivery API response. A preview URL is disallowed.
-See [Preview, cache, and crawlers](/delivery-api/preview-caching-crawling).

package/dist/docs/pickedql/index.md

@@ -1,54 +0,0 @@
----
-layout: docs
----
-
-# PickedQL
-
-PickedQL is a SQL query language for your Picked analytics data. Write short SQL with
-a virtual table and a virtual function. PickedQL expands them into a full query, and
-it adds the joins and the A/B test aggregations for you.
-
-## Quick start
-
-```sql
--- How many users are in the control group, and how many in the variant group?
-SELECT control_users(), variant_users()
-FROM metrics
-WHERE project_id = 'your-project-id'
-```
-
-PickedQL maps each table and adds each dimension join for you. You write short SQL
-that a person can read, and PickedQL does the rest.
-
-## How PickedQL works
-
-1. **Virtual table expansion**: a table name such as `metrics` maps to the data
-   tables below it.
-2. **Virtual function expansion**: a short function such as `control_users()` expands
-   to a full aggregate expression.
-3. **Automatic dimension joins**: PickedQL adds a `LEFT JOIN` when you point at a
-   dimension column, such as `device_category` or `country_code`. You write no join.
-4. **Tenant isolation**: every query must hold a tenant filter in the `WHERE` clause.
-   That filter is `project_id` for most tables. The `projects` table uses `id`
-   instead, because the `id` of the row is the project ID. PickedQL reads the filter
-   and checks that you have permission for that project.
-5. **SQL passthrough**: standard SQL works next to a virtual function. This includes
-   `CASE WHEN`, a window function, and a subquery.
-
-## Best practices
-
-- **Use `metrics` for a dashboard**: data that PickedQL aggregates first is much
-  faster than raw events for a standard report.
-- **Use `events` to go deeper**: raw event data lets you build any breakdown or
-  funnel that you want.
-- **Use `experience_journey` for a sankey chart or a funnel chart**: one line of SQL
-  returns `source, target, users`. PickedQL builds the eight common table expressions
-  for you. Those remove the duplicates, rank the top paths, and call `lagInFrame`.
-  Pass your parameters in the `WHERE` clause.
-- **Write no JOIN**: PickedQL adds each one when you point at a dimension column.
-- **Group by any dimension**: add a dimension column to `SELECT` and to `GROUP BY`.
-  PickedQL adds the join that it needs.
-- **Read the reference tables for no cost**: use `step_title`, `experience_title`, and
-  `project_name` directly in an `events` query. PickedQL joins the `steps`,
-  `experiences`, and `projects` reference tables for you.
-