@delmaredigital/payload-experiments 0.1.0-rc.7 → 0.2.0-rc.2

package/dist/admin/surface/test/VersionsSection.js

@@ -0,0 +1,208 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { TEST_PAGE as C } from '../../copy/testPage.js';
+import { ARMS_COPY, GROUP_LABELS, issueMessage } from '../../copy/arms.js';
+import { addHoldoutArm, addVariant, issuesByRow, removeArm, splitEvenly, totalWeight, withSlotsFor } from '../../arms/arms.model.js';
+import { allocationSentence } from '../../allocation.model.js';
+import { balanceWeight, orderedVersions, trafficShares } from './testPage.model.js';
+import { FieldErrors, ReadOnly, reasonFor, save, TextEdit } from './fields.js';
+import { Section } from './Section.js';
+const COLOURS = [
+    'var(--theme-success-500)',
+    'var(--theme-elevation-500)',
+    'var(--theme-warning-500)',
+    'var(--theme-error-500)',
+    'var(--theme-elevation-300)'
+];
+export function VersionsSection({ test, surface, parts }) {
+    const doc = test.doc;
+    const [weightEdit, setWeightEdit] = useState(null);
+    const releasedAllocation = useRef(null);
+    const [allocation, setAllocation] = useState(doc.allocation);
+    useEffect(()=>setWeightEdit(null), [
+        doc.arms
+    ]);
+    useEffect(()=>setAllocation(doc.allocation), [
+        doc.allocation
+    ]);
+    const reason = reasonFor(test, 'arms');
+    const live = weightEdit ? balanceWeight(doc.arms, weightEdit.key, weightEdit.weight) : doc.arms;
+    const ordered = orderedVersions(live);
+    const shares = trafficShares(ordered.map((row)=>row.arm));
+    const issues = issuesByRow(live, doc.kind);
+    const update = (transform)=>save(test, 'arms', ()=>({
+                arms: withSlotsFor(transform(test.doc.arms), test.doc.kind)
+            }));
+    const commitAllocation = ()=>{
+        if (allocation === test.doc.allocation || releasedAllocation.current === allocation) return;
+        releasedAllocation.current = allocation;
+        save(test, 'allocation', ()=>({
+                allocation
+            }));
+    };
+    return /*#__PURE__*/ _jsxs(Section, {
+        test: test,
+        sectionId: "versions",
+        children: [
+            /*#__PURE__*/ _jsx("div", {
+                className: "xp-version-rows",
+                children: ordered.map(({ arm, index }, position)=>/*#__PURE__*/ _jsxs("article", {
+                        className: "xp-version-row",
+                        children: [
+                            /*#__PURE__*/ _jsxs("h3", {
+                                children: [
+                                    /*#__PURE__*/ _jsx("span", {
+                                        style: {
+                                            background: COLOURS[position]
+                                        },
+                                        className: "xp-version-colour"
+                                    }),
+                                    GROUP_LABELS[arm.key]
+                                ]
+                            }),
+                            /*#__PURE__*/ _jsx(TextEdit, {
+                                label: `${GROUP_LABELS[arm.key]}: ${C.label}`,
+                                value: arm.label,
+                                reason: reason,
+                                onCommit: (label)=>update((arms)=>arms.map((current)=>current.key === arm.key ? {
+                                                ...current,
+                                                label
+                                            } : current))
+                            }),
+                            /*#__PURE__*/ _jsx(TextEdit, {
+                                label: `${GROUP_LABELS[arm.key]}: ${C.weight}`,
+                                type: "number",
+                                min: 0,
+                                max: 100,
+                                value: doc.arms[index].weight,
+                                reason: reason,
+                                validate: (raw)=>raw.trim() !== '' && Number.isInteger(Number(raw)) && Number(raw) >= 0 && Number(raw) <= 100,
+                                invalidMessage: C.invalidShare,
+                                onDraft: (value)=>setWeightEdit({
+                                        key: arm.key,
+                                        weight: Number(value)
+                                    }),
+                                onCommit: (value)=>update((arms)=>balanceWeight(arms, arm.key, Number(value)))
+                            }),
+                            /*#__PURE__*/ _jsx(parts.VersionContent, {
+                                test: test,
+                                surface: surface,
+                                armIndex: index
+                            }),
+                            issues.rows[index]?.map((issue, i)=>/*#__PURE__*/ _jsx("p", {
+                                    role: "alert",
+                                    children: issueMessage(issue, totalWeight(live))
+                                }, i)),
+                            /*#__PURE__*/ _jsx(FieldErrors, {
+                                test: test,
+                                path: `arms.${index}`
+                            }),
+                            !reason && arm.kind !== 'control' ? /*#__PURE__*/ _jsx("button", {
+                                type: "button",
+                                onClick: ()=>update((arms)=>splitEvenly(removeArm(arms, arm.key))),
+                                children: C.remove
+                            }) : null
+                        ]
+                    }, arm.key))
+            }),
+            /*#__PURE__*/ _jsx("div", {
+                className: "xp-traffic-bar",
+                role: "img",
+                "aria-label": `${C.traffic}: ${ordered.map(({ arm })=>`${arm.label} ${arm.weight}%`).join(', ')}`,
+                children: ordered.map(({ arm }, i)=>/*#__PURE__*/ _jsx("span", {
+                        style: {
+                            width: `${shares[i]}%`,
+                            background: COLOURS[i]
+                        }
+                    }, arm.key))
+            }),
+            issues.form.map((issue, i)=>/*#__PURE__*/ _jsx("p", {
+                    role: "alert",
+                    children: issueMessage(issue, totalWeight(live))
+                }, i)),
+            test.errors.arms ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: test.errors.arms
+            }) : null,
+            !reason ? /*#__PURE__*/ _jsxs(_Fragment, {
+                children: [
+                    /*#__PURE__*/ _jsxs("div", {
+                        className: "xp-section-actions",
+                        children: [
+                            /*#__PURE__*/ _jsx("button", {
+                                type: "button",
+                                disabled: doc.arms.filter((arm)=>arm.kind === 'variant').length >= 3,
+                                onClick: ()=>update((arms)=>addVariant(arms, doc.kind)),
+                                children: C.addVersion
+                            }),
+                            /*#__PURE__*/ _jsx("button", {
+                                type: "button",
+                                disabled: doc.arms.some((arm)=>arm.kind === 'holdout'),
+                                onClick: ()=>update(addHoldoutArm),
+                                children: C.addHoldout
+                            }),
+                            /*#__PURE__*/ _jsx("button", {
+                                type: "button",
+                                onClick: ()=>update(splitEvenly),
+                                children: C.split
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx("p", {
+                        children: ARMS_COPY.holdout
+                    }),
+                    /*#__PURE__*/ _jsx("p", {
+                        children: C.balanceHelp
+                    })
+                ]
+            }) : null,
+            reasonFor(test, 'allocation') ? /*#__PURE__*/ _jsx(ReadOnly, {
+                label: C.allocation,
+                value: `${doc.allocation}%`,
+                reason: reasonFor(test, 'allocation')
+            }) : /*#__PURE__*/ _jsxs("label", {
+                className: "xp-field",
+                children: [
+                    C.allocation,
+                    /*#__PURE__*/ _jsx("input", {
+                        type: "range",
+                        min: 1,
+                        max: 100,
+                        value: allocation,
+                        onChange: (e)=>{
+                            releasedAllocation.current = null;
+                            setAllocation(Number(e.target.value));
+                        },
+                        onPointerUp: commitAllocation,
+                        onKeyUp: (e)=>{
+                            if ([
+                                'ArrowLeft',
+                                'ArrowRight',
+                                'ArrowUp',
+                                'ArrowDown',
+                                'Home',
+                                'End',
+                                'PageUp',
+                                'PageDown'
+                            ].includes(e.key)) commitAllocation();
+                        },
+                        onBlur: commitAllocation
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsx("p", {
+                children: allocationSentence({
+                    allocation: reasonFor(test, 'allocation') ? doc.allocation : allocation,
+                    unitType: doc.unitType,
+                    arms: live,
+                    status: doc.status
+                })
+            }),
+            /*#__PURE__*/ _jsx(FieldErrors, {
+                test: test,
+                path: "allocation"
+            })
+        ]
+    });
+}

package/dist/admin/surface/test/fields.d.ts

@@ -0,0 +1,55 @@
+import type { ReactNode } from 'react';
+import type { SectionProps, TestDocApi } from '../contracts.js';
+import type { EditableField } from '../../../types/admin.js';
+import type { TestDocumentPatch } from '../testDocument.model.js';
+export declare function reasonFor(test: TestDocApi, field: string): string | null;
+export declare function save(test: TestDocApi, field: EditableField, patch: () => TestDocumentPatch): void;
+export declare function FieldErrors({ test, path }: {
+    test: TestDocApi;
+    path: string;
+}): import("react").JSX.Element;
+export declare function ReadOnly({ label, value, reason }: {
+    label: string;
+    value: ReactNode;
+    reason: string | null;
+}): import("react").JSX.Element;
+/** Local typing is intentionally separate from staging: build the current group on commit. */
+export declare function TextEdit({ label, value, onCommit, reason, multiline, placeholder, type, min, max, required, onDraft, validate, invalidMessage }: {
+    label: string;
+    value: string | number;
+    onCommit: (value: string) => void;
+    reason?: string | null;
+    onDraft?: (value: string) => void;
+    multiline?: boolean;
+    placeholder?: string;
+    type?: 'text' | 'number';
+    min?: number;
+    max?: number;
+    required?: boolean;
+    validate?: (value: string) => boolean;
+    invalidMessage?: string;
+}): import("react").JSX.Element;
+export declare const positiveInteger: (raw: string) => boolean;
+export declare function SelectEdit({ label, value, options, reason, onCommit, readOnlyValue }: {
+    label: string;
+    value: string;
+    options: readonly {
+        label: string;
+        value: string;
+    }[];
+    reason?: string | null;
+    onCommit: (value: string) => void;
+    readOnlyValue?: string;
+}): import("react").JSX.Element;
+export declare function CheckboxList({ label, value, options, reason, onToggle, readOnlyValue }: {
+    label: string;
+    value: string[];
+    options: readonly {
+        label: string;
+        value: string;
+    }[];
+    reason?: string | null;
+    onToggle: (value: string, checked: boolean) => void;
+    readOnlyValue?: string;
+}): import("react").JSX.Element;
+export declare function Hypothesis({ test }: SectionProps): import("react").JSX.Element;

package/dist/admin/surface/test/fields.js

@@ -0,0 +1,185 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useId, useState } from 'react';
+import { TEST_PAGE as C } from '../../copy/testPage.js';
+import { EDITABLE_BY_STATUS } from '../../../collections/experiments/editability.js';
+import { lockedReason } from '../../lockedNotice.model.js';
+export function reasonFor(test, field) {
+    return test.doc ? lockedReason(test.doc.status, field, EDITABLE_BY_STATUS) : null;
+}
+export function save(test, field, patch) {
+    if (!test.doc || reasonFor(test, field)) return;
+    test.stage(patch());
+    void test.commit();
+}
+export function FieldErrors({ test, path }) {
+    return /*#__PURE__*/ _jsx(_Fragment, {
+        children: Object.entries(test.errors).filter(([key])=>key === path || key.startsWith(`${path}.`)).map(([key, message])=>/*#__PURE__*/ _jsx("p", {
+                className: "xp-field-error",
+                role: "alert",
+                children: message
+            }, key))
+    });
+}
+export function ReadOnly({ label, value, reason }) {
+    return /*#__PURE__*/ _jsxs("div", {
+        className: "xp-read-only",
+        title: reason ?? undefined,
+        children: [
+            /*#__PURE__*/ _jsx("strong", {
+                children: label
+            }),
+            /*#__PURE__*/ _jsx("p", {
+                children: value
+            }),
+            reason ? /*#__PURE__*/ _jsx("small", {
+                children: reason
+            }) : null
+        ]
+    });
+}
+/** Local typing is intentionally separate from staging: build the current group on commit. */ export function TextEdit({ label, value, onCommit, reason, multiline, placeholder, type = 'text', min, max, required, onDraft, validate, invalidMessage }) {
+    const id = useId();
+    const [draft, setDraft] = useState(String(value));
+    const [error, setError] = useState(null);
+    useEffect(()=>setDraft(String(value)), [
+        value
+    ]);
+    const commit = ()=>{
+        if (draft === String(value)) return;
+        if (validate && !validate(draft)) {
+            setError(draft.trim() ? invalidMessage ?? null : null);
+            setDraft(String(value));
+            onDraft?.(String(value));
+            return;
+        }
+        onCommit(draft);
+    };
+    if (reason) return /*#__PURE__*/ _jsx(ReadOnly, {
+        label: label,
+        value: value === '' && placeholder ? placeholder : value,
+        reason: reason
+    });
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            /*#__PURE__*/ _jsxs("label", {
+                className: "xp-field",
+                htmlFor: id,
+                children: [
+                    /*#__PURE__*/ _jsx("span", {
+                        children: label
+                    }),
+                    multiline ? /*#__PURE__*/ _jsx("textarea", {
+                        id: id,
+                        value: draft,
+                        placeholder: placeholder,
+                        onChange: (e)=>{
+                            setDraft(e.target.value);
+                            onDraft?.(e.target.value);
+                        },
+                        onBlur: commit
+                    }) : /*#__PURE__*/ _jsx("input", {
+                        id: id,
+                        type: type,
+                        value: draft,
+                        min: min,
+                        max: max,
+                        required: required,
+                        placeholder: placeholder,
+                        "aria-invalid": error ? true : undefined,
+                        "aria-describedby": error ? `${id}-error` : undefined,
+                        onChange: (e)=>{
+                            setError(null);
+                            setDraft(e.target.value);
+                            onDraft?.(e.target.value);
+                        },
+                        onBlur: commit,
+                        onKeyDown: (e)=>{
+                            if (e.key === 'Enter') e.currentTarget.blur();
+                        }
+                    })
+                ]
+            }),
+            error ? /*#__PURE__*/ _jsx("p", {
+                className: "xp-field-error",
+                id: `${id}-error`,
+                role: "alert",
+                children: error
+            }) : null
+        ]
+    });
+}
+export const positiveInteger = (raw)=>raw.trim() !== '' && Number.isInteger(Number(raw)) && Number(raw) > 0;
+export function SelectEdit({ label, value, options, reason, onCommit, readOnlyValue }) {
+    const id = useId();
+    if (reason) {
+        return /*#__PURE__*/ _jsx(ReadOnly, {
+            label: label,
+            reason: reason,
+            value: readOnlyValue ?? options.find((o)=>o.value === value)?.label ?? value
+        });
+    }
+    return /*#__PURE__*/ _jsxs("label", {
+        className: "xp-field",
+        htmlFor: id,
+        children: [
+            /*#__PURE__*/ _jsx("span", {
+                children: label
+            }),
+            /*#__PURE__*/ _jsx("select", {
+                id: id,
+                value: value,
+                onChange: (e)=>onCommit(e.target.value),
+                children: options.map((option)=>/*#__PURE__*/ _jsx("option", {
+                        value: option.value,
+                        children: option.label
+                    }, option.value))
+            })
+        ]
+    });
+}
+export function CheckboxList({ label, value, options, reason, onToggle, readOnlyValue }) {
+    if (reason) return /*#__PURE__*/ _jsx(ReadOnly, {
+        label: label,
+        reason: reason,
+        value: readOnlyValue ?? value.map((v)=>options.find((o)=>o.value === v)?.label ?? v).join(', ')
+    });
+    return /*#__PURE__*/ _jsxs("fieldset", {
+        className: "xp-field",
+        children: [
+            /*#__PURE__*/ _jsx("legend", {
+                children: label
+            }),
+            options.map((option)=>/*#__PURE__*/ _jsxs("label", {
+                    children: [
+                        /*#__PURE__*/ _jsx("input", {
+                            type: "checkbox",
+                            checked: value.includes(option.value),
+                            onChange: (e)=>onToggle(option.value, e.target.checked)
+                        }),
+                        option.label
+                    ]
+                }, option.value))
+        ]
+    });
+}
+export function Hypothesis({ test }) {
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            /*#__PURE__*/ _jsx(TextEdit, {
+                label: C.hypothesis,
+                value: test.doc?.hypothesis ?? '',
+                multiline: true,
+                placeholder: C.hypothesisPlaceholder,
+                reason: reasonFor(test, 'hypothesis'),
+                onCommit: (value)=>save(test, 'hypothesis', ()=>({
+                            hypothesis: value
+                        }))
+            }),
+            /*#__PURE__*/ _jsx(FieldErrors, {
+                test: test,
+                path: "hypothesis"
+            })
+        ]
+    });
+}

package/dist/admin/surface/test/pageParts.d.ts

@@ -0,0 +1,2 @@
+import type { KindParts } from '../contracts.js';
+export declare const pageParts: KindParts;

package/dist/admin/surface/test/pageParts.js

@@ -0,0 +1,39 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { TEST_PAGE as C } from '../../copy/testPage.js';
+import { pageTargetIssue, setPageTarget, showsPageTarget } from '../../arms/pageTarget.model.js';
+import { FieldErrors, reasonFor, save, TextEdit } from './fields.js';
+function VersionContent({ test, armIndex }) {
+    const arm = test.doc?.arms[armIndex];
+    if (!arm || !test.doc) return null;
+    if (!showsPageTarget(test.doc.kind, arm.kind)) return /*#__PURE__*/ _jsx("p", {
+        children: C.holdoutContent
+    });
+    const issue = pageTargetIssue(arm.pageTarget, arm.kind);
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            /*#__PURE__*/ _jsx(TextEdit, {
+                label: `${arm.label}: ${C.pageAddress}`,
+                value: arm.pageTarget ?? '',
+                reason: reasonFor(test, 'arms'),
+                onCommit: (value)=>save(test, 'arms', ()=>({
+                            arms: test.doc.arms.map((current)=>current.key === arm.key ? setPageTarget(current, value) : current)
+                        }))
+            }),
+            issue ? /*#__PURE__*/ _jsx("p", {
+                role: "alert",
+                children: issue
+            }) : null,
+            /*#__PURE__*/ _jsx(FieldErrors, {
+                test: test,
+                path: `arms.${armIndex}.pageTarget`
+            })
+        ]
+    });
+}
+export const pageParts = {
+    Binding: ()=>/*#__PURE__*/ _jsx("p", {
+            children: C.pageBinding
+        }),
+    VersionContent
+};

package/dist/admin/surface/test/testPage.css

@@ -0,0 +1,23 @@
+.xp-test-page { color: var(--theme-text); background: var(--theme-bg); max-width: 90rem; margin: 0 auto; padding: 1.5rem; }
+.xp-test-header { position: sticky; top: 0; z-index: 10; background: var(--theme-bg); padding: 1rem 0; border-bottom: 1px solid var(--theme-elevation-150); }
+.xp-header-meta, .xp-section-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 1rem; margin-block: 1rem; }
+.xp-kind-chip, .xp-status-pill { border: 1px solid var(--theme-elevation-250); border-radius: 1rem; padding: .25rem .75rem; }
+.xp-status-pill--success, .xp-content-ready, .xp-section-check--done { color: var(--theme-success-600); }
+.xp-content-empty, .xp-status-pill--warning { color: var(--theme-warning-600); }
+.xp-test-section { padding-block: 1.5rem; border-bottom: 1px solid var(--theme-elevation-150); scroll-margin-top: 15rem; }
+.xp-version-rows { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr)); }
+.xp-version-row { border: 1px solid var(--theme-elevation-150); border-radius: var(--style-radius-s); padding: 1rem; }
+.xp-version-colour { display: inline-block; width: .75rem; height: .75rem; margin-right: .5rem; border-radius: 50%; }
+.xp-traffic-bar { display: flex; height: 1.25rem; background: var(--theme-elevation-100); margin-block: 1.5rem; overflow: hidden; border-radius: var(--style-radius-s); }
+.xp-traffic-bar > span { display: block; }
+.xp-field { display: flex; flex-direction: column; gap: .5rem; margin-block: 1rem; }
+.xp-field input, .xp-field textarea, .xp-field select { font: inherit; color: var(--theme-text); background: var(--theme-input-bg); border: 1px solid var(--theme-elevation-250); border-radius: var(--style-radius-s); padding: .65rem; }
+.xp-field textarea { min-height: 6rem; resize: vertical; }
+.xp-field input[type=range] { padding: 0; }
+.xp-read-only { padding-block: .5rem; }
+.xp-read-only p { margin-block: .5rem; }
+.xp-field-error { color: var(--theme-error-600); }
+.xp-test-page button { cursor: pointer; color: var(--theme-text); background: var(--theme-elevation-100); border: 1px solid var(--theme-elevation-250); padding: .65rem 1rem; border-radius: var(--style-radius-s); font: inherit; }
+.xp-test-page button:disabled { opacity: .5; cursor: default; }
+.xp-test-page summary { cursor: pointer; padding-block: .75rem; }
+.xp-targeting-row { border-bottom: 1px solid var(--theme-elevation-150); padding-bottom: 1rem; }

package/dist/admin/surface/test/testPage.model.d.ts

@@ -0,0 +1,17 @@
+import type { Arm, ArmKey, ExperimentKind, ExposurePolicy } from '../../../types/contracts.js';
+import type { PreflightResult } from '../../../types/endpoints.js';
+export declare function orderedVersions(arms: readonly Arm[]): Array<{
+    arm: Arm;
+    index: number;
+}>;
+/** Normalised visual shares only; invalid saved weights still surface as validation issues. */
+export declare function trafficShares(arms: readonly Arm[]): number[];
+export declare function durationSuggestion(preflight: PreflightResult | null, savedDays?: number | null): {
+    weeks: number;
+    plannedDurationDays: number;
+    sequentialTuningParameter: number;
+    feasible: boolean;
+} | null;
+export declare function exposureOptions(kind: ExperimentKind): readonly ExposurePolicy[];
+/** Keep the edited share exact and distribute the remaining whole percentages proportionally. */
+export declare function balanceWeight(arms: Arm[], key: ArmKey, weight: number): Arm[];

package/dist/admin/surface/test/testPage.model.js

@@ -0,0 +1,53 @@
+import { setWeight } from '../../arms/arms.model.js';
+const ORDER = [
+    'control',
+    'variantA',
+    'variantB',
+    'variantC',
+    'holdout'
+];
+export function orderedVersions(arms) {
+    return arms.map((arm, index)=>({
+            arm,
+            index
+        })).sort((a, b)=>ORDER.indexOf(a.arm.key) - ORDER.indexOf(b.arm.key));
+}
+/** Normalised visual shares only; invalid saved weights still surface as validation issues. */ export function trafficShares(arms) {
+    const weights = arms.map((arm)=>Number.isFinite(arm.weight) ? Math.max(0, arm.weight) : 0);
+    const sum = weights.reduce((a, b)=>a + b, 0);
+    return weights.map((weight)=>sum ? weight / sum * 100 : 0);
+}
+export function durationSuggestion(preflight, savedDays) {
+    const estimate = preflight?.estimate;
+    return estimate && estimate.plannedDurationDays !== savedDays ? estimate : null;
+}
+export function exposureOptions(kind) {
+    return kind === 'block' ? [
+        'render',
+        'viewport'
+    ] : kind === 'page' ? [
+        'pageview'
+    ] : [
+        'manual'
+    ];
+}
+/** Keep the edited share exact and distribute the remaining whole percentages proportionally. */ export function balanceWeight(arms, key, weight) {
+    if (!arms.some((arm)=>arm.key === key) || !Number.isInteger(weight) || weight < 0 || weight > 100) return arms;
+    const others = arms.filter((arm)=>arm.key !== key);
+    if (!others.length) return arms;
+    const total = others.reduce((sum, arm)=>sum + Math.max(0, Number.isFinite(arm.weight) ? arm.weight : 0), 0);
+    const denominator = total || others.length;
+    const raw = others.map((arm)=>(total ? Math.max(0, Number.isFinite(arm.weight) ? arm.weight : 0) : 1) * (100 - weight) / denominator);
+    const whole = raw.map(Math.floor);
+    const order = raw.map((_, i)=>i).sort((a, b)=>raw[b] - whole[b] - (raw[a] - whole[a]) || a - b);
+    const remainder = 100 - weight - whole.reduce((sum, value)=>sum + value, 0);
+    for(let i = 0; i < remainder; i++)whole[order[i]]++;
+    const shares = new Map(others.map((arm, i)=>[
+            arm.key,
+            whole[i]
+        ]));
+    return setWeight(arms, key, weight).map((arm)=>shares.has(arm.key) ? {
+            ...arm,
+            weight: shares.get(arm.key)
+        } : arm);
+}

package/dist/admin/surface/testDocument.model.d.ts

@@ -0,0 +1,39 @@
+import type { EditableField } from '../../types/admin.js';
+import type { Arm, DocId, ExperimentKind, ExposurePolicy, Status, TargetingRule, UnitType } from '../../types/contracts.js';
+/** The depth-zero collection document, including fields owned by the server. */
+export interface TestDocument {
+    id: DocId;
+    name: string;
+    slug: string;
+    status: Status;
+    kind: ExperimentKind;
+    unitType: UnitType;
+    hypothesis?: string | null;
+    arms: Arm[];
+    targeting?: TargetingRule[] | null;
+    allocation: number;
+    flagPoint?: string | null;
+    exposurePolicy: ExposurePolicy;
+    metrics?: {
+        primary?: DocId | null;
+        secondary?: DocId[] | null;
+        guardrails?: DocId[] | null;
+    } | null;
+    analysis?: {
+        method?: 'sequential' | 'bayesian' | null;
+        cuped?: 'auto' | 'off' | null;
+        minExposuresPerArm?: number | null;
+        plannedDurationDays?: number | null;
+        attributionWindowHours?: number | null;
+        sequentialTuningParameter?: number | null;
+        reachPerDay?: number | null;
+    } | null;
+    [key: string]: unknown;
+}
+export type TestDocumentPatch = Partial<Pick<TestDocument, EditableField>>;
+/** Drop unknown and locked keys even when the caller is untyped. Groups replace whole groups. */
+export declare function editablePatch(status: Status, partial: TestDocumentPatch): TestDocumentPatch;
+/** Only changed top-level keys go on the wire; arrays and groups remain intact. */
+export declare function changedPatch(saved: TestDocument, staged: TestDocumentPatch): TestDocumentPatch;
+/** Payload validation details may be nested under errors[0].data or top-level data. */
+export declare function payloadFieldErrors(envelope: unknown, section?: string, fallback?: string): Record<string, string>;