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

package/dist/exports/client.js

@@ -5,3 +5,4 @@ export { useExperiment } from '../client/useExperiment.js';
 export { ExperimentPageview } from '../client/ExperimentPageview.js';
 export { trackConversionBeacon } from '../client/trackConversionBeacon.js';
 export { MAX_EVENTS_PER_BODY, DEFAULT_MAX_BODY_BYTES } from '../constants.js';
+export { ExperimentGroup } from '../client/ExperimentGroup.js';

package/dist/exports/index.d.ts

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

package/dist/exports/index.js

@@ -2,3 +2,6 @@ export { createExperimentsPlugin } from '../plugin.js';
 export { defineFlagPoint, defineMetricSource } from '../define.js';
 export { contentDone } from '../contentDone.js';
 export { createArmSelectField } from '../fields/armSelect.js';
+export { createExperimentBlock } from '../blocks/createExperimentBlock.js';
+export { EXPERIMENT_BLOCK_SLUG } from '../blocks/model.js';
+export { xpGoalField } from '../fields/xpGoal.js';

package/dist/exports/puck.d.ts

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

package/dist/exports/puck.js

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

package/dist/exports/puckEditor.d.ts

@@ -1,4 +1,7 @@
 export { ExperimentSlotEditor, createExperimentSlotEditor } from '../puck/editor/ExperimentSlotEditor.js';
 export { experimentOutlinePlugin } from '../puck/editor/experimentOutlinePlugin.js';
+export { experimentsPuckEditor } from '../puck/editor/integration.js';
+export type { ExperimentsPuckIntegration } from '../types/puck.js';
 export { deriveAccent } from '../ui/accent.js';
+export { xpGoalPuckEditorField } from '../puck/editor/xpGoalPuckEditorField.js';
 export type { PuckRoutes } from '../puck/routes.js';

package/dist/exports/puckEditor.js

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

package/dist/exports/rsc.d.ts

@@ -16,3 +16,6 @@ export { compileManifest } from '../manifest/compile.js';
 export type { ManifestInputs, ManifestInputExperiment, ManifestPhase, ManifestCompileOptions } from '../manifest/compile.js';
 export type { Manifest, ManifestExperiment } from '../types/manifest.js';
 export { contentChangesBeforeHook as captureContentBaseline } from '../hooks/contentChanges.js';
+export { pageKindSeoContract, type PageKindSeoContractOptions, type PageKindSeoContractRow } from '../server/pageKindSeoContract.js';
+export { resolveExperimentBlocks } from '../server/resolveExperimentBlocks.js';
+export type { HostBlock, ExperimentBlock, ExperimentBlockGroup, ResolvedHostBlock, ResolvedExperimentBlocks } from '../blocks/model.js';

package/dist/exports/rsc.js

@@ -13,3 +13,5 @@ export { toClientAssignments } from '../server/toClientAssignments.js';
 // Pure manifest builder for host tests (CORE-43): the same compile transitions run, with no database access.
 export { compileManifest } from '../manifest/compile.js';
 export { contentChangesBeforeHook as captureContentBaseline } from '../hooks/contentChanges.js';
+export { pageKindSeoContract } from '../server/pageKindSeoContract.js';
+export { resolveExperimentBlocks } from '../server/resolveExperimentBlocks.js';

package/dist/fields/xpGoal.d.ts

@@ -0,0 +1,3 @@
+import type { TextField } from 'payload';
+/** The host renders this value as data-xp-goal on its interactive element. */
+export declare function xpGoalField(): TextField;

package/dist/fields/xpGoal.js

@@ -0,0 +1,16 @@
+import { XP_GOAL_FIELD } from '../admin/paths.js';
+import { validateClickGoal } from '../goals/validate.js';
+/** The host renders this value as data-xp-goal on its interactive element. */ export function xpGoalField() {
+    return {
+        name: 'xpGoal',
+        label: 'Click goal',
+        type: 'text',
+        admin: {
+            description: 'Choose the short name of the click goal to count here.',
+            components: {
+                Field: XP_GOAL_FIELD
+            }
+        },
+        validate: (value, { req })=>validateClickGoal(value, req)
+    };
+}

package/dist/globals/state.js

@@ -1,3 +1,4 @@
+import { preserveRetiredSlugs } from '../db/slugs.js';
 import { deny, isTrue } from '../collections/access.js';
 export function stateGlobal(options) {
     return {
@@ -13,12 +14,21 @@ export function stateGlobal(options) {
             update: deny,
             readVersions: deny
         },
+        hooks: {
+            beforeChange: [
+                preserveRetiredSlugs
+            ]
+        },
         fields: [
             {
                 name: 'revision',
                 type: 'number',
                 defaultValue: 0
             },
+            {
+                name: 'retiredSlugs',
+                type: 'json'
+            },
             {
                 name: 'manifest',
                 type: 'json'

package/dist/goals/cache.d.ts

@@ -0,0 +1,3 @@
+import type { Payload } from 'payload';
+/** Cache failures too, retaining the last good set and bounding retry traffic. */
+export declare function clickKeys(payload: Payload): Promise<ReadonlySet<string> | undefined>;

package/dist/goals/cache.js

@@ -0,0 +1,35 @@
+import { definedClickKeys } from '../db/clickGoals.js';
+import { pooledExecutor } from '../db/executor.js';
+import { safeError } from '../log.js';
+import { CLICK_KEY } from './key.js';
+const caches = new WeakMap();
+/** Cache failures too, retaining the last good set and bounding retry traffic. */ export async function clickKeys(payload) {
+    let entry = caches.get(payload);
+    if (!entry) {
+        entry = {
+            until: 0
+        };
+        caches.set(payload, entry);
+    }
+    if (entry.pending) return entry.pending;
+    if (Date.now() < entry.until) return entry.keys;
+    const current = entry;
+    current.pending = (async ()=>{
+        try {
+            current.keys = new Set([
+                ...await definedClickKeys(pooledExecutor(payload))
+            ].filter((key)=>CLICK_KEY.test(key)));
+        } catch (error) {
+            try {
+                payload.logger.error({
+                    err: safeError(error)
+                }, 'Experiments: click goal lookup failed');
+            } catch  {}
+        } finally{
+            current.until = Date.now() + 30_000;
+            current.pending = undefined;
+        }
+        return current.keys;
+    })();
+    return current.pending;
+}

package/dist/goals/fairness.d.ts

@@ -0,0 +1,40 @@
+import type { PayloadRequest } from 'payload';
+import type { Arm, DocId, ResolvedOptions } from '../types/contracts.js';
+import type { PlacementDoc } from '../db/placements.js';
+export declare const OUTSIDE_GOAL = "This goal isn't inside the part being tested, so every version shows it the same way.";
+export declare const LEGACY_FAIRNESS = "Goal fairness isn't checked for tests started before this update.";
+export interface GoalPlacement {
+    collection?: string;
+    id?: DocId;
+    path?: string;
+    title?: string;
+}
+export interface GoalContent {
+    keys: Array<{
+        key: string;
+        arms: string[];
+        label: string;
+    }>;
+    unchecked: GoalPlacement[];
+    readArms: string[];
+    skipped?: boolean;
+}
+type Experiment = {
+    id: DocId;
+    slug: string;
+    kind: string;
+    arms: Arm[];
+    pageCollection?: string | null;
+};
+/** Call outside a transition, or on Start's detached request after its locks.
+ * Frozen null placements are deliberately skipped by results (no anonymous scan).
+ */
+export declare function goalContent<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, options: ResolvedOptions<TUser>, experiment: Experiment, placements?: readonly PlacementDoc[] | null): Promise<GoalContent>;
+/** Readiness detail contains placement identifiers only. */
+export declare function goalPlacementDetail({ collection, id, path }: GoalPlacement): Omit<GoalPlacement, 'title'>;
+export declare function asymmetricGoal(content: GoalContent, source: string, arms: readonly {
+    key: string;
+}[]): boolean;
+export {};

package/dist/goals/fairness.js

@@ -0,0 +1,200 @@
+import { clickGoalContent } from '../db/clickGoals.js';
+import { safeError } from '../log.js';
+import { documentEditor, puckCollections } from '../options.js';
+import { EXPERIMENT_BLOCK_SLUG, hostBlocks, isObject, slotBlocks } from '../blocks/model.js';
+import { resolvePageCollection } from '../transitions/pageCollection.js';
+import { scanPlacements, uniquePlacementDocs } from '../transitions/placementInteractions.js';
+import { CLICK_KEY } from './key.js';
+export const OUTSIDE_GOAL = "This goal isn't inside the part being tested, so every version shows it the same way.";
+export const LEGACY_FAIRNESS = "Goal fairness isn't checked for tests started before this update.";
+/** Inspect inline JSON only; depth-zero relationship ids never dereference another document. */ function collect(value, into, label = '', labels) {
+    if (Array.isArray(value)) {
+        value.forEach((item)=>collect(item, into, label, labels));
+        return;
+    }
+    if (!isObject(value)) return;
+    const blockType = typeof value.blockType === 'string' ? value.blockType : typeof value.type === 'string' ? value.type : '';
+    const containing = labels.get(blockType) ?? (blockType || label);
+    if (typeof value.xpGoal === 'string' && CLICK_KEY.test(value.xpGoal)) into.set(value.xpGoal, containing || value.xpGoal);
+    Object.values(value).forEach((item)=>collect(item, into, containing, labels));
+}
+function blockLabels(req) {
+    const labels = new Map();
+    function walk(value) {
+        if (Array.isArray(value)) {
+            value.forEach(walk);
+            return;
+        }
+        if (!isObject(value)) return;
+        if (typeof value.slug === 'string' && isObject(value.labels) && typeof value.labels.singular === 'string') labels.set(value.slug, value.labels.singular);
+        for (const key of [
+            'blocks',
+            'fields',
+            'tabs'
+        ])walk(value[key]);
+    }
+    walk(req.payload.config.collections);
+    walk(req.payload.config.blocks);
+    return labels;
+}
+/** Call outside a transition, or on Start's detached request after its locks.
+ * Frozen null placements are deliberately skipped by results (no anonymous scan).
+ */ export async function goalContent(req, options, experiment, placements) {
+    if (experiment.kind !== 'page' && experiment.kind !== 'block') return {
+        keys: [],
+        unchecked: [],
+        readArms: [],
+        skipped: true
+    };
+    const byArm = new Map(experiment.arms.filter((a)=>a.kind !== 'holdout').map((a)=>[
+            a.key,
+            new Map()
+        ]));
+    const labels = blockLabels(req), unchecked = [], readArms = new Set();
+    const failed = (error, placement)=>{
+        unchecked.push(placement);
+        req.payload.logger.error({
+            err: safeError(error),
+            experimentId: experiment.id,
+            collection: placement.collection,
+            id: placement.id
+        }, 'Experiment click goal content lookup failed');
+    };
+    if (experiment.kind === 'page') {
+        let collection;
+        try {
+            collection = await resolvePageCollection(req, options, experiment, true);
+        } catch (error) {
+            failed(error, {});
+            return {
+                keys: [],
+                unchecked,
+                readArms: []
+            };
+        }
+        if (!collection?.contentOf) return {
+            keys: [],
+            unchecked,
+            readArms: [],
+            skipped: true
+        };
+        for (const arm of experiment.arms.filter((a)=>a.kind !== 'holdout' && a.pageTarget)){
+            const placement = {
+                collection: collection.slug,
+                path: arm.pageTarget
+            };
+            try {
+                const page = await collection.findByPath(arm.pageTarget, req);
+                if (!page?.published) continue;
+                const doc = await clickGoalContent(req, collection.slug, page.id);
+                if (!doc) {
+                    unchecked.push(placement);
+                    continue;
+                }
+                collect(collection.contentOf(doc), byArm.get(arm.key), '', labels);
+                readArms.add(arm.key);
+            } catch (error) {
+                failed(error, placement);
+            }
+        }
+    } else if (experiment.kind === 'block') {
+        if (placements === null) return {
+            keys: [],
+            unchecked,
+            readArms: [],
+            skipped: true
+        };
+        let docs = placements;
+        if (!docs) {
+            try {
+                docs = uniquePlacementDocs((await scanPlacements(req, options, experiment.slug)).filter((placement)=>placement.published));
+            } catch (error) {
+                failed(error, {});
+                return {
+                    keys: [],
+                    unchecked,
+                    readArms: []
+                };
+            }
+        }
+        for (const placement of docs){
+            try {
+                const doc = await clickGoalContent(req, placement.collection, placement.id);
+                if (!doc) continue;
+                const editor = documentEditor(options, placement.collection, doc);
+                if (editor === 'blocks') {
+                    const registration = options.blocks?.collections.find((c)=>c.slug === placement.collection);
+                    if (!registration) continue;
+                    for (const block of hostBlocks(doc[registration.field])){
+                        if (block.blockType !== (registration.blockSlug ?? EXPERIMENT_BLOCK_SLUG) || block.experiment !== experiment.slug) continue;
+                        for (const arm of experiment.arms.filter((a)=>a.kind !== 'holdout'))collect(slotBlocks(block, arm.slot ?? arm.key), byArm.get(arm.key), '', labels);
+                    }
+                } else {
+                    const registration = puckCollections(options).find((c)=>c.slug === placement.collection);
+                    if (!registration) continue;
+                    const walk = (value)=>{
+                        if (Array.isArray(value)) {
+                            value.forEach(walk);
+                            return;
+                        }
+                        if (!isObject(value)) return;
+                        const props = isObject(value.props) ? value.props : undefined;
+                        const ref = props?.experiment;
+                        if (value.type === 'ExperimentSlot' && props && (typeof ref === 'string' ? ref : isObject(ref) ? ref.slug : undefined) === experiment.slug) {
+                            for (const arm of experiment.arms.filter((a)=>a.kind !== 'holdout'))collect(props[arm.slot ?? arm.key], byArm.get(arm.key), '', labels);
+                            return;
+                        }
+                        Object.values(value).forEach(walk);
+                    };
+                    walk(doc[registration.field]);
+                }
+                for (const arm of byArm.keys())readArms.add(arm);
+            } catch (error) {
+                failed(error, placement);
+            }
+        }
+    }
+    const rows = new Map();
+    for (const arm of experiment.arms){
+        // Holdout renders the Original and has no row or slot of its own.
+        const key = arm.kind === 'holdout' ? experiment.arms.find((a)=>a.kind === 'control')?.key : arm.key;
+        if (key && readArms.has(key)) readArms.add(arm.key);
+        for (const [goal, label] of (key ? byArm.get(key) : undefined) ?? []){
+            const row = rows.get(goal) ?? {
+                key: goal,
+                arms: [],
+                label
+            };
+            row.arms.push(arm.key);
+            rows.set(goal, row);
+        }
+    }
+    return {
+        keys: [
+            ...rows.values()
+        ].sort((a, b)=>a.key.localeCompare(b.key)),
+        unchecked,
+        readArms: [
+            ...readArms
+        ]
+    };
+}
+/** Readiness detail contains placement identifiers only. */ export function goalPlacementDetail({ collection, id, path }) {
+    return {
+        ...collection === undefined ? {} : {
+            collection
+        },
+        ...id === undefined ? {} : {
+            id
+        },
+        ...path === undefined ? {} : {
+            path
+        }
+    };
+}
+export function asymmetricGoal(content, source, arms) {
+    if (content.skipped) return false;
+    const row = content.keys.find((row)=>`click:${row.key}` === source);
+    const read = arms.filter((arm)=>content.readArms.includes(arm.key));
+    return !!row && read.some((arm)=>row.arms.includes(arm.key)) && read.some((arm)=>!row.arms.includes(arm.key));
+}

package/dist/goals/key.d.ts

@@ -0,0 +1,4 @@
+/** Click keys are also metric slugs; keep the wire and field grammar identical. */
+export declare const CLICK_KEY: RegExp;
+export declare const isClickSource: (source: unknown) => source is string;
+export declare const validClickSource: (source: unknown) => source is string;

package/dist/goals/key.js

@@ -0,0 +1,3 @@
+/** Click keys are also metric slugs; keep the wire and field grammar identical. */ export const CLICK_KEY = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const isClickSource = (source)=>typeof source === 'string' && source.startsWith('click:');
+export const validClickSource = (source)=>isClickSource(source) && CLICK_KEY.test(source.slice(6));

package/dist/goals/picker/clickGoalPicker.model.d.ts

@@ -0,0 +1,29 @@
+export interface ClickGoal {
+    id: string | number;
+    name: string;
+    slug: string;
+    source: string;
+}
+export type PickerStatus = 'loading' | 'ready' | 'not-manager' | 'error';
+export declare function goalSlug(name: string): string;
+export declare function clickGoalSlug(name: string): string;
+export declare function definedClickGoals(rows: readonly ClickGoal[]): ClickGoal[];
+export declare function undefinedClickKey(status: PickerStatus, goals: readonly ClickGoal[], value: string): boolean;
+export declare function clickGoalBody(name: string, slug: string): {
+    name: string;
+    slug: string;
+    source: string;
+    direction: string;
+    attributionWindowHours: number;
+    minSampleSize: number;
+    capping: {
+        type: null;
+        value: null;
+    };
+};
+/** Payload nests field errors in data.errors; never show its raw message. */
+export declare function hasSlugError(body: unknown): boolean;
+export declare function clickGoalCreateError(slug: string, body?: unknown): {
+    slug?: string;
+    general?: string;
+};

package/dist/goals/picker/clickGoalPicker.model.js

@@ -0,0 +1,45 @@
+import { CLICK_KEY, isClickSource } from '../key.js';
+import { CLICK_GOAL_COPY as C } from './copy.js';
+export function goalSlug(name) {
+    return name.normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+export function clickGoalSlug(name) {
+    return goalSlug(name).slice(0, 64).replace(/[-_]+$/, '');
+}
+export function definedClickGoals(rows) {
+    return rows.filter((row)=>isClickSource(row.source));
+}
+export function undefinedClickKey(status, goals, value) {
+    return status === 'ready' && Boolean(value) && !goals.some((goal)=>goal.slug === value);
+}
+export function clickGoalBody(name, slug) {
+    return {
+        name: name.trim(),
+        slug,
+        source: `click:${slug}`,
+        direction: 'increase',
+        attributionWindowHours: 168,
+        minSampleSize: 150,
+        capping: {
+            type: null,
+            value: null
+        }
+    };
+}
+/** Payload nests field errors in data.errors; never show its raw message. */ export function hasSlugError(body) {
+    if (!body || typeof body !== 'object') return false;
+    const value = body;
+    if (value.path === 'slug') return true;
+    return Array.isArray(value.errors) && value.errors.some(hasSlugError) || hasSlugError(value.data);
+}
+export function clickGoalCreateError(slug, body) {
+    if (!CLICK_KEY.test(slug)) return {
+        slug: C.slugRule
+    };
+    if (hasSlugError(body)) return {
+        slug: C.duplicateSlug
+    };
+    return {
+        general: C.saveError
+    };
+}

package/dist/goals/picker/copy.d.ts

@@ -0,0 +1,16 @@
+/** Shared by Payload's field and the Puck sidebar, without either UI dependency. */
+export declare const CLICK_GOAL_COPY: {
+    readonly label: "Click goal";
+    readonly choose: "Choose a click goal";
+    readonly newGoal: "+ New click goal";
+    readonly title: "New click goal";
+    readonly name: "Name";
+    readonly slug: "Short name";
+    readonly advanced: "Advanced";
+    readonly createGoal: "Create goal";
+    readonly cancel: "Cancel";
+    readonly undefinedKey: "No click goal has this name yet. Create it with \"+ New click goal\".";
+    readonly slugRule: "Use 1–64 lowercase letters, numbers, underscores or hyphens, starting with a letter or number.";
+    readonly duplicateSlug: "Another goal already uses this short name. Change it under Advanced.";
+    readonly saveError: "Couldn't save the goal. Try again.";
+};

package/dist/goals/picker/copy.js

@@ -0,0 +1,15 @@
+/** Shared by Payload's field and the Puck sidebar, without either UI dependency. */ export const CLICK_GOAL_COPY = {
+    label: 'Click goal',
+    choose: 'Choose a click goal',
+    newGoal: '+ New click goal',
+    title: 'New click goal',
+    name: 'Name',
+    slug: 'Short name',
+    advanced: 'Advanced',
+    createGoal: 'Create goal',
+    cancel: 'Cancel',
+    undefinedKey: 'No click goal has this name yet. Create it with "+ New click goal".',
+    slugRule: 'Use 1–64 lowercase letters, numbers, underscores or hyphens, starting with a letter or number.',
+    duplicateSlug: 'Another goal already uses this short name. Change it under Advanced.',
+    saveError: "Couldn't save the goal. Try again."
+};

package/dist/goals/picker/useClickGoalPicker.d.ts

@@ -0,0 +1,30 @@
+import { type ClickGoal, type PickerStatus } from './clickGoalPicker.model.js';
+/** UI-free state shared by the two editor hosts. A refused read silently removes management. */
+export declare function useClickGoalPicker(apiRoute: string, { enabled, onSelect }: {
+    enabled?: boolean;
+    onSelect: (slug: string) => void;
+}): {
+    status: PickerStatus;
+    goals: ClickGoal[];
+    canManage: boolean;
+    undefinedKey: (value: string) => boolean;
+    panel: {
+        open: boolean;
+        name: string;
+        slug: string;
+        slugEdited: boolean;
+        advanced: boolean;
+        pending: boolean;
+        errors: {
+            slug?: string;
+            general?: string;
+        };
+    };
+    open: () => void;
+    cancel: () => void;
+    setName: (name: string) => void;
+    setSlug: (slug: string) => void;
+    setAdvanced: (advanced: boolean) => void;
+    create: () => Promise<void>;
+};
+export type ClickGoalPicker = ReturnType<typeof useClickGoalPicker>;