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

package/dist/puck/editor/experimentOutlinePlugin.js

@@ -0,0 +1,89 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createUsePuck, walkTree } from '@puckeditor/core';
+import { useEffect, useMemo, useState } from 'react';
+import { EXPERIMENT_SLOT_TYPE } from '../../types/puck.js';
+import { useArms } from './armsCache.js';
+const usePuckSelector = createUsePuck();
+const slots = [
+    'control',
+    'variantA',
+    'variantB',
+    'variantC'
+];
+// Puck 0.24.0 dist/chunk-DQXMVPVM.mjs:8040 (item attribute), 8126–8135
+// (direct zone containers). Zones have no stable attribute; avoid the CSS-module hash.
+const zone = 'div[class*="Layer-zones"]';
+const chain = (count)=>Array(count).fill(zone).join(' ~ ');
+function SlotRules({ item: [id, testId, emptySlots] }) {
+    const known = useArms(testId ?? undefined);
+    const [mounted, setMounted] = useState(false);
+    useEffect(()=>{
+        setMounted(true);
+    }, []);
+    // CSS.escape is a browser API: SSR and the first hydration render emit no rules.
+    if (!mounted) return null;
+    const rules = slots.flatMap((slot, index)=>{
+        // Original always remains available. Unknown bound tests must reveal every zone.
+        if (slot === 'control' || testId !== null && (!known || known.arms.includes(slot))) return [];
+        if (!emptySlots[index]) return [];
+        // Exactly the nth zone sibling: the positive chain matches n onward and the
+        // negated chain excludes n+1 onward. Unlike nth-child, DropLine siblings do not count.
+        const selector = `li[data-puck-layer-tree-id="${CSS.escape(id)}"] > ${chain(index + 1)}:not(${chain(index + 2)})`;
+        return [
+            `${selector} { display: none; }`
+        ];
+    }).join('\n');
+    return /*#__PURE__*/ _jsx("style", {
+        "data-xp-outline": id,
+        children: rules
+    });
+}
+function ExperimentOutline({ children }) {
+    // Public selector API in Puck 0.24, rather than the deprecated usePuck hook.
+    const key = usePuckSelector((state)=>{
+        const { data } = state.appState;
+        const items = new Map();
+        const collect = (content)=>{
+            for (const item of content)if (item.type === EXPERIMENT_SLOT_TYPE) {
+                const testId = item.props.experiment?.id;
+                items.set(item.props.id, [
+                    item.props.id,
+                    testId === undefined ? null : String(testId),
+                    slots.map((slot)=>{
+                        const content = item.props[slot];
+                        return !Array.isArray(content) || content.length === 0;
+                    })
+                ]);
+            }
+        };
+        walkTree(data, state.config, (content)=>{
+            collect(content);
+        });
+        // walkTree visits slots inside legacy zones, but does not call back on the zone itself.
+        for (const content of Object.values(data.zones ?? {}))collect(content);
+        return JSON.stringify([
+            ...items.values()
+        ]);
+    });
+    // Only binding/emptiness changes rebuild the rules, not edits to other page fields.
+    const rules = useMemo(()=>JSON.parse(key).map((item)=>/*#__PURE__*/ _jsx(SlotRules, {
+                item: item
+            }, item[0])), [
+        key
+    ]);
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            children,
+            rules
+        ]
+    });
+}
+/** Add to Puck's plugins so its outline wrapper composes with the host's overrides. */ export function experimentOutlinePlugin() {
+    return {
+        name: 'experiment-outline',
+        overrides: {
+            outline: ExperimentOutline
+        }
+    };
+}

package/dist/puck/experimentSlotField.d.ts

@@ -1,5 +1,7 @@
 import type { CustomField } from '@puckeditor/core';
 import type { ExperimentRef } from '../types/puck.js';
+import { type PuckRoutes } from './routes.js';
 export declare function createExperimentSlotField(opts?: {
     label?: string;
+    routes?: PuckRoutes;
 }): CustomField<ExperimentRef | null>;

package/dist/puck/experimentSlotField.js

@@ -1,13 +1,21 @@
 import { createElement } from 'react';
 import { ExperimentPicker } from './ExperimentPicker.js';
+import { resolvePuckRoutes } from './routes.js';
+import { PuckHostProvider } from './hostContext.js';
 import { pickerCopy } from './copy.js';
 export function createExperimentSlotField(opts) {
+    const routes = resolvePuckRoutes(opts?.routes);
     return {
         type: 'custom',
         label: opts?.label ?? pickerCopy.label,
-        render: ({ value, onChange })=>createElement(ExperimentPicker, {
-                value,
-                onChange
+        render: ({ value, onChange })=>createElement(PuckHostProvider, {
+                routes,
+                children: createElement('div', {
+                    className: 'xp-puck-field'
+                }, createElement(ExperimentPicker, {
+                    value,
+                    onChange
+                }))
             })
     };
 }

package/dist/puck/hostContext.d.ts

@@ -0,0 +1,10 @@
+import { resolvePuckRoutes } from './routes.js';
+import type { ReactNode } from 'react';
+export declare const usePuckRoutes: () => {
+    admin: string;
+    api: string;
+};
+export declare function PuckHostProvider({ routes, children }: {
+    routes: ReturnType<typeof resolvePuckRoutes>;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/puck/hostContext.js

@@ -0,0 +1,12 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+import { resolvePuckRoutes } from './routes.js';
+const PuckHostContext = /*#__PURE__*/ createContext(resolvePuckRoutes());
+export const usePuckRoutes = ()=>useContext(PuckHostContext);
+export function PuckHostProvider({ routes, children }) {
+    return /*#__PURE__*/ _jsx(PuckHostContext.Provider, {
+        value: routes,
+        children: children
+    });
+}

package/dist/puck/routes.d.ts

@@ -0,0 +1,12 @@
+export interface PuckRoutes {
+    admin?: string;
+    api?: string;
+}
+export declare const DEFAULT_PUCK_ROUTES: {
+    readonly admin: "/admin";
+    readonly api: "/api";
+};
+export declare function resolvePuckRoutes(routes?: PuckRoutes): {
+    admin: string;
+    api: string;
+};

package/dist/puck/routes.js

@@ -0,0 +1,11 @@
+// Payload's documented route defaults; hosts pass config.routes when customized.
+export const DEFAULT_PUCK_ROUTES = {
+    admin: '/admin',
+    api: '/api'
+};
+export function resolvePuckRoutes(routes) {
+    return {
+        admin: (routes?.admin ?? DEFAULT_PUCK_ROUTES.admin).replace(/\/$/, ''),
+        api: (routes?.api ?? DEFAULT_PUCK_ROUTES.api).replace(/\/$/, '')
+    };
+}

package/dist/puck/slotConfig.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentConfig } from '@puckeditor/core';
 import type { ExperimentSlotProps } from '../types/puck.js';
-export declare const experimentSlotLabel: "Experiment";
+export declare const experimentSlotLabel = "Experiment block";
 export declare const experimentSlotFields: NonNullable<ComponentConfig<ExperimentSlotProps>['fields']>;
 export declare const experimentSlotDefaultProps: NonNullable<ComponentConfig<ExperimentSlotProps>['defaultProps']>;

package/dist/puck/slotConfig.js

@@ -1,6 +1,6 @@
 import { createExperimentSlotField } from './experimentSlotField.js';
-import { pickerCopy, slotLabels } from './copy.js';
-export const experimentSlotLabel = pickerCopy.label;
+import { slotLabels } from './copy.js';
+export const experimentSlotLabel = 'Experiment block';
 export const experimentSlotFields = {
     experiment: createExperimentSlotField(),
     // Puck 0.24's defaultSlots prepends each slot, reversing declaration order in the outline.

package/dist/sanitizeReadinessDetail.js

@@ -8,6 +8,7 @@ const arm = (value)=>typeof value === 'string' && [
         'variantC',
         'holdout'
     ].includes(value);
+const path = (value)=>typeof value === 'string' && value.length <= 128 && value.startsWith('/') && !value.includes('//') && !/[^A-Za-z0-9_/-]/.test(value);
 const failure = (value)=>value === 'placements-failed' || value === 'forbidden' || value === 'not-found';
 /** Summary details contain identifiers only. Project known shapes rather than
  * recursively copying host objects: titles, messages and placement detail are text.
@@ -21,9 +22,17 @@ const failure = (value)=>value === 'placements-failed' || value === 'forbidden'
             } : undefined;
         case 'no-placements':
             return failure(detail) ? detail : undefined;
+        case 'page-in-use':
+            {
+                if (!object(detail) || !Array.isArray(detail.paths)) return undefined;
+                const paths = detail.paths.filter(path);
+                return paths.length ? {
+                    paths
+                } : undefined;
+            }
         case 'page-target-unpublished':
             // Paths only: no query, fragment, whitespace, URL authority or encoded text.
-            return typeof detail === 'string' && detail.length <= 128 && detail.startsWith('/') && !detail.includes('//') && !/[^A-Za-z0-9_/-]/.test(detail) ? detail : undefined;
+            return path(detail) ? detail : undefined;
         case 'flag-params-invalid':
             {
                 if (!Array.isArray(detail) || !detail.length || !detail.every((item)=>object(item) && arm(item.arm) && key(item.field))) return undefined;

package/dist/server/metadata.js

@@ -13,14 +13,21 @@ import { serverManifest } from './context.js';
     const live = manifest?.experiments.find((e)=>e.kind === 'page' && e.arms.some((a)=>a.pageTarget !== undefined && normalisePath(a.pageTarget) === normalisePath(path)));
     if (live) {
         const controlPath = live.arms.find((a)=>a.kind === 'control')?.pageTarget;
-        return controlPath && normalisePath(path) !== normalisePath(controlPath) ? {
+        if (!controlPath) return {};
+        // The Original's URL may be served with a variant's route: its canonical must stay on the Original,
+        // never the (noindexed) variant route the host would otherwise derive.
+        return normalisePath(path) !== normalisePath(controlPath) ? {
             robots: {
                 index: false
             },
             alternates: {
                 canonical: controlPath
             }
-        } : {};
+        } : {
+            alternates: {
+                canonical: controlPath
+            }
+        };
     }
     const archivedPath = manifest ? findNormalisedPathKey(manifest.archivedPages, path) : undefined;
     const archived = archivedPath === undefined ? undefined : manifest?.archivedPages[archivedPath];

package/dist/server/normaliseContentRelationships.d.ts

@@ -0,0 +1,7 @@
+import type { Block, Field } from 'payload';
+/** Undo depth expansion only where the collection schema declares relationships.
+ * Hidden fields and field-level afterRead hooks are unaffected by depth, so
+ * relationship expansion is the only depth-dependent transformation to undo.
+ * Other objects (especially JSON content with its own ids) must stay intact.
+ */
+export declare function normaliseContentRelationships(data: unknown, fields: Field[], blocks?: Block[], locales?: readonly string[]): unknown;

package/dist/server/normaliseContentRelationships.js

@@ -0,0 +1,62 @@
+import { contentBlocks } from '../transitions/contentFields.js';
+const object = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
+const id = (value)=>object(value) && 'id' in value ? value.id : value;
+/** Undo depth expansion only where the collection schema declares relationships.
+ * Hidden fields and field-level afterRead hooks are unaffected by depth, so
+ * relationship expansion is the only depth-dependent transformation to undo.
+ * Other objects (especially JSON content with its own ids) must stay intact.
+ */ export function normaliseContentRelationships(data, fields, blocks = [], locales = []) {
+    // With locale 'all', a localized field's value is { [locale]: value }: normalise each locale's value.
+    const localeMap = (value)=>locales.length > 0 && object(value) && Object.keys(value).length > 0 && Object.keys(value).every((key)=>locales.includes(key));
+    function lexical(value) {
+        if (!object(value)) return value;
+        const result = {
+            ...value
+        };
+        if (value.type === 'upload' || value.type === 'relationship') result.value = id(value.value);
+        if (Array.isArray(value.children)) result.children = value.children.map(lexical);
+        if (object(value.root)) result.root = lexical(value.root);
+        return result;
+    }
+    function fieldValue(value, field) {
+        if (field.type === 'relationship' || field.type === 'upload') {
+            const one = (entry)=>Array.isArray(field.relationTo) && object(entry) ? {
+                    ...entry,
+                    value: id(entry.value)
+                } : id(entry);
+            return field.hasMany && Array.isArray(value) ? value.map(one) : one(value);
+        }
+        if (field.type === 'richText') return lexical(value);
+        if (field.type === 'array' && Array.isArray(value)) return value.map((row)=>walk(row, field.fields));
+        if (field.type === 'blocks' && Array.isArray(value)) return value.map((row)=>{
+            const block = object(row) && contentBlocks(field, blocks).find((block)=>block.slug === row.blockType);
+            return block ? walk(row, block.fields) : row;
+        });
+        return 'fields' in field ? walk(value, field.fields) : value;
+    }
+    function walk(value, schema) {
+        if (!object(value)) return value;
+        let result = {
+            ...value
+        };
+        for (const field of schema){
+            if (field.type === 'tabs') {
+                for (const tab of field.tabs){
+                    if ('name' in tab && tab.name) {
+                        if (tab.name in result) result[tab.name] = walk(result[tab.name], tab.fields);
+                    } else result = walk(result, tab.fields);
+                }
+            } else if ('name' in field && field.name) {
+                if (field.name in result) {
+                    const value = result[field.name];
+                    result[field.name] = 'localized' in field && field.localized && localeMap(value) ? Object.fromEntries(Object.entries(value).map(([locale, entry])=>[
+                            locale,
+                            fieldValue(entry, field)
+                        ])) : fieldValue(value, field);
+                }
+            } else if ('fields' in field) result = walk(result, field.fields);
+        }
+        return result;
+    }
+    return walk(data, fields);
+}

package/dist/server/recordContentChange.d.ts

@@ -1,5 +1,5 @@
 import type { CollectionAfterChangeHook, CollectionBeforeChangeHook } from 'payload';
-/** Paired beforeChange capture: previousDoc may be an autosaved draft. */
+/** Paired raw beforeChange capture: previousDoc may be an autosaved draft. */
 export declare function capturePublishedContent({ req, collection, originalDoc, operation }: Parameters<CollectionBeforeChangeHook>[0]): Promise<void>;
 type ContentChangeArgs = Pick<Parameters<CollectionAfterChangeHook>[0], 'doc' | 'previousDoc' | 'req' | 'collection'>;
 /** Publish-only host helper. Audit failures are logged, never thrown into saves. */

package/dist/server/recordContentChange.js

@@ -1,9 +1,10 @@
 import { safeError } from '../log.js';
 import { isDeepStrictEqual } from 'node:util';
-import { appendContentChange, contentChangeSavepoint, previousPublishedContent, runningContentExperiment } from '../db/appends.js';
+import { appendContentChange, contentChangeSavepoint, previousPublishedContent, runningContentExperiment, storedContent } from '../db/appends.js';
 import { txExecutor } from '../db/executor.js';
 import { puckCollections } from '../options.js';
 import { withTransition } from '../transitions/kernel.js';
+import { normaliseContentRelationships } from './normaliseContentRelationships.js';
 const slots = [
     'control',
     'variantA',
@@ -54,8 +55,7 @@ function bindings(data, puck) {
     return found;
 }
 const baselineKey = (collection, id)=>`${collection}:${id}`;
-/** Paired beforeChange capture: previousDoc may be an autosaved draft. */ export async function capturePublishedContent({ req, collection, originalDoc, operation }) {
-    if (!collection.versions || !collection.versions.drafts) return;
+/** Paired raw beforeChange capture: previousDoc may be an autosaved draft. */ export async function capturePublishedContent({ req, collection, originalDoc, operation }) {
     if (await req.transactionID == null) {
         req.payload.logger?.debug('[payload-experiments] contentChanges baseline skipped without a transaction');
         return;
@@ -64,7 +64,7 @@ const baselineKey = (collection, id)=>`${collection}:${id}`;
     const baselines = req.context.xpPublishedContent ??= {};
     const key = baselineKey(collection.slug, id);
     delete baselines[key];
-    const audit = await contentChangeSavepoint(txExecutor(req), async ()=>operation === 'create' ? undefined : previousPublishedContent(req, collection.slug, id));
+    const audit = await contentChangeSavepoint(txExecutor(req), async ()=>operation === 'create' ? undefined : collection.versions && collection.versions.drafts ? previousPublishedContent(req, collection.slug, id) : storedContent(req, collection.slug, id));
     if (!audit.ok) throw audit.error;
     baselines[key] = {
         collection: collection.slug,
@@ -97,8 +97,8 @@ async function auditContentChange({ doc, previousDoc, req, collection }) {
     }
     const options = req.payload.config.custom?.xp;
     const registration = puckCollections(options ?? {}).find((entry)=>entry.slug === collection.slug);
-    const after = bindings(registration ? doc[registration.field] : doc, Boolean(registration));
-    const changes = (previous)=>{
+    const changes = (previous, current)=>{
+        const after = bindings(registration && object(current) ? current[registration.field] : current, Boolean(registration));
         const before = bindings(registration && object(previous) ? previous[registration.field] : previous, Boolean(registration));
         return [
             ...new Set([
@@ -107,12 +107,21 @@ async function auditContentChange({ doc, previousDoc, req, collection }) {
             ])
         ].filter((key)=>!isDeepStrictEqual(before.get(key)?.contents, after.get(key)?.contents)).map((key)=>after.get(key) ?? before.get(key));
     };
-    if (!drafts && !changes(previousDoc).length) return;
     // Include discovery reads in the savepoint: a SQL read error also aborts Postgres.
     // An explicit host call must supply its afterChange request's transaction.
     const executor = txExecutor(req);
     const audit = await contentChangeSavepoint(executor, async ()=>{
-        const changed = changes(drafts ? baseline?.doc : previousDoc);
+        // Compare like with like. A captured baseline is adapter-raw, so it meets the stored row after the
+        // write. Without one, previousDoc and doc are both afterRead documents (same locale projection,
+        // hidden fields and field hooks) that differ only in depth, so only relationships are normalised.
+        const locales = req.payload.config.localization ? req.payload.config.localization.localeCodes : [];
+        const normalise = (value)=>normaliseContentRelationships(value, collection.fields, req.payload.config.blocks, locales);
+        let changed;
+        if (baseline) {
+            const current = await storedContent(req, collection.slug, doc.id);
+            if (!current) throw new Error('The saved content row was not found.');
+            changed = changes(baseline.doc, current);
+        } else changed = changes(normalise(previousDoc), normalise(doc));
         const experiments = new Map();
         for (const binding of changed){
             const experiment = await runningContentExperiment(executor, binding);

package/dist/server/runResults.js

@@ -62,19 +62,50 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
     ];
     const linked = new Set(userIds);
     const identityConflicts = new Set();
+    const userByVisitor = new Map(identities.map((identity)=>[
+            identity.anonymousId,
+            identity.userId
+        ]));
+    const linksByUser = new Map();
+    for (const identity of identities){
+        const links = linksByUser.get(identity.userId) ?? [];
+        links.push(identity);
+        linksByUser.set(identity.userId, links);
+    }
+    // Last arm credited per user: enough to detect that a user's credited events span arms (a conflict).
+    const creditedArms = new Map();
+    const noteCredit = (userId, unitId)=>{
+        const arm = units.get(unitId)?.arm;
+        if (arm === undefined) return;
+        const previous = creditedArms.get(userId);
+        if (previous !== undefined && previous !== arm) identityConflicts.add(userId);
+        creditedArms.set(userId, arm);
+    };
     const credit = (events, userKeyed)=>{
         if (candidate.unitType === 'user') return events.map((event)=>({
                 ...event,
                 unitId: event.userId ?? event.unitId
             }));
-        const userEvents = events.filter((event)=>userKeyed || event.userId != null && linked.has(event.userId)).map((event)=>({
+        // §8.3's earliest exposed linked visitor applies only when the event has no
+        // exposed unit of its own. A visitor-keyed event stays on its own exposed
+        // browser even if an earlier linked browser saw another arm or is ineligible.
+        const direct = userKeyed ? [] : events.filter((event)=>units.has(event.unitId) || event.userId == null || !linked.has(event.userId));
+        const userEvents = events.filter((event)=>userKeyed || !units.has(event.unitId) && event.userId != null && linked.has(event.userId)).map((event)=>({
                 userId: String(event.userId ?? event.unitId),
                 value: event.value,
                 ts: event.ts
             }));
         const credited = creditUserEvents(units, identities, userEvents, (userId)=>identityConflicts.add(userId)).events;
-        return userKeyed ? credited : [
-            ...events.filter((event)=>event.userId == null || !linked.has(event.userId)),
+        for (const event of direct)if (event.userId != null && linked.has(event.userId)) {
+            noteCredit(event.userId, event.unitId);
+            // Keep the eligible-link diagnostic when direct credit bypasses the helper.
+            const arms = new Set(eligibleIdentityLinks(linksByUser.get(event.userId), event.ts).map((link)=>units.get(link.anonymousId).arm));
+            arms.add(units.get(event.unitId).arm);
+            if (arms.size > 1) identityConflicts.add(event.userId);
+        }
+        for (const event of credited)noteCredit(userByVisitor.get(event.unitId), event.unitId);
+        return [
+            ...direct,
             ...credited
         ];
     };
@@ -111,9 +142,10 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
                         from: start,
                         to
                     });
+                    // The two lookups overlap when a linked user's own browser was exposed.
                     return [
                         ...direct,
-                        ...signedIn
+                        ...signedIn.filter((event)=>!units.has(event.unitId))
                     ];
                 };
                 events = credit(await read(phase.analysis.cuped === 'auto' ? preFrom : from), false);

package/dist/transitions/checkStart.d.ts

@@ -1,7 +1,7 @@
 import type { Arm, DocId, ExperimentKind, ExposurePolicy, FlagPoint, MetricSource, ResolvedOptions, Status, TargetingRule, UnitType } from '../types/contracts.js';
 import type { ArmIssueCode, PreflightResult } from '../types/endpoints.js';
 import type { BlockPlacement, FlagPlacement } from './placements.js';
-export type ReadinessCode = ArmIssueCode | 'invalid-status' | 'no-planned-duration' | 'no-primary-metric' | 'no-reach-per-day' | 'page-no-targets' | 'page-target-unpublished' | 'page-targets-unchecked' | 'version-page-unavailable' | 'version-page-unchecked' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'no-placements' | 'empty-slot' | 'make-content-unsupported' | 'layer-unit-mismatch' | 'layer-full' | 'unknown-metric-source' | 'unit-source-mismatch' | 'block-path-rule' | 'undeclared-targeting-key' | 'invalid-targeting-rule';
+export type ReadinessCode = ArmIssueCode | 'invalid-status' | 'no-planned-duration' | 'no-primary-metric' | 'no-reach-per-day' | 'page-no-targets' | 'page-in-use' | 'page-target-unpublished' | 'page-targets-unchecked' | 'version-page-unavailable' | 'version-page-unchecked' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'no-placements' | 'empty-slot' | 'make-content-unsupported' | 'layer-unit-mismatch' | 'layer-full' | 'unknown-metric-source' | 'unit-source-mismatch' | 'block-path-rule' | 'undeclared-targeting-key' | 'invalid-targeting-rule';
 export interface StartExperiment {
     id: DocId;
     slug: string;
@@ -51,6 +51,7 @@ export interface CheckStartInput {
     flagPointBusy?: boolean;
     unpublishedPageTargets?: string[];
     pageTargetsUnchecked?: boolean;
+    pageTestsInUse?: Pick<StartExperiment, 'id' | 'arms'>[];
     layer?: {
         unitType: UnitType;
         usedSlices: number[];
@@ -61,5 +62,8 @@ export declare const ARM_CHECK_ORDER: readonly ArmIssueCode[];
 export declare const relationshipId: (value: DocId | {
     id: DocId;
 } | null | undefined) => DocId | undefined;
+/** Every path the runtime would match for these arms (pageRewrite, experimentMetadata): any string
+ * pageTarget, holdout included, normalised the same way ('' is '/'). Occupancy and lock keys use this. */
+export declare const pageTargetPaths: (arms: readonly Arm[]) => string[];
 /** Pure Review/Start predicates in refusal order. Inapplicable checks pass. */
 export declare function checkStart(input: CheckStartInput): PreflightResult['checks'];

package/dist/transitions/checkStart.js

@@ -1,4 +1,5 @@
 import { checkArms } from '../collections/experiments/armInvariants.js';
+import { normalisePath } from '../runtime/normalisePath.js';
 import { isOpValid } from '../targeting/ops.js';
 export const ARM_CHECK_ORDER = [
     'weights-total',
@@ -13,6 +14,10 @@ export const ARM_CHECK_ORDER = [
     'duplicate-slot'
 ];
 export const relationshipId = (value)=>value == null ? undefined : typeof value === 'object' ? value.id : value;
+/** Every path the runtime would match for these arms (pageRewrite, experimentMetadata): any string
+ * pageTarget, holdout included, normalised the same way ('' is '/'). Occupancy and lock keys use this. */ export const pageTargetPaths = (arms)=>[
+        ...new Set(arms.filter((arm)=>typeof arm.pageTarget === 'string').map((arm)=>normalisePath(arm.pageTarget)))
+    ].sort();
 const positive = (value)=>typeof value === 'number' && Number.isFinite(value) && value > 0;
 function invalidParams(arms, point) {
     return arms.flatMap((arm)=>{
@@ -56,6 +61,11 @@ function invalidParams(arms, point) {
         'viewport'
     ].includes(e.exposurePolicy) || positive(e.analysis?.reachPerDay));
     add('page-no-targets', e.kind !== 'page' || e.arms.filter((arm)=>arm.kind !== 'holdout').every((arm)=>typeof arm.pageTarget === 'string' && arm.pageTarget.trim().length > 0));
+    const occupiedPaths = new Set((input.pageTestsInUse ?? []).filter((other)=>String(other.id) !== String(e.id)).flatMap((other)=>pageTargetPaths(other.arms)));
+    const sharedPaths = e.kind === 'page' ? pageTargetPaths(e.arms).filter((path)=>occupiedPaths.has(path)) : [];
+    add('page-in-use', sharedPaths.length === 0, {
+        paths: sharedPaths
+    });
     add('page-target-unpublished', !input.unpublishedPageTargets?.length, input.unpublishedPageTargets?.[0]);
     add('page-targets-unchecked', true);
     if (input.pageTargetsUnchecked) checks[checks.length - 1].warning = true;

package/dist/transitions/decide.js

@@ -1,7 +1,9 @@
 import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
 import { reclaimSlices } from '../db/slices.js';
 import { decideGuard } from '../results/decideGuard.js';
-import { relationshipId } from './checkStart.js';
+import { lockPagePaths } from '../db/locks.js';
+import { routedPageTests } from '../db/pageOccupancy.js';
+import { pageTargetPaths, relationshipId } from './checkStart.js';
 import { expectedConfirm, matchesConfirm, storedWinnerLabel } from './confirmPhrases.js';
 import { withTransition } from './kernel.js';
 import { readPhaseRecord, setPhaseEndedAt, writePhaseRecord } from './phaseRecord.js';
@@ -45,6 +47,19 @@ export async function decide(req, { experimentId, winnerArm, note, confirmation
         }
         const test = await readPhaseRecord(req, experimentId, current.phase);
         if (test.phaseKind !== 'test') refuse('invalid-status');
+        if (current.kind === 'page' && current.status === 'stopped') {
+            // Deciding a stopped page test restores its routing: recheck page occupancy under the
+            // sorted path locks Start takes, so another test that started on these pages meanwhile wins.
+            // The frozen test-round arms are what decide restores; the stopped document's arms may have been edited.
+            const mine = pageTargetPaths(test.arms);
+            await lockPagePaths(exec, mine);
+            // Other tests' routed (frozen-round) arms, as the runtime matches them.
+            const occupied = new Set((await routedPageTests(exec)).filter((other)=>String(other.id) !== String(experimentId)).flatMap((other)=>pageTargetPaths(other.arms)));
+            const shared = mine.filter((path)=>occupied.has(path));
+            if (shared.length) refuse('page-in-use', {
+                paths: shared
+            });
+        }
         const winner = test.arms.find((arm)=>arm.key === winnerArm && arm.kind !== 'holdout');
         if (!winner) refuse('invalid-winner');
         // §7.8: decision snapshot lookup serves the authorised transition.

package/dist/transitions/placements.d.ts

@@ -1,11 +1,7 @@
 import type { PayloadRequest } from 'payload';
-import type { Arm, DocId, FlagPoint, ResolvedOptions } from '../types/contracts.js';
+import type { Arm, DocId, FlagPoint, PreviewPlacement, ResolvedOptions } from '../types/contracts.js';
 import type { ArmSlot } from '../types/puck.js';
-export interface BlockPlacement {
-    collection: string;
-    id: DocId;
-    title: string;
-    published: boolean;
+export interface BlockPlacement extends PreviewPlacement {
     slots: Record<ArmSlot, number>;
     locked?: boolean;
     localized?: boolean;

package/dist/transitions/placements.js

@@ -24,6 +24,7 @@ export async function scanBlockPlacements(req, args) {
         }
     })){
         const publishedIds = new Set();
+        const publishedSlugs = new Map();
         const draftsEnabled = req.payload.config.collections?.some((config)=>config.slug === collection && config.versions && config.versions.drafts);
         for (const draft of [
             false,
@@ -51,7 +52,10 @@ export async function scanBlockPlacements(req, args) {
                 for (const doc of result.docs){
                     if (!draft && doc._status === 'draft') continue;
                     if (draft && doc._status !== 'draft' && publishedIds.has(String(doc.id))) continue;
-                    if (!draft) publishedIds.add(String(doc.id));
+                    if (!draft) {
+                        publishedIds.add(String(doc.id));
+                        if (typeof doc.slug === 'string') publishedSlugs.set(String(doc.id), doc.slug);
+                    }
                     function walk(value) {
                         if (!value || typeof value !== 'object') return;
                         if (Array.isArray(value)) {
@@ -68,6 +72,9 @@ export async function scanBlockPlacements(req, args) {
                                 id: doc.id,
                                 title: String(doc.title ?? doc.name ?? doc.id),
                                 published: !draft || doc._status === 'published',
+                                ...publishedSlugs.has(String(doc.id)) ? {
+                                    slug: publishedSlugs.get(String(doc.id))
+                                } : {},
                                 slots: Object.fromEntries(slots.map((slot)=>[
                                         slot,
                                         Array.isArray(props[slot]) ? props[slot].length : 0

package/dist/transitions/preflightData.d.ts

@@ -13,6 +13,14 @@ export interface PreflightDependencies {
 export declare function loadStartInputs<TUser extends {
     id: DocId;
 }>(req: PayloadRequest, options: ResolvedOptions<TUser>, experimentId: DocId): Promise<CheckStartInput | null>;
+/** Occupancy from the arms the runtime routes on (frozen rounds), shared by preflight and
+ * Start's locked recheck. Raw SQL on the request's transaction when there is one. */
+export declare function loadPageTestsInUse(req: PayloadRequest): Promise<NonNullable<CheckStartInput['pageTestsInUse']>>;
+/** Page targets no registered collection reports as published. A lookup that throws counts as
+ * unpublished (logged). Start calls it again under its page-path locks on a detached request. */
+export declare function unpublishedPageTargets<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, options: ResolvedOptions<TUser>, experiment: Pick<StartExperiment, 'id' | 'arms'>): Promise<string[]>;
 /** Shared, request-scoped reads for summary; a failed row is null in tolerant mode.
  * Preflight/Start use the same builder and retain their throwing read behaviour.
  */