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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.217",
+  "version": "1.0.0-beta.219",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -33,26 +33,26 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.217",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.217",
-    "@aglyn/shared-data-types": "1.0.0-beta.217",
-    "@aglyn/shared-util-email": "1.0.0-beta.217",
-    "@aglyn/shared-util-first-touch": "1.0.0-beta.217",
-    "@aglyn/shared-util-http": "1.0.0-beta.217",
-    "@aglyn/shared-util-logger": "1.0.0-beta.217",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.217",
-    "@aglyn/shared-util-tools": "1.0.0-beta.217",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.217",
+    "@aglyn/shared-data-enums": "1.0.0-beta.219",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.219",
+    "@aglyn/shared-data-types": "1.0.0-beta.219",
+    "@aglyn/shared-util-email": "1.0.0-beta.219",
+    "@aglyn/shared-util-first-touch": "1.0.0-beta.219",
+    "@aglyn/shared-util-http": "1.0.0-beta.219",
+    "@aglyn/shared-util-logger": "1.0.0-beta.219",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.219",
+    "@aglyn/shared-util-tools": "1.0.0-beta.219",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.219",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",
     "acorn": "^8.18.0",
     "eventemitter2": "^6.4.9",
     "lodash-es": "^4.18.1",
-    "mobx": "^6.16.1",
-    "mobx-state-tree": "^7.3.2",
+    "mobx": "^7.0.5",
+    "mobx-state-tree": "^8.0.0",
     "nanoid": "^6.0.1",
-    "web-vitals": "^6.1.1"
+    "web-vitals": "^6.2.2"
   },
   "peerDependencies": {
     "@mui/material": "^9.3.1",

package/src/lib/app-utils/actions.d.ts

@@ -15,136 +15,27 @@
  * limitations under the License.
  */
 import { type ContactLifecycleStage, type CrmActivityKind, type CrmTaskKind } from './crm-kinds';
+import { type ClientInteractionStep, type InteractionCondition, type InteractionStepGuard, type InteractionTrigger, type SiteAlert, type SiteInteraction, type TriggerCombinator } from './site-interactions';
 /**
  * Actions builder (AGL-148): HubSpot-style event → action automation on
  * top of the AGL-128 event triggers. An action listens for a host event
  * (built-in or a custom name fired by another action), optionally filters
  * on the payload, and runs an ordered step list. Pure types + validation
- * here; the executor lives server-side where the I/O is (tenant utils).
- */
-/**
- * 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 action's trigger.
- */
-export declare const SITE_EVENT_TYPES: readonly ["scrollDepth", "scrollToElement", "elementClick", "elementVisible", "elementHoverEnter", "elementHoverLeave", "exitIntent", "timeOnPage", "pageVisit"];
-/** Site events that watch a specific element and need a selector. */
-export declare const ELEMENT_SCOPED_SITE_EVENTS: readonly ["scrollToElement", "elementClick", "elementVisible", "elementHoverEnter", "elementHoverLeave"];
-export type SiteEventType = (typeof SITE_EVENT_TYPES)[number];
-export declare function isSiteEventType(event: string): event is SiteEventType;
-/** Structured condition operators (AGL-557). */
-export declare const TRIGGER_CONDITION_OPS: readonly ["equals", "contains", "notEmpty"];
-export type TriggerConditionOp = (typeof TRIGGER_CONDITION_OPS)[number];
-/**
- * Structured per-action condition over the event payload (AGL-557): the
- * no-code sibling of the free-text `filter` expression, e.g. "only run
- * when the `subscribe` field is not empty". Evaluated against the same
- * scope as the filter (event name + payload fields); the action is
- * skipped when unmet.
- */
-export interface HostActionTriggerCondition {
-    /** Payload field the condition reads (a submitted form field name). */
-    field: string;
-    op: TriggerConditionOp;
-    /** Comparison value for `equals`/`contains`; unused by `notEmpty`. */
-    value?: string;
-}
-/**
- * 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 declare function evaluateTriggerCondition(condition: HostActionTriggerCondition | undefined | null, payload: Record<string, unknown>): boolean;
-/** How chained trigger conditions combine (AGL-565). */
-export declare const TRIGGER_COMBINATORS: readonly ["and", "or"];
-export type TriggerCombinator = (typeof TRIGGER_COMBINATORS)[number];
-/** Cap on chained conditions per trigger (AGL-565). */
-export declare 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 declare function normalizeTriggerConditions(trigger: Pick<HostActionTrigger, 'condition' | 'conditions'> | undefined | null): HostActionTriggerCondition[];
-/**
- * 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 declare function evaluateTriggerConditions(trigger: Pick<HostActionTrigger, 'condition' | 'conditions' | 'combinator'> | undefined | null, payload: Record<string, unknown>): boolean;
-export interface HostActionTrigger {
-    /**
-     * Event the action enrolls on: a HOST_EVENT_TYPE (server-emitted), a
-     * SITE_EVENT_TYPE (client-emitted, AGL-256), or a custom name fired by
-     * another action's `customEvent` step.
-     */
-    event: string;
-    /** Optional expression over the payload; runs only when truthy. */
-    filter?: string;
-    /** Optional structured payload condition (AGL-557); null clears it. */
-    condition?: HostActionTriggerCondition | null;
-    /**
-     * Chained payload conditions (AGL-565), combined with `combinator`.
-     * When present this list wins over the legacy single `condition`
-     * (see `normalizeTriggerConditions`); null clears it.
-     */
-    conditions?: HostActionTriggerCondition[] | null;
-    /** How the chained conditions combine (AGL-565); default `and`. */
-    combinator?: TriggerCombinator | null;
-    /** CSS selector for element-scoped site events (click/visible/scroll-to). */
-    selector?: string;
-    /** Percent 0-100 (scrollDepth) or seconds (timeOnPage). */
-    threshold?: number;
-    /** Path pattern the site event listens on (overlay glob rules); empty = all. */
-    pathPattern?: string;
-    /**
-     * Fire at most once per visitor (AGL-266, localStorage-keyed) instead
-     * of once per pageview. Site events only.
-     */
-    oncePerVisitor?: boolean;
-    /**
-     * Fire at most once per browser session (AGL-274,
-     * sessionStorage-keyed). Site events only.
-     */
-    oncePerSession?: boolean;
-    /**
-     * Minimum minutes between fires for the same visitor (AGL-274,
-     * localStorage timestamp). Site events only; ignored when
-     * `oncePerVisitor` is set.
-     */
-    cooldownMinutes?: number;
-    /**
-     * Fire on EVERY occurrence instead of once per pageview (AGL-562) —
-     * required for repeatable UI choreography (menu toggles, drawer
-     * open/close, hover show/hide). Site events only; the explicit
-     * per-session/visitor/cooldown caps above still win when set.
-     */
-    everyTime?: boolean;
-}
-/**
- * A per-STEP condition, and the difference between an automation and a flow.
- *
- * `HostActionTrigger.conditions` gates the whole action: every step runs or
- * none does. That is enough for "when a form is submitted, do these three
- * things" and not enough for anything with a shape — "wait three days, then,
- * only if they have not ordered, send the reminder" needs the condition to
- * belong to the step rather than to the run.
+ * here; the executor lives in the workflows plugin, where the I/O is.
  *
- * Same clause type and the same combinator as the trigger's, evaluated
- * against the same scope, so an author learns one condition editor and the
- * two can never disagree about what `contains` means.
- */
-export interface HostActionStepGuard {
-    conditions: HostActionTriggerCondition[];
-    /** How the clauses combine; default `and`, as on the trigger. */
-    combinator?: TriggerCombinator | null;
-}
+ * An action is a SITE INTERACTION (`site-interactions.ts`) with server steps
+ * added: its trigger, its conditions, its client steps and its storage are
+ * the platform's, and are re-exported here for the readers that take both
+ * from this module. What is declared below is the automation's own — the
+ * server steps, flows, recipes and webhooks.
+ */
+export * from './site-interactions';
+/** The automation's names for the platform's interaction shapes. */
+export type HostActionTriggerCondition = InteractionCondition;
+export type HostActionTrigger = InteractionTrigger;
+export type HostActionStepGuard = InteractionStepGuard;
+/** Alert produced by a `siteAlert` step, surfaced to the emitting client. */
+export type HostActionAlert = SiteAlert;
 /**
  * The scope key a resumed flow carries to say the wait ended on the CLOCK
  * rather than on the event it was watching for.
@@ -155,21 +46,11 @@ export interface HostActionStepGuard {
  * event payload's own fields, which are merchant-authored form field names.
  */
 export declare const FLOW_TIMED_OUT_FIELD = "_waitTimedOut";
-/**
- * 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 declare function evaluateStepGuard(guard: HostActionStepGuard | undefined | null, scope: Record<string, unknown>): boolean;
-export type HostActionStep = ({
+/** The steps an automation adds to the platform's client steps: the server's, run by the workflows plugin. */
+type ServerActionStep = ({
     type: 'runWorkflow';
     workflowId?: string;
     workflowName?: string;
-} | {
-    type: 'siteAlert';
-    message: string;
-    severity?: 'info' | 'success' | 'warning' | 'error';
 } | {
     type: 'customEvent';
     eventName: string;
@@ -181,90 +62,6 @@ export type HostActionStep = ({
     type: 'webhookPost';
     webhookId?: string;
     webhookName?: string;
-} | {
-    type: 'showOverlay';
-    overlayId?: string;
-    overlayName?: string;
-} | {
-    type: 'stickyNav';
-    selector?: string;
-} | {
-    type: 'addClass';
-    selector: string;
-    className: string;
-} | {
-    type: 'removeClass';
-    selector: string;
-    className: string;
-} | {
-    type: 'toggleClass';
-    selector: string;
-    className: string;
-} | {
-    type: 'showElement';
-    selector: string;
-    delayMs?: number;
-    dismissOn?: ElementDismissOption[];
-} | {
-    type: 'hideElement';
-    selector: string;
-    delayMs?: number;
-} | {
-    type: 'toggleElement';
-    selector: string;
-    delayMs?: number;
-    dismissOn?: ElementDismissOption[];
-} | {
-    type: 'setAttribute';
-    selector: string;
-    name: string;
-    value: string;
-} | {
-    type: 'removeAttribute';
-    selector: string;
-    name: string;
-} | {
-    type: 'scrollTo';
-    selector: string;
-    /** Absent means `smooth`. A visitor who asks for reduced motion is always scrolled instantly. */
-    behavior?: ScrollToBehavior;
-    /** Pixels left above the target, so a sticky header does not cover it. Absent means 0. */
-    offsetPx?: number;
-} | {
-    type: 'playVideo';
-    selector: string;
-} | {
-    type: 'openDrawer';
-    drawerNodeId?: string;
-} | {
-    type: 'closeDrawer';
-    drawerNodeId?: string;
-} | {
-    type: 'toggleDrawer';
-    drawerNodeId?: string;
-} | {
-    type: 'openMenu';
-    menuNodeId?: string;
-} | {
-    type: 'closeMenu';
-    menuNodeId?: string;
-} | {
-    type: 'toggleMenu';
-    menuNodeId?: string;
-} | {
-    type: 'showHtml';
-    html: string;
-} | {
-    type: 'runJs';
-    code: string;
-} | {
-    type: 'redirect';
-    url?: string;
-    screenId?: string;
-} | {
-    type: 'trackGaEvent';
-    eventName: string;
-    params?: Record<string, string>;
 } | {
     type: 'sendEmail';
     subject: string;
@@ -351,12 +148,11 @@ export type HostActionStep = ({
     kind: CrmActivityKind;
     body: string;
 }) & {
-    /** See {@link HostActionStepGuard}. Absent means the step always runs. */
-    when?: HostActionStepGuard | null;
+    /** See {@link InteractionStepGuard}. Absent means the step always runs. */
+    when?: InteractionStepGuard | null;
 };
-/** Steps the tenant page runtime executes client-side (AGL-257). */
-export declare const CLIENT_ACTION_STEP_TYPES: ReadonlySet<HostActionStepType>;
-export declare function isClientActionStep(step: HostActionStep): boolean;
+/** A step of an automation: one of the platform's client steps, or one of its server steps. */
+export type HostActionStep = ClientInteractionStep | ServerActionStep;
 /**
  * The steps that suspend a run and continue it later, from a job beat.
  *
@@ -485,48 +281,12 @@ export declare function hostActionDocument(action: HostAction): HostActionDocume
  * a run that has not happened yet, whichever side would have executed it.
  */
 export declare function hostActionStepsForClient(steps: readonly HostActionStep[] | undefined | null): HostActionStep[];
+export type HostActionStepType = HostActionStep['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. Server steps
- * (sendEmail/notifyAdmins/enrollList/updateDataset/assignCampaign) are
- * re-checked against `actions` server-side in `runEventActions`.
- */
-export declare const BASIC_CLIENT_ACTION_STEP_TYPES: ReadonlySet<HostActionStepType>;
-/** A client step available on all plans (no `actions` entitlement). */
-export declare function isBasicClientActionStep(step: HostActionStep): boolean;
-/**
- * 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.
+ * `hosts/{hostId}/actions/{id}` doc: a site interaction whose steps may be
+ * the automation's server steps as well as the platform's client steps.
  */
-export declare function isClientStepEntitled(step: HostActionStep, entitlements: {
-    actionsEntitled: boolean;
-    allowJs: boolean;
-}): boolean;
-export type HostActionStepType = HostActionStep['type'];
-/** `hosts/{hostId}/actions/{id}` doc. */
-export interface HostAction {
-    name: string;
-    trigger: HostActionTrigger;
-    steps: HostActionStep[];
-    /** Disabled actions never run; new actions default enabled. */
-    enabled?: boolean;
+export interface HostAction extends SiteInteraction<HostActionStep> {
     /**
      * The recipe this action was installed from or begun as (AGL-2639), or
      * `null` for one begun blank. Absent on a document from before the stamp
@@ -535,53 +295,8 @@ export interface HostAction {
      */
     recipe?: CrmActionRecipeId | null;
 }
-export declare const ACTION_MAX_STEPS = 10;
 /** Custom-event chaining depth cap (mirrors CROSS_MAX_DEPTH). */
 export declare const ACTION_MAX_EVENT_DEPTH = 3;
-/**
- * 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 declare 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 declare const ACTION_EVENT_PARAM_NAME_MAX_LENGTH = 40;
-/** Self-dismiss triggers for shown elements (AGL-589). */
-export declare const ELEMENT_DISMISS_OPTIONS: readonly ["escape", "outsideClick"];
-export type ElementDismissOption = (typeof ELEMENT_DISMISS_OPTIONS)[number];
-/** Visibility grace-delay ceiling — enough for hover travel, no dead UIs. */
-export declare 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 declare const SCROLL_TO_BEHAVIORS: readonly ["smooth", "instant"];
-export type ScrollToBehavior = (typeof SCROLL_TO_BEHAVIORS)[number];
-/**
- * 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 declare const SCROLL_TO_MAX_OFFSET_PX = 1000;
-/** Custom event names: short, no collision with built-ins. */
-export declare const CUSTOM_EVENT_PATTERN: RegExp;
 /**
  * The shortest and longest a flow may wait.
  *
@@ -595,28 +310,6 @@ export declare const CUSTOM_EVENT_PATTERN: RegExp;
  */
 export declare const FLOW_WAIT_MIN_MINUTES = 1;
 export declare const FLOW_WAIT_MAX_MINUTES: number;
-/**
- * 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 declare const INTERACTION_ATTRIBUTE_NAME_PATTERN: RegExp;
-/**
- * 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 automation.
- */
-export declare function isInteractionAttributeAllowed(name: unknown): boolean;
 export declare const HOST_ACTION_STEP_LABELS: Record<HostActionStepType, string>;
 /**
  * Past-tense phrases for a run summary (AGL-2171).
@@ -652,11 +345,6 @@ export declare function isCustomEventName(event: string): boolean;
  * Server and console share this so bad steps never persist or run.
  */
 export declare function validateHostAction(action: HostAction): string | null;
-/** Alert produced by a `siteAlert` step, surfaced to the emitting client. */
-export interface HostActionAlert {
-    message: string;
-    severity: 'info' | 'success' | 'warning' | 'error';
-}
 /**
  * Webhooks (AGL-149) at `hosts/{hostId}/webhooks/{id}`. Outbound entries
  * are targets a `webhookPost` action step delivers to (HMAC-signed);
@@ -676,42 +364,5 @@ export interface HostWebhook {
     enabled?: boolean;
 }
 export declare const WEBHOOK_MAX_PER_HOST = 5;
-/**
- * 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 declare const ACTIONS_MAX_PER_HOST = 500;
 /** Outbound URLs must be public https — first-line SSRF guard. */
 export declare const WEBHOOK_URL_PATTERN: RegExp;