@picked/client 0.0.1-dev.1786072899095 → 0.0.1-dev.1786601464574

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

@@ -0,0 +1,216 @@
+---
+type: reference
+layout: docs
+---
+
+# Content
+
+The client holds every content record in one index, keyed by the id. The hooks on this
+page read that index.
+
+## The content record
+
+```ts
+interface Content {
+  id: string
+  contentModelKey?: string | null
+  data: Record<string, unknown>
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | The content entry id. |
+| `contentModelKey` | `string \| null` | The Key of the [Model](/reference/dashboard/content/models) that the entry belongs to. |
+| `data` | `Record<string, unknown>` | The field values, keyed by the field key from the schema. |
+
+The client registers the `content` array and the `references` array of the
+[experience content response](/reference/delivery-api/experience-content) into the same
+index. Your code can therefore read a referenced entry by its own id.
+
+## Read the content of a step
+
+`useStepContent()` in React, and `getStepContent()` in Svelte, give the `data` of the
+entry that the current step points at.
+
+:::code-group
+
+```tsx [React]
+import { useStepContent } from '@picked/react/hooks'
+
+export function Hero() {
+  const content = useStepContent()
+
+  return <h1>{String(content?.headline ?? '')}</h1>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+</script>
+
+<h1>{$content?.headline ?? ''}</h1>
+```
+
+:::
+
+`useStepContent()` returns the data, and React re-renders the component when the data
+changes. `getStepContent()` returns a store, which you read with the `$` prefix.
+
+## Read a record by id
+
+`useContent(id)` and `getContent(id)` return a store of one record. The store holds
+`null` until the client registers that record.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useContent } from '@picked/react/hooks'
+
+export function Banner() {
+  const banner = useUnit(useContent('entry_42'))
+
+  return <h1>{String(banner?.data.headline ?? '')}</h1>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getContent } from '@picked/svelte/hooks'
+
+  const banner = getContent('entry_42')
+</script>
+
+<h1>{$banner?.data.headline ?? ''}</h1>
+```
+
+:::
+
+## Resolve a reference field
+
+A [Reference field](/reference/dashboard/content/models#reference-fields) holds a pointer,
+and not the record. `useReference()` and `getReference()` resolve the pointer against the
+index.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReference, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategory() {
+  const content = useStepContent()
+  const category = useUnit(useReference(content?.category))
+
+  return <span>{String(category?.data.name ?? '')}</span>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReference } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const category = getReference(content.map((c) => c?.category ?? null, { skipVoid: false }))
+</script>
+
+<span>{$category?.data.name ?? ''}</span>
+```
+
+:::
+
+For a repeatable Reference field, use `useReferences()` and `getReferences()`. They give
+a list in field order.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReferences, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategories() {
+  const content = useStepContent()
+  const categories = useUnit(useReferences(content?.categories))
+
+  return (
+    <ul>
+      {categories.map((category) => (
+        <li key={category.id}>{String(category.data.name ?? '')}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReferences } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const categories = getReferences(content.map((c) => c?.categories ?? null, { skipVoid: false }))
+</script>
+
+<ul>
+  {#each $categories as category (category.id)}
+    <li>{category.data.name ?? ''}</li>
+  {/each}
+</ul>
+```
+
+:::
+
+The list holds no empty places. A pointer that Picked cannot resolve is absent from the
+list, so each item is a record.
+
+:::note
+The Svelte helpers accept a store, and the examples pass one. Content arrives after the
+component starts. A plain value therefore holds the result at "not set".
+:::
+
+## Reference hooks
+
+| Hook | Returns | When the target is absent |
+| --- | --- | --- |
+| `useReference(value)` | `Store<Content \| null>` | `null` |
+| `useReferences(value)` | `Store<Content[]>` | The item is absent from the list. |
+| `getReference(value)` | `Store<Content \| null>` | `null` |
+| `getReferences(value)` | `Store<Content[]>` | The item is absent from the list. |
+
+Each one accepts the raw field value, or a store of it. A single value that goes to
+`useReferences()` or `getReferences()` gives a list of one.
+
+A target is absent for three reasons. Somebody deleted the entry, the entry belongs to
+another workspace, or the chain of references is deeper than the limit. See
+[About content references](/explanation/content-references).
+
+## Read a pointer directly
+
+`@picked/client` gives you the readers behind the hooks, for the code that runs outside
+React and Svelte.
+
+| Export | Returns | Description |
+| --- | --- | --- |
+| `isContentReference(value)` | `boolean` | Whether the value is a pointer. |
+| `readReferenceId(value)` | `string \| null` | The target id of a single pointer. |
+| `readReferenceIds(value)` | `string[]` | Every target id, for a repeatable field. |
+| `deriveReference(contents, value)` | `Store<Content \| null>` | The store behind `useReference` and `getReference`. |
+| `deriveReferences(contents, value)` | `Store<Content[]>` | The store behind `useReferences` and `getReferences`. |
+
+```ts
+import { createClient, readReferenceIds } from '@picked/client'
+
+const client = createClient({ projectId: 'proj_123' })
+const content = client.contents.getById('entry_789').getState()
+const categoryIds = readReferenceIds(content?.data.categories)
+```
+
+## Related
+
+- [About content references](/explanation/content-references) — why a reference is a pointer.
+- [How to read a referenced entry](/how-to/read-a-referenced-entry)
+- [Experience content endpoint](/reference/delivery-api/experience-content) — the wire shape.
+- [Server snapshot](/reference/sdk/ssr/serialize) — content on a server render.

package/dist/docs/reference/sdk/plugins/dynamic-experiences.md

@@ -9,16 +9,64 @@ This plugin reads the configuration of your project from the Picked API at runti
 therefore control your experiences, feature flags, steps, fields, and conditions from
 the [dashboard](/reference/dashboard/experiences) alone.
 
+The plugin reads the configuration of your project and the CMS content of your
+experiences from one source. It does not mix them. Picked gives a configuration and its
+content the same version.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `'bundle' \| 'api'` | see below | Where to read the configuration and the content from. |
+| `apiUrl` | `string` | `https://api.picked.app` | Your own API URL, for a self-hosted or local API. |
+| `projectConfig` | `ProjectConfig` | none | A configuration that you give. The plugin makes no request for it. |
+| `getContent` | `function` | none | A function that you give. The plugin calls it for each experience that uses CMS content. |
+
+### mode
+
+| Value | Source | Use it when |
+| --- | --- | --- |
+| `'bundle'` | The data that the [Vite plugin](/reference/tools/vite-plugin) puts in your build | You want no API request when the page loads. |
+| `'api'` | The Picked API, read when the client starts | You want a workspace publish to reach users without a new deployment. |
+
+:::code-group
+
+```ts [app.ts]
+import { createClient } from '@picked/client'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  plugins: [dynamicExperiencesPlugin({ mode: 'bundle' })],
+})
+
+client.start()
+```
+
+:::
+
+If you do not set `mode`, the plugin uses the build data when the Vite plugin gave it
+some. In every other case it uses the API.
+
+### projectConfig and getContent
+
+These two replace the source for you. Keep the configuration and the content at the same
+version when you use them. The plugin cannot make that check for you.
+
 ## Preview mode
 
-After you [enter preview mode from the dashboard](/reference/dashboard/workspaces#preview), the SDK
+After you [enter preview mode from the dashboard](/how-to/preview-a-workspace), the SDK
 receives a preview token and starts preview mode:
 
-- The plugin reads fresh options from the API with that token. It bypasses the
-  build-time configuration and the cached options.
+- The plugin reads fresh options from the API with that token, for any value of `mode`.
+  It does not read the build-time configuration, a `projectConfig` that you give, or the
+  cached options.
 - A feature flag decision uses session storage. The decision resets when you close
   the tab.
 
+A `getContent` function keeps its place in a preview session, and it receives the token.
+You therefore decide what a preview means for your own content.
+
 ## Related
 
 - [About how Picked works](/explanation/how-picked-works) — how the plugin resolves your

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

@@ -26,8 +26,10 @@ const snapshot = await serialize(client, {
 `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`.
+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.
@@ -65,7 +67,7 @@ interface PickedSnapshot {
 | --- | --- |
 | `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. |
+| `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`
@@ -75,3 +77,4 @@ and read it back on the client.
 
 - [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/type-generation.md

@@ -0,0 +1,130 @@
+---
+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.
+
+The generated file augments the `PickedSchemaRegistry` interface of `@picked/client`. Your IDE reads the types as soon as the declaration file is part of your TypeScript project.
+
+## 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',
+  apiUrl: 'https://api.picked.app',
+  typesOutput: './src/picked-env.d.ts',
+  source: 'published',
+})
+```
+
+| Option | Description |
+| --- | --- |
+| `projectId` | **Required.** Your Picked project id. |
+| `apiUrl` | API origin (defaults to `https://api.picked.app`). |
+| `typesOutput` | Path for generated types (defaults to `./src/picked-env.d.ts`). |
+| `source` | Schema surface to type against: `'published'` (default) or `'preview'`. Preview requires `PICKED_PREVIEW_TOKEN` in the environment. |
+
+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.
+
+### 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({ disableLauncher: true }),
+  ],
+})
+```
+
+Project identity (`projectId`, `apiUrl`) comes from `picked.config.ts` — the plugin only accepts Vite-specific options:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `generateTypes` | `true` | Read the workspace schema and write types, in development and in a build. |
+| `disableLauncher` | `false` | Turn off the HTML page of the dev launcher. |
+
+Set `generateTypes: false` in a nested Vite build that must not regenerate types, such as a build for one more entry point.
+
+### 3. Or use the CLI
+
+Install `@picked/cli` and run:
+
+```bash
+picked generate types
+```
+
+In CI, `--check` writes no file and fails when the types are stale. See the [CLI reference](/reference/tools/cli) for each command.
+
+## 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.
+// source: published   `x-picked-version-id`: `ver_456`
+// Reference: `https://docs.picked.app/reference/sdk/type-generation`
+
+export interface WelcomePage { /* ... */ }
+export interface FieldValues { /* ... */ }
+export type FeatureKey = 'default' | 'winter-sale'
+
+declare module '@picked/client' {
+  interface PickedSchemaRegistry {
+    contentModels: { 'welcome-page': WelcomePage }
+    stepContentModels: { intro: 'welcome-page' }
+    fieldValues: FieldValues
+    featureKeys: FeatureKey
+  }
+}
+```
+
+Commit this file to the version control system, or regenerate it in CI after you publish a workspace change.
+
+## 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/cli.md

@@ -0,0 +1,141 @@
+---
+type: reference
+layout: docs
+---
+
+# CLI
+
+`@picked/cli` 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
+
+`@picked/cli` installs as a dev dependency and gives you the binary `picked`. It reads
+`picked.config.ts` from the current directory, so it runs from your project root. See
+[How to authenticate the CLI](/how-to/authenticate-the-cli) to install it and sign in.
+
+The `picked` package holds this command too, so a project that installs `picked` has it
+already.
+
+## 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, or report that `PICKED_TOKEN` is in use. |
+| `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. |
+
+`PICKED_TOKEN` supersedes each stored session and needs no browser, which is what a CI run
+uses. 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_TOKEN` | An access token in place of the stored session, for a CI or headless run. `picked login` is then not needed. |
+| `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` and `source`.
+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.