@delmaredigital/payload-experiments 0.3.0-rc.4 → 0.4.0-rc.2

package/README.md

@@ -1,5 +1,7 @@
 # @delmaredigital/payload-experiments
 
+> ⚠️ Upgrading to 0.4? Run `payload migrate:create` for four nullable plugin columns (`xp_experiments.page_collection` and its `_xp_experiments_v` counterpart, `xp_phases.placement_docs`, `xp_state.retired_slugs`), plus the Experiment block and `xpGoal` columns if you adopt them, then `payload generate:importmap`. Saves on pages, blocks and Puck collections can now be refused while a test runs on them (`page-busy`, `interacting-tests`); Puck tests whose slot is only on a draft can't start until the page is published; host `metricSources` ids may not start with `click:`; `admin.editorUrl` now receives a required `editor` argument. See the CHANGELOG's BREAKING section.
+
 > ⚠️ Upgrading to 0.3? For 0.3.0-rc.1, every `linkIdentity` call must supply `verified`; it now returns an outcome. Run `payload migrate:create` for the nullable `xp_identities.verified_at` column and `user_id` index, plus the release-pages columns listed in the CHANGELOG (`decision_pages_released_at` / `decision_pages_released_by` on `xp_experiments` and their `version_` counterparts on `_xp_experiments_v`). Existing identity links become unverified; see the CHANGELOG for optional backfill.
 
 > ⚠️ Upgrading to 0.2? After upgrading, run `payload generate:importmap`: the Tests surface is registered through admin.dependencies, and without it the Tests routes show a 'not installed' message instead of the Tests screen. In 0.2.0-rc.2, the Tests server views moved from `/rsc` to `/admin/rsc`, so the import map must be regenerated when upgrading from rc.1 too. The old experiments edit-form components are gone from `/admin/client`, and the `xp-experiments` admin list and edit views now redirect to the Tests surface.
@@ -426,6 +428,7 @@ schema. Optional callbacks integrate host-owned content:
 
 A `MetricSource`, registered in `metricSources`, has `id`, `label`,
 `kind: 'binomial' | 'count' | 'revenue'`, and `keyedBy: 'visitor' | 'user'`.
+Source ids starting with `click:` are reserved for click goals and refused at boot.
 `clientWritable` optionally permits client conversions (revenue is always
 server-only). `query({ from, to, unitIds? })` returns a promise of
 `[{ unitId, value, ts }]`, **one row per event**, with `ts` a `Date`; use the
@@ -456,6 +459,21 @@ are recorded with `trackConversion`. Beacon conversions for a non-writable name
 are dropped silently. Only listed names become `events:<name>` sources. They
 support visitor and user units and do not represent counts or revenue in v1.
 
+### Testing page SEO in the host
+
+`pageKindSeoContract({ secret, original, versions, state, winner? })` from `/rsc`
+returns `{ manifest, rows }`. States are `running`, `decided` and `archived`;
+provide a winner path for the latter two. Build the host's test runtime with
+`loadManifest: async () => manifest` and the same secret. For each row, set
+`next/headers` to its signed `headers`, render metadata for `servedPath`, and
+assert `expect.robots`, `expect.canonical` and `expect.inSitemap` against the
+host's metadata and sitemap functions. This includes the Original served as
+each version, including the homepage.
+
+A host-level test mocks four boundaries: `next/headers`, the page loader,
+the runtime and the site URL. Set `metadataBase` so relative canonical paths
+resolve to your site URL.
+
 ### Whole-page options
 
 | Option | Purpose |
@@ -489,7 +507,18 @@ pages: {
 Adapt both callbacks for the site's homepage path. These checks run before Start;
 they do not protect pages from later deletion, unpublishing or renaming. Keep an
 archived winner published at the same address: archived test URLs still point to it.
-No migration is needed.
+Whole-page registrations also install the sidebar test status and content-change hooks.
+For 0.4.0, run `payload migrate:create` for `xp_state.retired_slugs`,
+`xp_experiments.page_collection` and its version column, then
+`payload generate:importmap`.
+
+`contentOf(doc)` optionally selects the content your site renders (for example,
+`doc.layout`). Published copies are compared with nested `id` and `blockName`
+keys removed. Without it, content checks and page content-change comparisons
+are skipped. `copyHint` (up to 200 characters), `copyUrl` (a root-relative path)
+and `copyLabel` (up to 40 characters, requires `copyUrl`) customize the guidance
+for making version pages. The default copy link opens the registered collection's
+list under the configured admin route.
 
 ### `admin` options
 
@@ -504,7 +533,7 @@ For example, pass:
 
 ```ts
 admin: {
-  editorUrl: ({ collection, id, draft }) =>
+  editorUrl: ({ collection, id, draft, editor, doc }) =>
     `/admin/puck-editor/${encodeURIComponent(collection)}/${encodeURIComponent(String(id))}`,
   previewUrl: async ({ collection, slug }) => {
     if (collection !== 'pages' || slug === undefined) return null
@@ -570,7 +599,10 @@ separately. Only manual, viewport and pageview exposure policies are accepted.
 Conversions require a client-writable source, never revenue; client values are
 stored as `1`, attributes are allow-listed, and the host's `events.rateLimit`
 adapter runs when supplied. Accepted and dropped events both return `202 {}`;
-malformed requests can return errors.
+malformed requests can return errors. `click:<key>` conversions are also accepted
+for defined click-goal keys matching `[a-z0-9][a-z0-9_-]{0,63}`; undefined or
+invalid keys are dropped with `202`. Clicks carry no attributes, and defined
+keys may be cached for up to 30 seconds.
 
 **The real bound on slow or method-override bodies is the host firewall/platform
 timeout.** A stream under the byte limit can remain open, and Payload can read
@@ -588,13 +620,15 @@ for these patterns.
 
 ## Admin and client
 
-The sidebar includes a **Tests** group with **All tests** and **Goals**. The
-dashboard also includes **Tests** and **Goals** cards above its widgets. Goals
-appears only for users who can manage tests. Both additions follow the host's
-admin route and keep host-provided navigation and dashboard entries first.
-After upgrading, run `payload generate:importmap` to register the dashboard card
-component and the server nav wrapper.
-A host nav group also labelled "Tests" shares Payload's NavGroup DOM id and open-state preference with the plugin's group, so pick another label.
+**Tests** is a regular navigation group for managers only, with **All tests**
+and **Goals**. It is the first named group, after Payload's default
+Collections/Globals groups when the host has ungrouped entities. Payload's own
+dashboard shows the Tests cards. A host collection with `group: 'Tests'` joins
+the plugin's group.
+
+After upgrading, run `payload generate:importmap` to register the two list views
+and the Goals edit redirect. Without regeneration, both list URLs and the Goal
+create/edit URLs show Payload's raw views.
 
 ### Client assignments and exposure
 
@@ -647,32 +681,61 @@ configured to allow client writes; record revenue on the server.
 
 ### Puck render and editor configs
 
-Register the factories from `/puck` and `/puck/editor`, using the same
-`ExperimentSlot` component name in both configs. Pass the host's Payload routes:
+Works with: payload-puck ≥0.10.3 (experiments ≥0.4.0).
+
+For payload-puck hosts, add one integration object on each side. In the render
+config, pass `integrations` to `extendConfig`:
 
 ```ts
-import { createExperimentSlot } from '@delmaredigital/payload-experiments/puck'
-import { createExperimentSlotEditor, experimentOutlinePlugin } from '@delmaredigital/payload-experiments/puck/editor'
+import { extendConfig } from '@delmaredigital/payload-puck/config'
+import { experimentsPuck } from '@delmaredigital/payload-experiments/puck'
+import { baseConfig } from './baseConfig'
 
-const routes = { admin: '/manage', api: '/content-api' } // Same as Payload config.routes
-const accent = '#1f3a68' // Same as the plugin's theme.accent
+export const renderConfig = extendConfig({
+  base: baseConfig,
+  integrations: [experimentsPuck()],
+})
+```
 
-// Render config
-components: { ExperimentSlot: createExperimentSlot({ routes }) }
+Call `experimentsPuckEditor()` once at module scope in a `'use client'` module,
+then pass that array to `PuckConfigProvider`. A new object per render rebuilds
+Puck's config and plugin list.
 
-// Editor config
-components: { ExperimentSlot: createExperimentSlotEditor({ routes, accent }) }
-```
+```tsx
+'use client'
 
-Add `experimentOutlinePlugin()` to Puck's `plugins` alongside this block config
-(with payload-puck, use its `plugins` option). It composes with the host's outline
-override and hides empty version slots that the block's test doesn't use. Content
-in an unused slot stays visible in the outline and gets a warning in the block.
+import { PuckConfigProvider } from '@delmaredigital/payload-puck/client'
+import { experimentsPuckEditor } from '@delmaredigital/payload-experiments/puck/editor'
+import { editorConfig } from './editorConfig'
 
-```ts
-plugins: [experimentOutlinePlugin()]
+const integrations = [experimentsPuckEditor()]
+
+export function PuckProvider({ children }: { children: React.ReactNode }) {
+  return <PuckConfigProvider config={editorConfig} integrations={integrations}>
+    {children}
+  </PuckConfigProvider>
+}
 ```
 
+Each object includes the test block and its **A/B tests** sidebar category. The
+editor object also includes the outline plugin: it hides empty version slots
+that the block's test doesn't use, while content in unused slots stays visible
+with a warning. Both helpers accept `{ routes }`; the editor also accepts
+`accent`. Use the host's Payload routes and the plugin's `theme.accent`.
+
+#### Wiring Puck by hand
+
+The separate pieces stay exported:
+
+- `/puck`: `ExperimentSlot`, `createExperimentSlot({ routes })`,
+  `EXPERIMENT_SLOT_TYPE` and `createExperimentSlotField({ routes })`.
+- `/puck/editor`: `ExperimentSlotEditor`,
+  `createExperimentSlotEditor({ routes, accent })` and `experimentOutlinePlugin()`.
+
+Register the render and editor blocks under the same `EXPERIMENT_SLOT_TYPE` key (import it from `/puck`),
+add a sidebar category listing it, and add `experimentOutlinePlugin()` to Puck's
+`plugins`. It composes with the host's outline override.
+
 Routes default to Payload's `/admin` and `/api` when omitted. The existing
 `ExperimentSlot` and `ExperimentSlotEditor` exports remain available with these
 defaults. Hosts on non-default routes switch to the factories. The standalone
@@ -815,3 +878,35 @@ The WCAG 2.x gate requires at least 4.5:1 **foreground text on the accent fill**
 in each theme (the accent is used as a fill, not as page text). A failing
 colour is refused with its ratio. Status chips retain Payload semantic colours.
 `deriveAccent` is also exported from `/puck/editor` for editor integrations.
+
+## Click goals
+
+Click goals use a goal's short name as their key (`click:<short-name>`). Add
+`xpGoalField()` from the root entry to a host block or array row. Its manager
+picker includes inline creation with "+ New click goal"; run
+`payload generate:importmap` to register the picker. For Puck's `xpGoal` prop,
+use `xpGoalPuckEditorField()` from `/puck/editor` in your editor config and
+`xpGoalPuckField()` from `/puck` in your render config. Run the
+host's `payload migrate:create`: each table using the Payload field (and its
+version table) gains a nullable text column. Render the value on the actual
+interactive element as `data-xp-goal={xpGoal}`; code can also set
+`data-xp-goal="join"` directly. Define a click goal with that short name first.
+For managers, an undefined key blocks the save through the Payload field's
+server validation, refreshing a cached miss immediately.
+Draft saves are also refused when the collection validates drafts
+(`versions.drafts.validate`). Editors without goal-management access see a
+plain text input. Goals in
+related documents and keys placed only in code are invisible to the content
+fairness check.
+
+`ExperimentsProvider` records native clicks when its server assignments arm
+click goals. Nested providers share one document listener; the deepest armed
+provider supplies the route and pageview id. Enter on links/buttons and Space
+on buttons count through the browser's native click. A focusable `div` needs
+`role="button"` and the host's own keyboard handler. Beacons use `sendBeacon`
+(with a keepalive fallback) so navigation/unload does not discard the click.
+Click and exposure beacons share `events.rateLimit`; size the adapter for both.
+New click goals are accepted within 30 seconds. A click goal may be primary;
+primary and guardrail goals must appear in every tested version or outside all
+of them. Secondary asymmetry warns, and results health checks published rows
+again on every run.

package/dist/admin/MetricSourceSelect.js

@@ -1,14 +1,14 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { SelectInput, useField } from '@payloadcms/ui';
-import { metricSourceHint, metricSourceOptions } from './metricSource.model.js';
+import { metricSourceHint, metricSourceOptions, sourceFor } from './metricSource.model.js';
 import { METRICS_COPY } from './copy/metrics.js';
 export function MetricSourceSelect({ path, field, readOnly }) {
     const { value, setValue } = useField({
         path
     });
     const sources = field.admin?.custom?.sources ?? [];
-    const hint = metricSourceHint(sources.find((source)=>source.id === value));
+    const hint = metricSourceHint(sourceFor(value, sources));
     const locked = Boolean(readOnly || field.admin?.readOnly);
     return /*#__PURE__*/ _jsxs("div", {
         children: [
@@ -19,7 +19,7 @@ export function MetricSourceSelect({ path, field, readOnly }) {
                 description: field.admin?.description,
                 required: field.required,
                 options: metricSourceOptions(sources),
-                value: value ?? '',
+                value: sourceFor(value, sources)?.id ?? value ?? '',
                 readOnly: locked,
                 onChange: (option)=>{
                     if (!locked) setValue(option && !Array.isArray(option) ? option.value : null);

package/dist/admin/PlacementStatus.d.ts

@@ -0,0 +1,3 @@
+import type { UIFieldClientProps } from 'payload';
+/** Manage-only endpoint: access-filtered editors see no status or error text. */
+export declare function PlacementStatus(_props: UIFieldClientProps): import("react").JSX.Element;

package/dist/admin/PlacementStatus.js

@@ -0,0 +1,54 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useConfig, useDocumentInfo } from '@payloadcms/ui';
+import { useEffect, useMemo, useState } from 'react';
+import { formatAdminURL } from 'payload/shared';
+import { createApi } from './api.js';
+import { pageStatusCopy } from './placementStatus.model.js';
+/** Manage-only endpoint: access-filtered editors see no status or error text. */ export function PlacementStatus(_props) {
+    const { id, collectionSlug } = useDocumentInfo();
+    const { config } = useConfig();
+    const api = useMemo(()=>createApi(config.routes.api), [
+        config.routes.api
+    ]);
+    const [tests, setTests] = useState([]);
+    useEffect(()=>{
+        let active = true;
+        setTests([]);
+        if (id != null && collectionSlug) void api.placementStatus({
+            docs: [
+                {
+                    collection: collectionSlug,
+                    id
+                }
+            ]
+        }).then((result)=>{
+            if (active && result.ok) setTests(result.data?.docs[`${collectionSlug}:${id}`]?.tests ?? []);
+        });
+        return ()=>{
+            active = false;
+        };
+    }, [
+        api,
+        collectionSlug,
+        id
+    ]);
+    return /*#__PURE__*/ _jsx(_Fragment, {
+        children: tests.map((test)=>{
+            const copy = pageStatusCopy(test);
+            return copy ? /*#__PURE__*/ _jsxs("p", {
+                children: [
+                    copy,
+                    ' ',
+                    /*#__PURE__*/ _jsx("a", {
+                        href: formatAdminURL({
+                            adminRoute: config.routes.admin,
+                            path: `/experiments/by-slug/${encodeURIComponent(test.slug)}`
+                        }),
+                        children: "Back to the test"
+                    })
+                ]
+            }, test.slug) : null;
+        })
+    });
+}

package/dist/admin/PreviewLinks.d.ts

@@ -1,6 +1,7 @@
 import type { DocId } from '../types/contracts.js';
 import type { PreflightResult } from '../types/endpoints.js';
-export declare function PreviewLinks({ experimentId, placements, arms, flagPoint }: {
+export declare function PreviewLinks({ experimentId, placements, arms, flagPoint, apiRoute }: {
+    apiRoute: string;
     flagPoint?: string;
     experimentId: DocId;
     placements: PreflightResult['placements'];

package/dist/admin/PreviewLinks.js

@@ -8,8 +8,8 @@ import { REVIEW_COPY as C } from './copy/review.js';
 import { TEST_PAGE } from './copy/testPage.js';
 import { API_MESSAGES, refusalMessage } from './copy/common.js';
 import { actionablePreviewPages } from './previewLinks.model.js';
-export function PreviewLinks({ experimentId, placements, arms, flagPoint }) {
-    const api = useApi();
+export function PreviewLinks({ experimentId, placements, arms, flagPoint, apiRoute }) {
+    const api = useApi(apiRoute);
     const inFlight = useRef(false);
     const [busy, setBusy] = useState(false);
     const [error, setError] = useState(null);

package/dist/admin/TestsDashboardCards.d.ts

@@ -1,3 +1,4 @@
 import './theme.css';
 import './dashboard.css';
+/** @deprecated Retained for existing import maps until 0.5.0. */
 export declare function TestsDashboardCards(): import("react").JSX.Element | null;

package/dist/admin/TestsDashboardCards.js

@@ -1,20 +1,16 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { surfaceUrls } from './surfaceUrls.js';
 import './theme.css';
 import './dashboard.css';
 import { Card, useAuth, useConfig } from '@payloadcms/ui';
-import { formatAdminURL } from 'payload/shared';
 import { SURFACE_COPY } from './copy/surface.js';
-export function TestsDashboardCards() {
+/** @deprecated Retained for existing import maps until 0.5.0. */ export function TestsDashboardCards() {
     const { config } = useConfig();
     const { permissions } = useAuth();
     const testPermissions = permissions?.collections?.['xp-experiments'];
     const canManage = testPermissions?.update === true;
     if (!canManage) return null;
-    const href = (path)=>formatAdminURL({
-            adminRoute: config.routes.admin,
-            path
-        });
     return /*#__PURE__*/ _jsxs("section", {
         className: "xp-dash-group",
         "aria-labelledby": "xp-dash-title",
@@ -32,7 +28,7 @@ export function TestsDashboardCards() {
                             title: SURFACE_COPY.navAllTests,
                             titleAs: "h3",
                             buttonAriaLabel: SURFACE_COPY.dashShowTests,
-                            href: href('/experiments'),
+                            href: surfaceUrls.home(config.routes.admin),
                             id: "card-xp-tests"
                         })
                     }),
@@ -41,7 +37,7 @@ export function TestsDashboardCards() {
                             title: SURFACE_COPY.navGoals,
                             titleAs: "h3",
                             buttonAriaLabel: SURFACE_COPY.dashShowGoals,
-                            href: href('/experiments/goals'),
+                            href: surfaceUrls.goals(config.routes.admin),
                             id: "card-xp-goals"
                         })
                     })

package/dist/admin/TestsNavLink.d.ts

@@ -1,4 +1,5 @@
 import './theme.css';
+/** @deprecated Retained for existing import maps until 0.5.0. */
 declare function TestsNav({ isOpen }: {
     isOpen?: boolean;
 }): import("react").JSX.Element | null;

package/dist/admin/TestsNavLink.js

@@ -1,22 +1,16 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { surfaceUrls } from './surfaceUrls.js';
 import './theme.css';
 import { Link, NavGroup, useAuth, useConfig } from '@payloadcms/ui';
-import { formatAdminURL } from 'payload/shared';
 import { usePathname } from 'next/navigation.js';
 import { SURFACE_COPY } from './copy/surface.js';
-function TestsNav({ isOpen = true }) {
+/** @deprecated Retained for existing import maps until 0.5.0. */ function TestsNav({ isOpen = true }) {
     const { config } = useConfig();
     const { permissions } = useAuth();
     const pathname = usePathname();
-    const href = formatAdminURL({
-        adminRoute: config.routes.admin,
-        path: '/experiments'
-    });
-    const goalsHref = formatAdminURL({
-        adminRoute: config.routes.admin,
-        path: '/experiments/goals'
-    });
+    const href = surfaceUrls.home(config.routes.admin);
+    const goalsHref = surfaceUrls.goals(config.routes.admin);
     const base = href.replace(/\/$/, '');
     const goalsBase = goalsHref.replace(/\/$/, '');
     const goalsActive = pathname === goalsBase || Boolean(pathname?.startsWith(`${goalsBase}/`));

package/dist/admin/actions/ConfirmDialog.d.ts

@@ -8,7 +8,8 @@ export declare function DialogFrame({ title, onClose, children, initialFocus, di
     onClose: () => void;
     children: ReactNode;
 }): import("react").JSX.Element;
-export declare function ConfirmDialog({ id, action, winnerLabel, onClose, canManage, isDecided }: {
+export declare function ConfirmDialog({ id, action, winnerLabel, onClose, canManage, isDecided, apiRoute }: {
+    apiRoute: string;
     canManage?: boolean;
     isDecided?: boolean;
     id: DocId;

package/dist/admin/actions/ConfirmDialog.js

@@ -20,8 +20,8 @@ export function DialogFrame({ title, onClose, children, initialFocus, dismissibl
         children: children
     });
 }
-export function ConfirmDialog({ id, action, winnerLabel, onClose, canManage = false, isDecided = false }) {
-    const api = useApi();
+export function ConfirmDialog({ id, action, winnerLabel, onClose, canManage = false, isDecided = false, apiRoute }) {
+    const api = useApi(apiRoute);
     const [typed, setTyped] = useState('');
     const [busy, setBusy] = useState(false);
     const [reportBusy, setReportBusy] = useState(false);

package/dist/admin/actions/DecideDialog.d.ts

@@ -1,7 +1,8 @@
 import type { DocId } from '../../types/contracts.js';
 import type { PreflightResult } from '../../types/endpoints.js';
 import type { ActionGroup } from './actions.model.js';
-export declare function DecideDialog({ id, arms, checks, onClose }: {
+export declare function DecideDialog({ id, arms, checks, onClose, apiRoute }: {
+    apiRoute: string;
     id: DocId;
     arms: readonly ActionGroup[];
     checks?: PreflightResult['checks'];

package/dist/admin/actions/DecideDialog.js

@@ -10,8 +10,8 @@ import { RESULTS_COPY } from '../copy/results.js';
 import { ACTIONS_COPY as C, decideCopy } from '../copy/actions.js';
 import { decideState } from './decide.model.js';
 import { DialogFrame } from './ConfirmDialog.js';
-export function DecideDialog({ id, arms, checks = [], onClose }) {
-    const api = useApi();
+export function DecideDialog({ id, arms, checks = [], onClose, apiRoute }) {
+    const api = useApi(apiRoute);
     const [snapshot, setSnapshot] = useState(null);
     const [chosenArm, setChosenArm] = useState(null);
     const [note, setNote] = useState('');

package/dist/admin/api.d.ts

@@ -1,5 +1,5 @@
 import type { DocId } from '../types/contracts.js';
-import type { RestoreContentEntryBody, RestoreContentEntryResult, DismissContentEntryBody, DismissContentEntryResult, AddMetricBody, AllocateBody, ArchiveBody, DecideBody, MakeContentResult, PreflightResult, PreviewTokenResult, RefusalCode, ResultsResponse, SummaryResponse, TransitionSuccess } from '../types/endpoints.js';
+import type { WrapBlockBody, PagesResult, PlacementStatusBody, PlacementStatusResult, RestoreContentEntryBody, RestoreContentEntryResult, DismissContentEntryBody, DismissContentEntryResult, AddMetricBody, AllocateBody, ArchiveBody, DecideBody, MakeContentResult, AddMetricResult, ClickKeysResult, PreflightResult, PreviewTokenResult, RefusalCode, ResultsResponse, SummaryResponse, TransitionSuccess } from '../types/endpoints.js';
 import { refusalMessage } from './copy/common.js';
 export type ApiResult<T> = {
     ok: true;
@@ -13,9 +13,24 @@ export type ApiResult<T> = {
 };
 type RequestOptions = NonNullable<Parameters<typeof refusalMessage>[3]>;
 export declare function createApi(apiBase: string): {
+    findTestIdBySlug: (slug: string) => Promise<Extract<ApiResult<DocId>, {
+        ok: false;
+    }> | {
+        ok: true;
+        data: DocId;
+    }>;
+    deleteTest: (id: DocId) => Promise<ApiResult<unknown>>;
+    wrapBlock: (body: WrapBlockBody) => Promise<ApiResult<Record<string, unknown>>>;
+    pages: (query: {
+        collection: string;
+        q?: string;
+        path?: string;
+        page?: number;
+    }, signal?: AbortSignal) => Promise<ApiResult<PagesResult>>;
+    placementStatus: (body: PlacementStatusBody) => Promise<ApiResult<PlacementStatusResult>>;
     start: (id: DocId) => Promise<ApiResult<TransitionSuccess>>;
     allocate: (id: DocId, body: AllocateBody, options?: RequestOptions) => Promise<ApiResult<TransitionSuccess>>;
-    addMetric: (id: DocId, body: AddMetricBody, options?: RequestOptions) => Promise<ApiResult<TransitionSuccess>>;
+    addMetric: (id: DocId, body: AddMetricBody, options?: RequestOptions) => Promise<ApiResult<AddMetricResult>>;
     stop: (id: DocId) => Promise<ApiResult<TransitionSuccess>>;
     decide: (id: DocId, body: DecideBody) => Promise<ApiResult<TransitionSuccess>>;
     releaseHoldout: (id: DocId) => Promise<ApiResult<TransitionSuccess>>;
@@ -24,6 +39,7 @@ export declare function createApi(apiBase: string): {
     dismissContentEntry: (id: DocId, body: DismissContentEntryBody) => Promise<ApiResult<DismissContentEntryResult>>;
     restoreContentEntry: (id: DocId, body: RestoreContentEntryBody) => Promise<ApiResult<RestoreContentEntryResult>>;
     archive: (id: DocId, body: ArchiveBody) => Promise<ApiResult<TransitionSuccess>>;
+    clickKeys: (id: DocId) => Promise<ApiResult<ClickKeysResult>>;
     preflight: (id: DocId) => Promise<ApiResult<PreflightResult>>;
     previewToken: (id: DocId, arm: string) => Promise<ApiResult<PreviewTokenResult>>;
     results: (id: DocId, options?: {

package/dist/admin/api.js

@@ -1,13 +1,18 @@
 import { API_MESSAGES, refusalMessage } from './copy/common.js';
+import { BLOCK_COPY } from './copy/blocks.js';
 import { CONTENT_ENTRY_REFUSALS } from './copy/actions.js';
 export function createApi(apiBase) {
+    const collectionBase = `${apiBase.replace(/\/$/, '')}/xp-experiments`;
     const base = `${apiBase.replace(/\/$/, '')}/xp/experiments`;
     const route = (id, action)=>`${base}/${encodeURIComponent(id)}/${action}`;
-    async function request(path, method, body, options) {
+    async function request(path, method, body, options, signal) {
         try {
             const response = await fetch(path(), {
                 method,
                 credentials: 'include',
+                ...signal ? {
+                    signal
+                } : {},
                 ...body === undefined ? {} : {
                     headers: {
                         'Content-Type': 'application/json'
@@ -48,7 +53,7 @@ export function createApi(apiBase) {
                     code
                 } : {},
                 message: refusalMessage(code, response.status, typeof error?.message === 'string' ? error.message : undefined, options),
-                retryable: code === 'commit-unverified' || response.status >= 500 && response.status !== 501
+                retryable: code === 'page-busy' || code === 'commit-unverified' || response.status >= 500 && response.status !== 501
             };
         } catch  {
             return {
@@ -61,6 +66,45 @@ export function createApi(apiBase) {
     }
     const post = (id, action, body, options)=>request(()=>route(id, action), 'POST', body, options);
     return {
+        findTestIdBySlug: async (slug)=>{
+            const result = await request(()=>`${collectionBase}?where[slug][equals]=${encodeURIComponent(slug)}&depth=0&limit=1`, 'GET');
+            if (!result.ok) return result;
+            const id = result.data?.docs?.[0]?.id;
+            if (id === undefined) return {
+                ok: false,
+                status: 404,
+                code: 'not-found',
+                message: refusalMessage('not-found', 404, undefined, {
+                    notFound: BLOCK_COPY.alreadyDeleted
+                }),
+                retryable: false
+            };
+            return {
+                ok: true,
+                data: id
+            };
+        },
+        deleteTest: (id)=>request(()=>`${collectionBase}/${encodeURIComponent(id)}`, 'DELETE', undefined, {
+                notFound: BLOCK_COPY.noLongerDraft,
+                forbidden: BLOCK_COPY.noLongerDraft,
+                codes: {
+                    'invalid-status': BLOCK_COPY.noLongerDraft
+                }
+            }),
+        wrapBlock: (body)=>request(()=>`${apiBase.replace(/\/$/, '')}/xp/blocks/wrap`, 'POST', body),
+        pages: (query, signal)=>request(()=>`${apiBase.replace(/\/$/, '')}/xp/pages?${new URLSearchParams({
+                    collection: query.collection,
+                    ...query.q ? {
+                        q: query.q
+                    } : {},
+                    ...query.path !== undefined ? {
+                        path: query.path
+                    } : {},
+                    ...query.page ? {
+                        page: String(query.page)
+                    } : {}
+                })}`, 'GET', undefined, undefined, signal),
+        placementStatus: (body)=>request(()=>`${apiBase.replace(/\/$/, '')}/xp/placements/status`, 'POST', body),
         start: (id)=>post(id, 'start'),
         allocate: (id, body, options)=>post(id, 'allocate', body, options),
         addMetric: (id, body, options)=>post(id, 'add-metric', body, options),
@@ -72,6 +116,7 @@ export function createApi(apiBase) {
         dismissContentEntry: (id, body)=>post(id, 'content-report/dismiss', body, CONTENT_ENTRY_REFUSALS),
         restoreContentEntry: (id, body)=>post(id, 'content-report/restore', body, CONTENT_ENTRY_REFUSALS),
         archive: (id, body)=>post(id, 'archive', body),
+        clickKeys: (id)=>request(()=>route(id, 'click-keys'), 'GET'),
         preflight: (id)=>request(()=>route(id, 'preflight'), 'GET'),
         previewToken: (id, arm)=>request(()=>`${route(id, 'preview-token')}?arm=${encodeURIComponent(arm)}`, 'GET'),
         results: (id, options = {})=>request(()=>{

package/dist/admin/blocks/BlockPanel.d.ts

@@ -0,0 +1,4 @@
+import type { UIFieldClientProps } from 'payload';
+export declare function BlockStatusField({ path }: UIFieldClientProps): import("react").JSX.Element | null;
+export declare function BlockSlotRowLabel(): import("react").JSX.Element;
+export declare function CopyOriginalField({ path }: UIFieldClientProps): import("react").JSX.Element | null;