@picked/client 0.0.1-dev.1777856271317 → 0.0.1-dev.1777867216429

package/dist/docs/api/pagination.md

@@ -0,0 +1,176 @@
+---
+layout: docs
+---
+
+# Pagination
+
+The Picked API uses Relay-style cursor-based pagination for all list fields that may return large result sets. This guide explains the connection pattern and demonstrates how to paginate through results.
+
+## Connection pattern
+
+Paginated fields return a **connection** object with the following shape:
+
+```graphql
+type ExampleConnection {
+  edges: [ExampleEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type ExampleEdge {
+  cursor: String!
+  node: Example!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `edges` | An ordered list of edges, each containing a `cursor` and a `node` (the actual data object) |
+| `pageInfo.hasNextPage` | `true` if more results exist after the last edge |
+| `pageInfo.hasPreviousPage` | `true` if results exist before the first edge |
+| `pageInfo.startCursor` | Cursor of the first edge in the current page |
+| `pageInfo.endCursor` | Cursor of the last edge in the current page |
+| `totalCount` | Total number of items across all pages |
+
+## Forward pagination with `first` and `after`
+
+To paginate forward through results, use the `first` argument to specify the page size and the `after` argument to specify the cursor to start after.
+
+### First page
+
+Omit the `after` argument to fetch the first page:
+
+```graphql
+query {
+  organizations(input: { first: 10 }) {
+    edges {
+      cursor
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+### Next page
+
+Pass the `endCursor` from the previous response as the `after` argument:
+
+```graphql
+query {
+  organizations(input: { first: 10, after: "cursor_from_previous_page" }) {
+    edges {
+      cursor
+      node {
+        id
+        name
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    totalCount
+  }
+}
+```
+
+## Checking for more pages
+
+Before requesting the next page, check the `hasNextPage` field:
+
+- `hasNextPage: true` — more results are available; pass `endCursor` to the next request's `after` argument
+- `hasNextPage: false` — all results have been fetched; stop paginating
+
+## Full paginated query example
+
+The following example fetches all members of an organization, page by page:
+
+```graphql
+# Page 1
+query {
+  organization(input: { slug: "my-company" }) {
+    members(first: 20) {
+      edges {
+        cursor
+        node {
+          id
+          userEmail
+          role
+          joinedAt
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      totalCount
+    }
+  }
+}
+```
+
+If `pageInfo.hasNextPage` is `true`, fetch the next page:
+
+```graphql
+# Page 2
+query {
+  organization(input: { slug: "my-company" }) {
+    members(first: 20, after: "cursor_from_page_1") {
+      edges {
+        cursor
+        node {
+          id
+          userEmail
+          role
+          joinedAt
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      totalCount
+    }
+  }
+}
+```
+
+Continue until `hasNextPage` returns `false`.
+
+## Paginated fields
+
+The following fields in the schema return connection types and support `first`/`after` pagination:
+
+| Parent Type | Field | Connection Type |
+|------------|-------|----------------|
+| `Query` | `organizations` | `OrganizationConnection` |
+| `User` | `organizations` | `OrganizationConnection` |
+| `User` | `invitations` | `ViewerInvitationConnection` |
+| `Organization` | `members` | `OrganizationMemberConnection` |
+| `Organization` | `invitations` | `OrganizationInvitationConnection` |
+| `Organization` | `projects` | `ProjectConnection` |
+| `Project` | `reports` | `ProjectReportConnection` |
+
+All of these fields accept the same `first` and `after` arguments and return the standard `edges`, `pageInfo`, and `totalCount` structure.
+
+## Tips
+
+- **Default page size** — if `first` is omitted, the API applies a default limit. Explicitly setting `first` ensures predictable page sizes.
+- **Cursors are opaque** — cursor strings should be treated as opaque tokens. Do not parse, construct, or modify them. Pass them exactly as received from the API.
+- **Stable ordering** — results within a connection are returned in a stable order. The same cursor always refers to the same position in the result set.
+- **Combine with other fields** — pagination arguments can be used alongside other query fields. For example, fetching an organization and its first page of members in a single request is common and efficient.

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

@@ -0,0 +1,72 @@
+---
+layout: docs
+---
+
+# Image optimisation service
+
+The Picked image optimisation service is a hosted endpoint at `https://img.picked.app`. It fetches images from allowed source domains, resizes them, re-encodes to modern formats (WebP or AVIF), and caches the result.
+
+## Endpoint
+
+```
+GET https://img.picked.app/_next/image?url={source}&w={width}&q={quality}
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `url` | URL-encoded URL of the source image. Must point to an allowed source domain (see below). |
+| `w` | Target width in pixels. Must match one of the supported widths. |
+| `q` | Target quality (`25`, `50`, `75`, or `100`). |
+
+The service performs content negotiation: if the requesting browser advertises `image/avif` or `image/webp` in its `Accept` header, the response uses that format. Otherwise the response uses the source format.
+
+## Allowed source domains
+
+The service only fetches from these hostnames:
+
+- `**.picked.app`
+
+A request whose `url` parameter resolves to any other hostname returns `400 Bad Request`.
+
+## Supported widths
+
+```
+640, 750, 828, 1080, 1200, 1920, 2048, 3840
+```
+
+Requests with any other width return `400 Bad Request`. Pick the smallest width that covers your target rendering size at the user's device pixel ratio.
+
+## Supported qualities
+
+```
+25, 50, 75, 100
+```
+
+Lower values reduce bandwidth significantly. `75` is a good default for most images; use `25` or `50` for thumbnails on slow networks.
+
+## Responsive images
+
+Combine the endpoint with the standard `srcset` attribute to let browsers pick the right width per viewport:
+
+```html
+<img
+  src="https://img.picked.app/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75"
+  srcset="
+    https://img.picked.app/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=640&q=75 640w,
+    https://img.picked.app/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75 1080w,
+    https://img.picked.app/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1920&q=75 1920w
+  "
+  sizes="(max-width: 768px) 100vw, 720px"
+  alt="..."
+/>
+```
+
+## Caching
+
+Optimised responses are cached by the upstream CDN. The minimum cache TTL is 60 seconds; the actual lifetime depends on the CDN's eviction policy. If you change the source image at the same URL, expect the optimised variant to remain cached for at least that interval.
+
+## Security
+
+- SVG sources are not optimised. Requests for SVG return the original bytes if the source is allowed; the service never executes embedded scripts.
+- Optimised responses carry a strict `Content-Security-Policy` (`default-src *; script-src 'none'; sandbox;`) so even a compromised source cannot run scripts in a viewing browser.
+- The response uses `Content-Disposition: inline`, never `attachment`.

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

@@ -35,14 +35,14 @@ When the client starts, the plugin resolves your project configuration using a t
 
 1. **Preview mode** — When you [enter preview mode from the dashboard](/workspaces#preview), the plugin fetches fresh config from the API. Feature decisions use session storage so they are not persisted beyond the current tab.
 
-2. **Build-time config** — If `projectConfig` was passed as a plugin option, or the [Vite Plugin](/tooling/vite-plugin) injected config at build time, the plugin uses that config with no network request.
+2. **Build-time config** — If `projectConfig` was passed as a plugin option, or the [Vite Plugin](/vite-plugin) injected config at build time, the plugin uses that config with no network request.
 
 3. **Runtime fetch** — Otherwise, the plugin fetches config from the API when the client starts.
 
 Once resolved, the plugin registers all features, conditions, fields, steps, and experiences with the client. Experiences then initialize according to their [conditions](/sdk/conditions) and [target selectors](/sdk/experiences).
 
 :::note
-The [Vite Plugin](/tooling/vite-plugin) eliminates the runtime API request in production by embedding your project config at build time. This is the recommended setup for Vite-based applications.
+The [Vite Plugin](/vite-plugin) eliminates the runtime API request in production by embedding your project config at build time. This is the recommended setup for Vite-based applications.
 :::
 
 ## Feature Allocation

package/dist/docs/workspaces.mdx

@@ -18,6 +18,12 @@ A workspace is a version of your project's configuration. Use workspaces to stag
 
 Each project has a workspace that holds your experiences, features, and entity configurations. When you make changes in the dashboard — editing a flow, updating a feature, or modifying an entity — those changes exist in the workspace until you publish.
 
+A workspace is in one of three states:
+
+- **Live** — the workspace the SDK serves to visitors. There is exactly one live workspace per project.
+- **Draft** — a workspace not currently serving traffic. You can edit, preview, and publish a draft to make it live.
+- **Archived** — a draft you have set aside. Archived workspaces stay editable but are filtered out of the default workspaces list.
+
 ## Preview
 
 Preview your workspace to see how changes look before publishing.
@@ -34,10 +40,63 @@ Your site opens in a new tab with the unpublished workspace applied. Preview use
 Publishing creates an immutable snapshot of your workspace. Once published, the SDK serves the new configuration to visitors.
 
 1. Click **Publish** in the workspace toolbar.
-2. Confirm in the publish dialog.
+2. Review the change preview in the publish modal.
+3. Click **Publish** to confirm.
 
 The publish button is only enabled when there are unpublished changes. A status badge in the toolbar shows whether the workspace has unpublished changes or is up to date.
 
+## Change previews
+
+The publish modal shows a side-by-side change preview comparing the current workspace against the last published snapshot. Use it to verify exactly what your visitors will see after publishing.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}?action=publish"
+  alt="The publish modal showing a change preview with added experiences, steps, and conditions"
+  selector='[role="dialog"]'
+  wait='[role="dialog"]'
+  hide={['[data-testid="publish-diff-replaces-version"]']}
+  renderWidth={720}
+  renderHeight={579}
+/>
+
+The preview groups changes by entity type — experiences, features, steps, fields, actions, and conditions. Each row shows whether the entity was **added**, **removed**, or **modified**. For modifications, expand the row to see which properties changed.
+
+When the change preview includes breaking changes — for example, removing a field that other steps still reference — a banner highlights the breaking entries above the diff so you can reconsider before publishing.
+
+The first publish of a workspace has no previous snapshot to compare against, so the publish modal shows the workspace's contents as the initial publish without a diff.
+
 ## Unpublished changes
 
 The workspace tracks whether any changes have been made since the last publish. If you create or update an experience, feature, or entity after the last publish, the toolbar shows a warning badge indicating unpublished changes.
+
+## Workspace settings
+
+The workspace settings page (**Settings** in the workspace nav) covers renaming, archiving, and deleting a workspace.
+
+### Rename
+
+Change the workspace name in the **Name** field and click **Save**. Names are unique within a project — duplicates are rejected with a validation error.
+
+### Archive
+
+Archiving moves a draft workspace out of the default workspaces list without deleting it. Use it for drafts you want to set aside for later without losing the work.
+
+1. Open the workspace settings page.
+2. Click **Archive** in the page header.
+3. Confirm in the modal.
+
+Live workspaces cannot be archived directly — make a different workspace live first, then archive the previous one.
+
+### Unarchive
+
+Restore an archived workspace to draft status from the same page. The settings page detects the archived state and switches the toolbar button to **Unarchive**.
+
+### Delete
+
+Deleting a workspace permanently removes it and its entities. This is destructive and cannot be undone — prefer archive when in doubt.
+
+1. Open the workspace settings page.
+2. In the **Danger zone** card at the bottom, click **Delete**.
+3. Confirm in the modal.
+
+Live workspaces cannot be deleted. Archive or publish a different workspace first to free the workspace for deletion.

package/dist/esm/form/index.js

@@ -389,7 +389,32 @@ function y(e) {
 	if (t instanceof HTMLInputElement) return t.type === "checkbox" ? t.checked : t.value;
 	if (t instanceof HTMLSelectElement || t instanceof HTMLTextAreaElement) return t.value;
 }
-function b(e, t, r, i) {
+function b(e, t, n) {
+	let r = e.currentTarget;
+	if (t.multiple) {
+		if (r instanceof HTMLInputElement && r.type === "checkbox") return x(e, r, n);
+		if (r instanceof HTMLSelectElement && r.multiple) return Array.from(r.selectedOptions, (e) => e.value);
+	}
+	return y(e);
+}
+function x(e, t, n) {
+	if (e.type === "input") return;
+	let r = Array.isArray(n) ? n.map(String) : [];
+	return e.type === "change" ? S(r, String(t.value)) : r;
+}
+function S(e, t) {
+	return e.includes(t) ? e.filter((e) => e !== t) : [...e, t];
+}
+function C(e, t, n) {
+	return (r) => {
+		let i = b(r, e, t);
+		i !== void 0 && n({
+			fieldKey: e.key,
+			value: i
+		});
+	};
+}
+function w(e, t, r, i) {
 	let { client: s, experienceInstance: c } = e, { currentStepStore: l, goToNextStep: u } = c, d = n(l, c, (e, t) => ({
 		stepId: e?.id,
 		experienceId: t.id
@@ -404,49 +429,31 @@ function b(e, t, r, i) {
 		},
 		target: f
 	});
-	let { fieldInputEvent: h, fieldChangeEvent: _, fieldBlurEvent: b, touchedStore: x, fieldErrorsStore: S, formErrorsStore: C } = g(s, p, f), w = n({
+	let { fieldInputEvent: h, fieldChangeEvent: _, fieldBlurEvent: y, touchedStore: b, fieldErrorsStore: x, formErrorsStore: S } = g(s, p, f), w = n({
 		fields: p,
 		responses: s.responses.listStore,
 		staged: f,
-		fieldErrors: S,
-		touched: x,
+		fieldErrors: x,
+		touched: b,
 		experienceAndStepId: d
 	}, ({ fields: e, responses: t, staged: n, fieldErrors: r, touched: i, experienceAndStepId: a }) => e.map((e) => {
-		let o = (t) => {
-			let n = y(t);
-			n !== void 0 && h({
-				fieldKey: e.key,
-				value: n
-			});
-		}, s = (t) => {
-			let n = y(t);
-			n !== void 0 && _({
-				fieldKey: e.key,
-				value: n
-			});
-		}, c = (t) => {
-			let n = y(t);
-			n !== void 0 && b({
-				fieldKey: e.key,
-				value: n
-			});
-		}, l = n[e.key] ?? t.find((t) => t.fieldKey === e.key)?.value ?? e.defaultValue, u = r[e.key], d = e.type === "number" ? "number" : "text", f = e.type === "boolean" ? "checkbox" : d, { experienceId: p, stepId: m } = a, g = `${p}-${m ?? "step"}-${e.id}`;
+		let o = n[e.key] ?? t.find((t) => t.fieldKey === e.key)?.value ?? e.defaultValue, s = C(e, o, h), c = C(e, o, _), l = C(e, o, y), u = r[e.key], d = e.type === "number" ? "number" : "text", f = e.type === "boolean" ? "checkbox" : d, { experienceId: p, stepId: m } = a, g = `${p}-${m ?? "step"}-${e.id}`;
 		return {
 			...e,
-			value: l,
+			value: o,
 			error: u,
 			touched: i[e.key] ?? !1,
 			props: {
 				id: g,
 				name: e.key,
 				key: e.key,
-				value: l,
+				value: o,
 				type: f,
 				required: e.required,
 				placeholder: e.placeholder,
-				oninput: o,
-				onchange: s,
-				onblur: c
+				oninput: s,
+				onchange: c,
+				onblur: l
 			}
 		};
 	})), { submitEvent: T, isFormSubmitting: E, onBeforeSubmit: D, onSuccess: O, onError: k, submitStarted: A, validationErrorsReceived: j } = v({
@@ -461,20 +468,20 @@ function b(e, t, r, i) {
 	return o({
 		clock: A,
 		fn: () => ({}),
-		target: x
+		target: b
 	}), o({
 		clock: A,
 		fn: () => ({}),
-		target: S
+		target: x
 	}), o({
 		clock: j,
 		source: p,
 		fn: (e, t) => Object.fromEntries(t.map((t) => [e.find((e) => e.key === t.fieldKey)?.key ?? t.fieldKey, t])),
-		target: S
+		target: x
 	}), {
 		form: {
 			props: { onsubmit: T },
-			errors: C,
+			errors: S,
 			submitting: E,
 			onBeforeSubmit: D,
 			onSuccess: O,
@@ -484,4 +491,4 @@ function b(e, t, r, i) {
 	};
 }
 //#endregion
-export { l as buildResponsesFromFormData, m as createFieldEvaluator, g as createFieldValidation, b as createForm, v as createSubmitPipeline, y as getEventValue, p as getStepFields };
+export { l as buildResponsesFromFormData, m as createFieldEvaluator, g as createFieldValidation, w as createForm, v as createSubmitPipeline, y as getEventValue, p as getStepFields };