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

package/dist/transitions/preflightData.js

@@ -3,6 +3,8 @@ import { safeError } from '../log.js';
 import { powerMetricWeeks } from '@delmaredigital/experiments-stats';
 import { checkStart, relationshipId } from './checkStart.js';
 import { flagPlacements, scanBlockPlacements } from './placements.js';
+import { routedPageTests } from '../db/pageOccupancy.js';
+import { pooledExecutor, txExecutor } from '../db/executor.js';
 const failureDetail = (cause)=>{
     const name = cause instanceof Error ? cause.name : undefined;
     return cause instanceof Forbidden || name === 'Forbidden' ? 'forbidden' : cause instanceof NotFound || name === 'NotFound' ? 'not-found' : 'placements-failed';
@@ -28,6 +30,30 @@ const failureDetail = (cause)=>{
         experiment
     ])).get(String(experiment.id)) ?? 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 async function loadPageTestsInUse(req) {
+    return routedPageTests(await req.transactionID != null ? txExecutor(req) : pooledExecutor(req.payload));
+}
+/** 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 async function unpublishedPageTargets(req, options, experiment) {
+    const targets = await Promise.all(experiment.arms.filter((arm)=>arm.kind !== 'holdout' && arm.pageTarget?.trim()).map(async (arm)=>{
+        for (const collection of options.pages?.collections ?? []){
+            try {
+                const page = await collection.findByPath(arm.pageTarget, req);
+                if (page?.published === true) return null;
+            } catch (cause) {
+                req.payload.logger.error({
+                    err: safeError(cause),
+                    experimentId: experiment.id,
+                    collection: collection.slug,
+                    id: arm.pageTarget
+                }, 'Experiment page lookup failed');
+            }
+        }
+        return arm.pageTarget;
+    }));
+    return targets.filter((target)=>target !== null);
+}
 const metricIds = (experiment)=>[
         experiment.metrics?.primary,
         ...experiment.metrics?.secondary ?? [],
@@ -58,6 +84,7 @@ const metricIds = (experiment)=>[
     })();
     const blockSlugs = new Set(experiments.filter((e)=>e.kind === 'block').map((e)=>e.slug));
     // Lazy promises prevent unhandled rejections and share failed reads as well as successful ones.
+    let pageTestsInUse;
     let blocks;
     let state;
     const busyPoints = new Map();
@@ -84,27 +111,10 @@ const metricIds = (experiment)=>[
                 return failureDetail(cause);
             };
             if (experiment.kind === 'page') {
+                pageTestsInUse ??= loadPageTestsInUse(req);
+                input.pageTestsInUse = await pageTestsInUse;
                 input.pageTargetsUnchecked = options.pages === undefined;
-                if (options.pages) {
-                    input.unpublishedPageTargets = [];
-                    for (const arm of experiment.arms.filter((arm)=>arm.kind !== 'holdout' && arm.pageTarget?.trim())){
-                        let published = false;
-                        for (const collection of options.pages.collections){
-                            try {
-                                const page = await collection.findByPath(arm.pageTarget, req);
-                                if (page?.published === true) published = true;
-                            } catch (cause) {
-                                req.payload.logger.error({
-                                    err: safeError(cause),
-                                    experimentId: experiment.id,
-                                    collection: collection.slug,
-                                    id: arm.pageTarget
-                                }, 'Experiment page lookup failed');
-                            }
-                        }
-                        if (!published) input.unpublishedPageTargets.push(arm.pageTarget);
-                    }
-                }
+                if (options.pages) input.unpublishedPageTargets = await unpublishedPageTargets(req, options, experiment);
             }
             if (experiment.kind === 'block') {
                 try {
@@ -248,16 +258,23 @@ const metricIds = (experiment)=>[
     }
     return inputs;
 }
-function placementUrls(options, placement) {
+// Bound each optional host preview lookup so it cannot indefinitely hold preflight open.
+const PREVIEW_URL_TIMEOUT_MS = 2000;
+// Resolve host preview lookups in a bounded pool instead of launching one per slot.
+const PREVIEW_URL_CONCURRENCY = 8;
+async function placementUrls(options, placement, pendingPreviews, onFailure, previews) {
     const result = {};
     const { collection, id, published } = placement;
-    try {
-        const url = options.admin?.previewUrl?.({
-            collection,
-            id
-        });
-        if (typeof url === 'string') result.url = url;
-    } catch  {}
+    // One host lookup per page version: several slots on a page share it.
+    const key = JSON.stringify([
+        collection,
+        String(id),
+        published
+    ]);
+    let preview = previews.get(key);
+    if (!preview) previews.set(key, preview = previewLookup(options, placement, pendingPreviews, onFailure));
+    const url = await preview;
+    if (url !== undefined) result.url = url;
     try {
         const url = options.admin?.editorUrl?.({
             collection,
@@ -268,6 +285,43 @@ function placementUrls(options, placement) {
     } catch  {}
     return result;
 }
+async function previewLookup(options, placement, pendingPreviews, onFailure) {
+    const { collection, id, title, published, slug } = placement;
+    const previewUrl = options.admin?.previewUrl;
+    let found;
+    if (previewUrl) {
+        let timer;
+        try {
+            if (pendingPreviews.count >= PREVIEW_URL_CONCURRENCY) throw new Error('Preview URL lookups at capacity');
+            pendingPreviews.count++;
+            // A timeout cannot cancel host work: retain its permit until that work settles.
+            const lookup = Promise.resolve().then(()=>previewUrl({
+                    collection,
+                    id,
+                    title,
+                    published,
+                    ...slug !== undefined ? {
+                        slug
+                    } : {}
+                })).finally(()=>{
+                pendingPreviews.count--;
+            });
+            const url = await Promise.race([
+                lookup,
+                new Promise((_, reject)=>{
+                    timer = setTimeout(()=>reject(new Error('Preview URL lookup timed out')), PREVIEW_URL_TIMEOUT_MS);
+                })
+            ]);
+            if (typeof url === 'string') found = url;
+            else if (url !== null && url !== undefined) throw new TypeError('Invalid preview URL result');
+        } catch (cause) {
+            onFailure(cause, placement);
+        } finally{
+            clearTimeout(timer);
+        }
+    }
+    return found;
+}
 async function primaryHistory(source, now) {
     if (!source) return null;
     const from = new Date(now.getTime() - 28 * 86400000);
@@ -378,15 +432,41 @@ export async function preflightData(req, { experimentId, options }, { now = new
         }
     }
     const requiredSlots = e.arms.filter((arm)=>arm.kind !== 'holdout').map((arm)=>arm.slot);
-    const placements = (input.placements ?? []).map((placement)=>({
+    const blocks = input.placements ?? [];
+    const placements = new Array(blocks.length);
+    let nextPlacement = 0;
+    const pendingPreviews = {
+        count: 0
+    };
+    const previews = new Map();
+    let loggedPreviewFailure = false;
+    const onPreviewFailure = (cause, placement)=>{
+        if (loggedPreviewFailure) return;
+        loggedPreviewFailure = true;
+        req.payload.logger.warn({
+            err: safeError(cause),
+            experimentId: e.id,
             collection: placement.collection,
-            id: placement.id,
-            title: placement.title,
-            slots: placement.slots,
-            ...placementUrls(options, placement),
-            ok: requiredSlots.every((slot)=>slot && placement.slots[slot] > 0),
-            detail: placement.published ? 'Published' : 'Draft'
-        }));
+            id: placement.id
+        }, 'Experiment preview URL lookup failed');
+    };
+    await Promise.all(Array.from({
+        length: Math.min(PREVIEW_URL_CONCURRENCY, blocks.length)
+    }, async ()=>{
+        while(nextPlacement < blocks.length){
+            const index = nextPlacement++;
+            const placement = blocks[index];
+            placements[index] = {
+                collection: placement.collection,
+                id: placement.id,
+                title: placement.title,
+                slots: placement.slots,
+                ...await placementUrls(options, placement, pendingPreviews, onPreviewFailure, previews),
+                ok: requiredSlots.every((slot)=>slot && placement.slots[slot] > 0),
+                detail: placement.published ? 'Published' : 'Draft'
+            };
+        }
+    }));
     for (const placement of input.flagPlacements ?? [])placements.push({
         collection: e.flagPoint ?? '',
         id: placement.arm,

package/dist/transitions/start.js

@@ -1,14 +1,15 @@
+import { lockPagePaths } from '../db/locks.js';
 import { lockMetricsForFreeze } from '../db/metricUsage.js';
 import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
 import { claimSlices } from '../db/slices.js';
-import { unpublishedPageCopy } from '../admin/copy/readiness.js';
+import { pageInUseCopy, unpublishedPageCopy } from '../admin/copy/readiness.js';
 import { XpRefusal } from '../errors.js';
 import { isOpValid } from '../targeting/ops.js';
 import { newSeed } from '../runtime/seed.js';
-import { checkStart, relationshipId } from './checkStart.js';
+import { checkStart, pageTargetPaths, relationshipId } from './checkStart.js';
 import { withTransition } from './kernel.js';
 import { writePhaseRecord } from './phaseRecord.js';
-import { loadStartInputs } from './preflightData.js';
+import { loadPageTestsInUse, loadStartInputs, unpublishedPageTargets } from './preflightData.js';
 import { resolveCaps } from './resolveCaps.js';
 export async function readExperiment(req, id) {
     // §7.8: internal lookup serves the authorised transition write. Preserve
@@ -30,6 +31,7 @@ export async function readExperiment(req, id) {
 }
 export function refuse(code, detail) {
     const messages = {
+        'page-in-use': pageInUseCopy(detail?.paths?.[0] ?? 'this page'),
         'page-target-unpublished': unpublishedPageCopy(typeof detail === 'string' ? detail : 'This page'),
         'invalid-status': 'This action is not available in the current status.',
         'stale-draft': 'The experiment changed. Review it again before starting.',
@@ -46,6 +48,7 @@ export function refuse(code, detail) {
     const conflict = [
         'invalid-status',
         'stale-draft',
+        'page-in-use',
         'flag-point-busy',
         'layer-full',
         'allocation-lower',
@@ -107,6 +110,33 @@ export async function start(req, { experimentId, options }) {
         const current = await readExperiment(req, experimentId);
         if (current.updatedAt !== updatedAt) refuse('stale-draft');
         if (current.status !== 'draft' && current.status !== 'stopped') refuse('invalid-status');
+        if (current.kind === 'page') {
+            // Independent experiment/layer locks do not serialize overlapping pages.
+            // Re-read occupancy after acquiring sorted path locks; hold through commit.
+            // A waiting Start then sees the first Start's live test on this transaction.
+            await lockPagePaths(exec, pageTargetPaths(current.arms));
+            const recheck = checkStart({
+                ...input,
+                experiment: current,
+                pageTestsInUse: await loadPageTestsInUse(req)
+            }).find((check)=>check.code === 'page-in-use' && !check.ok);
+            if (recheck) refuse('page-in-use', recheck.detail);
+            if (options.pages) {
+                // The page guard takes the same path locks, so a delete, unpublish or rename that committed
+                // while Start waited is visible now. Read it on a detached request (committed state, outside
+                // this transaction): a refused host read must not kill the transition (CORE-21).
+                // (the make-content pattern: drop the transaction id for the reads, restore it after).
+                const transactionID = req.transactionID;
+                delete req.transactionID;
+                let unpublished;
+                try {
+                    unpublished = await unpublishedPageTargets(req, options, current);
+                } finally{
+                    req.transactionID = transactionID;
+                }
+                if (unpublished.length) refuse('page-target-unpublished', unpublished[0]);
+            }
+        }
         if (current.kind === 'flag' && current.flagPoint) {
             const busy = await req.payload.find({
                 collection: 'xp-experiments',

package/dist/types/contracts.d.ts

@@ -3,6 +3,14 @@ import type { ExperimentsServerRuntime } from './runtime.js';
 import type { ArmSlot } from './puck.js';
 import type { TargetingOp } from '../targeting/ops.js';
 export type DocId = string | number;
+export interface PreviewPlacement {
+    collection: string;
+    id: DocId;
+    title: string;
+    published: boolean;
+    /** The published main row's string slug, including on draft placements; absent for unpublished documents, never a draft/version row's slug. */
+    slug?: string;
+}
 export type Attributes = Record<string, string | number | boolean>;
 export type ExposurePolicy = 'render' | 'viewport' | 'pageview' | 'manual';
 export type ExperimentKind = 'block' | 'page' | 'flag' | 'code';
@@ -93,6 +101,15 @@ export type RateLimiter = (args: {
 export type ExperimentsAccess = (args: {
     req: PayloadRequest;
 }) => boolean | Promise<boolean>;
+export interface ExperimentsPageCollection {
+    slug: string;
+    pathOf: (doc: Record<string, unknown>) => string | null;
+    /** Lookup with the supplied req and overrideAccess: false. Under an anonymous req (results checks) only published pages are visible, so a hit is { published: true } or null. Under a req that can read drafts (Start), a draft-only page may be reported as { published: false }. */
+    findByPath: (path: string, req: PayloadRequest) => Promise<{
+        id: string | number;
+        published: boolean;
+    } | null>;
+}
 export interface ExperimentsPluginOptions<TUser extends {
     id: string | number;
 } = {
@@ -114,10 +131,7 @@ export interface ExperimentsPluginOptions<TUser extends {
             id: DocId;
             draft?: boolean;
         }) => string;
-        previewUrl?: (args: {
-            collection: string;
-            id: DocId;
-        }) => string;
+        previewUrl?: (placement: PreviewPlacement) => string | null | undefined | Promise<string | null | undefined>;
         descriptions?: {
             block?: string;
             document?: string;
@@ -135,15 +149,7 @@ export interface ExperimentsPluginOptions<TUser extends {
         values?: string[];
     }>;
     pages?: {
-        collections: Array<{
-            slug: string;
-            pathOf: (doc: Record<string, unknown>) => string | null;
-            /** Published-only lookup using the supplied req and overrideAccess: false. Results checks supply an anonymous req. */
-            findByPath: (path: string, req: PayloadRequest) => Promise<{
-                id: string | number;
-                published: boolean;
-            } | null>;
-        }>;
+        collections: ExperimentsPageCollection[];
     };
     puck?: {
         enabled: boolean;

package/dist/types/endpoints.d.ts

@@ -7,7 +7,7 @@ import type { Snapshot, VerdictCode } from './snapshot.js';
 export type ArmIssueCode = 'weights-total' | 'control-count' | 'control-first' | 'holdout-last' | 'holdout-count' | 'variant-count' | 'duplicate-key' | 'duplicate-slot' | 'slot-required' | 'invalid-key';
 /** Content-report dismiss/restore refusals (CORE-44). */
 export type ContentEntryRefusal = 'not-decided' | 'entry-not-found' | 'entry-ok' | 'entry-dismissed' | 'entry-not-dismissed';
-export type RefusalCode = ArmIssueCode | 'not-found' | ContentEntryRefusal | 'no-planned-duration' | 'no-primary-metric' | 'no-placements' | 'empty-slot' | 'page-no-targets' | 'page-target-unpublished' | 'page-user-unit' | 'version-page-unavailable' | 'version-page-unchecked' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'layer-full' | 'layer-unit-mismatch' | 'unknown-metric-source' | 'unit-source-mismatch' | 'no-reach-per-day' | 'invalid-status' | 'stale-draft' | 'stale-edit' | 'commit-unverified' | 'allocation-lower' | 'confirmation-required' | 'invalid-winner' | 'slices-taken' | 'locked-placement' | 'not-implemented' | 'forbidden' | 'unauthenticated' | 'body-too-large' | 'invalid-body' | 'too-many-ids' | 'invalid-phase' | 'invalid-ids' | 'recompute-failed' | 'analysis-failed' | 'undeclared-targeting-key' | 'invalid-targeting-rule' | 'block-path-rule' | 'duplicate-metric';
+export type RefusalCode = ArmIssueCode | 'not-found' | ContentEntryRefusal | 'no-planned-duration' | 'no-primary-metric' | 'no-placements' | 'empty-slot' | 'page-in-use' | 'page-no-targets' | 'page-target-unpublished' | 'page-user-unit' | 'version-page-unavailable' | 'version-page-unchecked' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'layer-full' | 'layer-unit-mismatch' | 'unknown-metric-source' | 'unit-source-mismatch' | 'no-reach-per-day' | 'invalid-status' | 'stale-draft' | 'stale-edit' | 'commit-unverified' | 'allocation-lower' | 'confirmation-required' | 'invalid-winner' | 'slices-taken' | 'locked-placement' | 'not-implemented' | 'forbidden' | 'unauthenticated' | 'body-too-large' | 'invalid-body' | 'too-many-ids' | 'invalid-phase' | 'invalid-ids' | 'recompute-failed' | 'analysis-failed' | 'undeclared-targeting-key' | 'invalid-targeting-rule' | 'block-path-rule' | 'duplicate-metric';
 export type ErrorEnvelope = {
     errors: Array<{
         code: RefusalCode;

package/dist/ui/Tabs.d.ts

@@ -1,14 +1,16 @@
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
 import './ui.css';
 export interface Tab {
     id: string;
     label: string;
     content: ReactNode;
+    actions?: ReactNode;
     disabled?: boolean;
 }
-export declare function Tabs({ items, label, value, onChange }: {
+export declare function Tabs({ items, label, value, onChange, tabListRef }: {
     items: Tab[];
     label: string;
     value?: string;
     onChange?: (id: string) => void;
+    tabListRef?: Ref<HTMLDivElement>;
 }): import("react").JSX.Element;

package/dist/ui/Tabs.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useId, useState } from 'react';
 import './ui.css';
-export function Tabs({ items, label, value, onChange }) {
+export function Tabs({ items, label, value, onChange, tabListRef }) {
     const prefix = useId();
     const [local, setLocal] = useState(()=>items.find((item)=>!item.disabled)?.id);
     const requested = value ?? local;
@@ -14,31 +14,38 @@ export function Tabs({ items, label, value, onChange }) {
     return /*#__PURE__*/ _jsxs("div", {
         className: "xp-ui-tabs",
         children: [
-            /*#__PURE__*/ _jsx("div", {
-                role: "tablist",
-                "aria-label": label,
-                className: "xp-ui-tablist",
-                children: items.map((item)=>/*#__PURE__*/ _jsx("button", {
-                        type: "button",
-                        role: "tab",
-                        id: `${prefix}-tab-${item.id}`,
-                        "aria-controls": `${prefix}-panel-${item.id}`,
-                        "aria-selected": selected === item.id,
-                        tabIndex: selected === item.id ? 0 : -1,
-                        disabled: item.disabled,
-                        className: "xp-ui-tab",
-                        onClick: ()=>select(item.id),
-                        onKeyDown: (event)=>{
-                            const enabled = items.filter((tab)=>!tab.disabled);
-                            const index = enabled.findIndex((tab)=>tab.id === item.id);
-                            const next = event.key === 'ArrowRight' ? enabled[(index + 1) % enabled.length] : event.key === 'ArrowLeft' ? enabled[(index - 1 + enabled.length) % enabled.length] : event.key === 'Home' ? enabled[0] : event.key === 'End' ? enabled.at(-1) : undefined;
-                            if (!next) return;
-                            event.preventDefault();
-                            select(next.id);
-                            event.currentTarget.ownerDocument.getElementById(`${prefix}-tab-${next.id}`)?.focus();
-                        },
-                        children: item.label
-                    }, item.id))
+            /*#__PURE__*/ _jsxs("div", {
+                ref: tabListRef,
+                className: "xp-ui-tabs-header",
+                children: [
+                    /*#__PURE__*/ _jsx("div", {
+                        role: "tablist",
+                        "aria-label": label,
+                        className: "xp-ui-tablist",
+                        children: items.map((item)=>/*#__PURE__*/ _jsx("button", {
+                                type: "button",
+                                role: "tab",
+                                id: `${prefix}-tab-${item.id}`,
+                                "aria-controls": `${prefix}-panel-${item.id}`,
+                                "aria-selected": selected === item.id,
+                                tabIndex: selected === item.id ? 0 : -1,
+                                disabled: item.disabled,
+                                className: "xp-ui-tab",
+                                onClick: ()=>select(item.id),
+                                onKeyDown: (event)=>{
+                                    const enabled = items.filter((tab)=>!tab.disabled);
+                                    const index = enabled.findIndex((tab)=>tab.id === item.id);
+                                    const next = event.key === 'ArrowRight' ? enabled[(index + 1) % enabled.length] : event.key === 'ArrowLeft' ? enabled[(index - 1 + enabled.length) % enabled.length] : event.key === 'Home' ? enabled[0] : event.key === 'End' ? enabled.at(-1) : undefined;
+                                    if (!next) return;
+                                    event.preventDefault();
+                                    select(next.id);
+                                    event.currentTarget.ownerDocument.getElementById(`${prefix}-tab-${next.id}`)?.focus();
+                                },
+                                children: item.label
+                            }, item.id))
+                    }),
+                    items.find((item)=>item.id === selected)?.actions
+                ]
             }),
             items.map((item)=>/*#__PURE__*/ _jsx("div", {
                     role: "tabpanel",

package/dist/ui/accent.d.ts

@@ -10,12 +10,31 @@ export interface AccentSet {
 }
 /** WCAG 2.x relative luminance contrast. */
 export declare function contrast(a: string, b: string): number;
-/** Pure shared host-accent derivation. Reference surfaces match theme.css's Payload
- * 3.90.2 white / elevation-50 dark. Dark adjustment increases HSL lightness until
- * the quantised hex reaches 3:1. Hover/active move up to 12/24% in the interaction direction, clamped to preserve text contrast; subtle is 8% tint. */
+/** Contrast floors for accent text and focus rings. Black or white always clears them on a real
+ * surface, so the fallbacks below are defensive; tests raise the floors to exercise them. */
+type Floors = {
+    text: number;
+    focus: number;
+};
+/** Pure shared host-accent derivation using theme.css's reference surfaces. */
 export declare function deriveAccent(input: string): {
     light: AccentSet;
     dark: AccentSet;
 };
+/** Module-only surface injection; not a package API. Dark adjustment raises HSL
+ * lightness to 3:1. Interaction steps preserve the foreground and prefer the
+ * original direction when both steps reach 1.1:1; subtle remains an 8% tint. */
+export declare function deriveAccentFor(input: string, surfaces: {
+    light: string;
+    dark: string;
+}, floors?: Floors): {
+    light: AccentSet;
+    dark: AccentSet;
+};
 /** Validated hex values only; specificity exceeds theme.css regardless of load order. */
 export declare function accentStyles(input?: string): string | undefined;
+/** The plugin and Puck factory accept exactly the same host accent. */
+export declare function validateAccent(accent: unknown): void;
+/** Inline variables use the same names as the admin accent stylesheet. */
+export declare function accentVariables(set: AccentSet): Record<string, string>;
+export {};

package/dist/ui/accent.js

@@ -38,11 +38,8 @@ function mix(a, b, amount) {
     }
     return undefined;
 }
-function set(accent, surface, dark = false) {
-    const fg = contrast(accent, '#ffffff') >= contrast(accent, '#141414') ? '#ffffff' : '#141414';
-    // Light fills with dark text lighten on interaction. Dark-theme fills follow
-    // the default dark tokens and also lighten. Clamp to preserve one foreground.
-    const target = dark || fg === '#141414' ? '#ffffff' : '#000000';
+const interactionStep = (accent, states)=>Math.min(contrast(accent, states.hover), contrast(states.hover, states.active));
+/** Keep the old 12/24% steps when visible, otherwise search the full direction. */ function interaction(accent, fg, target) {
     let low = 0, high = 0.24;
     for(let i = 0; i < 24; i++){
         const amount = (low + high) / 2;
@@ -50,32 +47,93 @@ function set(accent, surface, dark = false) {
         else high = amount;
     }
     const amount = contrast(mix(accent, target, 0.24), fg) >= 4.5 ? 0.24 : low;
-    const accentText = againstSurface(accent, surface, 4.5);
+    const original = {
+        hover: mix(accent, target, amount / 2),
+        active: mix(accent, target, amount)
+    };
+    if (interactionStep(accent, original) >= 1.1) return original;
+    const candidates = [
+        accent
+    ];
+    let hover;
+    for(let step = 1; step <= 1000; step++){
+        const candidate = mix(accent, target, step / 1000);
+        if (contrast(candidate, fg) < 4.5) break;
+        candidates.push(candidate);
+        if (!hover && contrast(accent, candidate) >= 1.1) hover = candidate;
+        else if (hover && contrast(hover, candidate) >= 1.1) return {
+            hover,
+            active: candidate
+        };
+    }
+    // If two full steps cannot fit, maximise the smaller step to the last safe fill.
+    const active = candidates[candidates.length - 1];
+    return candidates.reduce((best, candidate)=>{
+        const next = {
+            hover: candidate,
+            active
+        };
+        return interactionStep(accent, next) > interactionStep(accent, best) ? next : best;
+    }, {
+        hover: accent,
+        active
+    });
+}
+const FLOORS = {
+    text: 4.5,
+    focus: 3
+};
+function set(accent, surface, dark = false, floors = FLOORS) {
+    const fg = contrast(accent, '#ffffff') >= contrast(accent, '#141414') ? '#ffffff' : '#141414';
+    const target = dark || fg === '#141414' ? '#ffffff' : '#000000';
+    const preferred = interaction(accent, fg, target);
+    const other = interaction(accent, fg, target === '#ffffff' ? '#000000' : '#ffffff');
+    const states = interactionStep(accent, preferred) >= 1.1 || interactionStep(accent, preferred) >= interactionStep(accent, other) ? preferred : other;
+    const accentText = againstSurface(accent, surface, floors.text);
     return {
         accent,
-        hover: mix(accent, target, amount / 2),
-        active: mix(accent, target, amount),
+        ...states,
         subtle: mix(surface, accent, 0.08),
         fg,
-        focus: againstSurface(accent, surface, 3) ?? 'var(--xp-text)',
+        focus: againstSurface(accent, surface, floors.focus) ?? 'var(--xp-text)',
         accentText: accentText ?? 'var(--xp-text)',
         accentTextDecoration: accentText ? 'none' : 'underline'
     };
 }
-/** Pure shared host-accent derivation. Reference surfaces match theme.css's Payload
- * 3.90.2 white / elevation-50 dark. Dark adjustment increases HSL lightness until
- * the quantised hex reaches 3:1. Hover/active move up to 12/24% in the interaction direction, clamped to preserve text contrast; subtle is 8% tint. */ export function deriveAccent(input) {
+/** Pure shared host-accent derivation using theme.css's reference surfaces. */ export function deriveAccent(input) {
+    return deriveAccentFor(input, {
+        light: '#ffffff',
+        dark: '#222222'
+    });
+}
+/** Module-only surface injection; not a package API. Dark adjustment raises HSL
+ * lightness to 3:1. Interaction steps preserve the foreground and prefer the
+ * original direction when both steps reach 1.1:1; subtle remains an 8% tint. */ export function deriveAccentFor(input, surfaces, floors = FLOORS) {
     const accent = hexOf(rgb(input));
     let dark = accent;
-    for(let step = 1; contrast(dark, '#222222') < 3 && step <= 1000; step++)dark = lighten(accent, step / 1000);
+    for(let step = 1; contrast(dark, surfaces.dark) < 3 && step <= 1000; step++)dark = lighten(accent, step / 1000);
     return {
-        light: set(accent, '#ffffff'),
-        dark: set(dark, '#222222', true)
+        light: set(accent, surfaces.light, false, floors),
+        dark: set(dark, surfaces.dark, true, floors)
     };
 }
 /** Validated hex values only; specificity exceeds theme.css regardless of load order. */ export function accentStyles(input) {
     if (!input) return undefined;
     const sets = deriveAccent(input);
-    const declarations = (s)=>Object.entries(s).map(([name, value])=>`--xp-${name === 'accentText' ? 'accent-text' : name === 'accentTextDecoration' ? 'accent-text-decoration' : name === 'focus' || name === 'accent' ? name : `accent-${name}`}:${value};`).join('');
+    const declarations = (s)=>Object.entries(accentVariables(s)).map(([name, value])=>`${name}:${value};`).join('');
     return `:root:root, [data-theme="light"][data-theme="light"]{${declarations(sets.light)}}\n[data-theme="dark"][data-theme="dark"]{${declarations(sets.dark)}}`;
 }
+/** The plugin and Puck factory accept exactly the same host accent. */ export function validateAccent(accent) {
+    if (accent === undefined || accent === '') return;
+    if (typeof accent !== 'string' || !/^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(accent)) throw new Error('Experiments theme.accent must be a CSS hex colour (#rgb or #rrggbb)');
+    for (const [mode, set] of Object.entries(deriveAccent(accent))){
+        const ratio = contrast(set.accent, set.fg);
+        if (ratio < 4.5) throw new Error(`Experiments theme.accent ${accent}: ${mode} foreground contrast ${ratio.toFixed(2)}:1 is below 4.5:1`);
+    }
+}
+/** Inline variables use the same names as the admin accent stylesheet. */ export function accentVariables(set) {
+    return Object.fromEntries(Object.entries(set).map(([name, value])=>[
+            `--xp-${name === 'accentText' ? 'accent-text' : name === 'accentTextDecoration' ? 'accent-text-decoration' : name === 'focus' || name === 'accent' ? name : `accent-${name}`}`,
+            value
+        ]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-experiments",
-  "version": "0.3.0-rc.1",
+  "version": "0.3.0-rc.4",
   "description": "No-code A/B testing for Payload CMS and Next.js: block, page and flag experiments with holdouts, layers, exposure logging and honest statistics inside the admin — no vendor",
   "type": "module",
   "license": "MIT",
@@ -68,6 +68,8 @@
       "default": "./dist/exports/puckEditor.js"
     },
     "./puck/editor.css": "./dist/puck/editor/editor.css",
+    "./admin/theme.css": "./dist/admin/theme.css",
+    "./admin/ui.css": "./dist/ui/ui.css",
     "./package.json": "./package.json"
   },
   "files": [
@@ -135,7 +137,8 @@
     "@electric-sql/pglite": "^0.5.13",
     "@puckeditor/core": "^0.24.0",
     "drizzle-orm": "0.45.2",
-    "drizzle-kit": "0.31.7"
+    "drizzle-kit": "0.31.7",
+    "yaml": "2.9.1"
   },
   "scripts": {
     "build": "swc ./src -d ./dist --strip-leading-paths --config-file ../../.swcrc && tsc -p tsconfig.build.json && copyfiles -u 1 \"src/**/*.css\" dist",