@aglyn/aglyn 1.0.0-beta.217 → 1.0.0-beta.219

package/src/lib/app-utils/site-interactions.js

@@ -0,0 +1,554 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { resolveAuthoredEventName, sanitizeEventParams } from "./analytics-events.js";
+import { sanitizeAuthorHtml } from "./author-html.js";
+import { PLUGIN_INTERACTION_STEPS_DECLARED } from "../plugin-manager/first-party-plugins.generated.js";
+/**
+ * SITE INTERACTIONS: what a published page does when a visitor does something.
+ *
+ * An interaction is a trigger and an ordered step list. The trigger names an
+ * event — a SITE event the page runtime watches for itself (a click, a hover,
+ * an element scrolled into view, exit intent), or an event raised on the
+ * server — narrowed by payload conditions and capped in how often it fires.
+ * The steps the platform knows are the ones a page carries out in the
+ * visitor's own browser: showing and hiding elements, opening menus and
+ * drawers, classes and ARIA attributes, scrolling, playing a video, an alert,
+ * a redirect, an analytics event, author HTML and script.
+ *
+ * An interaction is stored on the element that carries it
+ * (`node-interactions.ts`) or as a row of `hosts/{hostId}/actions`, and the
+ * same shape holds more than the platform's own steps. A plugin adds steps of
+ * its own — the workflows plugin's server steps, which a page hands to
+ * `/api/events/dispatch` for the host-event listener that owns them. The
+ * platform types only its own steps ({@link ClientInteractionStep}), knows any
+ * other step only by its `type`, and treats every step that is not one of its
+ * client steps as the server's to run. A plugin that wants one of its steps
+ * offered in the interaction builder DECLARES it, under `interactionSteps` in
+ * `plugins.config.json` ({@link InteractionStepDeclaration}); nothing here
+ * names a plugin.
+ */ /**
+ * Client-side site events (AGL-256) the tenant page runtime emits:
+ * element interactions, scroll behavior, dwell time, and exit intent.
+ * Trigger config (selector/threshold/path) rides the interaction's trigger.
+ */ export const SITE_EVENT_TYPES = [
+    'scrollDepth',
+    'scrollToElement',
+    'elementClick',
+    'elementVisible',
+    // Hover choreography (AGL-562): delegated enter/leave on the trigger
+    // selector — the nav-menu/drawer show-hide building blocks.
+    'elementHoverEnter',
+    'elementHoverLeave',
+    'exitIntent',
+    'timeOnPage',
+    'pageVisit'
+];
+/** Site events that watch a specific element and need a selector. */ export const ELEMENT_SCOPED_SITE_EVENTS = [
+    'scrollToElement',
+    'elementClick',
+    'elementVisible',
+    'elementHoverEnter',
+    'elementHoverLeave'
+];
+export function isSiteEventType(event) {
+    return SITE_EVENT_TYPES.includes(event);
+}
+/** Structured condition operators (AGL-557). */ export const TRIGGER_CONDITION_OPS = [
+    'equals',
+    'contains',
+    'notEmpty'
+];
+/**
+ * Evaluates a structured trigger condition (AGL-557). String-coerces the
+ * payload value; `equals`/`contains` compare trimmed + case-insensitive
+ * so checkbox values like "Yes" match an author-typed "yes". A missing
+ * field never matches (and is "empty" for `notEmpty`); an absent or
+ * field-less condition always passes, mirroring the filter's default.
+ */ export function evaluateTriggerCondition(condition, payload) {
+    var _condition_value;
+    var _condition_field;
+    const field = condition == null ? void 0 : (_condition_field = condition.field) == null ? void 0 : _condition_field.trim();
+    if (!condition || !field) return true;
+    const raw = (payload != null ? payload : {})[field];
+    const actual = (raw == null ? '' : String(raw)).trim().toLowerCase();
+    if (condition.op === 'notEmpty') return actual.length > 0;
+    const expected = String((_condition_value = condition.value) != null ? _condition_value : '').trim().toLowerCase();
+    if (condition.op === 'equals') return actual === expected;
+    if (condition.op === 'contains') {
+        return expected.length > 0 && actual.includes(expected);
+    }
+    return false;
+}
+/** How chained trigger conditions combine (AGL-565). */ export const TRIGGER_COMBINATORS = [
+    'and',
+    'or'
+];
+/** Cap on chained conditions per trigger (AGL-565). */ export const ACTION_MAX_CONDITIONS = 5;
+/**
+ * Normalizes a trigger's condition clauses to a list (AGL-565): the
+ * `conditions` array wins when present; a legacy single `condition`
+ * (AGL-557) becomes a one-element list. Read-time only — persisted docs
+ * are never migrated, so pre-565 single-condition docs keep working
+ * unchanged.
+ */ export function normalizeTriggerConditions(trigger) {
+    const conditions = trigger == null ? void 0 : trigger.conditions;
+    if (Array.isArray(conditions)) return conditions.filter(Boolean);
+    return (trigger == null ? void 0 : trigger.condition) ? [
+        trigger.condition
+    ] : [];
+}
+/**
+ * Evaluates a trigger's condition list with its combinator (AGL-565):
+ * `and` (the default) requires every condition to pass, `or` any one.
+ * Per-condition semantics are unchanged from AGL-557
+ * (`evaluateTriggerCondition`), and an empty list always passes — which
+ * covers every pre-565 doc without conditions.
+ */ export function evaluateTriggerConditions(trigger, payload) {
+    const conditions = normalizeTriggerConditions(trigger);
+    if (!conditions.length) return true;
+    return (trigger == null ? void 0 : trigger.combinator) === 'or' ? conditions.some((condition)=>evaluateTriggerCondition(condition, payload)) : conditions.every((condition)=>evaluateTriggerCondition(condition, payload));
+}
+/**
+ * Evaluates a step's own guard, with the trigger's semantics.
+ *
+ * An absent or clause-less guard passes, exactly as an absent trigger
+ * condition does — so every step written before guards existed keeps running.
+ */ export function evaluateStepGuard(guard, scope) {
+    var _ref;
+    const conditions = ((_ref = guard == null ? void 0 : guard.conditions) != null ? _ref : []).filter(Boolean);
+    if (!conditions.length) return true;
+    return (guard == null ? void 0 : guard.combinator) === 'or' ? conditions.some((condition)=>evaluateTriggerCondition(condition, scope)) : conditions.every((condition)=>evaluateTriggerCondition(condition, scope));
+}
+/** Steps the tenant page runtime executes client-side (AGL-257). */ export const CLIENT_ACTION_STEP_TYPES = new Set([
+    'showOverlay',
+    'stickyNav',
+    'addClass',
+    'removeClass',
+    'toggleClass',
+    'showElement',
+    'hideElement',
+    'toggleElement',
+    'openDrawer',
+    'closeDrawer',
+    'toggleDrawer',
+    'openMenu',
+    'closeMenu',
+    'toggleMenu',
+    'setAttribute',
+    'removeAttribute',
+    'scrollTo',
+    'playVideo',
+    'showHtml',
+    'runJs',
+    'redirect',
+    'trackGaEvent',
+    'siteAlert'
+]);
+export function isClientActionStep(step) {
+    return CLIENT_ACTION_STEP_TYPES.has(step.type);
+}
+/**
+ * Basic presentational interactions (AGL-577): the subset of client steps
+ * that are pure DOM choreography — menu/drawer open-close, element
+ * show/hide, class toggles, sticky nav, navigation, and client-only
+ * alerts. They carry NO server cost and touch NO data, so they run on
+ * every plan (the `interactions` feature, on by default everywhere).
+ *
+ * The powerful client steps stay behind the `actions` entitlement:
+ * `showOverlay` (marketing overlays), `showHtml` (arbitrary HTML
+ * injection), and `trackGaEvent` (analytics). `runJs` keeps its own
+ * higher `webhooks` (Business) gate. A step that is not a client step is
+ * the server's, and is re-checked against `actions` where it runs.
+ */ export const BASIC_CLIENT_ACTION_STEP_TYPES = new Set([
+    'stickyNav',
+    'addClass',
+    'removeClass',
+    'toggleClass',
+    'showElement',
+    'hideElement',
+    'toggleElement',
+    'openDrawer',
+    'closeDrawer',
+    'toggleDrawer',
+    'openMenu',
+    'closeMenu',
+    'toggleMenu',
+    'setAttribute',
+    'removeAttribute',
+    // Moving the page and pressing a player the author placed: no data, no
+    // server, and nothing a Video element's own poster does not already do
+    // on every plan.
+    'scrollTo',
+    'playVideo',
+    'redirect',
+    'siteAlert'
+]);
+/** A client step available on all plans (no `actions` entitlement). */ export function isBasicClientActionStep(step) {
+    return BASIC_CLIENT_ACTION_STEP_TYPES.has(step.type);
+}
+/**
+ * Whether a client step may run for the given entitlement tier (AGL-577).
+ * This is the single source of truth the page enricher uses to trim the
+ * client-automation payload per plan:
+ *
+ * - Basic presentational steps → always (every plan).
+ * - `runJs` → `allowJs` (Business `webhooks` tier).
+ * - Remaining advanced client steps (overlay / showHtml / analytics) →
+ *   `actionsEntitled` (`actions` tier).
+ *
+ * Server steps are not client steps and always return false here; they
+ * are dispatched and re-authorized server-side.
+ */ export function isClientStepEntitled(step, entitlements) {
+    if (!isClientActionStep(step)) return false;
+    if (isBasicClientActionStep(step)) return true;
+    if (step.type === 'runJs') return entitlements.allowJs;
+    return entitlements.actionsEntitled;
+}
+/** The longest step list an interaction may hold. */ export const ACTION_MAX_STEPS = 10;
+/**
+ * Cap on the parameters one `trackGaEvent` step may carry (AGL-1587).
+ *
+ * Not a storage concern. These pairs are the least trustworthy analytics
+ * input on the platform — both halves are typed by a site author and land in
+ * that site's own GA4 property — and a bounded list is one an author can read
+ * back in full before publishing, which is the only review a parameter ever
+ * gets. GA4 caps custom parameters per event as well and drops the overflow
+ * without saying so, so an unbounded editor would let an author configure
+ * parameters that are never delivered and never explained. Ten, the same
+ * ceiling {@link ACTION_MAX_STEPS} puts on the step list itself.
+ */ export const ACTION_MAX_EVENT_PARAMS = 10;
+/**
+ * Longest analytics parameter NAME GA4 accepts; it drops a longer one on
+ * arrival, so a name over this is silence rather than a truncated dimension.
+ * The value half is capped by `ANALYTICS_PARAM_MAX_LENGTH`, which truncates
+ * instead of dropping.
+ */ export const ACTION_EVENT_PARAM_NAME_MAX_LENGTH = 40;
+/** Self-dismiss triggers for shown elements (AGL-589). */ export const ELEMENT_DISMISS_OPTIONS = [
+    'escape',
+    'outsideClick'
+];
+/** Visibility grace-delay ceiling — enough for hover travel, no dead UIs. */ export const ELEMENT_VISIBILITY_MAX_DELAY_MS = 5000;
+/**
+ * How a `scrollTo` step moves the page. Stored in documents; never rename a
+ * value. `instant` rather than the DOM's `auto`, because `auto` defers to the
+ * site's CSS `scroll-behavior` — a site that sets `smooth` there would animate
+ * a scroll the author asked to be instant.
+ */ export const SCROLL_TO_BEHAVIORS = [
+    'smooth',
+    'instant'
+];
+/**
+ * The largest offset a `scrollTo` step may leave above its target.
+ *
+ * The offset exists to clear a sticky header, which is tens of pixels and
+ * rarely more than a few hundred with an announcement bar stacked on it. A
+ * thousand leaves room for any header while still refusing the extra digit
+ * that would park the target off the bottom of the screen.
+ */ export const SCROLL_TO_MAX_OFFSET_PX = 1000;
+/** Custom event names: short, no collision with built-ins. */ export const CUSTOM_EVENT_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{1,39}$/;
+/**
+ * The attribute names an interaction may write (AGL-2546).
+ *
+ * An unrestricted attribute setter is a self-XSS vector authored through the
+ * interactions UI: it reaches `href`, `src`, `onclick`, `formaction` and
+ * `style`, and on a site with collaborators the author and the victim need
+ * not be the same person. `aria-*` and `data-*` carry the entire
+ * accessibility use case and none of that exposure.
+ *
+ * Deliberately NOT solved by an entitlement gate. `runJs` is Business-gated
+ * because it is dangerous at any tier; this has to work on every plan,
+ * because a screen-reader user's access to a menu is not a paid feature.
+ */ export const INTERACTION_ATTRIBUTE_NAME_PATTERN = /^(?:aria|data)-[a-z][a-z0-9-]*$/;
+/**
+ * Whether an interaction is allowed to write this attribute name.
+ *
+ * Case-insensitive because HTML attribute names are, and a rejected name is
+ * a no-op rather than an error: a step that cannot run must not break the
+ * steps after it in the same interaction.
+ */ export function isInteractionAttributeAllowed(name) {
+    return typeof name === 'string' && INTERACTION_ATTRIBUTE_NAME_PATTERN.test(name.trim().toLowerCase());
+}
+/** Every step the first-party plugins declare, in `plugins.config.json` order. */ export function declaredInteractionSteps() {
+    return PLUGIN_INTERACTION_STEPS_DECLARED;
+}
+/** The declared step of this type, or `null` for one no plugin declares. */ export function declaredInteractionStep(type, declarations = PLUGIN_INTERACTION_STEPS_DECLARED) {
+    var _declarations_find;
+    return (_declarations_find = declarations.find((declaration)=>declaration.type === type)) != null ? _declarations_find : null;
+}
+/**
+ * Validates an interaction's shape; returns a human-readable error or null.
+ * Every surface that writes one shares this, so a bad step never persists or
+ * runs.
+ *
+ * The platform checks what is its own: the name, the trigger and its
+ * conditions, the step count, each step's guard, its client steps, and the
+ * pick of every declared step that picks a record. A step it does not know is
+ * left to its owner, through `validateStep`.
+ */ export function validateInteraction(interaction, options = {}) {
+    var _ref, _interaction_steps;
+    var _interaction_name, _interaction_trigger_event, _interaction_trigger, _interaction_trigger_selector, _interaction_trigger1, _interaction_trigger2, _interaction_trigger3, _interaction_trigger4;
+    if (!((_interaction_name = interaction.name) == null ? void 0 : _interaction_name.trim())) return 'Name the action';
+    const event = (_ref = (_interaction_trigger = interaction.trigger) == null ? void 0 : (_interaction_trigger_event = _interaction_trigger.event) == null ? void 0 : _interaction_trigger_event.trim()) != null ? _ref : '';
+    if (!event) return 'Pick a trigger event';
+    // A server event or a custom one fired by another step is, like a site
+    // event, a name; every built-in server event fits the custom pattern.
+    if (!isSiteEventType(event) && !CUSTOM_EVENT_PATTERN.test(event)) {
+        return 'Custom event names are 2–40 letters, digits, dashes';
+    }
+    // Site-event trigger config (AGL-256; hover events AGL-562).
+    if (ELEMENT_SCOPED_SITE_EVENTS.includes(event) && !((_interaction_trigger1 = interaction.trigger) == null ? void 0 : (_interaction_trigger_selector = _interaction_trigger1.selector) == null ? void 0 : _interaction_trigger_selector.trim())) {
+        return 'This trigger needs a CSS selector';
+    }
+    if ([
+        'scrollDepth',
+        'timeOnPage'
+    ].includes(event) && !(Number((_interaction_trigger2 = interaction.trigger) == null ? void 0 : _interaction_trigger2.threshold) > 0)) {
+        return event === 'scrollDepth' ? 'Set the scroll percentage (1–100)' : 'Set the seconds on page';
+    }
+    // Frequency caps (AGL-274).
+    if (((_interaction_trigger3 = interaction.trigger) == null ? void 0 : _interaction_trigger3.cooldownMinutes) != null && !(Number(interaction.trigger.cooldownMinutes) >= 1)) {
+        return 'Cooldown must be at least 1 minute';
+    }
+    // Structured payload conditions (AGL-557; chained AGL-565).
+    const combinator = (_interaction_trigger4 = interaction.trigger) == null ? void 0 : _interaction_trigger4.combinator;
+    if (combinator != null && !TRIGGER_COMBINATORS.includes(combinator)) {
+        return 'Combine conditions with AND or OR';
+    }
+    const conditions = normalizeTriggerConditions(interaction.trigger);
+    if (conditions.length > ACTION_MAX_CONDITIONS) {
+        return `Conditions are capped at ${ACTION_MAX_CONDITIONS}`;
+    }
+    for (const [index, condition] of conditions.entries()){
+        var _condition_field, _condition_value;
+        // Single-condition messages stay exactly as AGL-557 shipped them;
+        // the row marker only appears once there are rows to tell apart.
+        const where = conditions.length > 1 ? ` (condition ${index + 1})` : '';
+        if (!TRIGGER_CONDITION_OPS.includes(condition.op)) {
+            return `Pick a condition operator${where}`;
+        }
+        if (!((_condition_field = condition.field) == null ? void 0 : _condition_field.trim())) {
+            return `Name the field the condition checks${where}`;
+        }
+        if (condition.op !== 'notEmpty' && !((_condition_value = condition.value) == null ? void 0 : _condition_value.trim())) {
+            return `Enter the value the condition compares against${where}`;
+        }
+    }
+    const steps = (_interaction_steps = interaction.steps) != null ? _interaction_steps : [];
+    if (!steps.length) return 'Add at least one step';
+    if (steps.length > ACTION_MAX_STEPS) {
+        return `Actions are capped at ${ACTION_MAX_STEPS} steps`;
+    }
+    for (const [index, step] of steps.entries()){
+        var _ref1;
+        var _step_when, _step_when1;
+        const label = `Step ${index + 1}`;
+        // A step's own guard, checked with the same messages the trigger's
+        // clauses get — one condition editor, one set of complaints about it.
+        const guardClauses = ((_ref1 = (_step_when = step.when) == null ? void 0 : _step_when.conditions) != null ? _ref1 : []).filter(Boolean);
+        if (guardClauses.length > ACTION_MAX_CONDITIONS) {
+            return `${label}: conditions are capped at ${ACTION_MAX_CONDITIONS}`;
+        }
+        if (((_step_when1 = step.when) == null ? void 0 : _step_when1.combinator) != null && !TRIGGER_COMBINATORS.includes(step.when.combinator)) {
+            return `${label}: combine conditions with AND or OR`;
+        }
+        for (const clause of guardClauses){
+            var _clause_field, _clause_value;
+            if (!TRIGGER_CONDITION_OPS.includes(clause.op)) {
+                return `${label}: pick a condition operator`;
+            }
+            if (!((_clause_field = clause.field) == null ? void 0 : _clause_field.trim())) {
+                return `${label}: name the field the condition checks`;
+            }
+            if (clause.op !== 'notEmpty' && !((_clause_value = clause.value) == null ? void 0 : _clause_value.trim())) {
+                return `${label}: enter the value the condition compares against`;
+            }
+        }
+        const owned = options.validateStep == null ? void 0 : options.validateStep.call(options, step, label);
+        if (owned) return owned;
+        const declared = declaredInteractionStep(step.type, options.declarations);
+        if (declared == null ? void 0 : declared.picks) {
+            const id = step[declared.picks.idField];
+            const name = step[declared.picks.nameField];
+            if (!(typeof id === 'string' && id.trim()) && !(typeof name === 'string' && name.trim())) {
+                return `${label}: ${declared.picks.missing}`;
+            }
+        }
+        if (isClientActionStep(step)) {
+            const problem = clientStepProblem(step, label);
+            if (problem) return problem;
+        }
+    }
+    return null;
+}
+/** A client step's own complaint, or null. The step's guard is checked by the caller. */ function clientStepProblem(step, label) {
+    var _step_message, _step_selector, _step_selector1, _step_code, _step_url;
+    if (step.type === 'siteAlert' && !((_step_message = step.message) == null ? void 0 : _step_message.trim())) {
+        return `${label}: enter the alert message`;
+    }
+    if (step.type === 'addClass' || step.type === 'removeClass' || step.type === 'toggleClass') {
+        var _step_selector2, _step_className;
+        if (!((_step_selector2 = step.selector) == null ? void 0 : _step_selector2.trim())) return `${label}: enter a CSS selector`;
+        if (!((_step_className = step.className) == null ? void 0 : _step_className.trim())) return `${label}: enter the class name`;
+    }
+    // Element show/hide steps (AGL-562) always target a selector; drawer
+    // (AGL-562) and menu (AGL-568) commands may omit the target (the
+    // page's first drawer/menu answers).
+    if ((step.type === 'showElement' || step.type === 'hideElement' || step.type === 'toggleElement') && !((_step_selector = step.selector) == null ? void 0 : _step_selector.trim())) {
+        return `${label}: pick the element to show or hide`;
+    }
+    if (step.type === 'showElement' || step.type === 'hideElement' || step.type === 'toggleElement') {
+        // Choreography options (AGL-589).
+        const delay = step.delayMs;
+        if (delay != null && !(Number.isInteger(delay) && delay >= 0 && delay <= ELEMENT_VISIBILITY_MAX_DELAY_MS)) {
+            return `${label}: delay must be 0–${ELEMENT_VISIBILITY_MAX_DELAY_MS}ms`;
+        }
+        const dismiss = step.dismissOn;
+        if (dismiss != null && !(Array.isArray(dismiss) && dismiss.every((option)=>ELEMENT_DISMISS_OPTIONS.includes(option)))) {
+            return `${label}: dismiss options are escape and outsideClick`;
+        }
+    }
+    // One-target steps (AGL-2867). The runtime does nothing for a target it
+    // cannot find, so a missing one is refused here, where it can be fixed.
+    if (step.type === 'scrollTo') {
+        var _step_selector3;
+        if (!((_step_selector3 = step.selector) == null ? void 0 : _step_selector3.trim())) {
+            return `${label}: pick the element to scroll to`;
+        }
+        const behavior = step.behavior;
+        if (behavior != null && !SCROLL_TO_BEHAVIORS.includes(behavior)) {
+            return `${label}: scroll smoothly or instantly`;
+        }
+        const offset = step.offsetPx;
+        if (offset != null && !(Number.isInteger(offset) && offset >= 0 && offset <= SCROLL_TO_MAX_OFFSET_PX)) {
+            return `${label}: the offset must be 0–${SCROLL_TO_MAX_OFFSET_PX}px`;
+        }
+    }
+    if (step.type === 'playVideo' && !((_step_selector1 = step.selector) == null ? void 0 : _step_selector1.trim())) {
+        return `${label}: pick the video to play`;
+    }
+    if (step.type === 'showHtml') {
+        var _step_html;
+        if (!((_step_html = step.html) == null ? void 0 : _step_html.trim())) return `${label}: enter the HTML`;
+        // AGL-2486: the author-facing half of the runtime sanitizer, exactly as
+        // the reserved analytics name below is the author-facing half of the
+        // runtime refusal. `site-runtime.tsx` runs this HTML through
+        // `sanitizeAuthorHtml` for a VISITOR, where the only thing it can do
+        // with markup it refuses is drop it and say nothing — so an author who
+        // pastes an embed snippet gets a step that runs, reports success, and
+        // shows nothing. The refusal is reported HERE, where the person who
+        // can fix it is looking, and it is the SAME function that will run at
+        // render rather than a second description of its rules.
+        const removals = [];
+        const safe = sanitizeAuthorHtml(step.html, removals);
+        if (!safe.trim()) {
+            var _ref;
+            var _removals_;
+            return `${label}: none of this HTML can be shown on a published page — ${(_ref = (_removals_ = removals[0]) == null ? void 0 : _removals_.message) != null ? _ref : 'it is removed by the sanitizer.'}`;
+        }
+        if (removals.length) {
+            return `${label}: ${removals[0].message}${removals.length > 1 ? ` (+${removals.length - 1} more)` : ''}`;
+        }
+    }
+    if (step.type === 'runJs' && !((_step_code = step.code) == null ? void 0 : _step_code.trim())) {
+        return `${label}: enter the JavaScript`;
+    }
+    if (step.type === 'redirect' && !((_step_url = step.url) == null ? void 0 : _step_url.trim()) && !step.screenId) {
+        return `${label}: pick a page or enter the destination URL`;
+    }
+    if (step.type === 'trackGaEvent') {
+        var _step_params, _step_params1;
+        var _step_eventName;
+        if (!((_step_eventName = step.eventName) == null ? void 0 : _step_eventName.trim())) {
+            return `${label}: name the analytics event`;
+        }
+        // AGL-1587: the author-facing half of the runtime refusal. The runtime
+        // can only drop a bad name silently — it is executing for a VISITOR —
+        // so the name is checked HERE, where the person who can fix it is.
+        const resolved = resolveAuthoredEventName(step.eventName);
+        if (resolved.reason === 'reserved') {
+            return `${label}: "${step.eventName.trim()}" is a reserved analytics event name — pick another`;
+        }
+        if (!resolved.name) {
+            return `${label}: the analytics event name must start with a letter`;
+        }
+        const params = Object.entries((_step_params = step.params) != null ? _step_params : {});
+        if (params.length > ACTION_MAX_EVENT_PARAMS) {
+            return `${label}: analytics parameters are capped at ${ACTION_MAX_EVENT_PARAMS}`;
+        }
+        for (const [key, value] of params){
+            if (!key.trim()) return `${label}: name every analytics parameter`;
+            if (key.trim().length > ACTION_EVENT_PARAM_NAME_MAX_LENGTH) {
+                return `${label}: the "${key.trim().slice(0, 16)}…" parameter name is over ${ACTION_EVENT_PARAM_NAME_MAX_LENGTH} characters, which GA4 drops`;
+            }
+            if (!String(value != null ? value : '').trim()) {
+                return `${label}: enter a value for the "${key.trim()}" parameter`;
+            }
+        }
+        // The author-facing half of the runtime sanitizer, the same shape the
+        // reserved name above and the `showHtml` check take. `trackAuthoredEvent`
+        // strips a parameter that can carry personal data and says nothing about
+        // it, because it is executing for a VISITOR — so an author who binds a
+        // form field into a parameter gets a step that runs, reports success,
+        // and delivers an event missing the dimension it was created for. The
+        // strip is reported HERE, by running the REAL `sanitizeEventParams`
+        // rather than a second description of its rules, so the two can never
+        // disagree about which parameter survives.
+        const kept = sanitizeEventParams((_step_params1 = step.params) != null ? _step_params1 : undefined);
+        const stripped = params.find(([key])=>!(key in kept));
+        if (stripped) {
+            return `${label}: the "${stripped[0]}" parameter is never sent — an analytics parameter must not carry a visitor's own details`;
+        }
+    }
+    return null;
+}
+/**
+ * How many LIVE action documents one host may hold (AGL-2266).
+ *
+ * `hosts/{hostId}/actions` was in NO exclusion list in
+ * `cloud/firebase-firestore.rules`, so the host catch-all's `allow create`
+ * granted it to any editor, client-direct, on any plan — and the import
+ * route's own table said so in as many words: *"no `RESOURCES` entry and no
+ * quota key anywhere; all three creators write the document client-direct."*
+ * A free org could therefore mint unbounded Firestore documents from the
+ * browser against a $0 subscription. Unbounded infrastructure, not a bypass of
+ * anything we sell, which is `WEBHOOK_MAX_PER_HOST`'s (AGL-1360) and
+ * `NON_PAGE_SCREEN_MAX_PER_HOST`'s (AGL-1399) shape exactly: a flat PLATFORM
+ * cap with no `OrgEntitlements` key, no variation by plan, and nothing on the
+ * price list to explain.
+ *
+ * ## Not gated on the `actions` entitlement, deliberately
+ *
+ * `actions` is a Pro feature and `interactions` is free, and BOTH write this
+ * collection — the interaction builder and the besigner's preset wiring create
+ * the same document type the Pro actions card does. Gating creation on the
+ * paid flag would take element interactions away from every free and starter
+ * site, which is a pricing change wearing a cap's clothes. The runtime already
+ * checks the entitlement where it decides what may RUN
+ * (`run-event-actions.ts`), which is the right place for it.
+ *
+ * ## Why 500
+ *
+ * Sized to the busiest plausible site rather than to today's data. An action
+ * is authored per interactive element, so a heavy marketing site with dropdown
+ * choreography on every section reaches tens; presets wire a handful at a
+ * time. 500 is far past anything authoring produces and well short of what a
+ * script in a loop wants, which is the only property a flat cap needs. Live
+ * documents only — the interactions provider soft-deletes with `deletedAt`, so
+ * counting tombstones would be AGL-1173's bug one collection over, where
+ * removing an interaction never frees its slot.
+ */ export const ACTIONS_MAX_PER_HOST = 500;
+
+//# sourceMappingURL=site-interactions.js.map