@delmaredigital/payload-experiments 0.3.0-rc.4 → 0.4.0-rc.2

package/dist/goals/picker/useClickGoalPicker.js

@@ -0,0 +1,220 @@
+'use client';
+import { useEffect, useRef, useState } from 'react';
+import { fetchAllDocs } from '../../lib/fetchAllDocs.js';
+import { CLICK_KEY } from '../key.js';
+import { clickGoalBody, clickGoalCreateError, clickGoalSlug, definedClickGoals, undefinedClickKey } from './clickGoalPicker.model.js';
+const goalLists = new Map();
+function publish(list, state) {
+    // A read may finish after its last row unmounts and a new list has started.
+    if (!list.listeners.length || goalLists.get(state.api) !== list) return;
+    list.state = state;
+    list.listeners.forEach((listener)=>listener(state));
+}
+/** Mounted rows at the same API base share the in-flight read and its result. */ function loadGoals(api) {
+    const cached = goalLists.get(api);
+    if (cached && (cached.state.status === 'loading' || cached.state.status === 'ready')) return cached;
+    const list = cached ?? {
+        state: {
+            api,
+            status: 'loading',
+            goals: []
+        },
+        listeners: []
+    };
+    if (cached) publish(list, {
+        api,
+        status: 'loading',
+        goals: []
+    });
+    goalLists.set(api, list);
+    void (async ()=>{
+        try {
+            const result = await fetchAllDocs(`${api}/xp-metrics?where[source][like]=click:&depth=0`, {
+                credentials: 'include'
+            });
+            if (result.ok) {
+                publish(list, {
+                    api,
+                    status: 'ready',
+                    goals: definedClickGoals(result.docs)
+                });
+                return;
+            }
+            publish(list, {
+                api,
+                status: result.status === 403 ? 'not-manager' : 'error',
+                goals: []
+            });
+        } catch  {
+            publish(list, {
+                api,
+                status: 'error',
+                goals: []
+            });
+        }
+    })();
+    return list;
+}
+const emptyPanel = ()=>({
+        open: false,
+        name: '',
+        slug: '',
+        slugEdited: false,
+        advanced: false,
+        pending: false,
+        errors: {}
+    });
+/** UI-free state shared by the two editor hosts. A refused read silently removes management. */ export function useClickGoalPicker(apiRoute, { enabled = true, onSelect }) {
+    const api = apiRoute.replace(/\/$/, '');
+    const [loaded, setLoaded] = useState({
+        api,
+        status: 'loading',
+        goals: []
+    });
+    const [panel, setPanel] = useState(emptyPanel);
+    const flight = useRef(false);
+    const binding = useRef({
+        api,
+        enabled,
+        live: true,
+        onSelect
+    });
+    binding.current.api = api;
+    binding.current.enabled = enabled;
+    binding.current.onSelect = onSelect;
+    useEffect(()=>{
+        binding.current.live = true;
+        return ()=>{
+            binding.current.live = false;
+        };
+    }, []);
+    useEffect(()=>{
+        if (!enabled) return;
+        setPanel(emptyPanel());
+        const list = loadGoals(api);
+        setLoaded(list.state);
+        list.listeners.push(setLoaded);
+        return ()=>{
+            list.listeners = list.listeners.filter((listener)=>listener !== setLoaded);
+            if (!list.listeners.length && goalLists.get(api) === list) goalLists.delete(api);
+        };
+    }, [
+        api,
+        enabled
+    ]);
+    const status = !enabled ? 'not-manager' : loaded.api === api ? loaded.status : 'loading';
+    const goals = status === 'ready' ? loaded.goals : [];
+    const canManage = status === 'ready';
+    async function create() {
+        if (!canManage || !panel.open || flight.current || !panel.name.trim()) return;
+        if (!CLICK_KEY.test(panel.slug)) {
+            setPanel((current)=>({
+                    ...current,
+                    advanced: true,
+                    errors: clickGoalCreateError(panel.slug)
+                }));
+            return;
+        }
+        flight.current = true;
+        setPanel((current)=>({
+                ...current,
+                pending: true,
+                errors: {}
+            }));
+        const current = ()=>binding.current.live && binding.current.enabled && binding.current.api === api;
+        try {
+            const response = await fetch(`${api}/xp-metrics`, {
+                method: 'POST',
+                credentials: 'include',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify(clickGoalBody(panel.name, panel.slug))
+            });
+            const body = await response.json().catch(()=>undefined);
+            if (!response.ok) {
+                if (!current()) return;
+                if (response.status === 403) {
+                    setLoaded({
+                        api,
+                        status: 'not-manager',
+                        goals: []
+                    });
+                    setPanel(emptyPanel());
+                    return;
+                }
+                const errors = clickGoalCreateError(panel.slug, body);
+                setPanel((value)=>({
+                        ...value,
+                        pending: false,
+                        advanced: value.advanced || Boolean(errors.slug),
+                        errors
+                    }));
+                return;
+            }
+            const doc = body?.doc;
+            if (!doc || typeof doc.slug !== 'string' || typeof doc.name !== 'string' || !isFiniteId(doc.id)) throw new Error('response');
+            const list = goalLists.get(api);
+            if (list) publish(list, {
+                api,
+                status: 'ready',
+                goals: [
+                    ...list.state.goals.filter((goal)=>goal.id !== doc.id),
+                    doc
+                ]
+            });
+            if (!current()) return;
+            binding.current.onSelect(doc.slug);
+            setPanel(emptyPanel());
+        } catch  {
+            if (current()) setPanel((value)=>({
+                    ...value,
+                    pending: false,
+                    errors: clickGoalCreateError(panel.slug)
+                }));
+        } finally{
+            flight.current = false;
+        }
+    }
+    return {
+        status,
+        goals,
+        canManage,
+        undefinedKey: (value)=>undefinedClickKey(status, goals, value),
+        panel,
+        open: ()=>{
+            if (canManage) setPanel({
+                ...emptyPanel(),
+                open: true
+            });
+        },
+        cancel: ()=>{
+            if (!flight.current) setPanel(emptyPanel());
+        },
+        setName: (name)=>setPanel((value)=>{
+                const slug = value.slugEdited ? value.slug : clickGoalSlug(name);
+                const invalid = !value.slugEdited && !CLICK_KEY.test(slug);
+                return {
+                    ...value,
+                    name,
+                    slug,
+                    advanced: value.advanced || invalid,
+                    errors: invalid ? clickGoalCreateError(slug) : {}
+                };
+            }),
+        setSlug: (slug)=>setPanel((value)=>({
+                    ...value,
+                    slug,
+                    slugEdited: true,
+                    errors: {}
+                })),
+        setAdvanced: (advanced)=>setPanel((value)=>({
+                    ...value,
+                    advanced
+                })),
+        create
+    };
+}
+function isFiniteId(id) {
+    return typeof id === 'string' || typeof id === 'number' && Number.isFinite(id);
+}

package/dist/goals/validate.d.ts

@@ -0,0 +1,3 @@
+import type { PayloadRequest } from 'payload';
+/** Shared publish validation for Payload fields and Puck JSON props. */
+export declare function validateClickGoal(value: string | null | undefined, req: PayloadRequest): Promise<true | string>;

package/dist/goals/validate.js

@@ -0,0 +1,14 @@
+import { definedClickKeys } from '../db/clickGoals.js';
+import { pooledExecutor } from '../db/executor.js';
+import { clickKeys } from './cache.js';
+import { CLICK_KEY } from './key.js';
+/** Shared publish validation for Payload fields and Puck JSON props. */ export async function validateClickGoal(value, req) {
+    if (!value) return true;
+    if (!CLICK_KEY.test(value)) return 'Use a click goal short name.';
+    const options = req.payload.config.custom?.xp;
+    if (!options || await options.access.manage({
+        req
+    }) !== true) return true;
+    const keys = await clickKeys(req.payload);
+    return !keys || keys.has(value) || (await definedClickKeys(pooledExecutor(req.payload))).has(value) || 'No click goal has this name yet. Create it with "+ New click goal".';
+}

package/dist/hooks/pageGuard.d.ts

@@ -1,5 +1,9 @@
-import type { CollectionAfterOperationHook, CollectionBeforeChangeHook, CollectionBeforeDeleteHook, CollectionBeforeOperationHook } from 'payload';
+import type { CollectionAfterChangeHook, CollectionAfterOperationHook, CollectionBeforeChangeHook, CollectionBeforeDeleteHook, CollectionBeforeOperationHook } from 'payload';
+import { type PlacementTest } from '../db/placements.js';
 export declare const pageGuardBeforeOperation: CollectionBeforeOperationHook;
 export declare const pageGuardAfterOperation: CollectionAfterOperationHook;
+export declare function guardExperimentIds(tests: readonly PlacementTest[], slugs: readonly string[], collection: string, paths: readonly string[], held: unknown, tags?: Set<string>): string[];
 export declare const pageGuardBeforeDelete: CollectionBeforeDeleteHook;
 export declare const pageGuardBeforeChange: CollectionBeforeChangeHook;
+/** Unwrapped: these writes must fail the publish closed, unlike the best-effort audit. */
+export declare const pageGuardAfterChange: CollectionAfterChangeHook;

package/dist/hooks/pageGuard.js

@@ -1,14 +1,18 @@
-import { previousPublishedContent } from '../db/appends.js';
-import { lockPagePaths } from '../db/locks.js';
-import { txExecutor } from '../db/executor.js';
+import { previousPublishedContent, storedContent } from '../db/appends.js';
+import { lockPlacementScope, sortLockKeys } from '../db/locks.js';
+import { txExecutor, pooledExecutor } 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';
+import { placementGuardCopy, pageGuardCopy, READINESS_COPY } from '../admin/copy/readiness.js';
+import { placementSlugs } from '../blocks/bindings.js';
+import { isObject } from '../blocks/model.js';
+import { placementTests, appendPlacementDoc } from '../db/placements.js';
+import { isPageBusy } from '../db/pageBusy.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.
 const operations = (req)=>req.context.xpPageGuardOperations;
 export const pageGuardBeforeOperation = ({ args, operation })=>{
-    if (operation !== 'update' && operation !== 'restoreVersion') return;
+    if (operation !== 'create' && operation !== 'update' && operation !== 'restoreVersion') return;
     const call = args;
     let collections = operations(call.req);
     if (!collections) call.req.context.xpPageGuardOperations = collections = new Map();
@@ -22,7 +26,7 @@ export const pageGuardBeforeOperation = ({ args, operation })=>{
 };
 export const pageGuardAfterOperation = ({ req, collection, operation, result })=>{
     // beforeOperation reports by-id updates as 'update'; afterOperation reports 'updateByID'.
-    if (operation === 'update' || operation === 'updateByID' || operation === 'restoreVersion') {
+    if (operation === 'create' || operation === 'update' || operation === 'updateByID' || operation === 'restoreVersion') {
         const collections = operations(req);
         const stack = collections?.get(collection.slug);
         stack?.pop();
@@ -30,110 +34,168 @@ 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;
-        }
+function optionsOf(req) {
+    return req.payload.config.custom?.xp;
+}
+function registration(req, slug) {
+    return optionsOf(req).pages?.collections.find((entry)=>entry.slug === slug);
+}
+const active = (test)=>test.status === 'running' || test.status === 'decided';
+const pathsOf = (req, collection, rows)=>{
+    const page = registration(req, collection);
+    return page ? sortLockKeys(rows.flatMap((row)=>{
+        const path = row ? page.pathOf(row) : null;
+        return path === null ? [] : [
+            normalisePath(path)
+        ];
+    })) : [];
+};
+/** The later audit also recognises arm-select tags; include those ids in its lock superset. */ function taggedIds(value, ids = new Set()) {
+    if (Array.isArray(value)) value.forEach((v)=>taggedIds(v, ids));
+    else if (isObject(value)) {
+        if (typeof value.experiment === 'string' && typeof value.arm === 'string') ids.add(value.experiment);
+        Object.values(value).forEach((v)=>taggedIds(v, ids));
     }
-    // page guard: the hook must see test placements regardless of the editor's access
-    const tests = await req.payload.find({
-        collection: 'xp-experiments',
-        req,
-        overrideAccess: true,
-        depth: 0,
-        limit: 0,
-        where: {
-            and: [
-                {
-                    kind: {
-                        equals: 'page'
-                    }
-                },
-                {
-                    status: {
-                        in: [
-                            'running',
-                            'decided',
-                            'archived'
-                        ]
-                    }
-                }
-            ]
-        }
-    });
-    for (const test of tests.docs){
-        const decision = test.decision;
+    return ids;
+}
+export function guardExperimentIds(tests, slugs, collection, paths, held, tags = new Set()) {
+    const excluded = new Set(Array.isArray(held) ? held.map(String) : []);
+    return sortLockKeys(tests.filter((test)=>slugs.includes(test.slug) || tags.has(String(test.id)) || test.kind === 'page' && (!test.pageCollection || test.pageCollection === collection) && test.arms.some((a)=>typeof a.pageTarget === 'string' && paths.includes(normalisePath(a.pageTarget)))).map((test)=>String(test.id)).filter((id)=>!excluded.has(id)));
+}
+function protect(tests, path) {
+    for (const test of tests){
+        if (test.kind !== 'page' || !active(test) && test.status !== 'archived') continue;
         const archived = test.status === 'archived';
-        if (archived && (!decision?.winnerArm || decision.discardedAt || decision.pagesReleasedAt)) continue;
-        // page guard: the hook must see test placements regardless of the editor's access
-        const phases = await req.payload.find({
-            collection: 'xp-phases',
-            req,
-            overrideAccess: true,
-            depth: 0,
-            limit: 1,
-            sort: '-phase',
-            where: {
-                experiment: {
-                    equals: test.id
-                },
-                phaseKind: {
-                    equals: 'test'
-                }
-            }
-        });
-        const phase = phases.docs[0];
-        if (!phase) throw new XpRefusal('invalid-phase', READINESS_COPY.missingVersions, {
+        if (archived && (!test.winnerArm || test.discardedAt || test.pagesReleasedAt)) continue;
+        if (!test.arms.length) throw new XpRefusal('invalid-phase', READINESS_COPY.missingVersions, {
+            experimentId: test.id
+        }, 409);
+        const arms = archived ? test.arms.filter((a)=>a.kind === 'control' || a.key === test.winnerArm) : test.arms;
+        const matched = arms.find((a)=>typeof a.pageTarget === 'string' && normalisePath(a.pageTarget) === path);
+        if (matched) throw new XpRefusal('locked-placement', pageGuardCopy(test.name, test.status, archived && matched.key !== test.winnerArm ? 'original' : 'winner'), {
             experimentId: test.id
         }, 409);
-        const arms = phase.arms;
-        const protectedArms = archived ? arms.filter((arm)=>arm.kind === 'control' || arm.key === decision.winnerArm) : arms;
-        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);
-        }
     }
 }
-function registration(req, slug) {
-    return (req.payload.config.custom?.xp).pages?.collections.find((entry)=>entry.slug === slug);
+function refuseInteraction(tests, beforeSlugs, afterSlugs, beforePaths, afterPaths, collection) {
+    const blocks = tests.filter((test)=>test.kind === 'block' && active(test) && afterSlugs.includes(test.slug));
+    const pages = tests.filter((test)=>test.kind === 'page' && active(test) && (!test.pageCollection || test.pageCollection === collection));
+    for (const page of pages){
+        if (!page.arms.some((a)=>typeof a.pageTarget === 'string' && afterPaths.includes(normalisePath(a.pageTarget)))) continue;
+        const block = blocks[0];
+        if (!block) continue;
+        const preExisting = beforeSlugs.includes(block.slug) && page.arms.some((a)=>typeof a.pageTarget === 'string' && beforePaths.includes(normalisePath(a.pageTarget)));
+        throw new XpRefusal('interacting-tests', placementGuardCopy(page, block, preExisting), {
+            experimentId: page.id,
+            blockId: block.id
+        }, 409);
+    }
+}
+function mapBusy(error) {
+    if (isPageBusy(error)) throw new XpRefusal('page-busy', 'This page is being updated by a test right now. Try again in a moment.', undefined, 409, {
+        cause: error
+    });
+    throw error;
 }
 export const pageGuardBeforeDelete = async ({ req, id, collection })=>{
     const page = registration(req, collection.slug);
     if (!page) return;
-    const published = await previousPublishedContent(req, collection.slug, id);
-    if (!published || published._status === 'draft') return;
-    const path = page.pathOf(published);
-    if (path !== null) await protect(req, path);
+    try {
+        const published = await previousPublishedContent(req, collection.slug, id);
+        if (!published || published._status === 'draft') return;
+        const paths = pathsOf(req, collection.slug, [
+            published
+        ]);
+        const exec = await req.transactionID != null ? txExecutor(req) : pooledExecutor(req.payload);
+        let tests = await placementTests(exec);
+        if (await req.transactionID != null) {
+            await lockPlacementScope(exec, guardExperimentIds(tests, placementSlugs(optionsOf(req), collection.slug, published), collection.slug, paths, req.context.xpHeldExperiments, taggedIds(published)), paths);
+            tests = await placementTests(exec);
+        }
+        for (const path of paths)protect(tests.filter((t)=>!t.pageCollection || t.pageCollection === collection.slug), path);
+    } catch (error) {
+        mapBusy(error);
+    }
 };
 export const pageGuardBeforeChange = async ({ req, collection, originalDoc, operation, data })=>{
-    if (operation !== 'update') return data;
-    const page = registration(req, collection.slug);
-    if (!page) return data;
     const drafts = Boolean(collection.versions && collection.versions.drafts);
-    // updateDocument computes isSavingDraft from draftArg and _status before
-    // beforeChange, and writes the main row only when !isSavingDraft.
     const call = operations(req)?.get(collection.slug)?.at(-1);
     if (drafts && call?.draft && (call.restore || data._status !== 'published')) return data;
-    const published = await previousPublishedContent(req, collection.slug, originalDoc.id);
-    if (!published || published._status === 'draft') return data;
-    const path = page.pathOf(published);
-    const unpublishing = drafts && data._status === 'draft';
-    const trashing = collection.trash && data.deletedAt != null && !originalDoc.deletedAt;
-    if (path !== null && (trashing || unpublishing || page.pathOf({
+    const after = operation === 'create' ? data : {
         ...originalDoc,
         ...data
-    }) !== path)) await protect(req, path);
-    return data;
+    };
+    const options = optionsOf(req);
+    try {
+        const published = operation === 'create' ? undefined : await previousPublishedContent(req, collection.slug, originalDoc.id);
+        const before = published?._status === 'draft' ? undefined : published;
+        const beforeSlugs = placementSlugs(options, collection.slug, before);
+        const afterSlugs = placementSlugs(options, collection.slug, after);
+        const beforePaths = pathsOf(req, collection.slug, [
+            before
+        ]), afterPaths = pathsOf(req, collection.slug, [
+            after
+        ]);
+        const paths = sortLockKeys([
+            ...beforePaths,
+            ...afterPaths
+        ]);
+        const exec = await req.transactionID != null ? txExecutor(req) : pooledExecutor(req.payload);
+        let tests = await placementTests(exec);
+        const publishes = !drafts || after._status === 'published';
+        const noTransaction = ()=>{
+            if (publishes && tests.some((t)=>t.kind === 'block' && active(t) && afterSlugs.includes(t.slug))) throw new XpNoTransactionError('Save this page with transactions on.');
+        };
+        if (await req.transactionID == null) noTransaction();
+        else {
+            try {
+                await lockPlacementScope(exec, guardExperimentIds(tests, [
+                    ...beforeSlugs,
+                    ...afterSlugs
+                ], collection.slug, paths, req.context.xpHeldExperiments, taggedIds([
+                    before,
+                    after
+                ])), paths);
+                tests = await placementTests(exec);
+            } catch (error) {
+                if (!(error instanceof XpNoTransactionError)) throw error;
+                // Only a session lost after discovery reaches this fallback. The first discovery
+                // read and delete have no fallback: a dead session fails those operations closed.
+                tests = await placementTests(pooledExecutor(req.payload));
+                noTransaction();
+            }
+        }
+        if (operation === 'update' && before) {
+            const page = registration(req, collection.slug);
+            const old = page?.pathOf(before);
+            const unpublishing = drafts && data._status === 'draft';
+            const trashing = collection.trash && data.deletedAt != null && !originalDoc.deletedAt;
+            if (old != null && (unpublishing || trashing || page.pathOf(after) !== old)) protect(tests.filter((t)=>!t.pageCollection || t.pageCollection === collection.slug), normalisePath(old));
+        }
+        if (publishes) refuseInteraction(tests, beforeSlugs, afterSlugs, beforePaths, afterPaths, collection.slug);
+        return data;
+    } catch (error) {
+        mapBusy(error);
+    }
+};
+/** Unwrapped: these writes must fail the publish closed, unlike the best-effort audit. */ export const pageGuardAfterChange = async ({ req, collection, doc })=>{
+    const call = operations(req)?.get(collection.slug)?.at(-1);
+    const drafts = Boolean(collection.versions && collection.versions.drafts);
+    if (drafts && (doc._status !== 'published' || call?.draft && call.restore)) return doc;
+    if (await req.transactionID == null) return doc;
+    try {
+        const stored = await storedContent(req, collection.slug, doc.id);
+        if (!stored) throw new Error('The saved placement row was not found.');
+        const slugs = placementSlugs(optionsOf(req), collection.slug, stored);
+        const exec = txExecutor(req);
+        for (const test of (await placementTests(exec))){
+            if (test.kind === 'block' && active(test) && slugs.includes(test.slug)) await appendPlacementDoc(exec, test.id, test.phase, {
+                collection: collection.slug,
+                id: doc.id
+            });
+        }
+        return doc;
+    } catch (error) {
+        mapBusy(error);
+    }
 };

package/dist/hooks/puckGoals.d.ts

@@ -0,0 +1,3 @@
+import { type CollectionBeforeChangeHook } from 'payload';
+/** Validate only the Puck JSON included in a publishing write. */
+export declare function puckGoalsBeforeChange(field: string): CollectionBeforeChangeHook;

package/dist/hooks/puckGoals.js

@@ -0,0 +1,38 @@
+import { ValidationError } from 'payload';
+import { validateClickGoal } from '../goals/validate.js';
+/** Validate only the Puck JSON included in a publishing write. */ export function puckGoalsBeforeChange(field) {
+    return async function validatePuckGoals({ collection, data, originalDoc, req }) {
+        const drafts = Boolean(collection.versions && collection.versions.drafts);
+        if (drafts && data._status !== 'published') return data;
+        // Publishing a stored draft without resending its JSON publishes the draft's JSON.
+        let value = data[field] !== undefined ? data[field] : drafts ? originalDoc?.[field] : undefined;
+        if (value === undefined) return data;
+        if (typeof value === 'string') {
+            try {
+                value = JSON.parse(value);
+            } catch  {
+                return data;
+            }
+        }
+        const errors = [];
+        async function walk(value, path) {
+            if (!value || typeof value !== 'object') return;
+            for (const [key, prop] of Object.entries(value)){
+                const propPath = `${path}.${key}`;
+                if (key === 'xpGoal' && typeof prop === 'string') {
+                    const result = await validateClickGoal(prop, req);
+                    if (result !== true) errors.push({
+                        path: propPath,
+                        message: result
+                    });
+                } else await walk(prop, propPath);
+            }
+        }
+        await walk(value, field);
+        if (errors.length) throw new ValidationError({
+            collection: collection.slug,
+            errors
+        });
+        return data;
+    };
+}

package/dist/onInit.js

@@ -1,8 +1,37 @@
+import { findRegisteredBlocksField } from './blocks/formState.js';
+import { EXPERIMENT_BLOCK_SLUG } from './blocks/model.js';
+import { contentBlocks } from './transitions/contentFields.js';
 import { validateDimensions } from './events/dimensions.js';
 import { assertPostgresAdapter, probeTransactions } from './db/adapter.js';
 import { hasHostAttributesOf } from './server/serverRuntime.js';
+// Diagnostic only: named containers are never accepted by the top-level readers.
+function registeredPaths(fields, name, parent = []) {
+    return fields.flatMap((field)=>{
+        const path = 'name' in field && field.name ? [
+            ...parent,
+            field.name
+        ] : parent;
+        if (field.type === 'blocks' && field.name === name) return [
+            path.join('.')
+        ];
+        if (field.type === 'tabs') return field.tabs.flatMap((tab)=>registeredPaths(tab.fields, name, 'name' in tab && tab.name ? [
+                ...path,
+                tab.name
+            ] : path));
+        return 'fields' in field ? registeredPaths(field.fields, name, path) : [];
+    });
+}
 export function createOnInit(options) {
     return async (payload)=>{
+        for (const registration of options.blocks?.collections ?? []){
+            const config = payload.config.collections.find((c)=>c.slug === registration.slug);
+            const found = findRegisteredBlocksField(config?.fields ?? [], registration.field);
+            if (!found) throw new Error(`Experiments blocks field ${registration.slug}.${registeredPaths(config?.fields ?? [], registration.field)[0] ?? registration.field} must be a top-level blocks field and must contain ${registration.blockSlug ?? EXPERIMENT_BLOCK_SLUG}`);
+            if (!contentBlocks(found.field, payload.config.blocks).some((b)=>b.slug === (registration.blockSlug ?? EXPERIMENT_BLOCK_SLUG))) {
+                throw new Error(`Experiments blocks field ${registration.slug}.${registration.field} must contain ${registration.blockSlug ?? EXPERIMENT_BLOCK_SLUG}`);
+            }
+        }
+        if (options.metricSources?.some((source)=>source.id.startsWith('click:'))) throw new Error('metricSources ids starting with click: are reserved for click goals');
         validateDimensions(options.events?.dimensions);
         assertPostgresAdapter(payload);
         await probeTransactions(payload);

package/dist/options.d.ts

@@ -7,3 +7,5 @@ export declare function puckCollections(options: Pick<ExperimentsPluginOptions,
 export declare function resolveOptions<TUser extends {
     id: string | number;
 }>(input: ExperimentsPluginOptions<TUser>): ResolvedOptions<TUser>;
+/** One published-row rule shared by scans, bindings, writes and editor links. */
+export declare function documentEditor(options: Pick<ExperimentsPluginOptions, 'puck' | 'blocks'>, collection: string, doc: Record<string, unknown>): 'puck' | 'blocks' | 'page';