@picked/client 0.0.1-dev.1789541668638 → 0.0.1-next.1

package/dist/docs/reference/sdk/ssr/rendering-and-hydration.md

@@ -1,103 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Rendering and Hydration
-
-Seed a Picked client from the server snapshot, render your slots, and hydrate. This
-page covers React and Svelte.
-
-## React: `PickedProvider`
-
-`PickedProvider` gives a client to each component below it. Its props are a union of
-two modes:
-
-| Props | Mode | Description |
-| --- | --- | --- |
-| `{ options, snapshot? }` | Create | The provider calls `createClient(options)` and hydrates the client from the snapshot. |
-| `{ client, snapshot? }` | Adopt | The provider uses a client that is there already, such as a global one for the whole application. It can also seed that client from the snapshot. |
-
-The provider seeds the client at once, so the server and the first paint on the
-client give the same markup. In the browser the provider calls `client.start()` from
-an effect. `start()` is idempotent, so it changes nothing on a client that already
-started.
-
-```tsx
-import { PickedProvider, ExperienceSlot } from '@picked/react'
-
-<PickedProvider options={options} snapshot={snapshot}>
-  <ExperienceSlot name="page" />
-</PickedProvider>
-```
-
-## Svelte: `setPickedContext`
-
-`setPickedContext` does the same work in the Svelte style. Call it one time at the
-top of the `<script>` block of a component. It takes the same two modes,
-`{ options, snapshot? }` or `{ client, snapshot? }`, and it returns the client.
-
-```svelte
-<script lang="ts">
-  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-## Render the page component
-
-The SDK does not connect content to a component. You own the component that a Page
-renders. Register it under the name that the Page uses. The Page Layout in the dashboard
-points at that same name. The component reads the resolved entry data
-through a content hook: `useStepContent()` in React, and `getStepContent()` in
-Svelte.
-
-:::code-group
-
-```tsx [React]
-import { useStepContent } from '@picked/react/hooks'
-
-export function CMSPage() {
-  const content = useStepContent()
-  if (!content) {
-    return <p>Loading page content…</p>
-  }
-
-  const title = typeof content.title === 'string' ? content.title : ''
-  return (
-    <article>
-      <h1>{title}</h1>
-    </article>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import { getStepContent } from '@picked/svelte/hooks'
-
-  const content = getStepContent()
-</script>
-
-{#if $content}
-  <article>
-    <h1>{typeof $content.title === 'string' ? $content.title : ''}</h1>
-  </article>
-{:else}
-  <p>Loading page content…</p>
-{/if}
-```
-
-:::
-
-`useStepContent()` returns the `data` object of the entry directly. It returns `null`
-while no content is registered. `getStepContent()` returns a store, and you read it
-with `$content`.
-
-## Related
-
-- [How to server-render a page](/how-to/server-render-a-page) — the full example.
-- [Slots and placements](/reference/sdk/ssr/slots-and-placements)

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

@@ -1,80 +0,0 @@
----
-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'
-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`.
-
-The content that it reads holds the entries of the steps. It also holds the entries that
-a [reference field](/reference/dashboard/content/models#reference-fields) reaches.
-
-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. It holds the entries of the steps, and every entry that a reference field reaches. The server render and the first paint in the browser therefore resolve the same pointers. |
-| `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)
-- [Content](/reference/sdk/content) — how to read a content record in a component.

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

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

@@ -1,86 +0,0 @@
----
-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, useStoreGlobal } from '@picked/react/hooks'
-
-function ContactForm() {
-  const { step, fields } = useStep()
-  const currentStep = useStoreGlobal(step)
-  const currentFields = useStoreGlobal(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/sdk/type-generation.md

@@ -1,196 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# Type Generation
-
-Picked can generate TypeScript types from your workspace schema so field values, feature keys, content models, and step layouts are typed in your app.
-
-## Quick start
-
-### 1. Add `picked.config.ts`
-
-Create a `picked.config.ts` in your project root:
-
-```typescript
-import { defineConfig } from 'picked/config'
-
-export default defineConfig({
-  projectId: 'your-project-id',
-  typesOutput: './src/picked-env.d.ts',
-})
-```
-
-| Option | Description |
-| --- | --- |
-| `projectId` | **Required.** Your Picked project id. |
-| `typesOutput` | Path for generated types (defaults to `./src/picked-env.d.ts`). |
-| `source` | Schema surface to type against: `'published'` (default) or `'preview'`. |
-| `previewToken` | Workspace preview token. Required when `source` is `'preview'`, and read only then. |
-
-The `source` value matches the `x-picked-source` field on the [workspace schema](/reference/delivery-api/workspace-schema) document — it controls whether tooling fetches the published or preview workspace shape.
-
-A preview token reads one workspace, and it does not expire. Leave both `source` and
-`previewToken` out of the committed file, and pick a workspace instead:
-
-```bash
-picked login
-picked workspace use
-```
-
-That writes the choice, and that workspace's token, to `.picked/settings.json`, which is
-per-developer and which Git ignores. Each developer points at their own workspace, and the
-committed file holds no token.
-
-You can also set the values here. Every developer then reads the same workspace:
-
-```typescript
-export default defineConfig({
-  projectId: 'your-project-id',
-  source: 'preview',
-  previewToken: 'the-workspace-preview-token',
-})
-```
-
-Three places can give the token. Tooling reads the first of them that has one: the
-`PICKED_PREVIEW_TOKEN` environment variable, then the workspace that
-[`picked workspace use`](/reference/tools/cli) chose, then this `previewToken` option.
-
-### 2. Enable the Vite plugin (recommended)
-
-If you use Vite, add `@picked/vite-plugin-picked`. Type generation runs automatically on `dev` and `build` when `generateTypes` is enabled (the default):
-
-```typescript
-import { picked } from '@picked/vite-plugin-picked'
-
-export default defineConfig({
-  plugins: [picked()],
-})
-```
-
-The project id comes from `picked.config.ts`. A failure stops the
-run. See [the plugin reference](/reference/tools/vite-plugin) for `generateTypes` and every
-other option.
-
-### 3. Or use the CLI
-
-Install [`picked`](/reference/tools/cli) and run:
-
-```bash
-picked generate types
-```
-
-## Keep the types current
-
-Commit `picked-env.d.ts`. A workspace changes after you commit it, so the file goes stale,
-and stale types describe fields your workspace no longer has.
-
-Run this check in CI, next to your other checks:
-
-```bash
-picked generate types --check
-```
-
-`--check` writes no file. It reads the live workspace schema and compares it with the
-committed file. A match gives status `0`. A difference gives status `1` and names the file:
-
-```
-Types are out of date: /home/runner/work/your-app/src/picked-env.d.ts
-```
-
-To clear it, run `picked generate types` and commit the result. The check reads no cached
-schema, so an API it cannot reach fails the check.
-
-:::note
-`--check` reads the workspace that the resolved configuration names. A CI run that has no
-`.picked/settings.json` reads the workspace your committed `picked.config.ts` names.
-:::
-
-## Workspace selection
-
-Tooling reads `projectId` and `source` from your committed `picked.config.ts`. The Picked [CLI](/reference/tools/cli) points that tooling at a different project or a draft workspace, and leaves the file as it is. It writes the selection to `.picked/settings.json`, which is per-developer and which Git ignores. That selection supersedes the committed default.
-
-See [How to switch workspaces](/how-to/switch-workspaces) for the full set of steps.
-
-## Generated output
-
-The generated `picked-env.d.ts` file looks like:
-
-```typescript
-// GENERATED by `@picked/typegen` — do not edit by hand.
-// Reference: `https://docs.picked.app/reference/sdk/type-generation`
-
-export type WelcomePage = { /* ... */ }
-export type FieldValues = { /* ... */ }
-export type FeatureKey =
-  | 'default'
-  | 'hero'
-  | 'winter-sale'
-
-declare module '@picked/client' {
-  interface PickedSchemaRegistry {
-    contentModels: {
-      'welcome-page': WelcomePage
-    }
-    stepContentModels: {
-      'intro': 'welcome-page'
-    }
-    featureValues: {
-      'hero':
-        | false
-        | 'hero-a'
-        | 'hero-b'
-    }
-    fieldValues: FieldValues
-    featureKeys: FeatureKey
-  }
-}
-```
-
-Commit this file to the version control system, or regenerate it in CI after you publish a workspace change.
-
-### Feature flag values
-
-A Text feature flag declares the values that it can serve, so `useFeatureResult` narrows
-the bucket to those values:
-
-```typescript
-const result = useFeatureResult('hero')
-```
-
-The `bucket` property then has the type `false | 'hero-a' | 'hero-b'`.
-
-`featureValues` holds the Text feature flags alone. A Boolean feature flag, and a feature
-flag that your application defines, both keep the general `boolean | string` type. The
-`FeatureValueFor<'hero'>` type gives the same union on its own.
-
-## Keys the application defines
-
-An application can define a feature, an action, a field, a step, or an experience of its
-own. It does this through `createClient` options or through a `register` method. The
-workspace has no record of such a key, so the generated types have none either.
-
-A hook still accepts one. Each key type holds the keys of the workspace and any other
-string. Your editor shows the workspace keys, and no local key is an error:
-
-```typescript
-useFeature('winter-sale')             // from the workspace, and suggested
-useFeature('summer-sales-experiment') // from createClient, and accepted
-```
-
-Each key type has a `Known` form that holds the workspace keys alone —
-`KnownFeatureKeys`, `KnownActionKeys`, `KnownFieldKeys`, `KnownStepKeys`, and
-`KnownExperienceKeys`. Use one where you want the workspace set and nothing else.
-
-## Cache
-
-Type generation writes its artefacts under `.picked/`: the schema JSON and a manifest. The first run adds this directory to `.gitignore` for you.
-
-## Related
-
-- [CLI](/reference/tools/cli) — commands, authentication, and environment variables.
-- [How to switch workspaces](/how-to/switch-workspaces) — read a draft workspace on your machine.
-- [Vite plugin](/reference/tools/vite-plugin) — the build-time prefetch and the dev launcher.
-- [Workspace schema](/reference/delivery-api/workspace-schema) — the schema endpoint.
-- [Delivery API](/reference/delivery-api) — the published surface and the preview surface.

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

@@ -1,16 +0,0 @@
----
-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/cli.md

@@ -1,146 +0,0 @@
----
-type: reference
-layout: docs
----
-
-# CLI
-
-`picked` is the command-line tool for local Picked development. It generates TypeScript
-types from your workspace schema and lets you switch which project or workspace your local
-tooling loads — without hand-editing `picked.config.ts`.
-
-## Installation
-
-The [`picked`](/reference/sdk) package holds this command, the client, and the
-`picked.config` helpers:
-
-```bash
-npm install picked
-```
-
-The command reads `picked.config.ts` from the current directory, so run it from your
-project root. See [How to authenticate the CLI](/how-to/authenticate-the-cli) to sign in.
-
-`@picked/cli` holds the command on its own, for a project that wants no other part of the
-package.
-
-## Commands
-
-| Command | Description |
-| --- | --- |
-| `picked login` | Sign in with your browser (OAuth) to the API origin of the current directory. Stores a session under `~/.picked/auth/`. |
-| `picked logout` | Clear the stored session for the current directory's API origin. |
-| `picked whoami` | Print the identity signed in to the API origin of the current directory. |
-| `picked status` | Print the resolved selection and the committed `picked.config` default. |
-| `picked workspace list` | List each org, project, and workspace that you can read. Alias `ls`. `--json` gives machine output. |
-| `picked workspace use` | Set the active project or workspace. Alias `picked use`. Interactive, or `--project` and `--workspace`. |
-| `picked generate types` | Read the workspace schema and write `picked-env.d.ts`. `--check` verifies and writes nothing. |
-
-### `picked generate types`
-
-Writes the typed schema declaration. See [Type generation](/reference/sdk/type-generation)
-for the `picked.config.ts` reference and the generated output.
-
-```bash
-picked generate types
-```
-
-In CI, `--check` writes nothing and fails when the committed types are stale:
-
-```bash
-picked generate types --check
-# → "Types are up to date (`…/src/picked-env.d.ts`)."  (status 0)
-# → "Types are out of date: `…/src/picked-env.d.ts`"   (status 1)
-```
-
-### `picked workspace list`
-
-```bash
-picked workspace list
-```
-
-```
-Acme Corp. (acme-corporation)
-  Storefront [proj_a1b2]
-    Default Storefront [LIVE] (live)
-    Checkout rework [DRAFT]
-```
-
-`--json` gives a machine-readable tree. Each prompt and heading goes to `stderr`, so the
-`stdout` of `--json` stays clean when you send it to another command.
-
-### `picked workspace use`
-
-Sets the active selection, then regenerates types. See
-[How to switch workspaces](/how-to/switch-workspaces) for the full set of steps.
-
-```bash
-picked workspace use                                  # interactive picker
-picked workspace use --project proj_a1b2              # the project's published (live) version
-picked workspace use --project proj_a1b2 --workspace ws_id      # preview a specific workspace via its token
-```
-
-```
-Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
-Generated types at /app/src/picked-env.d.ts
-```
-
-`--no-generate` sets the selection and leaves the types as they are.
-
-:::warning
-`picked workspace use` regenerates types by default. Types that no longer match the
-workspace give no error, and a developer can fail to see the problem for a long time. Use
-`--no-generate` only when you regenerate the types yourself.
-:::
-
-## Authentication
-
-`picked login` signs in through the browser. It uses an authorization-code flow with PKCE
-against the Picked OAuth server. `picked whoami` prints the identity for the current origin.
-`picked logout` clears it.
-
-The CLI holds one auth config file for each API origin, outside each repository. Every
-command reads and writes only the origin that the current directory resolves to, and never
-a session for another API.
-
-| File | Contents |
-| --- | --- |
-| `~/.picked/auth/<origin>.json` | The OAuth session for one API origin — access token, refresh token, expiry — with the CLI's registered client id for that origin. File mode `600`. Refreshed as it nears expiry. |
-
-An API deployment with no OAuth client registration rejects `picked login`, and has no
-other flow.
-
-A CLI session is a developer credential. It is not an
-[API key](/reference/dashboard/api-keys), which authenticates server-to-server calls, and
-not [dashboard sign-in](/reference/management-api/authentication).
-
-## Environment variables
-
-| Variable | Effect |
-| --- | --- |
-| `PICKED_API_URL` | The API origin that the CLI reads. Supersedes `picked.config` `apiUrl` and the `https://api.picked.app` default. |
-| `PICKED_PROJECT_ID` | Supersedes the resolved project id, above the active selection and the committed configuration. |
-| `PICKED_PREVIEW_TOKEN` | Supersedes the preview token. Applies only when the resolved source is `preview`. |
-
-### How the selection resolves
-
-Tooling — `picked generate types` and the
-[Vite plugin](/reference/tools/vite-plugin) — resolves the configuration in this order. Each
-layer supersedes the layer before it:
-
-1. **`picked.config.ts`** — the committed default: `projectId`, `source`, and
-   `previewToken`.
-2. **`.picked/settings.json`** — the per-developer active selection that
-   `picked workspace use` writes. It supersedes `projectId` and `source`, and Git ignores it.
-3. **Environment variables** — `PICKED_PROJECT_ID` and `PICKED_PREVIEW_TOKEN` supersede
-   both, for a CI or headless run.
-
-`picked status` prints the resolved result.
-
-## Related
-
-- [How to authenticate the CLI](/how-to/authenticate-the-cli) — install and sign in.
-- [How to switch workspaces](/how-to/switch-workspaces) — the draft-preview workflow.
-- [Type generation](/reference/sdk/type-generation) — `picked.config.ts` and the generated types.
-- [Vite plugin](/reference/tools/vite-plugin) — reads the same selection in development and in a build.
-- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — how a preview token behaves.