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

package/README.md

@@ -271,7 +271,10 @@ Other server integrations:
 - `recordContentChange({ doc, previousDoc, req, collection })` can be called
   from a host collection's `afterChange` for content tagged with the arm-select
   field; for a collection with drafts, also add `captureContentBaseline` to its
-  `beforeChange` hooks so the previously published content can be compared. Supply that hook's transaction request. Puck collections get the hook
+  `beforeChange` hooks so the previously published content can be compared.
+  Collections without drafts can also add `captureContentBaseline` for an exact
+  raw comparison; without it, the helper normalises relationships to ids. No host
+  change is required for collections without drafts. Supply that hook's transaction request. Puck collections get the hook
   automatically when enabled. Markers compare published content; drafts and
   autosaves do not add markers (collections without drafts record on save).
   Neither the helper nor the installed hooks ever throw into your save: a
@@ -281,7 +284,10 @@ Other server integrations:
   canonical; archived losing paths point canonically to the winner. It reads
   the signed request context via `headers()`, so it decides from the URL the
   visitor requested, not the rewritten route, and the Original's URL is never
-  noindex. Call it only from a dynamic `generateMetadata`, never inside
+  noindex. While a test is live the Original's URL also gets a canonical to
+  itself, even when it is served with a variant's route: merge this result after
+  your own metadata so its `alternates.canonical` wins over one derived from the
+  rendered route. Call it only from a dynamic `generateMetadata`, never inside
   `'use cache'`; `path` is the fallback when the proxy did not run.
   `experimentSitemapFilter(path, manifest)` is a synchronous build-time filter:
   pass a privately server-loaded manifest and keep paths for which it returns
@@ -488,13 +494,23 @@ No migration is needed.
 ### `admin` options
 
 Host links and kind descriptions are optional. For a host using payload-puck's
-editor route and a `puck-templates` collection, pass:
+editor route, public pages and a `puck-templates` collection:
+
+| Option | Signature and behavior |
+| --- | --- |
+| `admin.previewUrl` | `(placement: PreviewPlacement) => string \| null \| undefined \| Promise<string \| null \| undefined>`. Receives `collection`, `id`, `title`, `published`, and optional `slug`. May be async; return `null` to hide preview for that placement. Each call has a 2 s limit, with at most 8 lookups awaited concurrently. |
+
+For example, pass:
 
 ```ts
 admin: {
   editorUrl: ({ collection, id, draft }) =>
     `/admin/puck-editor/${encodeURIComponent(collection)}/${encodeURIComponent(String(id))}`,
-  previewUrl: ({ id }) => `/preview/template/${encodeURIComponent(String(id))}`,
+  previewUrl: async ({ collection, slug }) => {
+    if (collection !== 'pages' || slug === undefined) return null
+    // Match the site's public page routing, including its homepage convention.
+    return slug === 'home' ? '/' : `/${slug}`
+  },
   descriptions: {
     block: 'Try different content on a landing page.',
     document: 'Try different versions of a donation ask.',
@@ -503,11 +519,21 @@ admin: {
 }
 ```
 
-Use your host's preview route for `previewUrl`. Preflight resolves both URL
-callbacks on the server for block placements; it passes only URL strings to the
-client. Missing or failed callbacks leave the URL unset, and the client uses the
-admin collection route when no editor URL is supplied. Kind descriptions are
-available to the server views through `config.custom.xp`.
+`PreviewPlacement` is exported from the package root and `/rsc`. Its `slug` is
+the published main row's string slug, including for a placement found in a newer
+draft with a different slug. It is absent for unpublished documents. `published`
+describes the placement's version; the callback receives no other document fields.
+An async callback can also look up the public path by `collection` and `id` using
+the host's own data access. The old `({ collection, id }) => string` form still works.
+
+Preflight resolves the URL callbacks on the server for block placements and sends
+only URL strings to the client. A null/undefined result, a non-string, an exception,
+a rejected promise or a timeout leaves preview hidden for that placement. When an
+editor URL exists, the admin offers "Edit on page"; when neither URL exists, it
+omits the row. Timed-out host work cannot be cancelled and keeps its concurrency
+slot until it settles; if all 8 slots remain occupied, further preview lookups
+are skipped for that preflight. Kind descriptions are available to the server views through
+`config.custom.xp`.
 
 A flag point can also declare `description?: string` to explain the setting below its label.
 
@@ -567,7 +593,8 @@ 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.
+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.
 
 ### Client assignments and exposure
 
@@ -620,19 +647,41 @@ configured to allow client writes; record revenue on the server.
 
 ### Puck render and editor configs
 
-Register `ExperimentSlot` from `@delmaredigital/payload-experiments/puck` in
-your render config and `ExperimentSlotEditor` from
-`@delmaredigital/payload-experiments/puck/editor` in your editor config, using
-the same `ExperimentSlot` component name:
+Register the factories from `/puck` and `/puck/editor`, using the same
+`ExperimentSlot` component name in both configs. Pass the host's Payload routes:
 
 ```ts
+import { createExperimentSlot } from '@delmaredigital/payload-experiments/puck'
+import { createExperimentSlotEditor, experimentOutlinePlugin } from '@delmaredigital/payload-experiments/puck/editor'
+
+const routes = { admin: '/manage', api: '/content-api' } // Same as Payload config.routes
+const accent = '#1f3a68' // Same as the plugin's theme.accent
+
 // Render config
-components: { ExperimentSlot }
+components: { ExperimentSlot: createExperimentSlot({ routes }) }
 
 // Editor config
-components: { ExperimentSlot: ExperimentSlotEditor }
+components: { ExperimentSlot: createExperimentSlotEditor({ routes, accent }) }
+```
+
+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.
+
+```ts
+plugins: [experimentOutlinePlugin()]
 ```
 
+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
+`createExperimentSlotField({ routes })` also accepts the host's routes.
+
+Pass the same accent as the plugin's `theme.accent`: the editor cannot read
+Payload config. Both use the same validator and report the same error for an
+invalid colour. Without an accent the editor uses the neutral palette.
+
 Load the editor stylesheet inside the Puck iframe. With Tailwind v4, add the
 package import **after** Tailwind in the CSS that builds your editor iframe
 stylesheet (the stylesheet listed in payload-puck's `editorStylesheets`):
@@ -648,6 +697,15 @@ The editor CSS includes its own light and dark palette, selected by
 `data-theme="dark"` or the `dark` class on the iframe's `<html>`. The client component's CSS import alone
 does not reach an iframe configured with `syncHostStyles: false`.
 
+If Puck runs outside Payload's admin, the page needs Payload's admin styles (the plugin's tokens map onto them) and the plugin's admin styles, plus `data-theme="light"` or `data-theme="dark"` on `<html>`. Inside the admin all of this is already in place:
+
+```css
+@import "@payloadcms/next/css";
+@import "@payloadcms/ui/styles.css";
+@import "@delmaredigital/payload-experiments/admin/theme.css";
+@import "@delmaredigital/payload-experiments/admin/ui.css";
+```
+
 Resolve the Puck data on the server with `resolveExperimentData` before
 rendering it. The render component shows only the selected group's slot. The
 editor lets you select a block experiment, edit each group's content, copy the

package/dist/admin/PreviewLinks.js

@@ -5,8 +5,9 @@ import { Button } from '../ui/Button.js';
 import { armLabel } from './labels.js';
 import { useApi } from './useApi.js';
 import { REVIEW_COPY as C } from './copy/review.js';
-import { API_MESSAGES } from './copy/common.js';
-import { previewPages } from './previewLinks.model.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();
     const inFlight = useRef(false);
@@ -17,20 +18,37 @@ export function PreviewLinks({ experimentId, placements, arms, flagPoint }) {
         inFlight.current = true;
         setBusy(true);
         setError(null);
+        let win = null;
         try {
+            win = window.open('', '_blank');
+            if (!win) {
+                setError(C.previewBlocked);
+                return;
+            }
+            // Clearing opener immediately gives the same opener protection as noopener: the
+            // previewed page cannot reach window.opener. The admin URL may be sent as
+            // referrer to the host's own site (resolved against location.origin); accepted.
+            try {
+                win.opener = null;
+            } catch  {}
             const result = await api.previewToken(experimentId, arm);
+            // The person closed the blank tab while the token loaded: nothing to show or report.
+            if (win.closed) return;
             if (!result.ok) {
-                setError(result.message);
+                win.close();
+                setError(result.status === 0 ? API_MESSAGES.network : refusalMessage(result.code, result.status));
                 return;
             }
-            if (!result.data?.token) {
+            if (typeof result.data?.token !== 'string' || !result.data.token) {
+                win.close();
                 setError(API_MESSAGES.unreadable);
                 return;
             }
             const target = new URL(url, window.location.origin);
             target.searchParams.set('xp_preview', result.data.token);
-            window.open(target.href, '_blank', 'noopener,noreferrer');
+            win.location.replace(target.href);
         } catch  {
+            win?.close();
             setError(API_MESSAGES.failed);
         } finally{
             inFlight.current = false;
@@ -40,7 +58,7 @@ export function PreviewLinks({ experimentId, placements, arms, flagPoint }) {
     return /*#__PURE__*/ _jsxs("div", {
         className: "xp-preview-links",
         children: [
-            previewPages(placements, flagPoint).map((placement)=>/*#__PURE__*/ _jsxs("div", {
+            actionablePreviewPages(placements, flagPoint).map((placement)=>/*#__PURE__*/ _jsxs("div", {
                     className: "xp-preview-row",
                     children: [
                         /*#__PURE__*/ _jsxs("p", {
@@ -49,26 +67,29 @@ export function PreviewLinks({ experimentId, placements, arms, flagPoint }) {
                                 placement.slotCount > 1 ? ` ${C.placedTimes(placement.slotCount)}` : null
                             ]
                         }),
-                        /*#__PURE__*/ _jsx("div", {
+                        /*#__PURE__*/ _jsxs("div", {
                             className: "xp-ui-button-group",
-                            children: placement.url ? arms.filter((arm)=>arm.kind !== 'holdout' && arm.key !== 'holdout').map((arm)=>/*#__PURE__*/ _jsxs(Button, {
-                                    variant: "secondary",
+                            children: [
+                                placement.url ? arms.filter((arm)=>arm.kind !== 'holdout' && arm.key !== 'holdout').map((arm)=>/*#__PURE__*/ _jsxs(Button, {
+                                        variant: "secondary",
+                                        size: "sm",
+                                        disabled: busy,
+                                        onClick: ()=>{
+                                            void preview(placement.url, arm.key);
+                                        },
+                                        children: [
+                                            C.preview,
+                                            " ",
+                                            arm.label?.trim() || armLabel(arm.key)
+                                        ]
+                                    }, arm.key)) : null,
+                                placement.editorUrl ? /*#__PURE__*/ _jsx(Button, {
+                                    variant: "link",
                                     size: "sm",
-                                    disabled: busy,
-                                    onClick: ()=>{
-                                        void preview(placement.url, arm.key);
-                                    },
-                                    children: [
-                                        C.preview,
-                                        " ",
-                                        arm.label?.trim() || armLabel(arm.key)
-                                    ]
-                                }, arm.key)) : /*#__PURE__*/ _jsx(Button, {
-                                variant: "secondary",
-                                size: "sm",
-                                disabled: true,
-                                children: C.noPreview
-                            })
+                                    href: placement.editorUrl,
+                                    children: TEST_PAGE.editOnPage
+                                }) : null
+                            ]
                         })
                     ]
                 }, placement.key)),

package/dist/admin/TestsNavLink.d.ts

@@ -1,3 +1,5 @@
 import './theme.css';
-declare function TestsNav(): import("react").JSX.Element | null;
+declare function TestsNav({ isOpen }: {
+    isOpen?: boolean;
+}): import("react").JSX.Element | null;
 export { TestsNav as TestsNavLink };

package/dist/admin/TestsNavLink.js

@@ -5,7 +5,7 @@ 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() {
+function TestsNav({ isOpen = true }) {
     const { config } = useConfig();
     const { permissions } = useAuth();
     const pathname = usePathname();
@@ -38,9 +38,9 @@ function TestsNav() {
             active: goalsActive
         }
     ];
-    // getPreference is async and can fetch; let NavGroup default to open.
     return /*#__PURE__*/ _jsx(NavGroup, {
         label: SURFACE_COPY.title,
+        isOpen: isOpen,
         children: entries.map((entry)=>{
             const props = {
                 className: 'nav__link',

package/dist/admin/armSelect/ArmSelectField.js

@@ -1,9 +1,11 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { fetchAllDocs } from '../../lib/fetchAllDocs.js';
 import { Banner, Button, SelectInput, useConfig, useField } from '@payloadcms/ui';
 import { useEffect, useState } from 'react';
 import { bindArmSelect, experimentId } from './armSelect.model.js';
 import { ARM_SELECT_COPY } from '../copy/armSelect.js';
+/** Only authored copy reaches the field; transport or parse errors read as unavailable. */ const knownCopy = (reason)=>reason instanceof Error && Object.values(ARM_SELECT_COPY).includes(reason.message) ? reason.message : ARM_SELECT_COPY.unavailable;
 export function ArmSelectField({ path, field, readOnly }) {
     const { config } = useConfig();
     const api = config.routes.api;
@@ -26,27 +28,17 @@ export function ArmSelectField({ path, field, readOnly }) {
         if (!point) return;
         const controller = new AbortController();
         async function list(statuses) {
-            const docs = [];
-            let page = 1;
-            while(!controller.signal.aborted){
-                const query = new URLSearchParams({
-                    depth: '0',
-                    limit: '100',
-                    page: String(page),
-                    'where[flagPoint][equals]': point,
-                    'where[status][in]': statuses
-                });
-                const response = await fetch(`${api}/xp-experiments?${query}`, {
-                    credentials: 'include',
-                    signal: controller.signal
-                });
-                if (!response.ok) throw new Error(response.status === 403 ? ARM_SELECT_COPY.forbidden : ARM_SELECT_COPY.unavailable);
-                const data = await response.json();
-                docs.push(...data.docs);
-                if (!data.hasNextPage) break;
-                page++;
-            }
-            return docs;
+            const query = new URLSearchParams({
+                depth: '0',
+                'where[flagPoint][equals]': point,
+                'where[status][in]': statuses
+            });
+            const response = await fetchAllDocs(`${api}/xp-experiments?${query}`, {
+                credentials: 'include',
+                signal: controller.signal
+            });
+            if (!response.ok) throw new Error(response.status === 403 ? ARM_SELECT_COPY.forbidden : ARM_SELECT_COPY.unavailable);
+            return response.docs;
         }
         void Promise.all([
             list('running,decided'),
@@ -63,7 +55,7 @@ export function ArmSelectField({ path, field, readOnly }) {
         }).catch((reason)=>{
             if (!controller.signal.aborted) setError({
                 key,
-                message: reason instanceof Error ? reason.message : ARM_SELECT_COPY.unavailable
+                message: knownCopy(reason)
             });
         });
         return ()=>controller.abort();

package/dist/admin/arms/arms.model.d.ts

@@ -1,21 +1 @@
-import type { ArmIssue } from '../../collections/experiments/armInvariants.js';
-import type { Arm, ArmKey, ExperimentKind } from '../../types/contracts.js';
-export declare function defaultArms(kind?: ExperimentKind): Arm[];
-/** Keep content slots in step with the experiment kind, including an unset kind. */
-export declare function withSlotsFor(arms: Arm[], kind?: ExperimentKind): Arm[];
-export declare function totalWeight(arms: Arm[]): number;
-export declare function addVariant(arms: Arm[], kind?: ExperimentKind): Arm[];
-export declare function removeArm(arms: Arm[], key: ArmKey): Arm[];
-export declare function addHoldoutArm(arms: Arm[]): Arm[];
-export declare function removeHoldout(arms: Arm[]): Arm[];
-export declare function splitEvenly(arms: Arm[]): Arm[];
-export declare function setWeight(arms: Arm[], key: ArmKey, weight: number): Arm[];
-export declare function issuesByRow(arms: Arm[], kind?: ExperimentKind): {
-    rows: ArmIssue[][];
-    form: ArmIssue[];
-};
-export declare const ARM_FIELDS: readonly ["key", "label", "weight", "kind", "slot", "params", "pageTarget"];
-/** Payload arrays store each row's values at separate field paths. */
-export declare function readArms(fields: Record<string, {
-    value?: unknown;
-}>, path?: string): Arm[];
+export * from '../../arms/model.js';

package/dist/admin/arms/arms.model.js

@@ -1,153 +1 @@
-import { addHoldout, checkArms } from '../../collections/experiments/armInvariants.js';
-import { GROUP_LABELS } from '../copy/arms.js';
-const VARIANTS = [
-    'variantA',
-    'variantB',
-    'variantC'
-];
-export function defaultArms(kind) {
-    return withSlotsFor([
-        {
-            key: 'control',
-            kind: 'control',
-            label: GROUP_LABELS.control,
-            weight: 50
-        },
-        {
-            key: 'variantA',
-            kind: 'variant',
-            label: GROUP_LABELS.variantA,
-            weight: 50
-        }
-    ], kind);
-}
-/** Keep content slots in step with the experiment kind, including an unset kind. */ export function withSlotsFor(arms, kind) {
-    const next = arms.map((arm)=>{
-        if (kind === 'block' && arm.kind !== 'holdout') return arm.slot === arm.key ? arm : {
-            ...arm,
-            slot: arm.key
-        };
-        // Postgres returns null for unset columns; null counts as "no slot" so a loaded doc is not rewritten.
-        if (arm.slot == null) return arm;
-        const { slot: _slot, ...rest } = arm;
-        return rest;
-    });
-    return next.every((arm, index)=>arm === arms[index]) ? arms : next;
-}
-const finiteWeight = (weight)=>Number.isFinite(weight) ? weight : 0;
-export function totalWeight(arms) {
-    return arms.reduce((sum, arm)=>sum + finiteWeight(arm.weight), 0);
-}
-export function addVariant(arms, kind) {
-    if (!arms.some((arm)=>arm.kind === 'control')) return arms;
-    const key = VARIANTS.find((candidate)=>!arms.some((arm)=>arm.key === candidate));
-    if (!key || arms.filter((arm)=>arm.kind === 'variant').length >= 3) return arms;
-    const block = kind === 'block' || kind === undefined && arms.some((arm)=>arm.slot !== undefined);
-    const variant = {
-        key,
-        kind: 'variant',
-        label: GROUP_LABELS[key],
-        weight: 0,
-        ...block ? {
-            slot: key
-        } : {}
-    };
-    const index = arms.findIndex((arm)=>arm.kind === 'holdout');
-    const result = [
-        ...arms
-    ];
-    result.splice(index < 0 ? arms.length : index, 0, variant);
-    return result;
-}
-export function removeArm(arms, key) {
-    if (arms.some((arm)=>arm.key === key && arm.kind === 'control')) return arms;
-    if (key === 'holdout') return removeHoldout(arms);
-    return arms.filter((arm)=>arm.key !== key);
-}
-export function addHoldoutArm(arms) {
-    if (!arms.some((arm)=>arm.kind === 'control') || arms.some((arm)=>arm.kind === 'holdout' || arm.key === 'holdout')) return arms;
-    return addHoldout(arms.map((arm)=>Number.isFinite(arm.weight) ? arm : {
-            ...arm,
-            weight: 0
-        }));
-}
-// Largest remainder, with equal fractional remainders awarded to Original first.
-function distribute(arms, total, proportional) {
-    if (!arms.length) return arms;
-    const weightTotal = totalWeight(arms);
-    const useWeights = proportional && weightTotal > 0;
-    const denominator = useWeights ? weightTotal : arms.length;
-    const numerators = arms.map((arm)=>(useWeights ? finiteWeight(arm.weight) : 1) * total);
-    const weights = numerators.map((numerator)=>Math.floor(numerator / denominator));
-    const order = arms.map((_, i)=>i).sort((a, b)=>numerators[b] % denominator - numerators[a] % denominator || Number(arms[b].kind === 'control') - Number(arms[a].kind === 'control') || a - b);
-    const remainder = total - weights.reduce((sum, weight)=>sum + weight, 0);
-    for(let i = 0; i < remainder; i++)weights[order[i % order.length]]++;
-    return arms.map((arm, i)=>({
-            ...arm,
-            weight: weights[i]
-        }));
-}
-export function removeHoldout(arms) {
-    if (!arms.some((arm)=>arm.kind === 'holdout')) return arms;
-    return distribute(arms.filter((arm)=>arm.kind !== 'holdout'), totalWeight(arms), true);
-}
-export function splitEvenly(arms) {
-    const holdout = arms.find((arm)=>arm.kind === 'holdout');
-    const weight = finiteWeight(holdout?.weight ?? 0);
-    return [
-        ...distribute(arms.filter((arm)=>arm.kind !== 'holdout'), 100 - weight, false),
-        ...holdout ? [
-            {
-                ...holdout,
-                weight
-            }
-        ] : []
-    ];
-}
-export function setWeight(arms, key, weight) {
-    return arms.map((arm)=>arm.key === key ? {
-            ...arm,
-            weight
-        } : arm);
-}
-export function issuesByRow(arms, kind) {
-    const rows = arms.map(()=>[]);
-    const form = [];
-    for (const issue of checkArms(arms, kind)){
-        const index = issue.armIndex ?? arms.findIndex((arm)=>arm.key === issue.armKey);
-        if (index >= 0 && index < arms.length) rows[index].push(issue);
-        else form.push(issue);
-    }
-    return {
-        rows,
-        form
-    };
-}
-export const ARM_FIELDS = [
-    'key',
-    'label',
-    'weight',
-    'kind',
-    'slot',
-    'params',
-    'pageTarget'
-];
-/** Payload arrays store each row's values at separate field paths. */ export function readArms(fields, path = 'arms') {
-    const indices = new Set();
-    for (const name of Object.keys(fields)){
-        if (!name.startsWith(`${path}.`)) continue;
-        const [index, field] = name.slice(path.length + 1).split('.');
-        if (/^\d+$/.test(index) && field === 'key') indices.add(Number(index));
-    }
-    return [
-        ...indices
-    ].sort((a, b)=>a - b).map((index)=>Object.fromEntries(ARM_FIELDS.flatMap((field)=>{
-            const value = fields[`${path}.${index}.${field}`]?.value;
-            return value === undefined ? [] : [
-                [
-                    field,
-                    value
-                ]
-            ];
-        })));
-}
+export * from '../../arms/model.js';

package/dist/admin/copy/arms.d.ts

@@ -1,6 +1,5 @@
-import type { ArmIssueCode } from '../../types/endpoints.js';
 export { ARM_LABELS as GROUP_LABELS } from '../../labels/arms.js';
-export declare const ISSUE_COPY: Record<ArmIssueCode, string>;
+export { ISSUE_COPY, issueMessage } from '../../arms/copy.js';
 export declare const ARMS_COPY: {
     readonly holdout: "The holdout sees the Original and is measured but not compared during the test. After you decide, it keeps seeing the Original so the winner can be compared with it.";
     readonly pageRequired: "Enter a page path for this group.";
@@ -12,7 +11,3 @@ export declare const ARMS_COPY: {
     readonly paramOption: "Choose an available option for {label}.";
     readonly paramCheckbox: "Choose yes or no for {label}.";
 };
-export declare function issueMessage(issue: {
-    code: string;
-    message: string;
-}, total: number): string;

package/dist/admin/copy/arms.js

@@ -1,16 +1,5 @@
 export { ARM_LABELS as GROUP_LABELS } from '../../labels/arms.js';
-export const ISSUE_COPY = {
-    'weights-total': 'Weights must add up to 100%. They add up to {total}% now.',
-    'control-count': 'Include exactly one Original.',
-    'control-first': 'Put the Original first.',
-    'holdout-last': 'Put the holdout last.',
-    'holdout-count': 'Include only one holdout.',
-    'variant-count': 'Include up to three variants.',
-    'duplicate-key': 'Each group must have a different standard name.',
-    'duplicate-slot': 'Each group must have a different content slot.',
-    'slot-required': 'Choose the matching content slot for this group.',
-    'invalid-key': 'Use the standard group names: Original, Variant A–C, Holdout.'
-};
+export { ISSUE_COPY, issueMessage } from '../../arms/copy.js';
 export const ARMS_COPY = {
     holdout: 'The holdout sees the Original and is measured but not compared during the test. After you decide, it keeps seeing the Original so the winner can be compared with it.',
     pageRequired: 'Enter a page path for this group.',
@@ -22,7 +11,3 @@ export const ARMS_COPY = {
     paramOption: 'Choose an available option for {label}.',
     paramCheckbox: 'Choose yes or no for {label}.'
 };
-export function issueMessage(issue, total) {
-    const copy = Object.hasOwn(ISSUE_COPY, issue.code) ? ISSUE_COPY[issue.code] : issue.message;
-    return copy.replace('{total}', String(total));
-}

package/dist/admin/copy/readiness.d.ts

@@ -34,6 +34,7 @@ export declare const READINESS_COPY: {
     readonly full: "This test's group is full. Lower how many people take part, or create the test again without the group.";
     readonly differentPeople: "This test's group counts different people. Create the test again without the group.";
     readonly uncheckedPages: "Version pages aren't checked; make sure each one is published.";
+    readonly chooseDifferentPage: "Choose a different page";
     readonly noTargets: "Add a page address for each version.";
     readonly pageVisitors: "Whole-page tests count visitors. Create the test again counting visitors.";
     readonly blockPathRule: "Remove the page-path rule in Who takes part; page block tests run on their page.";
@@ -45,6 +46,7 @@ export declare const READINESS_COPY: {
     readonly attributeFallback: "this attribute";
 };
 export declare const unsupportedContentCopy: (page: string) => string;
+export declare const pageInUseCopy: (path: string) => string;
 export declare const unpublishedPageCopy: (path: string) => string;
 /** Old responses may include raw host errors; unknown strings use authored copy. */
 export declare const placementFailureCopy: (reason: unknown) => "Couldn't check where this test is used. Try again." | "You don't have permission to check where this test is used." | "A page used by this test no longer exists. Choose another page.";
@@ -59,6 +61,7 @@ export declare const attributeNext: (attribute: string) => string;
 export declare const stoppedCopy: (date: string | null) => string;
 export declare const decidedCopy: (date: string | null, winner: string) => string;
 export declare const runningCopy: (date: string | null, people: number | null, days: number | null) => string;
-export declare const pageGuardCopy: (name: string, status: "running" | "decided" | "archived") => string;
+/** After archive the guard protects the winner and the Original; only the winner page is "the winner". */
+export declare const pageGuardCopy: (name: string, status: "running" | "decided" | "archived", role?: "winner" | "original") => string;
 export declare const versionPageUnavailableCopy: (path: string, status?: string) => string;
 export declare const versionPageUncheckedCopy: (path: string, status?: string) => string;

package/dist/admin/copy/readiness.js

@@ -34,6 +34,7 @@ export const READINESS_COPY = {
     full: "This test's group is full. Lower how many people take part, or create the test again without the group.",
     differentPeople: "This test's group counts different people. Create the test again without the group.",
     uncheckedPages: "Version pages aren't checked; make sure each one is published.",
+    chooseDifferentPage: 'Choose a different page',
     noTargets: 'Add a page address for each version.',
     pageVisitors: 'Whole-page tests count visitors. Create the test again counting visitors.',
     blockPathRule: 'Remove the page-path rule in Who takes part; page block tests run on their page.',
@@ -46,6 +47,7 @@ export const READINESS_COPY = {
     attributeFallback: 'this attribute'
 };
 export const unsupportedContentCopy = (page)=>`${page} has more than one language, so Make it the content isn't available for it; you'll copy the winning version by hand.`;
+export const pageInUseCopy = (path)=>`Another running or decided test already uses ${path}. Choose a different page, or finish that test first.`;
 export const unpublishedPageCopy = (path)=>`${path} isn't a published page. Publish it, or pick another page.`;
 /** Old responses may include raw host errors; unknown strings use authored copy. */ export const placementFailureCopy = (reason)=>PLACEMENT_FAILURE_COPY[typeof reason === 'string' && Object.hasOwn(PLACEMENT_FAILURE_COPY, reason) ? reason : 'placements-failed'];
 const withoutPeriod = (value)=>value.trim().replace(/[.!?]+$/, '');
@@ -64,6 +66,6 @@ export const runningCopy = (date, people, days)=>[
         people === null ? null : `${people.toLocaleString('en-US')} people so far`,
         days === null ? null : `about ${days} days to go`
     ].filter(Boolean).join(' · ');
-export const pageGuardCopy = (name, status)=>status === 'archived' ? `This page is shown at other addresses because the finished test "${name}" made it the winner. To free it, open the test and choose "Release pages".` : status === 'decided' ? `This page is part of the decided test "${name}". Choose "Make it the content" or "Discard winner" on the test before you delete, rename or unpublish it.` : `This page is part of the running test "${name}". Stop the test before you delete, rename or unpublish it.`;
+/** After archive the guard protects the winner and the Original; only the winner page is "the winner". */ export const pageGuardCopy = (name, status, role = 'winner')=>status === 'archived' ? role === 'original' ? `This page's address now shows the winner of the finished test "${name}". To free it, open the test and choose "Release pages".` : `This page is shown at other addresses because the finished test "${name}" made it the winner. To free it, open the test and choose "Release pages".` : status === 'decided' ? `This page is part of the decided test "${name}". Choose "Make it the content" or "Discard winner" on the test before you delete, rename or unpublish it.` : `This page is part of the running test "${name}". Stop the test before you delete, rename or unpublish it.`;
 export const versionPageUnavailableCopy = (path, status = 'running')=>`${path} isn't published, so visitors assigned to it see an error. Republish it, or ${status === 'decided' ? 'discard the winner' : 'stop the test'}.`;
 export const versionPageUncheckedCopy = (path, status = 'running')=>`Couldn't check whether ${path} is published. Check that it is still published, or ${status === 'decided' ? 'discard the winner' : 'stop the test'}.`;

package/dist/admin/copy/results.d.ts

@@ -57,6 +57,8 @@ export declare const RESULTS_COPY: {
     readonly infeasible: "A clear answer would take more than 90 days at this traffic.";
     readonly noCap: "Not capped: fewer than 20 people had this outcome in the 90 days before Start, so every value counts in full.";
     readonly quality: "Data quality";
+    readonly missingWinner: "The stored winner is missing from this round’s results.";
+    readonly missingWinnerNext: "Recompute; if it persists, contact a developer before trusting these results.";
     readonly srm: "Traffic isn't splitting as set. Check for caching or a page placed twice.";
     readonly multiGroup: "People who saw more than one group were excluded.";
     readonly multiGroupNext: "Check for caching or a page placed twice before trusting the results.";