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

package/dist/docs/reference/sdk/ssr/serialize.md

@@ -0,0 +1,77 @@
+---
+type: reference
+layout: docs
+---
+
+# Server Snapshot
+
+`serialize()` finds which experiences match a URL and reads their content on the
+server. It returns a snapshot as plain JSON, and you pass that snapshot to the
+client.
+
+## The `serialize(client, params)` function
+
+```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: '/promo' } },
+})
+```
+
+`serialize()` does this. It registers the project configuration on the client at once. It
+evaluates the condition of each experience against `attributes.location`. It reads
+the content for each experience whose steps point at layout content. It removes the
+duplicate content blobs, which it finds by their IDs. It then returns a
+`PickedSnapshot`.
+
+Give `serialize()` one client for each request. It does not support two calls at the
+same time on one client.
+
+```ts
+serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `projectConfig` | `ProjectConfig` | required | The published configuration, or the preview configuration, to register and choose against. |
+| `attributes.location` | `Partial<SerializeLocation>` | none | The URL fields that go into the selection context, such as `pathname`. |
+| `getContent` | `SerializeGetContent` | runtime API | Your own function to read content, in place of the runtime API. |
+| `previewToken` | `string` | none | The SDK sends this with the content request, so that preview content resolves during a preview render. |
+| `timeoutMs` | `number` | `10000` | The limit for each content request. After the limit, the SDK skips that blob and continues. |
+
+`SerializeLocation` carries the URL fields `href`, `pathname`, `search`, `hostname`,
+`origin`, `protocol`, `port`, `host`, and `hash`. Pass only the fields that your
+conditions read.
+
+## The snapshot
+
+```ts
+interface PickedSnapshot {
+  versionId: string | null
+  projectConfig: ProjectConfig
+  content: ContentBlob[]
+  conditionResults: Record<string, boolean>
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `versionId` | The project version that the snapshot was chosen against. It is `null` when the version is not known, for example in a preview. |
+| `projectConfig` | The options that the server chose with. They travel to the client, so that the client renders against exactly the same options. |
+| `content` | The content blobs for the chosen experiences, with the duplicates removed. |
+| `conditionResults` | The condition results that the server kept, under a key made from the rule hash. The client then reuses the choice of the server. |
+
+The snapshot is plain JSON. Write it into your HTML response with `JSON.stringify`
+and read it back on the client.
+
+## Related
+
+- [How to server-render a page](/how-to/server-render-a-page)
+- [How to render an unpublished preview](/how-to/render-an-unpublished-preview)

package/dist/docs/reference/sdk/ssr/slots-and-placements.md

@@ -0,0 +1,59 @@
+---
+type: reference
+layout: docs
+---
+
+# Slots and Placements
+
+A slot is a named mount point. `<ExperienceSlot name="page" />` renders every
+experience that points at that slot and whose condition matches.
+
+## What a slot is
+
+The `name` of a slot points at the `.picked-slot-<name>` selector. So
+`<ExperienceSlot name="page" />` renders every experience with the target selector
+`.picked-slot-page`, when the condition of that experience is active.
+
+The slot reads the active state of each experience from the seeded snapshot. It
+therefore renders at once, both in server-side rendering and at the first paint of
+the hydration.
+
+```tsx
+<ExperienceSlot name="page" />
+```
+
+## Point an experience at a slot
+
+Set the target selector of the experience to `.picked-slot-<name>`. An experience
+that points at `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The
+name of the slot and the end of the selector must match.
+
+## Placement order
+
+When more than one experience points at the same slot, they render in this placement
+order:
+
+```
+replace -> before -> prepend -> append -> after
+```
+
+`replace` wins. An active experience with the `replace` placement renders alone, and
+it replaces every other match in the slot. In every other case each active experience
+renders, in placement order.
+
+## More than one experience in one slot
+
+The slot collects each experience that points at its selector. It drops each one
+whose condition is not active. It then sorts the rest into placement order. When a `replace`
+experience is among the active ones, only that experience renders. With no active
+`replace`, the slot renders every active experience in the order `before`, `prepend`,
+`append`, `after`.
+
+One Page can therefore take a whole slot with `replace`, while another slot holds
+several experiences that use the other placements. A condition decides which
+experiences are active. See [Conditions](/reference/dashboard/conditions).
+
+## Related
+
+- [About server-side rendering](/explanation/why-server-side-rendering) — why placements
+  have an order.

package/dist/docs/reference/sdk/steps.md

@@ -0,0 +1,87 @@
+---
+type: reference
+layout: docs
+---
+
+# Steps
+
+Render your steps with `<StepRouter>` and `<Step>` from `@picked/react` or
+`@picked/svelte`. Reach the active step through `useStep()` or `getStep()`.
+
+## Reach the step context
+
+Inside a `Step` component, or inside any component that a `Step` renders, call
+`getStep()` or `useStep()` to reach the reactive context of the step:
+
+:::code-group
+
+```tsx [React]
+import { useStep } from '@picked/react/hooks'
+import { useUnit } from 'effector-react'
+
+function ContactForm() {
+  const { step, fields } = useStep()
+  const currentStep = useUnit(step)
+  const currentFields = useUnit(fields)
+
+  return (
+    <>
+      <h1>{currentStep.label}</h1>
+
+      {currentFields.map((field) => (
+        <div key={field.id}>
+          <label>{field.label}</label>
+          <input
+            name={field.id}
+            value={field.value ?? ''}
+            onChange={field.onChange}
+            onBlur={field.onBlur}
+          />
+          {field.error && field.touched && <p className="error">{field.error.userMessage}</p>}
+        </div>
+      ))}
+    </>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStep } from '@picked/svelte/hooks'
+
+  const { step, fields } = getStep()
+</script>
+
+<h1>{$step.label}</h1>
+
+{#each $fields as field}
+  <label>{field.label}</label>
+  <input
+    name={field.id}
+    value={field.value ?? ''}
+    onchange={field.onChange}
+    onblur={field.onBlur}
+  />
+  {#if field.error && field.touched}
+    <p class="error">{field.error.userMessage}</p>
+  {/if}
+{/each}
+```
+
+:::
+
+`getStep()` in Svelte, and `useStep()` in React, return a `StepContext` with these
+properties:
+
+| Property   | Type                                          | Description                                                                    |
+| ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
+| `step`     | `Store<ExperienceStep>`                       | A reactive store that holds the `id` and the `label` of the step                |
+| `fields`   | `Store<FormField[]>`                          | A reactive store of the fields, with their current values, errors, and handlers |
+| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether the router holds this step as the active one                            |
+| `form`     | Object                                        | The handlers for a form submission. See [Forms](#forms).                        |
+
+## Related
+
+- [How to render a step form](/how-to/render-a-step-form)
+- [How to run code on a form submission](/how-to/run-code-on-a-form-submission)
+- [About how Picked works](/explanation/how-picked-works) — why a flow is a graph.

package/dist/docs/reference/tools/chrome-extension.md

@@ -0,0 +1,16 @@
+---
+type: reference
+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)
+
+## Related
+
+- [How to debug with the Chrome extension](/how-to/debug-with-the-chrome-extension)

package/dist/docs/reference/tools/image-optimisation-service.md

@@ -0,0 +1,104 @@
+---
+type: reference
+layout: docs
+---
+
+# Image optimisation service
+
+The Picked service for image optimisation is a hosted endpoint at
+`https://img.picked-content.com`. It reads an image from an allowed source domain and
+resizes it. It then encodes the image again to a modern format, WebP or AVIF, and
+caches the result.
+
+## Endpoint
+
+```
+GET https://img.picked-content.com/_next/image?url={source}&w={width}&q={quality}
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `url` | The URL of the source image, URL-encoded. It must point at an allowed source domain. See below. |
+| `w` | The width in pixels. It must be one of the supported widths. |
+| `q` | The quality: `25`, `50`, `75`, or `100`. |
+
+The service chooses the response format. When the browser advertises `image/avif` or
+`image/webp` in its `Accept` header, the response uses that format. If it does not,
+the response uses the source format.
+
+## Allowed source domains
+
+The service reads only from these hostnames:
+
+- `**.picked.app`
+
+A request with a `url` parameter for any other hostname returns `400 Bad Request`.
+
+## Supported widths
+
+Device sizes, for a responsive image that spans the width of the viewport:
+
+```
+640, 750, 828, 1080, 1200, 1920, 2048, 3840
+```
+
+Image sizes, for a UI element of fixed size such as an icon, an avatar, or a
+thumbnail:
+
+```
+16, 32, 48, 64, 96, 128, 256, 384
+```
+
+A request with any other width returns `400 Bad Request`. Choose the smallest width
+that covers the size you render at the device pixel ratio of the visitor.
+
+## Supported qualities
+
+```
+25, 50, 75, 100
+```
+
+A lower value reduces the bandwidth by a large amount. `75` is a good default for
+most images. Use `25` or `50` for a thumbnail on a slow network.
+
+## Responsive images
+
+Use the endpoint together with the standard `srcset` attribute. The browser then
+picks the correct width for each viewport:
+
+```html
+<img
+  src="https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75"
+  srcset="
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=640&q=75 640w,
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75 1080w,
+    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1920&q=75 1920w
+  "
+  sizes="(max-width: 768px) 100vw, 720px"
+  alt="..."
+/>
+```
+
+## Cache
+
+The upstream CDN caches each optimised response. The smallest cache TTL is 60
+seconds. The real lifetime depends on the eviction policy of the CDN. When you change
+the source image at the same URL, the optimised copy stays in the cache for at least
+that time.
+
+## Security
+
+- The service does not optimise an SVG source. A request for an SVG returns the
+  original bytes when the source is allowed. The service never runs an embedded
+  script.
+- Each optimised response carries a strict `Content-Security-Policy`
+  (`default-src *; script-src 'none'; sandbox;`). A compromised source therefore
+  cannot run a script in the browser that shows the image.
+- The response uses `Content-Disposition: inline`, and never `attachment`.
+
+## Related
+
+- [Asset library](/reference/dashboard/content/asset-library) — where the images come
+  from.
+- [Content Security Policy](/reference/sdk/content-security-policy) — the `img-src`
+  entry this service needs.

package/dist/docs/reference/tools/mcp.md

@@ -0,0 +1,88 @@
+---
+type: reference
+layout: docs
+---
+
+# MCP server
+
+Control your Picked workspace from an AI tool that writes code, with the Model
+Context Protocol (MCP).
+
+## Tools
+
+### Discovery
+
+| Tool                     | Description                                                  |
+| ------------------------ | ------------------------------------------------------------ |
+| `list_projects`          | Lists your organizations and projects                        |
+| `get_workspace_overview` | Reads the full workspace state                               |
+| `get_schema_info`        | Reads the documentation for Picked concepts and the data model |
+| `get_picked_docs`        | Reads the complete Picked documentation, as text for an agent |
+
+### Experiences
+
+| Tool                     | Description                                                                               |
+| ------------------------ | ----------------------------------------------------------------------------------------- |
+| `create_experience`      | Creates an experience                                                                     |
+| `get_experience`         | Reads an experience, with its flow graph                                                  |
+| `list_experiences`       | Lists your experiences                                                                    |
+| `update_experience_flow` | Creates, updates, or deletes steps, conditions, actions, fields, nodes, and edges as one operation |
+
+### Steps, fields, conditions, and actions
+
+| Tool                                | Description     |
+| ----------------------------------- | --------------- |
+| `get_step` / `list_steps`           | Read steps      |
+| `get_field` / `list_fields`         | Read fields     |
+| `get_condition` / `list_conditions` | Read conditions |
+| `get_action` / `list_actions`       | Read actions    |
+
+### Feature flags
+
+| Tool             | Description                                          |
+| ---------------- | ---------------------------------------------------- |
+| `create_feature` | Creates a feature flag                               |
+| `get_feature`    | Reads a feature flag                                 |
+| `list_features`  | Lists your feature flags                             |
+| `update_feature` | Updates the name, description, state, or weight      |
+
+### Analytics
+
+| Tool             | Description                                                      |
+| ---------------- | ---------------------------------------------------------------- |
+| `query_pickedql` | Runs a PickedQL analytics query and returns the rows as a table  |
+
+Call `get_schema_info` with the topic `pickedql` to see the tables, the virtual
+functions, and the dimension columns before you write a query.
+
+### Publish
+
+| Tool                | Description                                    |
+| ------------------- | ---------------------------------------------- |
+| `get_preview_url`   | Makes a preview URL for your unpublished work  |
+| `publish_workspace` | Publishes the workspace                        |
+
+## Example prompts
+
+- "List my Picked projects and show me the options on each one"
+- "Create a feature flag called 'new-checkout' at 50% traffic"
+- "Create an experience with a step that collects an email address"
+- "Show me control and variant users by the device type for the last 30 days"
+- "Make a preview URL for my workspace on `https://example.com`"
+
+## Tips
+
+- Ask your agent for a list of your projects first. Then ask it to read your
+  workspace and report the options on each record.
+- For a large experience, ask your agent about flow graphs and JSON Logic. The agent
+  can read the documentation for you.
+- An update to an experience flow is atomic. Your agent can create steps, fields,
+  nodes, and edges in one operation.
+- See a preview of your work on your site before you publish, to check that each page
+  is correct.
+- Ask your agent to run a PickedQL query on your analytics data. The agent can read
+  the schema, write the SQL, and explain the rows.
+
+## Related
+
+- [How to connect the MCP server](/how-to/connect-the-mcp-server)

package/dist/docs/reference/tools/vite-plugin.md

@@ -0,0 +1,88 @@
+---
+type: reference
+layout: docs
+---
+
+# Vite Plugin
+
+`@picked/vite-plugin-picked` adds Picked to your Vite project. It reads the options
+of your project at build time. It then injects them through the Vite `define`
+option, so the SDK makes no API request at runtime. In development it also serves a
+launcher page. On that page you can see a preview of an experience with your own
+feature flag values.
+
+## How it works
+
+### Build-time config injection
+
+When Vite starts, in both `dev` and `build`, the plugin does this:
+
+1. It reads the configuration of your project from the Picked API.
+2. It embeds those options in your bundle.
+3. The SDK reads the embedded configuration at runtime and makes no network request.
+
+When a preview token is there at runtime, the SDK ignores the embedded configuration and
+reads fresh data from the API.
+
+### Preload of the data file
+
+Vite puts the options of your project in their own JavaScript file. For each HTML page
+in your build, the plugin adds a `<link rel="modulepreload">` for that file. The
+browser then gets it while it reads the page, and not later when the SDK starts.
+
+The CMS content of an experience stays in its own file and gets no preload. The
+browser gets it only when an experience needs it.
+
+Some applications make their HTML from the code, and not from an HTML file in your
+project. React Router in server mode is one of these. Such a build has no page for the
+plugin to add the link to. Add this line to the code that runs in the browser instead:
+
+:::code-group
+
+```ts [entry.client.ts]
+import 'virtual:picked/data'
+```
+
+:::
+
+Your framework then sees the file in its own list and adds the preload for you.
+
+### Dev launcher
+
+In development, the plugin serves an HTML page at `/`. On that page you can:
+
+- see every feature flag in your project with its current state;
+- turn a feature flag on or off for a local test;
+- see a preview of an experience with your own feature flag values.
+
+After the dev server starts, the launcher URL appears next to the Vite output:
+
+```
+  ➜  Picked:  http://localhost:5173/
+  ➜  Local:   http://localhost:5173/
+  ➜  Network: use --host to expose
+```
+
+## Options
+
+| Option           | Type      | Default                      | Description                                              |
+| ---------------- | --------- | ---------------------------- | -------------------------------------------------------- |
+| `projectId`      | `string`  | —                            | **Required.** The ID of your Picked project.             |
+| `apiUrl`         | `string`  | `https://api.picked.app`     | Your own API URL, for a self-hosted or local API.        |
+| `disableLauncher`| `boolean` | `false`                      | Turns the launcher page off in both dev and build output.|
+
+## Build output
+
+For a production build, `vite build`, the plugin writes an `index.html` file that
+holds the launcher page. Set `disableLauncher` to stop this. The file lets you deploy
+the launcher next to your application, so that a stakeholder can see a preview.
+
+The plugin writes that file only when your build made no `index.html` of its own. An
+application that has an HTML entry keeps its own page at the root of the output.
+
+The plugin also writes a `.picked` directory next to your Vite `root`. It holds the
+options of your project and the CMS content of each experience.
+
+## Related
+
+- [How to install the Vite plugin](/how-to/install-the-vite-plugin)