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

package/dist/admin/useLayerUsage.js

@@ -1,4 +1,5 @@
 'use client';
+import { fetchAllDocs } from '../lib/fetchAllDocs.js';
 import { useConfig } from '@payloadcms/ui';
 import { useEffect, useState } from 'react';
 import { layerUsage } from './layerUsage.model.js';
@@ -13,33 +14,23 @@ export function useLayerExperiments(layerId) {
         if (id == null) return;
         const controller = new AbortController();
         async function load() {
-            const docs = [];
-            let page = 1;
-            while(!controller.signal.aborted){
-                const query = new URLSearchParams({
-                    depth: '0',
-                    limit: '100',
-                    page: String(page),
-                    'where[layer][equals]': id,
-                    'where[status][in]': 'running,decided'
-                });
-                const response = await fetch(`${api}/xp-experiments?${query}`, {
-                    credentials: 'include',
-                    signal: controller.signal
-                });
-                if (!response.ok) {
-                    if (!controller.signal.aborted) setState(null);
-                    return;
-                }
-                const data = await response.json();
-                docs.push(...data.docs);
-                if (!data.hasNextPage) break;
-                page++;
+            const query = new URLSearchParams({
+                depth: '0',
+                'where[layer][equals]': id,
+                'where[status][in]': 'running,decided'
+            });
+            const response = await fetchAllDocs(`${api}/xp-experiments?${query}`, {
+                credentials: 'include',
+                signal: controller.signal
+            });
+            if (!response.ok) {
+                if (!controller.signal.aborted) setState(null);
+                return;
             }
             if (!controller.signal.aborted) setState({
                 api,
                 id: id,
-                usage: layerUsage(docs)
+                usage: layerUsage(response.docs)
             });
         }
         void load().catch(()=>{

package/dist/admin/views/TestsNavLinkServer.d.ts

@@ -0,0 +1,2 @@
+import type { ServerProps } from 'payload';
+export declare function TestsNavLinkServer({ payload, user, permissions }: Pick<ServerProps, 'payload' | 'user' | 'permissions'>): Promise<string | number | bigint | boolean | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined>;

package/dist/admin/views/TestsNavLinkServer.js

@@ -0,0 +1,43 @@
+import { RenderServerComponent } from '@payloadcms/ui/elements/RenderServerComponent';
+import { SURFACE_COPY } from '../copy/surface.js';
+import { XP_TESTS_NAV_CLIENT } from '../paths.js';
+export async function TestsNavLinkServer({ payload, user, permissions }) {
+    const testPermissions = permissions?.collections?.['xp-experiments'];
+    if (!user?.collection || testPermissions?.update !== true) return null;
+    const result = await payload.find({
+        collection: 'payload-preferences',
+        where: {
+            and: [
+                {
+                    key: {
+                        equals: 'nav'
+                    }
+                },
+                {
+                    'user.relationTo': {
+                        equals: user.collection
+                    }
+                },
+                {
+                    'user.value': {
+                        equals: user.id
+                    }
+                }
+            ]
+        },
+        limit: 1,
+        pagination: false,
+        depth: 0,
+        user,
+        overrideAccess: false
+    });
+    const value = result.docs[0]?.value;
+    // Resolve the CSS-bearing client boundary through Payload's public import map.
+    return RenderServerComponent({
+        Component: XP_TESTS_NAV_CLIENT,
+        importMap: payload.importMap,
+        clientProps: {
+            isOpen: value?.groups?.[SURFACE_COPY.title]?.open ?? true
+        }
+    });
+}

package/dist/arms/copy.d.ts

@@ -0,0 +1,6 @@
+import type { ArmIssueCode } from '../types/endpoints.js';
+export declare const ISSUE_COPY: Record<ArmIssueCode, string>;
+export declare function issueMessage(issue: {
+    code: string;
+    message: string;
+}, total: number): string;

package/dist/arms/copy.js

@@ -0,0 +1,16 @@
+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 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/arms/model.d.ts

@@ -0,0 +1,23 @@
+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[];
+/** Keep the edited share exact and distribute the remaining whole percentages proportionally. */
+export declare function balanceWeight(arms: Arm[], key: ArmKey, weight: number): Arm[];

package/dist/arms/model.js

@@ -0,0 +1,173 @@
+import { addHoldout, checkArms } from '../collections/experiments/armInvariants.js';
+import { ARM_LABELS as GROUP_LABELS } from '../labels/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
+                ]
+            ];
+        })));
+}
+/** 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);
+}

package/dist/db/appends.d.ts

@@ -19,9 +19,13 @@ type AppendArgs<T> = {
     phase: number;
     entry: T;
 };
+/** Raw main-row read on the host transaction, without afterRead expansion.
+ * Adapter reads avoid Local API error handling killing the host transaction
+ * before the audit savepoint can recover.
+ */
+export declare function storedContent(req: PayloadRequest, collection: string, id: DocId): Promise<Record<string, unknown> | undefined>;
 /** Read the main collection row BEFORE the host write. Draft version retention
- * and unpublishing cannot remove this baseline. Adapter reads avoid Local API
- * error handling killing the host transaction before savepoint recovery.
+ * and unpublishing cannot remove this baseline.
  */
 export declare function previousPublishedContent(req: PayloadRequest, collection: string, id: DocId): Promise<Record<string, unknown> | undefined>;
 /** Serialize flagDefaults read/modify/write before the manifest builder bumps. */

package/dist/db/appends.js

@@ -1,10 +1,10 @@
 import { COLUMNS, TABLES } from './names.js';
 import { XpRefusal } from '../errors.js';
 import { qualifiedTable, quoteIdentifier as quote } from './sql.js';
-/** Read the main collection row BEFORE the host write. Draft version retention
- * and unpublishing cannot remove this baseline. Adapter reads avoid Local API
- * error handling killing the host transaction before savepoint recovery.
- */ export async function previousPublishedContent(req, collection, id) {
+/** Raw main-row read on the host transaction, without afterRead expansion.
+ * Adapter reads avoid Local API error handling killing the host transaction
+ * before the audit savepoint can recover.
+ */ export async function storedContent(req, collection, id) {
     const doc = await req.payload.db.findOne({
         collection,
         req,
@@ -16,6 +16,12 @@ import { qualifiedTable, quoteIdentifier as quote } from './sql.js';
         // Adapter reads have no access layer; document the audit's access posture.
         overrideAccess: false
     });
+    return doc ?? undefined;
+}
+/** Read the main collection row BEFORE the host write. Draft version retention
+ * and unpublishing cannot remove this baseline.
+ */ export async function previousPublishedContent(req, collection, id) {
+    const doc = await storedContent(req, collection, id);
     if (!doc) return undefined;
     // A draft created with content is already in the main table. Only the
     // existence of a published version matters here; never use its content as

package/dist/db/locks.d.ts

@@ -4,6 +4,7 @@ export declare const LOCK_NAMESPACES: {
     readonly layer: "xp:layer";
     readonly flagPoint: "xp:flagpoint";
     readonly experiment: "xp:experiment";
+    readonly pagePath: "xp:pagepath";
 };
 /** Transaction executor only. Call in layer → flag point → experiment order;
  * the manifest builder takes the state lock last, after transition writes.
@@ -13,3 +14,8 @@ export declare function lockTransitionScope(exec: Executor, scope: {
     layerId?: DocId | null;
     flagPointId?: string | null;
 }): Promise<void>;
+/** After layer → flag point → experiment, before metric/state locks. Paths must
+ * already be normalised with the runtime's rules. Sorted keys avoid deadlocks
+ * when different tests share several paths in different arm orders.
+ */
+export declare function lockPagePaths(exec: Executor, paths: readonly string[]): Promise<void>;

package/dist/db/locks.js

@@ -1,11 +1,13 @@
 export const LOCK_NAMESPACES = {
     layer: 'xp:layer',
     flagPoint: 'xp:flagpoint',
-    experiment: 'xp:experiment'
+    experiment: 'xp:experiment',
+    pagePath: 'xp:pagepath'
 };
 const LOCK_STATEMENTS = {
     layer: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.layer}'), hashtext($1))`,
     flagPoint: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.flagPoint}'), hashtext($1))`,
+    pagePath: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.pagePath}'), hashtext($1))`,
     experiment: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.experiment}'), hashtext($1))`
 };
 /** Transaction executor only. Call in layer → flag point → experiment order;
@@ -21,3 +23,13 @@ const LOCK_STATEMENTS = {
         String(scope.experimentId)
     ]);
 }
+/** After layer → flag point → experiment, before metric/state locks. Paths must
+ * already be normalised with the runtime's rules. Sorted keys avoid deadlocks
+ * when different tests share several paths in different arm orders.
+ */ export async function lockPagePaths(exec, paths) {
+    for (const path of [
+        ...new Set(paths)
+    ].sort())await exec.query(LOCK_STATEMENTS.pagePath, [
+        path
+    ]);
+}

package/dist/db/pageOccupancy.d.ts

@@ -0,0 +1,12 @@
+import type { Arm, DocId } from '../types/contracts.js';
+import type { Executor } from './executor.js';
+/** Page tests that occupy paths, with the arms the runtime routes on (`compileManifest`):
+ * - running or decided: the latest round's arms, or for a rollout the latest test round's;
+ * - archived with a standing result (winner, not discarded, pages not released): the latest test
+ *   round's arms whose paths are rewritten to the winner (archivedPages), so a new test cannot
+ *   silently take them over.
+ * Documents' arms may have been edited while stopped, so occupancy never reads them. */
+export declare function routedPageTests(exec: Executor): Promise<Array<{
+    id: DocId;
+    arms: Arm[];
+}>>;

package/dist/db/pageOccupancy.js

@@ -0,0 +1,45 @@
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+/** Page tests that occupy paths, with the arms the runtime routes on (`compileManifest`):
+ * - running or decided: the latest round's arms, or for a rollout the latest test round's;
+ * - archived with a standing result (winner, not discarded, pages not released): the latest test
+ *   round's arms whose paths are rewritten to the winner (archivedPages), so a new test cannot
+ *   silently take them over.
+ * Documents' arms may have been edited while stopped, so occupancy never reads them. */ export async function routedPageTests(exec) {
+    const e = COLUMNS.experiments, p = COLUMNS.phases;
+    const experiments = qualifiedTable(exec, TABLES.experiments), phases = qualifiedTable(exec, TABLES.phases);
+    const testRound = `LEFT JOIN LATERAL (SELECT ${q(p.arms)} AS arms FROM ${phases}
+      WHERE ${q(p.experimentId)} = x.${q(e.id)} AND ${q(p.phaseKind)} = 'test' ORDER BY ${q(p.phase)} DESC LIMIT 1) test ON true`;
+    const { rows } = await exec.query(`
+    SELECT x.${q(e.id)} AS "id", CASE WHEN latest.kind = 'rollout' THEN test.arms ELSE latest.arms END AS "arms", NULL::text AS "winnerArm"
+    FROM ${experiments} x
+    JOIN LATERAL (SELECT ${q(p.phaseKind)} AS kind, ${q(p.arms)} AS arms FROM ${phases}
+      WHERE ${q(p.experimentId)} = x.${q(e.id)} ORDER BY ${q(p.phase)} DESC LIMIT 1) latest ON true
+    ${testRound}
+    WHERE x.${q(e.kind)} = 'page' AND x.${q(e.status)} IN ('running', 'decided')
+    UNION ALL
+    SELECT x.${q(e.id)} AS "id", test.arms AS "arms", x.${q(e.decisionWinnerArm)} AS "winnerArm"
+    FROM ${experiments} x
+    ${testRound}
+    WHERE x.${q(e.kind)} = 'page' AND x.${q(e.status)} = 'archived' AND x.${q(e.decisionWinnerArm)} IS NOT NULL
+      AND x.${q(e.decisionDiscardedAt)} IS NULL AND x.${q(e.decisionPagesReleasedAt)} IS NULL
+    ORDER BY "id"`, []);
+    const occupied = [];
+    for (const row of rows){
+        const arms = Array.isArray(row.arms) ? row.arms : [];
+        if (row.winnerArm == null) {
+            occupied.push({
+                id: row.id,
+                arms
+            });
+            continue;
+        }
+        // compileManifest's archivedPages rule: every arm path other than the winner's.
+        const winnerPath = arms.find((arm)=>arm.key === row.winnerArm)?.pageTarget;
+        if (winnerPath) occupied.push({
+            id: row.id,
+            arms: arms.filter((arm)=>arm.pageTarget && arm.pageTarget !== winnerPath)
+        });
+    }
+    return occupied;
+}

package/dist/db/snapshots.js

@@ -32,12 +32,14 @@ const LATE_BEACON_GRACE_MS = 24 * 60 * 60 * 1000;
       'arms', p.${q(p.arms)}, 'allocation', p.${q(p.allocation)}, 'metricDefinitions', p.${q(p.metricDefinitions)},
       'analysis', p.${q(p.analysis)}, 'contentChanges', p.${q(p.contentChanges)}) AS "phase",
     e.${q(e.kind)} AS "kind", e.${q(e.phase)} AS "currentPhase", e.${q(e.unitType)} AS "unitType", e.${q(e.status)} AS "status", e.${q(e.decisionWinnerArm)} AS "winnerArm",
-    (SELECT max(s.${q(s.computedAt)}) FROM ${snapshots} s WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}) AS "latestComputedAt",
+    latest."computedAt" AS "latestComputedAt",
     (SELECT t.${q(p.arms)} FROM ${phases} t WHERE t.${q(p.experimentId)} = p.${q(p.experimentId)} AND t.${q(p.phaseKind)} = 'test' AND t.${q(p.phase)} <= p.${q(p.phase)} ORDER BY t.${q(p.phase)} DESC LIMIT 1) AS "testArms",
     frozen."snapshot" AS "frozenSnapshot",
     l.${q(l.slug)} AS "layerSlug", e.${q(e.layerSlices)} AS "layerSlices"
     FROM ${phases} p JOIN ${qualifiedTable(exec, TABLES.experiments)} e ON e.${q(e.id)} = p.${q(p.experimentId)}
     LEFT JOIN ${qualifiedTable(exec, TABLES.layers)} l ON l.${q(l.id)} = e.${q(e.layerId)}
+    LEFT JOIN LATERAL (SELECT max(s.${q(s.computedAt)}) AS "computedAt" FROM ${snapshots} s
+      WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}) latest ON true
     LEFT JOIN LATERAL (SELECT s.${q(s.snapshot)} AS "snapshot" FROM ${snapshots} s
       WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}
         AND p.${q(p.endedAt)} IS NOT NULL
@@ -53,8 +55,7 @@ const LATE_BEACON_GRACE_MS = 24 * 60 * 60 * 1000;
           AND done.${q(s.computedAt)} > p.${q(p.endedAt)} + $2 * interval '1 millisecond')))
       ${experimentId === undefined ? '' : ` AND p.${q(p.experimentId)} = $3`}
     ORDER BY (frozen."snapshot" IS NOT NULL),
-      CASE WHEN frozen."snapshot" IS NULL THEN
-        (SELECT max(s.${q(s.computedAt)}) FROM ${snapshots} s WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}) END NULLS FIRST,
+      CASE WHEN frozen."snapshot" IS NULL THEN latest."computedAt" END NULLS FIRST,
       CASE WHEN frozen."snapshot" IS NOT NULL THEN random() END,
       p.${q(p.experimentId)}, p.${q(p.phase)}`, params);
     return rows;

package/dist/exports/adminRsc.d.ts

@@ -1,3 +1,4 @@
 export { ExperimentsRootView } from '../admin/views/ExperimentsRootView.js';
 export { CollectionListRedirect } from '../admin/views/CollectionListRedirect.js';
 export { CollectionEditRedirect } from '../admin/views/CollectionEditRedirect.js';
+export { TestsNavLinkServer } from '../admin/views/TestsNavLinkServer.js';

package/dist/exports/adminRsc.js

@@ -1,3 +1,4 @@
 export { ExperimentsRootView } from '../admin/views/ExperimentsRootView.js';
 export { CollectionListRedirect } from '../admin/views/CollectionListRedirect.js';
 export { CollectionEditRedirect } from '../admin/views/CollectionEditRedirect.js';
+export { TestsNavLinkServer } from '../admin/views/TestsNavLinkServer.js';

package/dist/exports/index.d.ts

@@ -2,4 +2,4 @@ export { createExperimentsPlugin } from '../plugin.js';
 export { defineFlagPoint, defineMetricSource } from '../define.js';
 export { contentDone } from '../contentDone.js';
 export { createArmSelectField } from '../fields/armSelect.js';
-export type { SerializedFlagPoint, SerializedMetricSource, SerializedAttributeKeys, EditableField, Assignment, Assignments, FlagPointResult, ClientAssignments, RenderedExposure, DocId, Attributes, ExposurePolicy, ExperimentKind, Status, UnitType, ArmKey, ArmKind, TargetingRule, Arm, ParamField, MetricSource, FlagPoint, RateLimiter, ExperimentsAccess, ExperimentsPluginOptions, ArmIssueCode, RefusalCode, ReadinessCode, ErrorEnvelope, TransitionSuccess, AllocateBody, AddMetricBody, DecideBody, ArchiveBody, MakeContentResult, DismissContentEntryBody, DismissContentEntryResult, RestoreContentEntryBody, RestoreContentEntryResult, ContentReport, PreflightResult, PreviewTokenResult, PhaseSummary, ResultsResponse, SummaryResponse, EventBody, FlagDefault, Manifest, ManifestExperiment, ArmSlot, ExperimentRef, ExperimentSlotProps, ExperimentsProxyRuntimeOptions, ExperimentsProxyRuntime, ExperimentsServerRuntimeOptions, ExperimentsServerRuntime, VerdictCode, Snapshot, MetricUnavailableReason, ContentReportReason, } from '../types/index.js';
+export type { SerializedFlagPoint, SerializedMetricSource, SerializedAttributeKeys, EditableField, Assignment, Assignments, FlagPointResult, ClientAssignments, RenderedExposure, DocId, PreviewPlacement, Attributes, ExposurePolicy, ExperimentKind, Status, UnitType, ArmKey, ArmKind, TargetingRule, Arm, ParamField, MetricSource, FlagPoint, RateLimiter, ExperimentsAccess, ExperimentsPluginOptions, ExperimentsPageCollection, ArmIssueCode, RefusalCode, ReadinessCode, ErrorEnvelope, TransitionSuccess, AllocateBody, AddMetricBody, DecideBody, ArchiveBody, MakeContentResult, DismissContentEntryBody, DismissContentEntryResult, RestoreContentEntryBody, RestoreContentEntryResult, ContentReport, PreflightResult, PreviewTokenResult, PhaseSummary, ResultsResponse, SummaryResponse, EventBody, FlagDefault, Manifest, ManifestExperiment, ArmSlot, ExperimentRef, ExperimentSlotProps, ExperimentsProxyRuntimeOptions, ExperimentsProxyRuntime, ExperimentsServerRuntimeOptions, ExperimentsServerRuntime, VerdictCode, Snapshot, MetricUnavailableReason, ContentReportReason, } from '../types/index.js';

package/dist/exports/puck.d.ts

@@ -1,4 +1,5 @@
-export { ExperimentSlot } from '../puck/ExperimentSlot.js';
+export { ExperimentSlot, createExperimentSlot } from '../puck/ExperimentSlot.js';
 export { createExperimentSlotField } from '../puck/experimentSlotField.js';
 export { EXPERIMENT_SLOT_TYPE } from '../types/puck.js';
 export type { ArmSlot, ExperimentRef, ExperimentSlotProps } from '../types/puck.js';
+export type { PuckRoutes } from '../puck/routes.js';

package/dist/exports/puck.js

@@ -1,3 +1,3 @@
-export { ExperimentSlot } from '../puck/ExperimentSlot.js';
+export { ExperimentSlot, createExperimentSlot } from '../puck/ExperimentSlot.js';
 export { createExperimentSlotField } from '../puck/experimentSlotField.js';
 export { EXPERIMENT_SLOT_TYPE } from '../types/puck.js';

package/dist/exports/puckEditor.d.ts

@@ -1,2 +1,4 @@
-export { ExperimentSlotEditor } from '../puck/editor/ExperimentSlotEditor.js';
+export { ExperimentSlotEditor, createExperimentSlotEditor } from '../puck/editor/ExperimentSlotEditor.js';
+export { experimentOutlinePlugin } from '../puck/editor/experimentOutlinePlugin.js';
 export { deriveAccent } from '../ui/accent.js';
+export type { PuckRoutes } from '../puck/routes.js';

package/dist/exports/puckEditor.js

@@ -1,3 +1,4 @@
 'use client';
-export { ExperimentSlotEditor } from '../puck/editor/ExperimentSlotEditor.js';
+export { ExperimentSlotEditor, createExperimentSlotEditor } from '../puck/editor/ExperimentSlotEditor.js';
+export { experimentOutlinePlugin } from '../puck/editor/experimentOutlinePlugin.js';
 export { deriveAccent } from '../ui/accent.js';

package/dist/exports/rsc.d.ts

@@ -6,6 +6,7 @@ export { linkIdentity, type LinkIdentityOutcome } from '../server/linkIdentity.j
 export { trackConversion } from '../server/trackConversion.js';
 export { eraseUser } from '../server/eraseUser.js';
 export type { MetricUnavailableReason, ContentReportReason } from '../types/reasons.js';
+export type { PreviewPlacement } from '../types/contracts.js';
 export { runResults } from '../server/runResults.js';
 export { recordContentChange } from '../server/recordContentChange.js';
 export { experimentSitemapFilter } from '../server/sitemap.js';

package/dist/hooks/pageGuard.js

@@ -1,5 +1,8 @@
 import { previousPublishedContent } from '../db/appends.js';
-import { XpRefusal } from '../errors.js';
+import { lockPagePaths } from '../db/locks.js';
+import { txExecutor } from '../db/executor.js';
+import { normalisePath } from '../runtime/normalisePath.js';
+import { XpNoTransactionError, XpRefusal } from '../errors.js';
 import { pageGuardCopy, READINESS_COPY } from '../admin/copy/readiness.js';
 // createLocalReq replaces context with a shallow copy on nested calls. Keep
 // the shared stack in that context so both the outer req and its proxies see it.
@@ -28,6 +31,19 @@ export const pageGuardAfterOperation = ({ req, collection, operation, result })=
     return result;
 };
 async function protect(req, path) {
+    // Serialise with Start (CORE-52 path locks, taken there after the experiment lock): a concurrent Start
+    // either commits first, so this check sees it, or waits and then sees this change. Raw SQL on the
+    // host's transaction; without one there is nothing to hold the lock for.
+    if (await req.transactionID != null) {
+        try {
+            await lockPagePaths(txExecutor(req), [
+                normalisePath(path)
+            ]);
+        } catch (error) {
+            // A request id without a database session (e.g. a transaction already killed) has no lock to take.
+            if (!(error instanceof XpNoTransactionError)) throw error;
+        }
+    }
     // page guard: the hook must see test placements regardless of the editor's access
     const tests = await req.payload.find({
         collection: 'xp-experiments',
@@ -81,8 +97,10 @@ async function protect(req, path) {
         }, 409);
         const arms = phase.arms;
         const protectedArms = archived ? arms.filter((arm)=>arm.kind === 'control' || arm.key === decision.winnerArm) : arms;
-        if (protectedArms.some((arm)=>arm.pageTarget === path)) {
-            throw new XpRefusal('locked-placement', pageGuardCopy(String(test.name), test.status), {
+        const matched = protectedArms.find((arm)=>arm.pageTarget !== undefined && normalisePath(arm.pageTarget) === normalisePath(path));
+        if (matched) {
+            const role = archived && matched.key !== decision.winnerArm ? 'original' : 'winner';
+            throw new XpRefusal('locked-placement', pageGuardCopy(String(test.name), test.status, role), {
                 experimentId: test.id
             }, 409);
         }

package/dist/lib/fetchAllDocs.d.ts

@@ -0,0 +1,16 @@
+export type DocsResult<T> = {
+    ok: true;
+    docs: T[];
+} | {
+    ok: false;
+    status: number;
+    body: unknown;
+    reason?: 'page-limit-exceeded';
+};
+/** A successful REST response did not contain a readable document list. */
+export declare class DocsResponseError extends Error {
+}
+/** Read every Payload REST page with the caller's credentials and cancellation. Transport,
+ * invalid successful responses and aborts throw; HTTP refusals retain their status/body. Keeps the first document per id; refuses
+ * incomplete lists after 1000 pages with page-limit-exceeded. */
+export declare function fetchAllDocs<T>(url: string, options?: Pick<RequestInit, 'credentials' | 'signal'>): Promise<DocsResult<T>>;