@aglyn/plugins-marketing 1.0.0-beta.143

package/src/lib/components/use-overlay-copy-editor.d.ts

@@ -0,0 +1,79 @@
+import { type HostTokenSource } from '@aglyn/aglyn';
+export interface OverlayCopyEditor {
+    /**
+     * Stored copy as the author reads it in the text field: a variable's
+     * `{{var:id}}` shows as the `{{name}}` they typed.
+     */
+    editable: (text: string | undefined) => string;
+    /**
+     * Typed copy as it is stored: each `{{name}}` of a variable on this site
+     * becomes its rename-safe `{{var:id}}`, the only variable form a published
+     * page resolves. A name no variable carries is left as typed.
+     */
+    stored: (text: string | undefined) => string | undefined;
+    /**
+     * {@link stored}, capped at `max` characters as the author reads them — a
+     * cap applied to the stored form could cut an id token in half, and half a
+     * token reaches the visitor as typed.
+     */
+    storedWithin: (text: string | undefined, max: number) => string;
+    /** What a visitor reads for this copy on the published site. */
+    preview: (text: string | undefined) => string;
+    /**
+     * Tokens in this copy that a visitor would read exactly as typed. Empty
+     * until the variables have been read, because until then a name the site
+     * does have would be reported too.
+     */
+    shownAsTyped: (text: string | undefined) => string[];
+    /**
+     * Whether any of this copy holds a token while the site's variables are
+     * still being read. Stored now, a name the site does have would be saved in
+     * the form no published page resolves.
+     */
+    pending: (...texts: Array<string | undefined>) => boolean;
+}
+/**
+ * Overlay copy — an announcement bar's text, a popup's headline and body —
+ * edited against the site's variables (AGL-2885).
+ *
+ * A published page resolves a variable only in its `{{var:id}}` form, while
+ * an author types `{{saleEndsAt}}`. So a name is rewritten to its id token on
+ * the way into storage and back on the way into the text field, the same
+ * normalization the Besigner applies when an element saves, and a token that
+ * would still reach a visitor as typed is reported rather than saved in
+ * silence.
+ *
+ * Callers hold copy in its STORED form and show {@link OverlayCopyEditor.editable}
+ * of it, converting each change with {@link OverlayCopyEditor.stored}. A
+ * field seeded before the variables arrive then catches up on its own, with no
+ * second seed to race the author's typing.
+ *
+ * The variables are read only once some copy holds a token, since most bars
+ * and popups are plain text, and stay read after that, so deleting a token and
+ * typing it again does not read them twice.
+ */
+export declare function useOverlayCopyEditor(options: {
+    hostId: string;
+    /**
+     * The site document, for the details `preview` fills in. Optional for an
+     * editor with no preview: a `{{host.*}}` token always renders as the detail
+     * or as nothing, so whether a token shows as typed never depends on it.
+     */
+    host?: HostTokenSource | null;
+    /** Whether any copy this editor holds contains a `{{` token. */
+    usesTokens: boolean;
+}): OverlayCopyEditor;
+/**
+ * What a copy field says about variables while nothing in it is wrong.
+ *
+ * A placeholder rather than an example name: an example names a variable most
+ * sites do not have, and a token for a variable the site does not have is
+ * exactly what reaches a visitor as typed.
+ */
+export declare const OVERLAY_COPY_HELPER_TEXT = "To show a variable from Logic, type its name in double braces, like {{name}}";
+/**
+ * The helper text a copy field shows when some of its tokens would reach a
+ * visitor as typed, or undefined when none would.
+ */
+export declare function shownAsTypedHelperText(tokens: string[]): string | undefined;
+export default useOverlayCopyEditor;

package/src/lib/components/use-overlay-copy-editor.js

@@ -0,0 +1,110 @@
+/**
+ * @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.
+ */ 'use client';
+import { editableBindingTokens, normalizeBindingTokens } from "@aglyn/aglyn";
+import { collection, limit, query } from "firebase/firestore";
+import { useMemo, useState } from "react";
+import { useFirestore, useFirestoreCollection } from "@aglyn/tenant-feature-instance";
+import { overlayCopyTokensShownAsTyped, resolveOverlayCopy } from "../model/overlay-copy.js";
+/**
+ * How many variables an editor reads: the ceiling the published page reads
+ * them under, so the editor never recognizes a name the page cannot fill in.
+ */ const VARIABLES_CEILING = 100;
+/**
+ * Overlay copy — an announcement bar's text, a popup's headline and body —
+ * edited against the site's variables (AGL-2885).
+ *
+ * A published page resolves a variable only in its `{{var:id}}` form, while
+ * an author types `{{saleEndsAt}}`. So a name is rewritten to its id token on
+ * the way into storage and back on the way into the text field, the same
+ * normalization the Besigner applies when an element saves, and a token that
+ * would still reach a visitor as typed is reported rather than saved in
+ * silence.
+ *
+ * Callers hold copy in its STORED form and show {@link OverlayCopyEditor.editable}
+ * of it, converting each change with {@link OverlayCopyEditor.stored}. A
+ * field seeded before the variables arrive then catches up on its own, with no
+ * second seed to race the author's typing.
+ *
+ * The variables are read only once some copy holds a token, since most bars
+ * and popups are plain text, and stay read after that, so deleting a token and
+ * typing it again does not read them twice.
+ */ export function useOverlayCopyEditor(options) {
+    const { hostId, host, usesTokens } = options;
+    const firestore = useFirestore();
+    // Latched during render, React's pattern for state derived from an earlier
+    // render: once any copy has held a token, the read stays open.
+    const [wanted, setWanted] = useState(usesTokens);
+    if (usesTokens && !wanted) setWanted(true);
+    const { data: variableDocs, status } = useFirestoreCollection(()=>wanted ? query(collection(firestore, 'hosts', hostId, 'variables'), limit(VARIABLES_CEILING)) : null, [
+        firestore,
+        hostId,
+        wanted
+    ], {
+        idField: '$id'
+    });
+    const settled = wanted && status !== 'loading';
+    return useMemo(()=>{
+        // Keyed by id for resolution, as the published page keys them, and by
+        // name for the typed form. A deleted variable is neither: the page does
+        // not read one.
+        const byId = {};
+        const byName = {};
+        for (const variable of variableDocs != null ? variableDocs : []){
+            if (!(variable == null ? void 0 : variable.name) || variable.deletedAt) continue;
+            byId[variable.$id] = variable;
+            byName[variable.name] = variable;
+        }
+        const editable = (text)=>typeof text === 'string' ? editableBindingTokens(text, byName) : '';
+        const stored = (text)=>typeof text === 'string' && text.includes('{{') ? normalizeBindingTokens(text, byName) : text;
+        return {
+            editable,
+            stored,
+            storedWithin: (text, max)=>{
+                var _stored;
+                return (_stored = stored(editable(text).slice(0, max))) != null ? _stored : '';
+            },
+            preview: (text)=>{
+                var _stored;
+                return resolveOverlayCopy((_stored = stored(text)) != null ? _stored : '', byId, host);
+            },
+            shownAsTyped: (text)=>settled ? overlayCopyTokensShownAsTyped(stored(text), byId, host) : [],
+            pending: (...texts)=>!settled && texts.some((text)=>Boolean(text == null ? void 0 : text.includes('{{')))
+        };
+    }, [
+        variableDocs,
+        settled,
+        host
+    ]);
+}
+/**
+ * What a copy field says about variables while nothing in it is wrong.
+ *
+ * A placeholder rather than an example name: an example names a variable most
+ * sites do not have, and a token for a variable the site does not have is
+ * exactly what reaches a visitor as typed.
+ */ export const OVERLAY_COPY_HELPER_TEXT = 'To show a variable from Logic, type its name in double braces, like {{name}}';
+/**
+ * The helper text a copy field shows when some of its tokens would reach a
+ * visitor as typed, or undefined when none would.
+ */ export function shownAsTypedHelperText(tokens) {
+    if (!tokens.length) return undefined;
+    const list = tokens.join(', ');
+    return `Visitors would see ${list} exactly as typed. Use the name of a ` + 'variable from Logic, or remove the braces.';
+}
+export default useOverlayCopyEditor;
+
+//# sourceMappingURL=use-overlay-copy-editor.js.map

package/src/lib/components/use-overlay-copy-editor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/components/use-overlay-copy-editor.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n'use client'\n\nimport {\n  type BindingDocRef,\n  editableBindingTokens,\n  type HostTokenSource,\n  type HostVariable,\n  normalizeBindingTokens,\n} from '@aglyn/aglyn'\nimport { collection, limit, query } from 'firebase/firestore'\nimport { useMemo, useState } from 'react'\nimport {\n  useFirestore,\n  useFirestoreCollection,\n} from '@aglyn/tenant-feature-instance'\nimport {\n  overlayCopyTokensShownAsTyped,\n  resolveOverlayCopy,\n} from '../model/overlay-copy'\n\n/**\n * How many variables an editor reads: the ceiling the published page reads\n * them under, so the editor never recognizes a name the page cannot fill in.\n */\nconst VARIABLES_CEILING = 100\n\ntype VariableDoc = HostVariable & { $id: string; deletedAt?: unknown }\n\nexport interface OverlayCopyEditor {\n  /**\n   * Stored copy as the author reads it in the text field: a variable's\n   * `{{var:id}}` shows as the `{{name}}` they typed.\n   */\n  editable: (text: string | undefined) => string\n  /**\n   * Typed copy as it is stored: each `{{name}}` of a variable on this site\n   * becomes its rename-safe `{{var:id}}`, the only variable form a published\n   * page resolves. A name no variable carries is left as typed.\n   */\n  stored: (text: string | undefined) => string | undefined\n  /**\n   * {@link stored}, capped at `max` characters as the author reads them — a\n   * cap applied to the stored form could cut an id token in half, and half a\n   * token reaches the visitor as typed.\n   */\n  storedWithin: (text: string | undefined, max: number) => string\n  /** What a visitor reads for this copy on the published site. */\n  preview: (text: string | undefined) => string\n  /**\n   * Tokens in this copy that a visitor would read exactly as typed. Empty\n   * until the variables have been read, because until then a name the site\n   * does have would be reported too.\n   */\n  shownAsTyped: (text: string | undefined) => string[]\n  /**\n   * Whether any of this copy holds a token while the site's variables are\n   * still being read. Stored now, a name the site does have would be saved in\n   * the form no published page resolves.\n   */\n  pending: (...texts: Array<string | undefined>) => boolean\n}\n\n/**\n * Overlay copy — an announcement bar's text, a popup's headline and body —\n * edited against the site's variables (AGL-2885).\n *\n * A published page resolves a variable only in its `{{var:id}}` form, while\n * an author types `{{saleEndsAt}}`. So a name is rewritten to its id token on\n * the way into storage and back on the way into the text field, the same\n * normalization the Besigner applies when an element saves, and a token that\n * would still reach a visitor as typed is reported rather than saved in\n * silence.\n *\n * Callers hold copy in its STORED form and show {@link OverlayCopyEditor.editable}\n * of it, converting each change with {@link OverlayCopyEditor.stored}. A\n * field seeded before the variables arrive then catches up on its own, with no\n * second seed to race the author's typing.\n *\n * The variables are read only once some copy holds a token, since most bars\n * and popups are plain text, and stay read after that, so deleting a token and\n * typing it again does not read them twice.\n */\nexport function useOverlayCopyEditor(options: {\n  hostId: string\n  /**\n   * The site document, for the details `preview` fills in. Optional for an\n   * editor with no preview: a `{{host.*}}` token always renders as the detail\n   * or as nothing, so whether a token shows as typed never depends on it.\n   */\n  host?: HostTokenSource | null\n  /** Whether any copy this editor holds contains a `{{` token. */\n  usesTokens: boolean\n}): OverlayCopyEditor {\n  const { hostId, host, usesTokens } = options\n  const firestore = useFirestore()\n  // Latched during render, React's pattern for state derived from an earlier\n  // render: once any copy has held a token, the read stays open.\n  const [wanted, setWanted] = useState(usesTokens)\n  if (usesTokens && !wanted) setWanted(true)\n  const { data: variableDocs, status } = useFirestoreCollection<VariableDoc>(\n    () =>\n      wanted\n        ? query(\n            collection(firestore, 'hosts', hostId, 'variables'),\n            limit(VARIABLES_CEILING),\n          )\n        : null,\n    [firestore, hostId, wanted],\n    { idField: '$id' },\n  )\n  const settled = wanted && status !== 'loading'\n\n  return useMemo(() => {\n    // Keyed by id for resolution, as the published page keys them, and by\n    // name for the typed form. A deleted variable is neither: the page does\n    // not read one.\n    const byId: Record<string, HostVariable> = {}\n    const byName: Record<string, BindingDocRef> = {}\n    for (const variable of variableDocs ?? []) {\n      if (!variable?.name || variable.deletedAt) continue\n      byId[variable.$id] = variable\n      byName[variable.name] = variable\n    }\n    const editable = (text: string | undefined) =>\n      typeof text === 'string' ? editableBindingTokens(text, byName) : ''\n    const stored = (text: string | undefined) =>\n      typeof text === 'string' && text.includes('{{')\n        ? normalizeBindingTokens(text, byName)\n        : text\n    return {\n      editable,\n      stored,\n      storedWithin: (text, max) => stored(editable(text).slice(0, max)) ?? '',\n      preview: (text) => resolveOverlayCopy(stored(text) ?? '', byId, host),\n      shownAsTyped: (text) =>\n        settled ? overlayCopyTokensShownAsTyped(stored(text), byId, host) : [],\n      pending: (...texts) =>\n        !settled && texts.some((text) => Boolean(text?.includes('{{'))),\n    }\n  }, [variableDocs, settled, host])\n}\n\n/**\n * What a copy field says about variables while nothing in it is wrong.\n *\n * A placeholder rather than an example name: an example names a variable most\n * sites do not have, and a token for a variable the site does not have is\n * exactly what reaches a visitor as typed.\n */\nexport const OVERLAY_COPY_HELPER_TEXT =\n  'To show a variable from Logic, type its name in double braces, like {{name}}'\n\n/**\n * The helper text a copy field shows when some of its tokens would reach a\n * visitor as typed, or undefined when none would.\n */\nexport function shownAsTypedHelperText(tokens: string[]): string | undefined {\n  if (!tokens.length) return undefined\n  const list = tokens.join(', ')\n  return (\n    `Visitors would see ${list} exactly as typed. Use the name of a ` +\n    'variable from Logic, or remove the braces.'\n  )\n}\n\nexport default useOverlayCopyEditor\n"],"names":["editableBindingTokens","normalizeBindingTokens","collection","limit","query","useMemo","useState","useFirestore","useFirestoreCollection","overlayCopyTokensShownAsTyped","resolveOverlayCopy","VARIABLES_CEILING","useOverlayCopyEditor","options","hostId","host","usesTokens","firestore","wanted","setWanted","data","variableDocs","status","idField","settled","byId","byName","variable","name","deletedAt","$id","editable","text","stored","includes","storedWithin","max","slice","preview","shownAsTyped","pending","texts","some","Boolean","OVERLAY_COPY_HELPER_TEXT","shownAsTypedHelperText","tokens","length","undefined","list","join"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GACD;AAEA,SAEEA,qBAAqB,EAGrBC,sBAAsB,QACjB,eAAc;AACrB,SAASC,UAAU,EAAEC,KAAK,EAAEC,KAAK,QAAQ,qBAAoB;AAC7D,SAASC,OAAO,EAAEC,QAAQ,QAAQ,QAAO;AACzC,SACEC,YAAY,EACZC,sBAAsB,QACjB,iCAAgC;AACvC,SACEC,6BAA6B,EAC7BC,kBAAkB,QACb,2BAAuB;AAE9B;;;CAGC,GACD,MAAMC,oBAAoB;AAsC1B;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,qBAAqBC,OAUpC;IACC,MAAM,EAAEC,MAAM,EAAEC,IAAI,EAAEC,UAAU,EAAE,GAAGH;IACrC,MAAMI,YAAYV;IAClB,2EAA2E;IAC3E,+DAA+D;IAC/D,MAAM,CAACW,QAAQC,UAAU,GAAGb,SAASU;IACrC,IAAIA,cAAc,CAACE,QAAQC,UAAU;IACrC,MAAM,EAAEC,MAAMC,YAAY,EAAEC,MAAM,EAAE,GAAGd,uBACrC,IACEU,SACId,MACEF,WAAWe,WAAW,SAASH,QAAQ,cACvCX,MAAMQ,sBAER,MACN;QAACM;QAAWH;QAAQI;KAAO,EAC3B;QAAEK,SAAS;IAAM;IAEnB,MAAMC,UAAUN,UAAUI,WAAW;IAErC,OAAOjB,QAAQ;QACb,sEAAsE;QACtE,wEAAwE;QACxE,gBAAgB;QAChB,MAAMoB,OAAqC,CAAC;QAC5C,MAAMC,SAAwC,CAAC;QAC/C,KAAK,MAAMC,YAAYN,uBAAAA,eAAgB,EAAE,CAAE;YACzC,IAAI,EAACM,4BAAAA,SAAUC,IAAI,KAAID,SAASE,SAAS,EAAE;YAC3CJ,IAAI,CAACE,SAASG,GAAG,CAAC,GAAGH;YACrBD,MAAM,CAACC,SAASC,IAAI,CAAC,GAAGD;QAC1B;QACA,MAAMI,WAAW,CAACC,OAChB,OAAOA,SAAS,WAAWhC,sBAAsBgC,MAAMN,UAAU;QACnE,MAAMO,SAAS,CAACD,OACd,OAAOA,SAAS,YAAYA,KAAKE,QAAQ,CAAC,QACtCjC,uBAAuB+B,MAAMN,UAC7BM;QACN,OAAO;YACLD;YACAE;YACAE,cAAc,CAACH,MAAMI;oBAAQH;wBAAAA,UAAAA,OAAOF,SAASC,MAAMK,KAAK,CAAC,GAAGD,iBAA/BH,UAAwC;;YACrEK,SAAS,CAACN;oBAA4BC;uBAAnBvB,oBAAmBuB,UAAAA,OAAOD,iBAAPC,UAAgB,IAAIR,MAAMV;;YAChEwB,cAAc,CAACP,OACbR,UAAUf,8BAA8BwB,OAAOD,OAAOP,MAAMV,QAAQ,EAAE;YACxEyB,SAAS,CAAC,GAAGC,QACX,CAACjB,WAAWiB,MAAMC,IAAI,CAAC,CAACV,OAASW,QAAQX,wBAAAA,KAAME,QAAQ,CAAC;QAC5D;IACF,GAAG;QAACb;QAAcG;QAAST;KAAK;AAClC;AAEA;;;;;;CAMC,GACD,OAAO,MAAM6B,2BACX,+EAA8E;AAEhF;;;CAGC,GACD,OAAO,SAASC,uBAAuBC,MAAgB;IACrD,IAAI,CAACA,OAAOC,MAAM,EAAE,OAAOC;IAC3B,MAAMC,OAAOH,OAAOI,IAAI,CAAC;IACzB,OACE,CAAC,mBAAmB,EAAED,KAAK,qCAAqC,CAAC,GACjE;AAEJ;AAEA,eAAerC,qBAAoB"}

package/src/lib/constants/bundle-common.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @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.
+ */
+export declare const BUNDLE_ID = "marketing";

package/src/lib/constants/bundle-common.js

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */ export const BUNDLE_ID = 'marketing';
+
+//# sourceMappingURL=bundle-common.js.map

package/src/lib/constants/bundle-common.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/constants/bundle-common.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n */\n\nexport const BUNDLE_ID = 'marketing'\n"],"names":["BUNDLE_ID"],"mappings":"AAAA;;;;;;CAMC,GAED,OAAO,MAAMA,YAAY,YAAW"}

package/src/lib/model/campaign-membership-figures.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @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.
+ */
+/**
+ * WHAT THE RECORDS FILED UNDER A CAMPAIGN HOLD — which is not what the
+ * campaign caused.
+ *
+ * Every other figure on a campaign's page is ATTRIBUTION: the campaign's mail
+ * carried a link, a visitor followed it, and the conversion, the money or the
+ * landing is credited to the campaign because that chain was recorded. The
+ * figures this module produces are MEMBERSHIP: somebody put a form in this
+ * campaign, and the form has counters of its own.
+ *
+ * The two answer different questions and a reader who adds them together gets
+ * a wrong number in a direction that flatters the campaign. So nothing here
+ * is named for causation — nothing generated, nothing driven, nothing from
+ * this campaign — and the rollup carries the three facts a caller needs in
+ * order to describe the figure honestly rather than merely print it:
+ *
+ *  1. **Whether it is windowed.** A form's flat counters are lifetime and
+ *     include everything from before it was ever filed under this campaign.
+ *  2. **How many members recorded it.** A counter nothing recorded is `null`,
+ *     and a sum over three of five forms is a different statement from a sum
+ *     over five.
+ *  3. **How many members are in another campaign too.** `campaignIds` holds
+ *     up to twenty ids, so the same submissions legitimately count toward
+ *     more than one campaign and no total here is exclusive.
+ */
+import { type FormPeriodRange, type FormStatKind, type FormStats, type FormStatsTotals } from '@aglyn/aglyn/app-utils/forms';
+/** The dates a campaign container carries, as this module reads them. */
+export interface CampaignSpan {
+    startAtMs?: number | null;
+    endAtMs?: number | null;
+}
+/**
+ * The months a campaign's dates cover, for {@link formStatsTotals}.
+ *
+ * Both ends are optional in the stored campaign and stay optional here: an
+ * open-ended campaign is genuinely open-ended, and substituting today for a
+ * missing end would silently exclude a month whose figures are still moving.
+ *
+ * A campaign with NEITHER date produces an empty range, which
+ * {@link formStatsTotals} answers with lifetime totals. That is the correct
+ * answer — there is no window to confine the figures to — and it is why the
+ * caller must go on saying which of the two it is showing.
+ */
+export declare function campaignPeriodRange(span: CampaignSpan): FormPeriodRange;
+/** Whether a range confines anything. */
+export declare function isWindowedRange(range: FormPeriodRange): boolean;
+/** One member's contribution to the rollup. */
+export interface CampaignFormMember {
+    /** The form's own counters, already summed over the range or lifetime. */
+    totals: FormStatsTotals;
+    /** Campaigns the form is filed under, this one included. */
+    campaigns: number;
+}
+/**
+ * One summed counter, with the population it was summed over named.
+ *
+ * The shape `CampaignAggregate` uses for the mail figures, deliberately: a
+ * reader meets both on the same page, and a total that names its population
+ * on one section and not the other teaches that the silent one is complete.
+ */
+export interface CampaignMemberFigure {
+    /** `null` when no member recorded this counter at all. */
+    value: number | null;
+    /** Members that recorded it. */
+    recorded: number;
+    /** Members the sum ran over. */
+    members: number;
+}
+/** Every membership figure for one campaign's forms. */
+export interface CampaignFormsRollup extends Record<FormStatKind, CampaignMemberFigure> {
+    /** Forms filed under this campaign. */
+    members: number;
+    /** Of those, the ones filed under at least one other campaign as well. */
+    shared: number;
+}
+/**
+ * Add up what a campaign's forms hold.
+ *
+ * A counter stays `null` until some member records it, so a campaign whose
+ * forms have never counted views reports views as unmeasured rather than as
+ * zero. `recorded` is what lets the caller say "across 2 of 5 forms" where
+ * the two disagree — the same admission the mail rollup makes when a send is
+ * missing a counter.
+ */
+export declare function campaignFormsRollup(members: readonly CampaignFormMember[]): CampaignFormsRollup;
+/**
+ * A form's counters as this campaign may report them.
+ *
+ * Thin on purpose — the windowing rule lives in `formStatsTotals` so the
+ * forms surface and this one cannot disagree about which months a figure
+ * covers.
+ */
+export declare function campaignFormTotals(stats: FormStats | undefined | null, range: FormPeriodRange): FormStatsTotals;

package/src/lib/model/campaign-membership-figures.js

@@ -0,0 +1,113 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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.
+ */ /**
+ * WHAT THE RECORDS FILED UNDER A CAMPAIGN HOLD — which is not what the
+ * campaign caused.
+ *
+ * Every other figure on a campaign's page is ATTRIBUTION: the campaign's mail
+ * carried a link, a visitor followed it, and the conversion, the money or the
+ * landing is credited to the campaign because that chain was recorded. The
+ * figures this module produces are MEMBERSHIP: somebody put a form in this
+ * campaign, and the form has counters of its own.
+ *
+ * The two answer different questions and a reader who adds them together gets
+ * a wrong number in a direction that flatters the campaign. So nothing here
+ * is named for causation — nothing generated, nothing driven, nothing from
+ * this campaign — and the rollup carries the three facts a caller needs in
+ * order to describe the figure honestly rather than merely print it:
+ *
+ *  1. **Whether it is windowed.** A form's flat counters are lifetime and
+ *     include everything from before it was ever filed under this campaign.
+ *  2. **How many members recorded it.** A counter nothing recorded is `null`,
+ *     and a sum over three of five forms is a different statement from a sum
+ *     over five.
+ *  3. **How many members are in another campaign too.** `campaignIds` holds
+ *     up to twenty ids, so the same submissions legitimately count toward
+ *     more than one campaign and no total here is exclusive.
+ */ // Import the form-stat helpers from the context-free forms subpath, NOT the
+// `@aglyn/aglyn` barrel: this file is in the marketing model, which the
+// plugin's SERVER graph re-exports, and the full barrel pulls client React
+// contexts (createContext) that break the RSC server build (AGL-830).
+import { formPeriodKey, formStatsTotals, FORM_STAT_KINDS } from "@aglyn/aglyn/app-utils/forms";
+/**
+ * The months a campaign's dates cover, for {@link formStatsTotals}.
+ *
+ * Both ends are optional in the stored campaign and stay optional here: an
+ * open-ended campaign is genuinely open-ended, and substituting today for a
+ * missing end would silently exclude a month whose figures are still moving.
+ *
+ * A campaign with NEITHER date produces an empty range, which
+ * {@link formStatsTotals} answers with lifetime totals. That is the correct
+ * answer — there is no window to confine the figures to — and it is why the
+ * caller must go on saying which of the two it is showing.
+ */ export function campaignPeriodRange(span) {
+    const from = formPeriodKey(span.startAtMs);
+    const to = formPeriodKey(span.endAtMs);
+    return _extends({}, from ? {
+        from
+    } : {}, to ? {
+        to
+    } : {});
+}
+/** Whether a range confines anything. */ export function isWindowedRange(range) {
+    return Boolean(range.from || range.to);
+}
+/** A figure nothing has been added to yet. */ function emptyFigure(members) {
+    return {
+        value: null,
+        recorded: 0,
+        members
+    };
+}
+/**
+ * Add up what a campaign's forms hold.
+ *
+ * A counter stays `null` until some member records it, so a campaign whose
+ * forms have never counted views reports views as unmeasured rather than as
+ * zero. `recorded` is what lets the caller say "across 2 of 5 forms" where
+ * the two disagree — the same admission the mail rollup makes when a send is
+ * missing a counter.
+ */ export function campaignFormsRollup(members) {
+    const rollup = {
+        members: members.length,
+        shared: 0
+    };
+    for (const kind of FORM_STAT_KINDS)rollup[kind] = emptyFigure(members.length);
+    for (const member of members){
+        if (member.campaigns > 1) rollup.shared += 1;
+        for (const kind of FORM_STAT_KINDS){
+            var _figure_value;
+            const value = member.totals[kind];
+            if (value === null) continue;
+            const figure = rollup[kind];
+            figure.value = ((_figure_value = figure.value) != null ? _figure_value : 0) + value;
+            figure.recorded += 1;
+        }
+    }
+    return rollup;
+}
+/**
+ * A form's counters as this campaign may report them.
+ *
+ * Thin on purpose — the windowing rule lives in `formStatsTotals` so the
+ * forms surface and this one cannot disagree about which months a figure
+ * covers.
+ */ export function campaignFormTotals(stats, range) {
+    return formStatsTotals(stats, isWindowedRange(range) ? range : null);
+}
+
+//# sourceMappingURL=campaign-membership-figures.js.map

package/src/lib/model/campaign-membership-figures.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/plugins/marketing/src/lib/model/campaign-membership-figures.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * WHAT THE RECORDS FILED UNDER A CAMPAIGN HOLD — which is not what the\n * campaign caused.\n *\n * Every other figure on a campaign's page is ATTRIBUTION: the campaign's mail\n * carried a link, a visitor followed it, and the conversion, the money or the\n * landing is credited to the campaign because that chain was recorded. The\n * figures this module produces are MEMBERSHIP: somebody put a form in this\n * campaign, and the form has counters of its own.\n *\n * The two answer different questions and a reader who adds them together gets\n * a wrong number in a direction that flatters the campaign. So nothing here\n * is named for causation — nothing generated, nothing driven, nothing from\n * this campaign — and the rollup carries the three facts a caller needs in\n * order to describe the figure honestly rather than merely print it:\n *\n *  1. **Whether it is windowed.** A form's flat counters are lifetime and\n *     include everything from before it was ever filed under this campaign.\n *  2. **How many members recorded it.** A counter nothing recorded is `null`,\n *     and a sum over three of five forms is a different statement from a sum\n *     over five.\n *  3. **How many members are in another campaign too.** `campaignIds` holds\n *     up to twenty ids, so the same submissions legitimately count toward\n *     more than one campaign and no total here is exclusive.\n */\n\n// Import the form-stat helpers from the context-free forms subpath, NOT the\n// `@aglyn/aglyn` barrel: this file is in the marketing model, which the\n// plugin's SERVER graph re-exports, and the full barrel pulls client React\n// contexts (createContext) that break the RSC server build (AGL-830).\nimport {\n  formPeriodKey,\n  formStatsTotals,\n  FORM_STAT_KINDS,\n  type FormPeriodRange,\n  type FormStatKind,\n  type FormStats,\n  type FormStatsTotals,\n} from '@aglyn/aglyn/app-utils/forms'\n\n/** The dates a campaign container carries, as this module reads them. */\nexport interface CampaignSpan {\n  startAtMs?: number | null\n  endAtMs?: number | null\n}\n\n/**\n * The months a campaign's dates cover, for {@link formStatsTotals}.\n *\n * Both ends are optional in the stored campaign and stay optional here: an\n * open-ended campaign is genuinely open-ended, and substituting today for a\n * missing end would silently exclude a month whose figures are still moving.\n *\n * A campaign with NEITHER date produces an empty range, which\n * {@link formStatsTotals} answers with lifetime totals. That is the correct\n * answer — there is no window to confine the figures to — and it is why the\n * caller must go on saying which of the two it is showing.\n */\nexport function campaignPeriodRange(span: CampaignSpan): FormPeriodRange {\n  const from = formPeriodKey(span.startAtMs)\n  const to = formPeriodKey(span.endAtMs)\n  return { ...(from ? { from } : {}), ...(to ? { to } : {}) }\n}\n\n/** Whether a range confines anything. */\nexport function isWindowedRange(range: FormPeriodRange): boolean {\n  return Boolean(range.from || range.to)\n}\n\n/** One member's contribution to the rollup. */\nexport interface CampaignFormMember {\n  /** The form's own counters, already summed over the range or lifetime. */\n  totals: FormStatsTotals\n  /** Campaigns the form is filed under, this one included. */\n  campaigns: number\n}\n\n/**\n * One summed counter, with the population it was summed over named.\n *\n * The shape `CampaignAggregate` uses for the mail figures, deliberately: a\n * reader meets both on the same page, and a total that names its population\n * on one section and not the other teaches that the silent one is complete.\n */\nexport interface CampaignMemberFigure {\n  /** `null` when no member recorded this counter at all. */\n  value: number | null\n  /** Members that recorded it. */\n  recorded: number\n  /** Members the sum ran over. */\n  members: number\n}\n\n/** Every membership figure for one campaign's forms. */\nexport interface CampaignFormsRollup extends Record<FormStatKind, CampaignMemberFigure> {\n  /** Forms filed under this campaign. */\n  members: number\n  /** Of those, the ones filed under at least one other campaign as well. */\n  shared: number\n}\n\n/** A figure nothing has been added to yet. */\nfunction emptyFigure(members: number): CampaignMemberFigure {\n  return { value: null, recorded: 0, members }\n}\n\n/**\n * Add up what a campaign's forms hold.\n *\n * A counter stays `null` until some member records it, so a campaign whose\n * forms have never counted views reports views as unmeasured rather than as\n * zero. `recorded` is what lets the caller say \"across 2 of 5 forms\" where\n * the two disagree — the same admission the mail rollup makes when a send is\n * missing a counter.\n */\nexport function campaignFormsRollup(\n  members: readonly CampaignFormMember[],\n): CampaignFormsRollup {\n  const rollup = {\n    members: members.length,\n    shared: 0,\n  } as CampaignFormsRollup\n  for (const kind of FORM_STAT_KINDS) rollup[kind] = emptyFigure(members.length)\n  for (const member of members) {\n    if (member.campaigns > 1) rollup.shared += 1\n    for (const kind of FORM_STAT_KINDS) {\n      const value = member.totals[kind]\n      if (value === null) continue\n      const figure = rollup[kind]\n      figure.value = (figure.value ?? 0) + value\n      figure.recorded += 1\n    }\n  }\n  return rollup\n}\n\n/**\n * A form's counters as this campaign may report them.\n *\n * Thin on purpose — the windowing rule lives in `formStatsTotals` so the\n * forms surface and this one cannot disagree about which months a figure\n * covers.\n */\nexport function campaignFormTotals(\n  stats: FormStats | undefined | null,\n  range: FormPeriodRange,\n): FormStatsTotals {\n  return formStatsTotals(stats, isWindowedRange(range) ? range : null)\n}\n"],"names":["formPeriodKey","formStatsTotals","FORM_STAT_KINDS","campaignPeriodRange","span","from","startAtMs","to","endAtMs","isWindowedRange","range","Boolean","emptyFigure","members","value","recorded","campaignFormsRollup","rollup","length","shared","kind","member","campaigns","figure","totals","campaignFormTotals","stats"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;CAwBC,GAED,4EAA4E;AAC5E,wEAAwE;AACxE,2EAA2E;AAC3E,sEAAsE;AACtE,SACEA,aAAa,EACbC,eAAe,EACfC,eAAe,QAKV,+BAA8B;AAQrC;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,oBAAoBC,IAAkB;IACpD,MAAMC,OAAOL,cAAcI,KAAKE,SAAS;IACzC,MAAMC,KAAKP,cAAcI,KAAKI,OAAO;IACrC,OAAO,aAAMH,OAAO;QAAEA;IAAK,IAAI,CAAC,GAAQE,KAAK;QAAEA;IAAG,IAAI,CAAC;AACzD;AAEA,uCAAuC,GACvC,OAAO,SAASE,gBAAgBC,KAAsB;IACpD,OAAOC,QAAQD,MAAML,IAAI,IAAIK,MAAMH,EAAE;AACvC;AAkCA,4CAA4C,GAC5C,SAASK,YAAYC,OAAe;IAClC,OAAO;QAAEC,OAAO;QAAMC,UAAU;QAAGF;IAAQ;AAC7C;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASG,oBACdH,OAAsC;IAEtC,MAAMI,SAAS;QACbJ,SAASA,QAAQK,MAAM;QACvBC,QAAQ;IACV;IACA,KAAK,MAAMC,QAAQlB,gBAAiBe,MAAM,CAACG,KAAK,GAAGR,YAAYC,QAAQK,MAAM;IAC7E,KAAK,MAAMG,UAAUR,QAAS;QAC5B,IAAIQ,OAAOC,SAAS,GAAG,GAAGL,OAAOE,MAAM,IAAI;QAC3C,KAAK,MAAMC,QAAQlB,gBAAiB;gBAIlBqB;YAHhB,MAAMT,QAAQO,OAAOG,MAAM,CAACJ,KAAK;YACjC,IAAIN,UAAU,MAAM;YACpB,MAAMS,SAASN,MAAM,CAACG,KAAK;YAC3BG,OAAOT,KAAK,GAAG,EAACS,gBAAAA,OAAOT,KAAK,YAAZS,gBAAgB,KAAKT;YACrCS,OAAOR,QAAQ,IAAI;QACrB;IACF;IACA,OAAOE;AACT;AAEA;;;;;;CAMC,GACD,OAAO,SAASQ,mBACdC,KAAmC,EACnChB,KAAsB;IAEtB,OAAOT,gBAAgByB,OAAOjB,gBAAgBC,SAASA,QAAQ;AACjE"}

package/src/lib/model/compile-client-automations.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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 { type HostAction } from '@aglyn/aglyn/app-utils/actions';
+import type { ClientAutomation } from './site-contract';
+/** A raw `hosts/{hostId}/actions` doc paired with its id. */
+export interface RawHostAction {
+    id: string;
+    action: HostAction;
+}
+export interface CompileClientAutomationsOptions {
+    /** Leading-slash page path for pathPattern targeting. */
+    path: string;
+    /**
+     * `actions` entitlement (AGL-577). Basic presentational steps
+     * (menu/drawer/show-hide/class/nav/alert) always load; advanced client
+     * steps (overlay/showHtml/analytics) and server steps drop when false.
+     */
+    actionsEntitled: boolean;
+    /** Business-tier gate for `runJs` steps (dropped when false). */
+    allowJs: boolean;
+    /**
+     * Ignore each action's `pathPattern` (AGL-830). The besigner Preview shows
+     * a single composed screen and scopes relevance by selector match, so it
+     * skips path filtering rather than resolve the composed path.
+     */
+    matchAllPaths?: boolean;
+    /**
+     * Drop every automation that names a `pathPattern` (AGL-2511), for a
+     * surface whose own path is unknown — the designed 404 body, served from a
+     * per-host cache that no request path belongs to.
+     *
+     * The opposite of `matchAllPaths` and deliberately so: Preview knows the
+     * page and only lacks its composed address, so it keeps path-scoped
+     * automations; this caller cannot know the page at all, and running an
+     * automation scoped to `/pricing` on whatever URL 404'd would be a guess
+     * with a side effect. Interactions authored on nodes carry no pattern, so
+     * a nav's hover choreography — the reason this surface is enriched — is
+     * unaffected.
+     */
+    dropPathScoped?: boolean;
+}
+/**
+ * Pure action→client-automation mapping (AGL-256/577, extracted AGL-830):
+ * the single place the trigger config + entitlement-trimmed client steps are
+ * shaped. Both the server page-enricher (admin fetch) and the editor Preview
+ * (client fetch) feed their loaded action docs through this, so live and
+ * preview stay byte-for-byte consistent. No I/O, no firebase — safe on the
+ * client. Malformed entries are skipped, never thrown.
+ */
+export declare function compileClientAutomations(actions: RawHostAction[], options: CompileClientAutomationsOptions): ClientAutomation[];
+export default compileClientAutomations;

package/src/lib/model/compile-client-automations.js

@@ -0,0 +1,95 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 the entitlement/event predicates from the context-free actions
+// subpath, NOT the `@aglyn/aglyn` barrel: this file is in the marketing model,
+// which the plugin's SERVER graph re-exports, and the full barrel pulls client
+// React contexts (createContext) that break the RSC server build (AGL-830).
+import { hostActionStepsForClient, isClientActionStep, isClientStepEntitled, isSiteEventType } from "@aglyn/aglyn/app-utils/actions";
+import { overlayMatchesPath } from "./overlays.js";
+/**
+ * Pure action→client-automation mapping (AGL-256/577, extracted AGL-830):
+ * the single place the trigger config + entitlement-trimmed client steps are
+ * shaped. Both the server page-enricher (admin fetch) and the editor Preview
+ * (client fetch) feed their loaded action docs through this, so live and
+ * preview stay byte-for-byte consistent. No I/O, no firebase — safe on the
+ * client. Malformed entries are skipped, never thrown.
+ */ export function compileClientAutomations(actions, options) {
+    const automations = [];
+    for (const { id, action } of actions){
+        var _ref, _action_steps;
+        var _action_trigger, _action_trigger_pathPattern, _action_trigger1, _action_trigger2, _action_trigger3, _action_trigger4, _action_trigger5, _action_trigger6, _action_trigger7, _action_trigger8;
+        if (action.deletedAt || action.enabled === false) {
+            continue;
+        }
+        const event = String((_ref = (_action_trigger = action.trigger) == null ? void 0 : _action_trigger.event) != null ? _ref : '');
+        if (!isSiteEventType(event)) continue;
+        const pathPattern = (_action_trigger1 = action.trigger) == null ? void 0 : (_action_trigger_pathPattern = _action_trigger1.pathPattern) == null ? void 0 : _action_trigger_pathPattern.trim();
+        if (pathPattern && options.dropPathScoped) continue;
+        if (!options.matchAllPaths && pathPattern && !overlayMatchesPath({
+            pathPatterns: [
+                pathPattern
+            ]
+        }, options.path)) {
+            continue;
+        }
+        /*
+     * TRUNCATED AT THE FIRST WAIT, before anything else is decided.
+     *
+     * The browser runs its slice of the list the moment the trigger fires, so
+     * a client step sitting after a `wait` would execute at once — the popup
+     * an author scheduled for three days later would appear immediately, the
+     * delay would look correct on the server, and the two halves of one
+     * authored flow would disagree about when they happened. Everything past
+     * the first wait belongs to a run the job beat has not started yet.
+     */ const reachableSteps = hostActionStepsForClient(action.steps);
+        // Step-level entitlement tiering (AGL-577): basic presentational steps
+        // load on every plan; advanced client steps need `actions` and runJs
+        // needs `webhooks` — see isClientStepEntitled.
+        const clientSteps = reachableSteps.filter((step)=>isClientStepEntitled(step, {
+                actionsEntitled: options.actionsEntitled,
+                allowJs: options.allowJs
+            }));
+        // Server steps only dispatch (and are only re-authorized) when the org is
+        // actions-entitled — never advertise them otherwise, so basic-tier pages
+        // don't POST to /api/events/dispatch for a no-op.
+        const hasServerSteps = options.actionsEntitled && ((_action_steps = action.steps) != null ? _action_steps : []).some((step)=>!isClientActionStep(step));
+        if (!clientSteps.length && !hasServerSteps) continue;
+        automations.push(_extends({
+            id,
+            event
+        }, ((_action_trigger2 = action.trigger) == null ? void 0 : _action_trigger2.selector) ? {
+            selector: action.trigger.selector
+        } : {}, Number((_action_trigger3 = action.trigger) == null ? void 0 : _action_trigger3.threshold) > 0 ? {
+            threshold: Number(action.trigger.threshold)
+        } : {}, ((_action_trigger4 = action.trigger) == null ? void 0 : _action_trigger4.oncePerVisitor) === true ? {
+            oncePerVisitor: true
+        } : {}, ((_action_trigger5 = action.trigger) == null ? void 0 : _action_trigger5.oncePerSession) === true ? {
+            oncePerSession: true
+        } : {}, Number((_action_trigger6 = action.trigger) == null ? void 0 : _action_trigger6.cooldownMinutes) >= 1 ? {
+            cooldownMinutes: Number((_action_trigger7 = action.trigger) == null ? void 0 : _action_trigger7.cooldownMinutes)
+        } : {}, ((_action_trigger8 = action.trigger) == null ? void 0 : _action_trigger8.everyTime) === true ? {
+            everyTime: true
+        } : {}, {
+            steps: clientSteps,
+            hasServerSteps
+        }));
+    }
+    return automations;
+}
+export default compileClientAutomations;
+
+//# sourceMappingURL=compile-client-automations.js.map