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

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/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,11 +1,18 @@
-import { previousPublishedContent } from '../db/appends.js';
-import { XpRefusal } from '../errors.js';
-import { pageGuardCopy, READINESS_COPY } from '../admin/copy/readiness.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 { 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();
@@ -19,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();
@@ -27,95 +34,168 @@ export const pageGuardAfterOperation = ({ req, collection, operation, result })=
     }
     return result;
 };
-async function protect(req, path) {
-    // 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;
+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));
+    }
+    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;
-        if (protectedArms.some((arm)=>arm.pageTarget === path)) {
-            throw new XpRefusal('locked-placement', pageGuardCopy(String(test.name), test.status), {
-                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/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>>;

package/dist/lib/fetchAllDocs.js

@@ -0,0 +1,56 @@
+/** A successful REST response did not contain a readable document list. */ export 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 async function fetchAllDocs(url, options = {}) {
+    const [path, query] = url.split('?');
+    const params = new URLSearchParams(query);
+    params.set('limit', '100');
+    const docs = [];
+    const seen = new Set();
+    for(let page = 1; page <= 1000; page++){
+        options.signal?.throwIfAborted();
+        params.set('page', String(page));
+        const response = await fetch(`${path}?${params}`, options);
+        const body = await response.json().catch(()=>{
+            if (response.ok) throw new DocsResponseError();
+            return undefined;
+        });
+        options.signal?.throwIfAborted();
+        if (!response.ok) return {
+            ok: false,
+            status: response.status,
+            body
+        };
+        const data = body;
+        if (!Array.isArray(data?.docs)) throw new DocsResponseError();
+        for (const doc of data.docs){
+            const id = doc && typeof doc === 'object' && 'id' in doc ? doc.id : undefined;
+            if (typeof id === 'string' || typeof id === 'number') {
+                if (seen.has(id)) continue;
+                seen.add(id);
+            }
+            docs.push(doc);
+        }
+        if (data.docs.length === 0) return {
+            ok: true,
+            docs
+        };
+        if (typeof data.totalPages === 'number' && page >= data.totalPages) return {
+            ok: true,
+            docs
+        };
+        if (data.hasNextPage === false || data.hasNextPage !== true && !(typeof data.totalPages === 'number' && page < data.totalPages)) {
+            return {
+                ok: true,
+                docs
+            };
+        }
+    }
+    return {
+        ok: false,
+        status: 0,
+        body: undefined,
+        reason: 'page-limit-exceeded'
+    };
+}

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';