@delmaredigital/payload-experiments 0.3.0-rc.1 → 0.4.0-rc.1

package/dist/admin/surface/test/VersionsSection.js

@@ -10,6 +10,8 @@ import { addHoldoutArm, addVariant, issuesByRow, removeArm, splitEvenly, totalWe
 import { allocationSentence } from '../../allocation.model.js';
 import { balanceWeight, orderedVersions, trafficShares } from './testPage.model.js';
 import { FieldErrors, ReadOnly, reasonFor, save, TextEdit } from './fields.js';
+import { PAGE_COPY } from '../../copy/pages.js';
+import { testPageCollection } from '../pagePicker/pagePicker.model.js';
 import { Section } from './Section.js';
 const COLOURS = {
     control: 'var(--xp-series-muted)',
@@ -49,6 +51,9 @@ export function VersionsSection({ test, surface, parts }) {
         test: test,
         sectionId: "versions",
         children: [
+            doc.kind === 'page' && testPageCollection(surface.pageCollections, doc, test.preflight?.pagePlacements)?.contentChecks === false ? /*#__PURE__*/ _jsx("p", {
+                children: PAGE_COPY.contentChecksOff
+            }) : null,
             reason ? /*#__PURE__*/ _jsx("p", {
                 className: "xp-ui-help",
                 children: reason
@@ -70,8 +75,10 @@ export function VersionsSection({ test, surface, parts }) {
                             /*#__PURE__*/ _jsx("span", {})
                         ]
                     }),
-                    ordered.map(({ arm, index })=>/*#__PURE__*/ _jsxs("article", {
+                    ordered.filter(({ arm })=>doc.kind !== 'page' || arm.kind !== 'holdout').map(({ arm, index })=>/*#__PURE__*/ _jsxs("article", {
                             className: "xp-version-row",
+                            id: `xp-version-${arm.key}`,
+                            tabIndex: -1,
                             children: [
                                 /*#__PURE__*/ _jsx(TextEdit, {
                                     label: `${GROUP_LABELS[arm.key]}: ${C.label}`,
@@ -93,7 +100,7 @@ export function VersionsSection({ test, surface, parts }) {
                                     reason: reason,
                                     hideLabel: true,
                                     disabled: Boolean(reason),
-                                    validate: (raw)=>raw.trim() !== '' && Number.isInteger(Number(raw)) && Number(raw) >= 0 && Number(raw) <= 100,
+                                    isValid: (raw)=>raw.trim() !== '' && Number.isInteger(Number(raw)) && Number(raw) >= 0 && Number(raw) <= 100,
                                     invalidMessage: C.invalidShare,
                                     onDraft: (value)=>setWeightEdit({
                                             key: arm.key,
@@ -177,11 +184,11 @@ export function VersionsSection({ test, surface, parts }) {
                         onClick: ()=>update((arms)=>addVariant(arms, doc.kind)),
                         children: C.addVersion
                     }),
-                    /*#__PURE__*/ _jsx(Button, {
+                    doc.kind !== 'page' ? /*#__PURE__*/ _jsx(Button, {
                         disabled: Boolean(reason) || doc.arms.some((arm)=>arm.kind === 'holdout'),
                         onClick: ()=>update(addHoldoutArm),
                         children: C.addHoldout
-                    }),
+                    }) : null,
                     /*#__PURE__*/ _jsx(Button, {
                         disabled: Boolean(reason),
                         onClick: ()=>update(splitEvenly),
@@ -189,7 +196,7 @@ export function VersionsSection({ test, surface, parts }) {
                     })
                 ]
             }),
-            doc.arms.some((arm)=>arm.kind === 'holdout') ? /*#__PURE__*/ _jsx("p", {
+            doc.kind !== 'page' && doc.arms.some((arm)=>arm.kind === 'holdout') ? /*#__PURE__*/ _jsx("p", {
                 className: "xp-ui-help",
                 children: ARMS_COPY.holdout
             }) : null,

package/dist/admin/surface/test/fields.d.ts

@@ -15,7 +15,7 @@ export declare function ReadOnly({ label, value, reason, labelAction }: {
     labelAction?: ReactNode;
 }): import("react").JSX.Element;
 /** Local typing is intentionally separate from staging: build the current group on commit. */
-export declare function TextEdit({ label, value, onCommit, reason, multiline, placeholder, type, min, max, required, onDraft, validate, invalidMessage, hideLabel, disabled, help }: {
+export declare function TextEdit({ label, value, onCommit, reason, multiline, placeholder, type, min, max, required, onDraft, isValid, invalidMessage, hideLabel, disabled, help }: {
     label: string;
     value: string | number;
     onCommit: (value: string) => void;
@@ -27,14 +27,21 @@ export declare function TextEdit({ label, value, onCommit, reason, multiline, pl
     min?: number;
     max?: number;
     required?: boolean;
-    validate?: (value: string) => boolean;
+    isValid?: (value: string) => boolean;
     invalidMessage?: string;
     hideLabel?: boolean;
     disabled?: boolean;
     help?: string;
 }): import("react").JSX.Element;
 export declare const positiveInteger: (raw: string) => boolean;
-export declare function SelectEdit({ label, value, options, reason, onCommit, readOnlyValue, labelAction }: {
+export type OptionGroup = {
+    label?: string;
+    options: readonly {
+        label: string;
+        value: string;
+    }[];
+};
+export declare function SelectEdit({ label, value, options, groups, reason, onCommit, readOnlyValue, labelAction }: {
     label: string;
     value: string;
     options: readonly {
@@ -45,8 +52,9 @@ export declare function SelectEdit({ label, value, options, reason, onCommit, re
     onCommit: (value: string) => void;
     readOnlyValue?: string;
     labelAction?: ReactNode;
+    groups?: readonly OptionGroup[];
 }): import("react").JSX.Element;
-export declare function CheckboxList({ label, value, options, reason, onToggle, readOnlyValue, searchable }: {
+export declare function CheckboxList({ label, value, options, groups, reason, onToggle, readOnlyValue, searchable }: {
     label: string;
     value: string[];
     options: readonly {
@@ -57,6 +65,7 @@ export declare function CheckboxList({ label, value, options, reason, onToggle,
     onToggle: (value: string, checked: boolean) => void;
     readOnlyValue?: string;
     searchable?: boolean;
+    groups?: readonly OptionGroup[];
 }): import("react").JSX.Element;
 export declare function TestName({ test }: SectionProps): import("react").JSX.Element;
 export declare function Hypothesis({ test }: SectionProps): import("react").JSX.Element;

package/dist/admin/surface/test/fields.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useId, useState } from 'react';
-import { TextInput, NumberInput, Textarea, Select, SearchInput, CheckboxList as UICheckboxList } from '../../../ui/Inputs.js';
+import { TextInput, NumberInput, Textarea, Select, SearchInput, Checkbox, CheckboxList as UICheckboxList } from '../../../ui/Inputs.js';
 import { TEST_PAGE as C } from '../../copy/testPage.js';
 import { EDITABLE_BY_STATUS } from '../../../collections/experiments/editability.js';
 import { lockedReason } from '../../lockedNotice.model.js';
@@ -45,7 +45,7 @@ export function ReadOnly({ label, value, reason, labelAction }) {
         ]
     });
 }
-/** Local typing is intentionally separate from staging: build the current group on commit. */ export function TextEdit({ label, value, onCommit, reason, multiline, placeholder, type = 'text', min, max, required, onDraft, validate, invalidMessage, hideLabel = false, disabled = false, help }) {
+/** Local typing is intentionally separate from staging: build the current group on commit. */ export function TextEdit({ label, value, onCommit, reason, multiline, placeholder, type = 'text', min, max, required, onDraft, isValid, invalidMessage, hideLabel = false, disabled = false, help }) {
     const id = useId();
     const [draft, setDraft] = useState(String(value));
     const [error, setError] = useState(null);
@@ -54,7 +54,8 @@ export function ReadOnly({ label, value, reason, labelAction }) {
     ]);
     const commit = ()=>{
         if (draft === String(value)) return;
-        if (validate && !validate(draft)) {
+        // Named isValid, not validate: Payload 4's Local API has a validate method, which the access gate flags.
+        if (isValid && !isValid(draft)) {
             setError(draft.trim() ? invalidMessage ?? null : null);
             setDraft(String(value));
             onDraft?.(String(value));
@@ -96,7 +97,7 @@ export function ReadOnly({ label, value, reason, labelAction }) {
     });
 }
 export const positiveInteger = (raw)=>raw.trim() !== '' && Number.isInteger(Number(raw)) && Number(raw) > 0;
-export function SelectEdit({ label, value, options, reason, onCommit, readOnlyValue, labelAction }) {
+export function SelectEdit({ label, value, options, groups, reason, onCommit, readOnlyValue, labelAction }) {
     const id = useId();
     if (reason) {
         return /*#__PURE__*/ _jsx(ReadOnly, {
@@ -112,13 +113,22 @@ export function SelectEdit({ label, value, options, reason, onCommit, readOnlyVa
         labelAction: labelAction,
         value: value,
         onChange: (e)=>onCommit(e.target.value),
-        children: options.map((option)=>/*#__PURE__*/ _jsx("option", {
+        children: groups ? groups.map((group, index)=>group.label ? /*#__PURE__*/ _jsx("optgroup", {
+                label: group.label,
+                children: group.options.map((option)=>/*#__PURE__*/ _jsx("option", {
+                        value: option.value,
+                        children: option.label
+                    }, option.value))
+            }, index) : group.options.map((option)=>/*#__PURE__*/ _jsx("option", {
+                    value: option.value,
+                    children: option.label
+                }, option.value))) : options.map((option)=>/*#__PURE__*/ _jsx("option", {
                 value: option.value,
                 children: option.label
             }, option.value))
     });
 }
-export function CheckboxList({ label, value, options, reason, onToggle, readOnlyValue, searchable = false }) {
+export function CheckboxList({ label, value, options, groups, reason, onToggle, readOnlyValue, searchable = false }) {
     const id = useId();
     const [query, setQuery] = useState('');
     const visible = searchable ? options.filter((option)=>value.includes(option.value) || option.label.toLowerCase().includes(query.toLowerCase())) : options;
@@ -127,21 +137,43 @@ export function CheckboxList({ label, value, options, reason, onToggle, readOnly
         reason: reason,
         value: readOnlyValue ?? value.map((v)=>options.find((o)=>o.value === v)?.label ?? v).join(', ')
     });
-    return /*#__PURE__*/ _jsx(UICheckboxList, {
+    return /*#__PURE__*/ _jsxs(UICheckboxList, {
         id: id,
         label: label,
         value: value,
-        options: visible,
+        options: groups ? [] : visible,
         onChange: (next)=>{
             const changed = options.find((option)=>next.includes(option.value) !== value.includes(option.value));
             if (changed) onToggle(changed.value, next.includes(changed.value));
         },
-        children: searchable ? /*#__PURE__*/ _jsx(SearchInput, {
-            id: `${id}-search`,
-            label: C.searchGoals,
-            value: query,
-            onChange: (event)=>setQuery(event.target.value)
-        }) : null
+        children: [
+            searchable ? /*#__PURE__*/ _jsx(SearchInput, {
+                id: `${id}-search`,
+                label: C.searchGoals,
+                value: query,
+                onChange: (event)=>setQuery(event.target.value)
+            }) : null,
+            groups ? groups.map((group, index)=>{
+                const items = group.options.filter((option)=>visible.some((item)=>item.value === option.value));
+                return items.length ? /*#__PURE__*/ _jsxs("div", {
+                    children: [
+                        group.label ? /*#__PURE__*/ _jsx("h3", {
+                            children: group.label
+                        }) : null,
+                        /*#__PURE__*/ _jsx("ul", {
+                            children: items.map((option)=>/*#__PURE__*/ _jsx("li", {
+                                    children: /*#__PURE__*/ _jsx(Checkbox, {
+                                        id: `${id}-${index}-${option.value}`,
+                                        label: option.label,
+                                        checked: value.includes(option.value),
+                                        onChange: (event)=>onToggle(option.value, event.target.checked)
+                                    })
+                                }, option.value))
+                        })
+                    ]
+                }, index) : null;
+            }) : null
+        ]
     });
 }
 export function TestName({ test }) {

package/dist/admin/surface/test/jumpToSection.d.ts

@@ -1,3 +1,3 @@
 import type { SectionId } from '../contracts.js';
 /** Open disclosures before scrolling, then give keyboard users a meaningful landing. */
-export declare function jumpToSection(section: SectionId): void;
+export declare function jumpToSection(section: SectionId, arm?: string): void;

package/dist/admin/surface/test/jumpToSection.js

@@ -1,10 +1,11 @@
-/** Open disclosures before scrolling, then give keyboard users a meaningful landing. */ export function jumpToSection(section) {
+/** Open disclosures before scrolling, then give keyboard users a meaningful landing. */ export function jumpToSection(section, arm) {
     const target = document.getElementById(`section-${section}`);
     if (target instanceof HTMLDetailsElement) target.open = true;
-    target?.scrollIntoView?.({
+    const row = arm ? document.getElementById(`xp-version-${arm}`) : null;
+    (row ?? target)?.scrollIntoView?.({
         block: 'start'
     });
-    document.getElementById(`title-${section}`)?.focus({
+    (row ?? document.getElementById(`title-${section}`))?.focus({
         preventScroll: true
     });
 }

package/dist/admin/surface/test/pageParts.d.ts

@@ -1,2 +1,5 @@
-import type { KindParts } from '../contracts.js';
+import type { KindParts, SectionProps } from '../contracts.js';
+export declare function VersionContent({ test, surface, armIndex }: SectionProps & {
+    armIndex: number;
+}): import("react").JSX.Element | null;
 export declare const pageParts: KindParts;

package/dist/admin/surface/test/pageParts.js

@@ -1,15 +1,92 @@
 'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { TEST_PAGE as C } from '../../copy/testPage.js';
 import { pageTargetIssue, setPageTarget, showsPageTarget } from '../../arms/pageTarget.model.js';
+import { useState } from 'react';
+import { CopyRoute } from '../pagePicker/CopyRoute.js';
+import { PagePicker } from '../pagePicker/PagePicker.js';
+import { testPageCollection } from '../pagePicker/pagePicker.model.js';
+import { PAGE_COPY as P } from '../../copy/pages.js';
 import { FieldErrors, reasonFor, save, TextEdit } from './fields.js';
-function VersionContent({ test, armIndex }) {
+export function VersionContent({ test, surface, armIndex }) {
+    const [open, setOpen] = useState(false);
     const arm = test.doc?.arms[armIndex];
     if (!arm || !test.doc) return null;
     if (!showsPageTarget(test.doc.kind, arm.kind)) return /*#__PURE__*/ _jsx("span", {
         className: "xp-content-chip",
         children: C.holdoutContent
     });
+    const collection = testPageCollection(surface.pageCollections, test.doc, test.preflight?.pagePlacements);
+    const placement = test.preflight?.pagePlacements?.find((entry)=>entry.arm === arm.key);
+    if (collection) {
+        const picker = /*#__PURE__*/ _jsx(PagePicker, {
+            collection: collection,
+            test: test,
+            armKey: arm.key,
+            apiRoute: surface.apiRoute,
+            onChoose: ()=>setOpen(false)
+        });
+        return /*#__PURE__*/ _jsxs("div", {
+            className: "xp-version-content xp-version-content--page",
+            children: [
+                /*#__PURE__*/ _jsx("strong", {
+                    children: P.where
+                }),
+                /*#__PURE__*/ _jsx("p", {
+                    children: placement?.id != null ? /*#__PURE__*/ _jsxs(_Fragment, {
+                        children: [
+                            placement.title,
+                            " · ",
+                            placement.path,
+                            !placement.published ? /*#__PURE__*/ _jsxs(_Fragment, {
+                                children: [
+                                    " · ",
+                                    P.draft
+                                ]
+                            }) : null
+                        ]
+                    }) : arm.pageTarget ? /*#__PURE__*/ _jsxs(_Fragment, {
+                        children: [
+                            arm.pageTarget,
+                            " · ",
+                            P.draft
+                        ]
+                    }) : P.noPage
+                }),
+                placement?.id != null ? /*#__PURE__*/ _jsxs("div", {
+                    children: [
+                        placement.editorUrl ? /*#__PURE__*/ _jsx("a", {
+                            href: placement.editorUrl,
+                            target: "_blank",
+                            rel: "noopener",
+                            children: P.open
+                        }) : null,
+                        ' ',
+                        placement.url ? /*#__PURE__*/ _jsx("a", {
+                            href: placement.url,
+                            target: "_blank",
+                            rel: "noopener",
+                            children: P.preview
+                        }) : null
+                    ]
+                }) : null,
+                /*#__PURE__*/ _jsx("button", {
+                    type: "button",
+                    disabled: !!reasonFor(test, 'arms'),
+                    onClick: ()=>setOpen((value)=>!value),
+                    children: open ? P.close : arm.pageTarget ? P.change : P.choose
+                }),
+                open ? arm.kind === 'variant' ? /*#__PURE__*/ _jsx(CopyRoute, {
+                    collection: collection,
+                    children: picker
+                }) : picker : null,
+                /*#__PURE__*/ _jsx(FieldErrors, {
+                    test: test,
+                    path: `arms.${armIndex}.pageTarget`
+                })
+            ]
+        });
+    }
     const issue = pageTargetIssue(arm.pageTarget, arm.kind);
     return /*#__PURE__*/ _jsxs("div", {
         className: "xp-version-content",

package/dist/admin/surface/test/testPage.css

@@ -15,6 +15,13 @@
 .xp-grid-field .xp-ui-field > label { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
 .xp-version-content { display: flex; flex-wrap: nowrap; gap: var(--xp-space-2); align-items: center; min-width: 0; }
 .xp-version-content .xp-ui-button { white-space: nowrap; }
+.xp-version-content--page { flex-direction: column; align-items: stretch; gap: var(--xp-space-3); }
+.xp-version-content--page > button { align-self: flex-start; }
+.xp-page-picker input[type="search"] { width: 100%; }
+.xp-page-picker ul { list-style: none; padding: 0; margin-block: var(--xp-space-3); }
+.xp-page-picker li > button { display: block; width: 100%; text-align: left; }
+.xp-page-picker li > p { color: var(--xp-text-2); font: var(--xp-text-small); }
+.xp-copy-route ol { list-style: decimal; padding-inline-start: var(--xp-space-6); }
 .xp-content-chip { flex-shrink: 0; display: inline-flex; width: fit-content; border-radius: var(--xp-radius-chip); padding: var(--xp-space-half) var(--xp-space-2); font: var(--xp-text-small); background: var(--xp-surface-2); color: var(--xp-text-2); }
 .xp-content-chip.xp-content-ready { background: var(--xp-success-bg); color: var(--xp-success); }
 .xp-content-chip.xp-content-empty { background: var(--xp-warning-bg); color: var(--xp-warning); }
@@ -66,7 +73,7 @@
 .xp-readiness--bar { display: grid; grid-template-columns: minmax(0, 1fr) auto; align-items: center; gap: var(--xp-space-2) var(--xp-space-4); padding-block: var(--xp-space-3); min-height: 64px; border: 0; border-radius: 0; }
 .xp-readiness__state { display: flex; align-items: center; flex-wrap: wrap; gap: var(--xp-space-2); min-width: 0; }
 .xp-readiness__state p, .xp-readiness--bar > p { margin: 0; }
-.xp-readiness__state > p { font-weight: 500; }
+.xp-readiness__state > p { font-weight: 500; white-space: pre-line; }
 .xp-readiness--bar .xp-save-status, .xp-readiness__separator { color: var(--xp-text-3); font: var(--xp-text-small); }
 .xp-readiness__actions { display: flex; flex-wrap: wrap; align-items: center; gap: var(--xp-space-2); }
 .xp-readiness--bar > .xp-readiness__actions { grid-column: 2; grid-row: 1 / span 3; justify-content: flex-end; }

package/dist/admin/surface/test/testPage.model.d.ts

@@ -1,4 +1,4 @@
-import type { Arm, ArmKey, ExperimentKind, ExposurePolicy } from '../../../types/contracts.js';
+import type { Arm, ExperimentKind, ExposurePolicy } from '../../../types/contracts.js';
 import type { PreflightResult } from '../../../types/endpoints.js';
 export declare function orderedVersions(arms: readonly Arm[]): Array<{
     arm: Arm;
@@ -13,5 +13,4 @@ export declare function durationSuggestion(preflight: PreflightResult | null, sa
     feasible: boolean;
 } | null;
 export declare function exposureOptions(kind: ExperimentKind): readonly ExposurePolicy[];
-/** Keep the edited share exact and distribute the remaining whole percentages proportionally. */
-export declare function balanceWeight(arms: Arm[], key: ArmKey, weight: number): Arm[];
+export { balanceWeight } from '../../../arms/model.js';

package/dist/admin/surface/test/testPage.model.js

@@ -1,4 +1,3 @@
-import { setWeight } from '../../arms/arms.model.js';
 const ORDER = [
     'control',
     'variantA',
@@ -31,23 +30,4 @@ export function exposureOptions(kind) {
         'manual'
     ];
 }
-/** Keep the edited share exact and distribute the remaining whole percentages proportionally. */ export function balanceWeight(arms, key, weight) {
-    if (!arms.some((arm)=>arm.key === key) || !Number.isInteger(weight) || weight < 0 || weight > 100) return arms;
-    const others = arms.filter((arm)=>arm.key !== key);
-    if (!others.length) return arms;
-    const total = others.reduce((sum, arm)=>sum + Math.max(0, Number.isFinite(arm.weight) ? arm.weight : 0), 0);
-    const denominator = total || others.length;
-    const raw = others.map((arm)=>(total ? Math.max(0, Number.isFinite(arm.weight) ? arm.weight : 0) : 1) * (100 - weight) / denominator);
-    const whole = raw.map(Math.floor);
-    const order = raw.map((_, i)=>i).sort((a, b)=>raw[b] - whole[b] - (raw[a] - whole[a]) || a - b);
-    const remainder = 100 - weight - whole.reduce((sum, value)=>sum + value, 0);
-    for(let i = 0; i < remainder; i++)whole[order[i]]++;
-    const shares = new Map(others.map((arm, i)=>[
-            arm.key,
-            whole[i]
-        ]));
-    return setWeight(arms, key, weight).map((arm)=>shares.has(arm.key) ? {
-            ...arm,
-            weight: shares.get(arm.key)
-        } : arm);
-}
+export { balanceWeight } from '../../../arms/model.js';

package/dist/admin/surface/testDocument.model.d.ts

@@ -12,6 +12,7 @@ export interface TestDocument {
     arms: Arm[];
     targeting?: TargetingRule[] | null;
     allocation: number;
+    pageCollection?: string | null;
     flagPoint?: string | null;
     exposurePolicy: ExposurePolicy;
     metrics?: {

package/dist/admin/surface/testDocument.model.js

@@ -9,7 +9,8 @@ const EDITABLE_FIELDS = [
     'flagPoint',
     'metrics',
     'analysis',
-    'exposurePolicy'
+    'exposurePolicy',
+    'pageCollection'
 ];
 /** Drop unknown and locked keys even when the caller is untyped. Groups replace whole groups. */ export function editablePatch(status, partial) {
     return Object.fromEntries(EDITABLE_FIELDS.flatMap((field)=>Object.hasOwn(partial, field) && partial[field] !== undefined && isEditable(status, field) ? [

package/dist/admin/surface/useTestDocument.d.ts

@@ -1,14 +1,23 @@
-import type { DocId } from '../../types/contracts.js';
+import type { Arm, DocId } from '../../types/contracts.js';
 import type { PreflightResult } from '../../types/endpoints.js';
 import type { TestDocument, TestDocumentPatch } from './testDocument.model.js';
 /** Section data only: staging never saves. Call commit on blur or a section action. */
-export declare function useTestDocument(id: DocId, { apiRoute }: {
+export declare function useTestDocument(id: DocId, { apiRoute, refetchPreflightOnFocus }: {
     apiRoute: string;
+    refetchPreflightOnFocus?: boolean;
 }): {
     stage: (partial: TestDocumentPatch) => void;
     commit: () => Promise<void>;
     reload: () => Promise<void>;
     refreshPreflight: () => Promise<void>;
+    choosePage: (arm: Arm["key"], page: {
+        id: DocId;
+        path: string;
+    }) => Promise<void>;
+    chosenPages: Partial<Record<Arm["key"], {
+        id: DocId;
+        path: string;
+    }>>;
     doc: TestDocument | null;
     preflight: PreflightResult | null;
     preflightError: string | null;

package/dist/admin/surface/useTestDocument.js

@@ -7,6 +7,7 @@ import { changedPatch, editablePatch, payloadFieldErrors } from './testDocument.
 // Saves outlive their mounted reader. Reopening the same document must wait for its queue.
 const drainingSaves = new Map();
 const initialView = ()=>({
+        chosenPages: {},
         doc: null,
         preflight: null,
         preflightError: null,
@@ -55,6 +56,7 @@ function stage(session, partial) {
     if (!session.saved || session.view.stale || session.reloading || session.view.loadState !== 'ready' || session.controller.signal.aborted) return;
     const patch = editablePatch(session.saved.status, partial);
     if (!Object.keys(patch).length) return;
+    if (patch.pageCollection !== undefined && patch.pageCollection !== optimistic(session)?.pageCollection) session.view.chosenPages = {};
     session.pending = {
         ...session.pending,
         ...patch
@@ -63,7 +65,7 @@ function stage(session, partial) {
     if (!session.queue.length) session.view.saving = 'idle';
     session.publish();
 }
-/** Section data only: staging never saves. Call commit on blur or a section action. */ export function useTestDocument(id, { apiRoute }) {
+/** Section data only: staging never saves. Call commit on blur or a section action. */ export function useTestDocument(id, { apiRoute, refetchPreflightOnFocus = false }) {
     const base = apiRoute.replace(/\/$/, '');
     const documentId = String(id);
     const key = JSON.stringify([
@@ -90,11 +92,12 @@ function stage(session, partial) {
             controller,
             reloading: false,
             preflightReads: 0,
+            preflightLoading: false,
             publish () {
                 if (controller.signal.aborted) return;
                 session.view.doc = session.view.loadState === 'ready' ? optimistic(session) : null;
                 session.view.hasUnsaved = session.queue.length > 0 || Object.keys(session.pending).length > 0;
-                session.view.preflightPending = session.preflightReads > 0;
+                session.view.preflightPending = session.preflightReads > 0 || session.preflightLoading;
                 setState({
                     key,
                     view: {
@@ -109,7 +112,7 @@ function stage(session, partial) {
         async function refreshPreflight(initial = false) {
             if (controller.signal.aborted) return;
             const revision = ++preflightRevision;
-            session.preflightReads++;
+            session.preflightLoading = true;
             session.publish();
             // createApi has no signal option; this read must abort without cancelling submitted PATCHes.
             let data;
@@ -134,12 +137,9 @@ function stage(session, partial) {
             } catch  {
                 message = API_MESSAGES.network;
             }
-            session.preflightReads--;
             if (controller.signal.aborted) return;
-            if (revision !== preflightRevision) {
-                session.publish();
-                return;
-            }
+            if (revision !== preflightRevision) return;
+            session.preflightLoading = false;
             if (data) {
                 session.view.preflight = data;
                 session.view.preflightError = null;
@@ -215,8 +215,9 @@ function stage(session, partial) {
                                     ...edit
                                 }), {});
                             session.queue = [];
+                            // Server text is never shown; the stale-edit sentence is the admin's own.
                             session.view.errors = {
-                                _section: staleError.message || TEST_PAGE.staleEdit
+                                _section: TEST_PAGE.staleEdit
                             };
                         } else if (!response.ok) session.view.errors = {
                             ...session.view.errors,
@@ -256,12 +257,9 @@ function stage(session, partial) {
                     session.publish();
                 }
                 if (saved) {
-                    try {
-                        await refreshPreflight();
-                    } finally{
-                        session.preflightReads--;
-                        session.publish();
-                    }
+                    // Recovery is complete; readiness now belongs to the latest preflight read.
+                    session.preflightReads--;
+                    await refreshPreflight();
                 }
             };
             // Recover both the preceding tail and this step: unexpected throws must not strand later saves.
@@ -366,11 +364,52 @@ function stage(session, partial) {
     }, [
         key
     ]);
+    useEffect(()=>{
+        if (!refetchPreflightOnFocus) return;
+        let lastReturn = -Infinity;
+        const focus = ()=>{
+            if (document.visibilityState !== 'visible' || Date.now() - lastReturn < 100) return;
+            lastReturn = Date.now();
+            void refreshPreflight();
+        };
+        const visible = ()=>{
+            if (document.visibilityState === 'visible') focus();
+        };
+        window.addEventListener('focus', focus);
+        document.addEventListener('visibilitychange', visible);
+        return ()=>{
+            window.removeEventListener('focus', focus);
+            document.removeEventListener('visibilitychange', visible);
+        };
+    }, [
+        refetchPreflightOnFocus,
+        refreshPreflight
+    ]);
+    const choosePage = useCallback((arm, page)=>{
+        const session = current.current;
+        const doc = session?.key === key ? optimistic(session) : null;
+        if (!session || !doc) return Promise.resolve();
+        session.view.chosenPages = {
+            ...session.view.chosenPages,
+            [arm]: page
+        };
+        stage(session, {
+            arms: doc.arms.map((item)=>item.key === arm ? {
+                    ...item,
+                    pageTarget: page.path
+                } : item)
+        });
+        return commit();
+    }, [
+        key,
+        commit
+    ]);
     return {
         ...state.key === key ? state.view : initialView(),
         stage: stagePartial,
         commit,
         reload,
-        refreshPreflight
+        refreshPreflight,
+        choosePage
     };
 }

package/dist/admin/useApi.d.ts

@@ -1,4 +1,12 @@
-export declare function useApi(): {
+export declare function useApi(apiRoute: string): {
+    wrapBlock: (body: import("../types/endpoints.js").WrapBlockBody) => Promise<import("./api.js").ApiResult<Record<string, unknown>>>;
+    pages: (query: {
+        collection: string;
+        q?: string;
+        path?: string;
+        page?: number;
+    }, signal?: AbortSignal) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").PagesResult>>;
+    placementStatus: (body: import("../types/endpoints.js").PlacementStatusBody) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").PlacementStatusResult>>;
     start: (id: import("../types/contracts.js").DocId) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").TransitionSuccess>>;
     allocate: (id: import("../types/contracts.js").DocId, body: import("../types/endpoints.js").AllocateBody, options?: {
         notFound?: string;
@@ -9,7 +17,7 @@ export declare function useApi(): {
         notFound?: string;
         codes?: Readonly<Record<string, string>>;
         fallback?: string;
-    }) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").TransitionSuccess>>;
+    }) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").AddMetricResult>>;
     stop: (id: import("../types/contracts.js").DocId) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").TransitionSuccess>>;
     decide: (id: import("../types/contracts.js").DocId, body: import("../types/endpoints.js").DecideBody) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").TransitionSuccess>>;
     releaseHoldout: (id: import("../types/contracts.js").DocId) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").TransitionSuccess>>;
@@ -18,6 +26,7 @@ export declare function useApi(): {
     dismissContentEntry: (id: import("../types/contracts.js").DocId, body: import("../types/endpoints.js").DismissContentEntryBody) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").DismissContentEntryResult>>;
     restoreContentEntry: (id: import("../types/contracts.js").DocId, body: import("../types/endpoints.js").RestoreContentEntryBody) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").RestoreContentEntryResult>>;
     archive: (id: import("../types/contracts.js").DocId, body: import("../types/endpoints.js").ArchiveBody) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").TransitionSuccess>>;
+    clickKeys: (id: import("../types/contracts.js").DocId) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").ClickKeysResult>>;
     preflight: (id: import("../types/contracts.js").DocId) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").PreflightResult>>;
     previewToken: (id: import("../types/contracts.js").DocId, arm: string) => Promise<import("./api.js").ApiResult<import("../types/endpoints.js").PreviewTokenResult>>;
     results: (id: import("../types/contracts.js").DocId, options?: {