@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/dynamic-list-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/dynamic-list-rule.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 * The rule behind a dynamic list (`docs/specs/email-overhaul.md` §3b/§3c).\n *\n * A list has held manually enrolled members only. A dynamic one stores this\n * rule instead and materializes into the same `members` subcollection, so the\n * send path keeps reading one deterministic collection rather than running an\n * unbounded scan per campaign.\n *\n * ## It extends the segment vocabulary rather than inventing one\n *\n * `tags` and `captureSources` mean exactly what they mean in\n * `contactMatchesSegment`, which this module reuses rather than restating:\n * two filter languages over the same contact document would drift, and the\n * one that drifts is whichever the merchant is not looking at. What is new is\n * a SOURCE dimension, because a list must be able to draw from silos that are\n * not `contacts` at all.\n *\n * ## Every field reads a value that is already written\n *\n * Nothing here collects anything new. `tags`, `captureSources` and the\n * `behavior` figures are contact fields; `formNames` is the `formName` a\n * submission already stores; `createdAfterMs`/`createdBeforeMs` read the\n * `createdAt` all three person silos already stamp; `campaignIds` reads the\n * membership `campaign-membership.ts` defines, which the forms console writes\n * and the submit route propagates.\n *\n * ⚠️ A rule selects an AUDIENCE. It does not grant consent — a person matched\n * by \"submitted a form\" has not opted in by submitting it. Membership and\n * basis are separate joins and `marketing-consent.ts` owns the second one.\n */\n\nimport { normalizeCampaignIds } from './campaign-membership'\nimport {\n  CONTACT_SOURCE_LABELS,\n  contactMatchesSegment,\n  type ContactSource,\n} from './contacts'\nimport {\n  isContactLifecycleStage,\n  normalizeContactFieldKey,\n  type ContactCustomValue,\n  type ContactLifecycleStage,\n  CRM_CONTACT_VIEW_FIELDS,\n  crmContactCustomKey,\n  type CrmViewFilterClause,\n} from './crm'\n\n/** The silos a dynamic list may draw people from. */\nexport type DynamicListSource =\n  | 'contacts'\n  | 'leads'\n  | 'siteMembers'\n  /**\n   * `hosts/{hostId}/formSubmissions`, which is what answers \"everyone who\n   * submitted form X\" — the form's NAME is on the submission and on nothing\n   * else. A contact captured by a form records only that some form produced\n   * it (`sources.form`), so `captureSources` cannot express the question.\n   */\n  | 'formSubmissions'\n\n/**\n * The silos whose rows can be filed under a campaign.\n *\n * A contact carries the membership inside the holder's own facet and a form\n * submission carries the membership its form had when it arrived. A lead and a\n * site member carry none — nothing writes one — so the campaign dimension is\n * SKIPPED for them rather than failed, which is the same discipline every\n * silo-specific dimension here follows.\n *\n * Stated as a value because both the matcher and the materializer's enrichment\n * decide off it, and two lists would drift into a rule that selects a silo the\n * scan never reads the field for.\n */\nexport const CAMPAIGN_MEMBER_SILOS: DynamicListSource[] = [\n  'contacts',\n  'formSubmissions',\n]\n\n/** Purchase-history filters. Contacts only — no other silo stores RFM. */\nexport interface DynamicListBehavior {\n  ordersCountAtLeast?: number\n  ltvCentsAtLeast?: number\n  lastPurchaseWithinDays?: number\n  /**\n   * Lapsed customers. A person who has NEVER purchased does not match: the\n   * question is \"bought once and stopped\", and answering it with everybody\n   * who never bought would put the whole audience in a win-back campaign.\n   */\n  noPurchaseForDays?: number\n}\n\n/**\n * Engagement filters, read from the per-person rollup the delivery webhook\n * maintains on `emailDeliveries/{personKey}`.\n *\n * ## Why the \"for N days\" arms count people with no record, and\n * `noPurchaseForDays` beside them does not\n *\n * A purchase is an act the person performed, so \"no purchase on file\" is\n * strong evidence they did not buy — and somebody who never bought is not a\n * LAPSED customer. An open is not like that. We learn of one only if we\n * mailed them, the message arrived, and their client loaded the tracking\n * pixel, so \"no open on file\" and \"did not open\" rest on the same evidence.\n * A merchant asking for people who are not engaging means the silent ones\n * too, and the sentences the console reads back say which lean applies rather\n * than leaving it to be inferred.\n *\n * ## Opens are the weaker signal, and the field names keep them apart\n *\n * Apple's Mail Privacy Protection prefetches images, so an open is partly a\n * statement about a mail client; a click is a statement about a person. Both\n * are offered because both are stored, and they are never merged into one\n * \"engaged\" number that would hide which of the two a rule rests on.\n */\nexport interface DynamicListEngagement {\n  /** Opened any of our mail within the last N days. */\n  openedWithinDays?: number\n  /** Clicked a link in any of our mail within the last N days. */\n  clickedWithinDays?: number\n  /** No open on record for at least N days — never opened counts. */\n  notOpenedForDays?: number\n  /** No click on record for at least N days — never clicked counts. */\n  notClickedForDays?: number\n}\n\n/**\n * How a custom-field clause compares the stored value to the one it names.\n *\n * Seven operators and no more, because each one has to be readable back as\n * a sentence and each one has to state what it does with a BLANK value —\n * see {@link customValueMatches} for the lean every operator takes.\n */\nexport const DYNAMIC_LIST_CUSTOM_OPS = [\n  'eq',\n  'neq',\n  'contains',\n  'gt',\n  'lt',\n  'set',\n  'unset',\n] as const\n\nexport type DynamicListCustomOp = (typeof DYNAMIC_LIST_CUSTOM_OPS)[number]\n\n/** The operators that compare against a value the clause carries. */\nconst VALUED_CUSTOM_OPS: ReadonlySet<DynamicListCustomOp> = new Set([\n  'eq',\n  'neq',\n  'contains',\n  'gt',\n  'lt',\n])\n\n/**\n * One condition on one custom contact field (AGL-2603).\n *\n * `key` is the {@link ContactFieldDefinition.key} the value is stored under\n * in the holder's facet, `op` says how to compare and `value` is what to\n * compare with — absent for `set` and `unset`, which ask about presence\n * rather than content. Scalars only, because that is all a custom field may\n * hold.\n */\nexport interface DynamicListCustomClause {\n  key: string\n  op: DynamicListCustomOp\n  value?: string | number | boolean\n}\n\n/**\n * The most custom-field clauses one block may carry.\n *\n * A bound on the predicate rather than on the audience — every clause is\n * evaluated in memory against a candidate already read — kept small for the\n * reason the branch cap is: the rule is merchant-authored and a stored array\n * has no natural end.\n */\nexport const DYNAMIC_LIST_MAX_CUSTOM_CLAUSES = 20\n\n/**\n * One AND-block of filters.\n *\n * Everything except `sources` and `segmentId`, which stay on the rule itself\n * — see {@link DynamicListRule.sources} for why the source list may not move\n * into a branch and may not be negated.\n */\nexport interface DynamicListDimensions {\n  /** Contacts only: at least one of these tags. */\n  tags?: string[]\n  /** Contacts only: captured by at least one of these surfaces. */\n  captureSources?: ContactSource[]\n  /** `formSubmissions` only: at least one of these form names, case-insensitive. */\n  formNames?: string[]\n  /**\n   * {@link CAMPAIGN_MEMBER_SILOS} only: filed under at least one of these\n   * campaigns, by campaign id.\n   *\n   * ⚠️ NOT the campaign a person's browser was attributed TO. A campaign\n   * TOUCH says which ad or link brought somebody in and lives on the\n   * attribution record; this says which campaign the merchant FILED the\n   * record under. The two are different facts about different acts and a\n   * single dimension over both would answer neither question — see\n   * `campaign-attribution.ts` for the other one.\n   *\n   * ⛔ And membership is not consent. A person selected by this dimension has\n   * opted in to nothing: they are here because a merchant put a form in a\n   * campaign, which is the merchant's own act. The materializer enrolls with\n   * no basis at all, and this dimension does not change that.\n   */\n  campaignIds?: string[]\n  /** Any silo: the record was created at or after this instant. */\n  createdAfterMs?: number\n  /** Any silo: the record was created strictly before this instant. */\n  createdBeforeMs?: number\n  /** Contacts only. */\n  behavior?: DynamicListBehavior\n  /** Any silo — engagement is a fact about an address, not about a silo row. */\n  engagement?: DynamicListEngagement\n  /** Already a member of every one of these lists. */\n  inListIds?: string[]\n  /** A member of none of these lists — the \"not in list X\" every rival has. */\n  notInListIds?: string[]\n  /*\n   * THE CRM DIMENSIONS (AGL-2603) — contacts only, every one of them.\n   *\n   * All four read the holder's FACET on the shared contact row, beside the\n   * tags: an owner, a lifecycle stage, a company and a custom field are one\n   * business's knowledge of a person, and the materializer reads them under\n   * the sweeping site's own group so that no rule can select another\n   * holder's segmentation. A lead, a site member and a form submission carry\n   * none of them, so the dimensions are SKIPPED for those silos rather than\n   * failed — the same discipline `tags` follows, and the same caveat about a\n   * negated branch whose only filter is one of these.\n   *\n   * A contact with no value on the field does not match any of the first\n   * three: \"owned by A\" is not satisfied by nobody owning them. The custom\n   * operators each state their own lean — see {@link customValueMatches}.\n   */\n  /** Owned by any of these team members, by account uid. */\n  ownerUids?: string[]\n  /** In any of these lifecycle stages. */\n  lifecycleStages?: ContactLifecycleStage[]\n  /** At any of these companies, by `orgs/{orgId}/companies` id. */\n  companyIds?: string[]\n  /** Every clause must hold — AND within the dimension, unlike the lists above. */\n  custom?: DynamicListCustomClause[]\n  /**\n   * Opened or clicked a campaign sent by the sweeping holder's sites within\n   * the last N days (AGL-2616) — the re-engagement audience.\n   *\n   * Read from the holder's facet like the four above, and contacts only for\n   * the same reason. It is NOT the {@link engagement} block one field up:\n   * that reads the address-level rollup, which counts every sender's mail\n   * to the address — a receipt, an invite, a sibling business's newsletter —\n   * and a \"win back our quiet readers\" audience built on it would mail\n   * people who are reading somebody else. This reads what the delivery\n   * webhook stamped on OUR facet from OUR campaigns. A contact with no stamp\n   * does not match, the dated-window lean the CRM dimensions all take.\n   */\n  engagedWithinDays?: number\n}\n\n/** One OR branch: an AND-block that may be inverted. */\nexport interface DynamicListRuleGroup extends DynamicListDimensions {\n  /**\n   * Invert this branch.\n   *\n   * ⚠️ A branch whose dimensions do not apply to a candidate's silo matches\n   * VACUOUSLY — this rule language skips inapplicable dimensions rather than\n   * failing them — so negating such a branch excludes that silo entirely.\n   * That is the honest consequence of the skip rule rather than a special\n   * case bolted onto it, and every clause the console reads back names the\n   * silo its dimension applies to.\n   */\n  negate?: boolean\n}\n\n/** The stored `rule` on a `kind: 'dynamic'` list document. */\nexport interface DynamicListRule extends DynamicListDimensions {\n  /**\n   * Which silos to draw from. Empty is not \"all\" — it matches nobody.\n   *\n   * ⛔ NOT groupable and NOT negatable, and that is a materializer constraint\n   * rather than a modelling preference. `sources` is the SCAN PLAN: it\n   * decides which collections are paged and in what order, and it is what the\n   * resume cursor names when a sweep runs out of budget. A negated source\n   * would mean \"every silo except\", which is a scan of collections the rule\n   * does not name; a source inside an OR branch would mean two scan plans for\n   * one rule. Either breaks the budget, the cursor, or both.\n   */\n  sources: DynamicListSource[]\n  /** Reuse a saved contact segment's tags and sources. Contacts only. */\n  segmentId?: string\n  /**\n   * Reuse a saved contacts VIEW's filters (AGL-2617). Contacts only.\n   *\n   * `orgs/{orgId}/crmViews/{viewId}`, a view over the Contacts section.\n   * Resolved once by the materializer into the dimensions this rule\n   * language already has — see {@link dynamicListDimensionsForCrmView} —\n   * and applied to the rule's top-level block the way a segment is: it\n   * always applies, and it is not folded into the OR branches. A view whose\n   * filters this language cannot express narrows to nobody, which is the\n   * same lean a deleted segment takes: a rule must not quietly select more\n   * than the view it reads as.\n   */\n  viewId?: string\n  /**\n   * Invert the rule's own top-level block — \"people who do NOT match these\".\n   *\n   * Applies to the dimensions on this object and to the resolved segment. It\n   * does not touch `sources`, and it does not touch {@link any}, which is\n   * ANDed with it and carries its own per-branch negation.\n   */\n  negate?: boolean\n  /**\n   * OR branches. A candidate must match at least one of them.\n   *\n   * ANDed with the top-level block, so a rule can say \"drawn from contacts,\n   * tagged vip, AND (spent over $500 OR ordered at least three times)\" — the\n   * shape a flat AND list cannot express and every compared product has.\n   * Absent or empty is no constraint at all, rather than a constraint nothing\n   * satisfies.\n   */\n  any?: DynamicListRuleGroup[]\n}\n\n/** One person as the materializer reads them out of a silo. */\nexport interface DynamicListCandidate {\n  silo: DynamicListSource\n  email: string\n  name?: string\n  createdAtMs?: number | null\n  /** Contacts only. */\n  tags?: string[]\n  /** Contacts only — the `sources` map, not the rule's `captureSources`. */\n  sources?: Partial<Record<ContactSource, true>>\n  ordersCount?: number\n  ltvCents?: number\n  lastPurchaseAtMs?: number | null\n  /** `formSubmissions` only. */\n  formName?: string\n  /**\n   * {@link CAMPAIGN_MEMBER_SILOS} only — the campaigns this row is filed\n   * under.\n   *\n   * Read from a different place in each of the two silos and normalized to one\n   * shape by the scan: a submission carries the field at the top of its\n   * document, a contact carries it inside the reading holder's facet, because\n   * a contact row is shared by every site in the org.\n   */\n  campaignIds?: string[]\n  /*\n   * ENRICHMENT — filled by a keyed lookup, not by the silo document.\n   *\n   * The two below describe an ADDRESS rather than a row, so they cannot come\n   * out of the scan the way everything above does. The materializer fetches\n   * them a page at a time, by document key, and only for a rule that asks —\n   * see `dynamicListRuleNeedsEngagement` and `dynamicListRuleNeedsLists`.\n   * Absent means \"not looked up\"; the matcher reads absent as no record,\n   * which is the reading each dimension's own documentation states.\n   */\n  lastOpenedAtMs?: number | null\n  lastClickedAtMs?: number | null\n  /** Lists this person is already a member of, by list id. */\n  listIds?: string[]\n  /*\n   * THE CRM FIELDS (AGL-2603) — contacts only, read out of the sweeping\n   * holder's facet the way `campaignIds` is. Absent means the facet holds no\n   * value, which the matcher reads as \"does not match\" for the first three\n   * and as \"unset\" for a custom clause.\n   */\n  ownerUid?: string\n  lifecycleStage?: ContactLifecycleStage\n  companyId?: string\n  /** The holder's custom values, keyed by field key. */\n  custom?: Record<string, ContactCustomValue>\n  /**\n   * When the person last opened or clicked one of the holder's campaigns —\n   * the facet stamp, read the way the fields above are. Absent when the\n   * facet carries none, which the matcher reads as \"does not match\".\n   */\n  lastEmailEngagementAtMs?: number | null\n}\n\n/** A saved segment's filters, resolved by the caller from `segmentId`. */\nexport interface ResolvedSegmentFilters {\n  tags?: string[]\n  sources?: ContactSource[]\n}\n\nconst asStringArray = (value: unknown): string[] =>\n  Array.isArray(value)\n    ? value\n        .map((entry) => String(entry ?? '').trim())\n        .filter((entry) => entry.length > 0 && entry.length <= 120)\n        .slice(0, 50)\n    : []\n\nconst asPositiveNumber = (value: unknown): number | undefined => {\n  const parsed = Number(value)\n  return Number.isFinite(parsed) && parsed >= 0 ? parsed : undefined\n}\n\nconst DYNAMIC_LIST_SOURCES: DynamicListSource[] = [\n  'contacts',\n  'leads',\n  'siteMembers',\n  'formSubmissions',\n]\n\n/**\n * Coerces a stored rule to the shape the matcher expects.\n *\n * The rule is merchant-authored through the console and read back on a\n * scheduled sweep, so it arrives as whatever Firestore held. Unknown source\n * names are dropped rather than tolerated: a typo that fell through would\n * read as a silo the materializer never scans, and the list would quietly\n * materialize a smaller set than the rule appears to describe.\n */\n/**\n * The most OR branches one rule may carry.\n *\n * A bound on the PREDICATE, not on the audience — every branch is evaluated\n * in memory against a candidate the sweep has already read, so this costs no\n * Firestore work. It exists because the rule is merchant-authored and a\n * stored array has no natural end: a thousand branches would be a thousand\n * evaluations per candidate per sweep.\n *\n * ⚠️ Set ABOVE what the console form can produce, and that is a correctness\n * requirement rather than headroom. The form's \"any of these filters\" mode\n * puts each control in a branch of its own, so a reader who fills in every\n * box authors nineteen, plus one branch per custom-field condition up to\n * {@link DYNAMIC_LIST_MAX_CUSTOM_CLAUSES} — and dropping a branch NARROWS an\n * OR, so a cap the form could reach would silently select fewer people than\n * the sentences above the controls say. The rule editor's spec holds the sum\n * under this number.\n */\nexport const DYNAMIC_LIST_MAX_GROUPS = 40\n\n/**\n * The most lists one dimension may name.\n *\n * This one DOES cost reads — a named list is a keyed lookup per candidate per\n * page — so it is deliberately small, and it is the same number on both arms\n * so that \"in these\" and \"not in those\" cannot be combined into a larger\n * fan-out than either alone.\n */\nexport const DYNAMIC_LIST_MAX_LIST_REFERENCES = 5\n\n/**\n * Coerces a stored custom-field clause, or drops it.\n *\n * Dropped rather than tolerated for the reason a typo'd silo is: a clause\n * with a key no definition uses, an operator the matcher does not know, or a\n * missing value where one is compared against, is a filter no contact can\n * satisfy — and a rule that quietly matches nobody reads exactly like a rule\n * that has not run yet. The key goes through the definition's own normalizer\n * so a clause written against a label (`Plan Name`) still reaches the stored\n * key (`plan_name`), and a value is kept only as a scalar because that is all\n * a custom field may hold.\n */\nfunction normalizeCustomClause(raw: unknown): DynamicListCustomClause | null {\n  const entry = (raw ?? {}) as Record<string, unknown>\n  const key = normalizeContactFieldKey(entry['key'])\n  const op = entry['op']\n  if (\n    !key ||\n    typeof op !== 'string' ||\n    !(DYNAMIC_LIST_CUSTOM_OPS as readonly string[]).includes(op)\n  ) {\n    return null\n  }\n  const operator = op as DynamicListCustomOp\n  if (!VALUED_CUSTOM_OPS.has(operator)) return { key, op: operator }\n  const value = entry['value']\n  if (typeof value === 'string') {\n    const trimmed = value.trim().slice(0, 500)\n    return trimmed ? { key, op: operator, value: trimmed } : null\n  }\n  if (typeof value === 'number') {\n    return Number.isFinite(value) ? { key, op: operator, value } : null\n  }\n  if (typeof value === 'boolean') return { key, op: operator, value }\n  return null\n}\n\n/** Coerces the dimensions shared by the rule and each of its OR branches. */\nfunction normalizeDimensions(value: Record<string, unknown>): DynamicListDimensions {\n  const behavior = (value['behavior'] ?? {}) as Record<string, unknown>\n  const normalizedBehavior: DynamicListBehavior = {\n    ...(asPositiveNumber(behavior['ordersCountAtLeast']) !== undefined\n      ? { ordersCountAtLeast: asPositiveNumber(behavior['ordersCountAtLeast']) }\n      : {}),\n    ...(asPositiveNumber(behavior['ltvCentsAtLeast']) !== undefined\n      ? { ltvCentsAtLeast: asPositiveNumber(behavior['ltvCentsAtLeast']) }\n      : {}),\n    ...(asPositiveNumber(behavior['lastPurchaseWithinDays']) !== undefined\n      ? {\n          lastPurchaseWithinDays: asPositiveNumber(\n            behavior['lastPurchaseWithinDays'],\n          ),\n        }\n      : {}),\n    ...(asPositiveNumber(behavior['noPurchaseForDays']) !== undefined\n      ? { noPurchaseForDays: asPositiveNumber(behavior['noPurchaseForDays']) }\n      : {}),\n  }\n  const engagement = (value['engagement'] ?? {}) as Record<string, unknown>\n  const normalizedEngagement: DynamicListEngagement = {\n    ...(asPositiveNumber(engagement['openedWithinDays']) !== undefined\n      ? { openedWithinDays: asPositiveNumber(engagement['openedWithinDays']) }\n      : {}),\n    ...(asPositiveNumber(engagement['clickedWithinDays']) !== undefined\n      ? { clickedWithinDays: asPositiveNumber(engagement['clickedWithinDays']) }\n      : {}),\n    ...(asPositiveNumber(engagement['notOpenedForDays']) !== undefined\n      ? { notOpenedForDays: asPositiveNumber(engagement['notOpenedForDays']) }\n      : {}),\n    ...(asPositiveNumber(engagement['notClickedForDays']) !== undefined\n      ? { notClickedForDays: asPositiveNumber(engagement['notClickedForDays']) }\n      : {}),\n  }\n  const tags = asStringArray(value['tags'])\n  const captureSources = asStringArray(value['captureSources']) as ContactSource[]\n  const formNames = asStringArray(value['formNames'])\n  // Through the campaign field's own normalizer rather than the local string\n  // coercion: the cap, the dedupe and the trim are properties of the stored\n  // membership, and a second reading of them here would let a rule name more\n  // campaigns than any record is allowed to be filed under.\n  const campaignIds = normalizeCampaignIds(value['campaignIds'])\n  const createdAfterMs = asPositiveNumber(value['createdAfterMs'])\n  const createdBeforeMs = asPositiveNumber(value['createdBeforeMs'])\n  const inListIds = asStringArray(value['inListIds']).slice(\n    0,\n    DYNAMIC_LIST_MAX_LIST_REFERENCES,\n  )\n  const notInListIds = asStringArray(value['notInListIds']).slice(\n    0,\n    DYNAMIC_LIST_MAX_LIST_REFERENCES,\n  )\n  const ownerUids = asStringArray(value['ownerUids'])\n  // A stage the model does not name is dropped, not kept: kept, it would be\n  // a filter no contact can satisfy, and the rule would read as the stages\n  // it does name while selecting nobody.\n  const lifecycleStages = asStringArray(value['lifecycleStages']).filter(\n    isContactLifecycleStage,\n  )\n  const companyIds = asStringArray(value['companyIds'])\n  const custom = (Array.isArray(value['custom']) ? value['custom'] : [])\n    .slice(0, DYNAMIC_LIST_MAX_CUSTOM_CLAUSES)\n    .map(normalizeCustomClause)\n    .filter((clause): clause is DynamicListCustomClause => clause !== null)\n  const engagedWithinDays = asPositiveNumber(value['engagedWithinDays'])\n  return {\n    ...(tags.length ? { tags } : {}),\n    ...(captureSources.length ? { captureSources } : {}),\n    ...(formNames.length ? { formNames } : {}),\n    ...(campaignIds.length ? { campaignIds } : {}),\n    ...(createdAfterMs !== undefined ? { createdAfterMs } : {}),\n    ...(createdBeforeMs !== undefined ? { createdBeforeMs } : {}),\n    ...(Object.keys(normalizedBehavior).length\n      ? { behavior: normalizedBehavior }\n      : {}),\n    ...(Object.keys(normalizedEngagement).length\n      ? { engagement: normalizedEngagement }\n      : {}),\n    ...(inListIds.length ? { inListIds } : {}),\n    ...(notInListIds.length ? { notInListIds } : {}),\n    ...(ownerUids.length ? { ownerUids } : {}),\n    ...(lifecycleStages.length ? { lifecycleStages } : {}),\n    ...(companyIds.length ? { companyIds } : {}),\n    ...(custom.length ? { custom } : {}),\n    ...(engagedWithinDays !== undefined ? { engagedWithinDays } : {}),\n  }\n}\n\n/** True when a branch constrains nothing, so keeping it would widen the rule. */\nfunction dimensionsAreEmpty(dimensions: DynamicListDimensions): boolean {\n  return Object.keys(dimensions).length === 0\n}\n\nexport function normalizeDynamicListRule(stored: unknown): DynamicListRule {\n  const value = (stored ?? {}) as Record<string, unknown>\n  const sources = asStringArray(value['sources']).filter((source): source is DynamicListSource =>\n    (DYNAMIC_LIST_SOURCES as string[]).includes(source),\n  )\n  const segmentId = String(value['segmentId'] ?? '').trim()\n  const viewId = String(value['viewId'] ?? '').trim()\n  /*\n   * An empty OR branch is DROPPED rather than kept.\n   *\n   * A branch with no dimensions matches everybody, and `any` is satisfied by\n   * one branch — so a single empty one would silently disable every other\n   * branch beside it. Dropping it is the same decision the source filter\n   * makes about a typo'd silo name, for the same reason: a rule must not\n   * quietly select a different population than the one it reads as.\n   */\n  const groups = (Array.isArray(value['any']) ? value['any'] : [])\n    .slice(0, DYNAMIC_LIST_MAX_GROUPS)\n    .map((raw) => {\n      const entry = (raw ?? {}) as Record<string, unknown>\n      const dimensions = normalizeDimensions(entry)\n      return {\n        ...dimensions,\n        ...(entry['negate'] === true ? { negate: true } : {}),\n      } as DynamicListRuleGroup\n    })\n    .filter((group) => !dimensionsAreEmpty(stripNegate(group)))\n  return {\n    sources,\n    ...(segmentId ? { segmentId } : {}),\n    ...(viewId ? { viewId } : {}),\n    ...(value['negate'] === true ? { negate: true } : {}),\n    ...normalizeDimensions(value),\n    ...(groups.length ? { any: groups } : {}),\n  }\n}\n\n/** A branch without its flag, so emptiness is decided on its filters alone. */\nfunction stripNegate(group: DynamicListRuleGroup): DynamicListDimensions {\n  const { negate, ...dimensions } = group\n  void negate\n  return dimensions\n}\n\n/**\n * True when a rule can select nobody no matter what the data holds.\n *\n * Worth its own answer because the failure it prevents is silent: an empty\n * `sources` materializes an empty list, and an empty list reads in the\n * composer exactly like a rule that simply has not run yet.\n */\nexport function dynamicListRuleIsEmpty(rule: DynamicListRule): boolean {\n  return rule.sources.length === 0\n}\n\n/**\n * Does this person match the rule?\n *\n * AND across dimensions, OR within one — the same shape `contactMatchesSegment`\n * uses, so a merchant who has built a segment already knows how this reads.\n *\n * On top of that flat block sit two operators, and the whole verdict is:\n *\n * ```\n * silo is in sources\n *   AND (negate ? NOT top-level block : top-level block)\n *   AND (any branches ? at least one branch, each with its own negate : true)\n * ```\n *\n * Which is nested AND/OR with negation, arranged so that the only part the\n * materializer's scan plan depends on — `sources` — sits outside both\n * operators and cannot be touched by either.\n *\n * Dimensions that do not apply to a candidate's silo are SKIPPED rather than\n * failed. A rule of `sources: ['contacts','siteMembers'], tags: ['vip']` means\n * \"VIP contacts, and site members\" — reading `tags` against a member document\n * that cannot carry tags would make the second source contribute nobody, and\n * a source that silently contributes nobody is the same defect as a dropped\n * typo above.\n *\n * @param segment filters resolved from `rule.segmentId`, when it names one.\n * @param view    the dimensions resolved from `rule.viewId`, when it names\n *                one — see {@link dynamicListDimensionsForCrmView}.\n * @param nowMs   evaluation instant, injected so a sweep is reproducible.\n */\nexport function candidateMatchesDynamicListRule(\n  candidate: DynamicListCandidate,\n  rule: DynamicListRule,\n  options: {\n    segment?: ResolvedSegmentFilters | null\n    view?: DynamicListDimensions | null\n    nowMs: number\n  },\n): boolean {\n  /*\n   * The source filter, first and outside everything else. It is the one\n   * dimension that is neither negatable nor groupable, because it is the scan\n   * plan rather than a filter over what the scan found.\n   */\n  if (!rule.sources.includes(candidate.silo)) return false\n\n  /*\n   * A resolved VIEW is its own AND-block beside the rule's, inside the\n   * negatable top level with the segment — the view always applies, and a\n   * rule that inverts its block inverts the view with it, which is what\n   * \"nobody matching all of these\" reads as when a view is one of them.\n   * Beside rather than merged INTO the rule's dimensions: the lists within\n   * a dimension are OR, so merging a view's owners with the rule's would\n   * widen both.\n   */\n  const top =\n    matchesDimensions(candidate, rule, {\n      segment: options.segment ?? null,\n      nowMs: options.nowMs,\n    }) &&\n    (!options.view ||\n      matchesDimensions(candidate, options.view, {\n        segment: null,\n        nowMs: options.nowMs,\n      }))\n  if ((rule.negate === true ? !top : top) === false) return false\n\n  /*\n   * The OR branches, ANDed with the block above. Absent or empty is no\n   * constraint — `Array.prototype.some` on an empty array is `false`, which\n   * would turn a rule that named no branches into one nobody satisfies.\n   */\n  const groups = rule.any ?? []\n  if (!groups.length) return true\n  return groups.some((group) => {\n    const matched = matchesDimensions(candidate, group, {\n      // A saved segment belongs to the rule, not to a branch: it is resolved\n      // once by the caller from the rule's own `segmentId`, and folding it\n      // into every branch would make each branch narrower than it reads.\n      segment: null,\n      nowMs: options.nowMs,\n    })\n    return group.negate === true ? !matched : matched\n  })\n}\n\n/**\n * One AND-block of dimensions against one candidate.\n *\n * Extracted so the top-level block and every OR branch are decided by the\n * same code. Two implementations of \"does this person match these filters\"\n * would drift, and the half that drifts is whichever the merchant is not\n * looking at — the same reason `contactMatchesSegment` is reused here rather\n * than restated.\n */\nfunction matchesDimensions(\n  candidate: DynamicListCandidate,\n  rule: DynamicListDimensions,\n  options: { segment: ResolvedSegmentFilters | null; nowMs: number },\n): boolean {\n  const day = 86_400_000\n\n  if (rule.createdAfterMs !== undefined) {\n    // A record with no creation stamp cannot satisfy an age window, and\n    // admitting it would put people INTO an audience the merchant bounded on\n    // purpose. This is the opposite lean from the consent module's unknown\n    // handling, and deliberately so: there, the unknown keeps somebody\n    // reachable; here, it would add somebody the rule excluded.\n    if (candidate.createdAtMs == null) return false\n    if (candidate.createdAtMs < rule.createdAfterMs) return false\n  }\n  if (rule.createdBeforeMs !== undefined) {\n    if (candidate.createdAtMs == null) return false\n    if (candidate.createdAtMs >= rule.createdBeforeMs) return false\n  }\n\n  if (candidate.silo === 'formSubmissions' && rule.formNames?.length) {\n    const wanted = new Set(rule.formNames.map((name) => name.toLowerCase()))\n    if (!wanted.has(String(candidate.formName ?? '').trim().toLowerCase())) {\n      return false\n    }\n  }\n\n  /*\n   * FILED UNDER A CAMPAIGN — the two silos that can be, and only those.\n   *\n   * OR within the dimension, like every other list here: a merchant naming\n   * three campaigns means anyone in any of them, not the handful of people\n   * filed under all three at once.\n   *\n   * A row in a silo that carries no membership is SKIPPED rather than failed,\n   * so \"people in the spring push, and every site member\" contributes members\n   * — the same reading `tags` gets for a lead. ⚠️ Which also means a NEGATED\n   * branch whose only filter is this one excludes those silos entirely; that\n   * is the honest consequence of the skip rule, stated on the branch flag\n   * itself.\n   */\n  if (\n    rule.campaignIds?.length &&\n    CAMPAIGN_MEMBER_SILOS.includes(candidate.silo)\n  ) {\n    // An absent field reads as \"filed under nothing\", which is what a row\n    // written before the form named a campaign actually says.\n    const filed = new Set(candidate.campaignIds ?? [])\n    if (!rule.campaignIds.some((campaignId) => filed.has(campaignId))) {\n      return false\n    }\n  }\n\n  if (candidate.silo === 'contacts') {\n    const segmentFilters = {\n      tags: [...(options.segment?.tags ?? []), ...(rule.tags ?? [])],\n      sources: [\n        ...(options.segment?.sources ?? []),\n        ...(rule.captureSources ?? []),\n      ],\n    }\n    if (\n      !contactMatchesSegment(\n        { tags: candidate.tags ?? [], sources: candidate.sources ?? {} },\n        segmentFilters,\n      )\n    ) {\n      return false\n    }\n    const behavior = rule.behavior\n    if (behavior) {\n      if (\n        behavior.ordersCountAtLeast !== undefined &&\n        (candidate.ordersCount ?? 0) < behavior.ordersCountAtLeast\n      ) {\n        return false\n      }\n      if (\n        behavior.ltvCentsAtLeast !== undefined &&\n        (candidate.ltvCents ?? 0) < behavior.ltvCentsAtLeast\n      ) {\n        return false\n      }\n      if (behavior.lastPurchaseWithinDays !== undefined) {\n        const last = candidate.lastPurchaseAtMs ?? null\n        if (last === null) return false\n        if (last < options.nowMs - behavior.lastPurchaseWithinDays * day) {\n          return false\n        }\n      }\n      if (behavior.noPurchaseForDays !== undefined) {\n        const last = candidate.lastPurchaseAtMs ?? null\n        // Never purchased is not lapsed — see DynamicListBehavior.\n        if (last === null) return false\n        if (last > options.nowMs - behavior.noPurchaseForDays * day) {\n          return false\n        }\n      }\n    }\n    /*\n     * THE CRM DIMENSIONS — OR within each, AND across them, like the tags.\n     *\n     * An absent value matches none of the first three. \"Owned by A or B\" is\n     * a positive claim about the relationship, and a contact nobody owns is\n     * not a contact A owns; the same for a stage never set and a company\n     * never linked. The lean is the dated-window one rather than the\n     * consent module's: admitting the unknown here would put people INTO an\n     * audience the merchant bounded on purpose.\n     */\n    if (rule.ownerUids?.length) {\n      if (!candidate.ownerUid || !rule.ownerUids.includes(candidate.ownerUid)) {\n        return false\n      }\n    }\n    if (rule.lifecycleStages?.length) {\n      if (\n        !candidate.lifecycleStage ||\n        !rule.lifecycleStages.includes(candidate.lifecycleStage)\n      ) {\n        return false\n      }\n    }\n    if (rule.companyIds?.length) {\n      if (!candidate.companyId || !rule.companyIds.includes(candidate.companyId)) {\n        return false\n      }\n    }\n    // Every clause must hold. A merchant adding a second condition on a\n    // custom field is narrowing, which is what a second box on a form means\n    // everywhere else in it — the OR is the `any` branches, not this list.\n    for (const clause of rule.custom ?? []) {\n      if (!customValueMatches(candidate.custom?.[clause.key], clause)) {\n        return false\n      }\n    }\n    /*\n     * ENGAGED WITH OUR CAMPAIGNS — the facet stamp, on the same lean as\n     * `lastPurchaseWithinDays`: no stamp is no match. This is the one\n     * engagement figure that is about THIS holder's mail; the address-level\n     * arms further down are about the address.\n     */\n    if (rule.engagedWithinDays !== undefined) {\n      const last = candidate.lastEmailEngagementAtMs ?? null\n      if (last === null) return false\n      if (last < options.nowMs - rule.engagedWithinDays * day) return false\n    }\n  }\n\n  /*\n   * ENGAGEMENT — every silo, not contacts only.\n   *\n   * The rollup keys on the ADDRESS, and a lead, a site member and a form\n   * submission all have one. Restricting this to contacts the way `behavior`\n   * is restricted would be restricting it to the silo that happens to store\n   * the OTHER figures, which is not a fact about engagement.\n   */\n  const engagement = rule.engagement\n  if (engagement) {\n    const opened = candidate.lastOpenedAtMs ?? null\n    const clicked = candidate.lastClickedAtMs ?? null\n    if (engagement.openedWithinDays !== undefined) {\n      if (opened === null) return false\n      if (opened < options.nowMs - engagement.openedWithinDays * day) {\n        return false\n      }\n    }\n    if (engagement.clickedWithinDays !== undefined) {\n      if (clicked === null) return false\n      if (clicked < options.nowMs - engagement.clickedWithinDays * day) {\n        return false\n      }\n    }\n    // No record MATCHES the quiet arms — see DynamicListEngagement for why\n    // this leans the opposite way from `noPurchaseForDays` above it.\n    if (engagement.notOpenedForDays !== undefined && opened !== null) {\n      if (opened > options.nowMs - engagement.notOpenedForDays * day) {\n        return false\n      }\n    }\n    if (engagement.notClickedForDays !== undefined && clicked !== null) {\n      if (clicked > options.nowMs - engagement.notClickedForDays * day) {\n        return false\n      }\n    }\n  }\n\n  /*\n   * LIST MEMBERSHIP — \"and not the people already on my customers list\".\n   *\n   * An absent `listIds` reads as \"on no list\", and that is the reading a\n   * failed or skipped lookup gets too. The direction is chosen rather than\n   * defaulted: an unenriched candidate failing `inListIds` keeps them OUT of\n   * an audience, where an unenriched candidate passing `notInListIds` would\n   * let a lookup failure quietly re-admit the people a merchant excluded. The\n   * materializer runs the enrichment whenever a rule names a list, so the\n   * absent case is a lookup that failed rather than an ordinary one — and\n   * these two readings are what it costs when one does.\n   */\n  const memberOf = new Set(candidate.listIds ?? [])\n  if (rule.inListIds?.length) {\n    if (!rule.inListIds.every((listId) => memberOf.has(listId))) return false\n  }\n  if (rule.notInListIds?.length) {\n    if (rule.notInListIds.some((listId) => memberOf.has(listId))) return false\n  }\n\n  return true\n}\n\n/** A value that is on the record: not absent, not `null`, not blank text. */\nconst customValueIsSet = (value: ContactCustomValue | undefined): boolean =>\n  value !== undefined &&\n  value !== null &&\n  !(typeof value === 'string' && value.trim() === '')\n\n/** A value as text, for the comparisons that read it that way. */\nconst customValueText = (value: string | number | boolean): string =>\n  String(value).trim().toLowerCase()\n\n/**\n * Does one stored custom value satisfy one clause?\n *\n * Exported because the comparison is the whole meaning of the dimension and\n * a surface that previews a value against a clause must not carry a second\n * copy of it. The leans, per operator, because each has to be readable back\n * as a sentence the merchant can check against their intent:\n *\n *  - `eq` — the same value. Text compares case-insensitively and trimmed,\n *    because a `select` option typed as `Enterprise` and stored as\n *    `enterprise` is one option; a number and a boolean compare as\n *    themselves, and a number stored as text still equals the number.\n *  - `neq` — a value that is set AND differs. A blank does NOT count: a\n *    merchant excluding one plan is not asking for everyone whose plan was\n *    never recorded, and `unset` exists for that question.\n *  - `contains` — text containment, case-insensitive; a blank contains\n *    nothing.\n *  - `gt` / `lt` — numeric when both sides parse as numbers, text otherwise.\n *    Text ordering is what a `date` field stores (ISO dates order as text),\n *    and a blank is neither greater nor less than anything.\n *  - `set` / `unset` — presence. `false` and `0` are set; `null`, absent and\n *    blank text are not.\n */\nexport function customValueMatches(\n  value: ContactCustomValue | undefined,\n  clause: DynamicListCustomClause,\n): boolean {\n  const present = customValueIsSet(value)\n  switch (clause.op) {\n    case 'set':\n      return present\n    case 'unset':\n      return !present\n    default:\n      break\n  }\n  if (!present || clause.value === undefined) return false\n  const stored = value as string | number | boolean\n  const wanted = clause.value\n  switch (clause.op) {\n    case 'eq':\n      return customValueText(stored) === customValueText(wanted)\n    case 'neq':\n      return customValueText(stored) !== customValueText(wanted)\n    case 'contains':\n      return customValueText(stored).includes(customValueText(wanted))\n    case 'gt':\n    case 'lt': {\n      const left = Number(stored)\n      const right = Number(wanted)\n      const numeric =\n        typeof stored !== 'boolean' &&\n        typeof wanted !== 'boolean' &&\n        String(stored).trim() !== '' &&\n        String(wanted).trim() !== '' &&\n        Number.isFinite(left) &&\n        Number.isFinite(right)\n      if (numeric) return clause.op === 'gt' ? left > right : left < right\n      const a = customValueText(stored)\n      const b = customValueText(wanted)\n      return clause.op === 'gt' ? a > b : a < b\n    }\n    default:\n      return false\n  }\n}\n\n/** Every dimension block a rule carries: its own, then each OR branch. */\nfunction allDimensions(rule: DynamicListRule): DynamicListDimensions[] {\n  return [rule, ...(rule.any ?? [])]\n}\n\n/**\n * Does evaluating this rule need the sweeping holder's contact FACET?\n *\n * The campaign membership and the four CRM fields all live inside the facet,\n * which is keyed by the consent group the materializer has to resolve with\n * one org read. A rule that names none of them pays nothing — the same\n * opt-in cost `dynamicListRuleNeedsCampaigns` already describes, widened to\n * every dimension the facet holds so the materializer asks one question\n * rather than five.\n */\nexport function dynamicListRuleNeedsContactFacet(rule: DynamicListRule): boolean {\n  return allDimensions(rule).some(\n    (dimensions) =>\n      (dimensions.campaignIds?.length ?? 0) > 0 ||\n      (dimensions.ownerUids?.length ?? 0) > 0 ||\n      (dimensions.lifecycleStages?.length ?? 0) > 0 ||\n      (dimensions.companyIds?.length ?? 0) > 0 ||\n      (dimensions.custom?.length ?? 0) > 0 ||\n      dimensions.engagedWithinDays !== undefined,\n  )\n}\n\n/**\n * Does evaluating this rule need the per-person engagement rollup?\n *\n * Asked by the materializer before it spends a keyed read per candidate. A\n * rule with no engagement clause anywhere pays nothing, which is what keeps\n * the lookup an opt-in cost rather than a tax on every sweep.\n */\nexport function dynamicListRuleNeedsEngagement(rule: DynamicListRule): boolean {\n  return allDimensions(rule).some(\n    (dimensions) =>\n      dimensions.engagement !== undefined &&\n      Object.keys(dimensions.engagement).length > 0,\n  )\n}\n\n/**\n * Does evaluating this rule need a contact's campaign membership?\n *\n * Asked by the materializer before it resolves the consent group the facet is\n * keyed by — one org read, and only for a rule that names a campaign. A\n * submission's membership is on the row the sweep already paged and costs\n * nothing either way, so this answers about the CONTACTS silo's extra work.\n */\nexport function dynamicListRuleNeedsCampaigns(rule: DynamicListRule): boolean {\n  return allDimensions(rule).some(\n    (dimensions) => (dimensions.campaignIds?.length ?? 0) > 0,\n  )\n}\n\n/**\n * The rule with one list id removed from both membership arms.\n *\n * ⛔ A dynamic list whose rule referred to ITSELF would oscillate, and the\n * oscillation removes people. `notInListIds: [self]` matches everybody on the\n * first sweep, which enrolls them; on the second sweep they are all members,\n * so nobody matches, and reconciliation deletes every row the rule created.\n * The third sweep enrolls them again. Membership would flip on every beat of\n * the materializing sweep forever, and half of those beats are deletions.\n *\n * A self-reference also cannot mean anything useful — the answer depends on\n * whether the sweep has run yet — so it is dropped rather than refused: a\n * merchant who picks their own audience gets the rule without that clause,\n * which is what it would have meant if it meant anything.\n */\nexport function dynamicListRuleWithoutListReference(\n  rule: DynamicListRule,\n  listId: string,\n): DynamicListRule {\n  if (!listId) return rule\n  const strip = <T extends DynamicListDimensions>(dimensions: T): T => {\n    const inListIds = (dimensions.inListIds ?? []).filter((id) => id !== listId)\n    const notInListIds = (dimensions.notInListIds ?? []).filter(\n      (id) => id !== listId,\n    )\n    const next = { ...dimensions }\n    if (dimensions.inListIds) {\n      if (inListIds.length) next.inListIds = inListIds\n      else delete next.inListIds\n    }\n    if (dimensions.notInListIds) {\n      if (notInListIds.length) next.notInListIds = notInListIds\n      else delete next.notInListIds\n    }\n    return next\n  }\n  const stripped = strip(rule)\n  /*\n   * A branch whose ONLY filter was the self-reference is dropped, not kept\n   * empty: an empty branch matches everybody, and one satisfied branch\n   * satisfies `any`, so keeping it would silently disable every branch\n   * beside it. Same reasoning as the normalizer's own empty-branch drop.\n   */\n  const groups = (rule.any ?? [])\n    .map((group) => strip(group))\n    .filter((group) => Object.keys(stripNegate(group)).length > 0)\n  if (groups.length) stripped.any = groups\n  else delete stripped.any\n  return stripped\n}\n\n/** Every list id this rule refers to, in either direction, de-duplicated. */\nexport function dynamicListRuleListIds(rule: DynamicListRule): string[] {\n  const ids = new Set<string>()\n  for (const dimensions of allDimensions(rule)) {\n    for (const listId of dimensions.inListIds ?? []) ids.add(listId)\n    for (const listId of dimensions.notInListIds ?? []) ids.add(listId)\n  }\n  return [...ids]\n}\n\n/*==========================================\n * A SAVED CONTACTS VIEW, IN THIS LANGUAGE (AGL-2617).\n *\n * A view stores the Contacts list's own filter clauses — a field, an\n * operator, a value — and an audience rule stores dimensions. The two are\n * different vocabularies for overlapping questions: \"owner is Dana\" is an\n * `ownerUids` dimension, \"tagged vip or wholesale\" is a `tags` dimension,\n * \"created after June\" is `createdAfterMs`. So a view is USABLE as an\n * audience exactly as far as its clauses have a dimension here, and the\n * translation below is the whole of that claim: it is pure, it names every\n * clause it could not carry, and nothing about a view is matched any other\n * way. The alternative — evaluating the list's grammar inside the sweep —\n * would put a second matcher beside the one the console runs, in a module\n * that may not import the grammar's home.\n *\n * A clause with no dimension is UNSUPPORTED, never dropped. A name prefix,\n * an email, an `updatedAt` window, a form id: dropping one would make the\n * audience wider than the view it was picked as, and a campaign going to\n * the wrong people is the failure every part of this feature is shaped to\n * prevent. The picker offers only views that translate whole, and the\n * materializer treats a stored reference to one that does not the way it\n * treats a deleted segment.\n *=========================================*/\n\n/** What a view's filters became — see the section note. */\nexport interface DynamicListViewTranslation {\n  dimensions: DynamicListDimensions\n  /** The clauses this language has no dimension for. Empty means an audience. */\n  unsupported: CrmViewFilterClause[]\n}\n\nconst DAY_MS = 86_400_000\n\n/** The values an `isAnyOf` carries, or the one an equality does; `null` for any other operator. */\nconst viewClauseValues = (clause: CrmViewFilterClause): string[] | null => {\n  const value = clause.value.trim()\n  if (clause.op === 'isAnyOf') {\n    return value\n      .split(',')\n      .map((entry) => entry.trim())\n      .filter(Boolean)\n  }\n  if (clause.op === 'equals' || clause.op === 'is' || clause.op === 'contains') {\n    return value ? [value] : []\n  }\n  return null\n}\n\nconst CUSTOM_VIEW_OPS: Readonly<Record<string, DynamicListCustomOp>> = {\n  equals: 'eq',\n  is: 'eq',\n  '=': 'eq',\n  doesNotEqual: 'neq',\n  '!=': 'neq',\n  contains: 'contains',\n  '>': 'gt',\n  '<': 'lt',\n  isNotEmpty: 'set',\n  isEmpty: 'unset',\n}\n\n/**\n * A view's filters as the dimensions of one AND-block, and the clauses\n * that could not be.\n *\n * Every list operator keeps its own meaning across the translation:\n * `isAnyOf` is the OR the dimension lists already are, an equality is a\n * list of one, a `contains` on the tag array is one tag matched whole. The\n * dates read the clause's value as an instant — a day, as the filter bar\n * writes one — with `after` and `onOrBefore` stepping a day past it the\n * way the list's own matcher does. A purchase threshold has a floor here\n * and no ceiling, so `at least` and `over` carry and `under` cannot.\n */\nexport function dynamicListDimensionsForCrmView(\n  filters: readonly CrmViewFilterClause[],\n): DynamicListViewTranslation {\n  const fields = CRM_CONTACT_VIEW_FIELDS\n  const dimensions: DynamicListDimensions = {}\n  const unsupported: CrmViewFilterClause[] = []\n  const behavior: DynamicListBehavior = {}\n  const custom: DynamicListCustomClause[] = []\n  const extend = (\n    key: 'tags' | 'ownerUids' | 'companyIds',\n    values: string[],\n  ) => {\n    dimensions[key] = [...(dimensions[key] ?? []), ...values]\n  }\n\n  for (const clause of filters) {\n    const values = viewClauseValues(clause)\n    const value = clause.value.trim()\n    const customKey = crmContactCustomKey(clause.field)\n    if (customKey !== null) {\n      const key = normalizeContactFieldKey(customKey)\n      const op = CUSTOM_VIEW_OPS[clause.op]\n      if (key && op) {\n        custom.push(\n          op === 'set' || op === 'unset' ? { key, op } : { key, op, value },\n        )\n        continue\n      }\n      unsupported.push(clause)\n      continue\n    }\n    switch (clause.field) {\n      case fields.tags:\n        if (values?.length) {\n          extend('tags', values.map((tag) => tag.toLowerCase()))\n          continue\n        }\n        break\n      case fields.source:\n        if (values?.length) {\n          const sources = values.filter(\n            (source): source is ContactSource => source in CONTACT_SOURCE_LABELS,\n          )\n          if (sources.length === values.length) {\n            dimensions.captureSources = [\n              ...(dimensions.captureSources ?? []),\n              ...sources,\n            ]\n            continue\n          }\n        }\n        break\n      case fields.owner:\n        if (values?.length) {\n          extend('ownerUids', values)\n          continue\n        }\n        break\n      case fields.stage:\n        if (values?.length && values.every(isContactLifecycleStage)) {\n          dimensions.lifecycleStages = [\n            ...(dimensions.lifecycleStages ?? []),\n            ...(values as ContactLifecycleStage[]),\n          ]\n          continue\n        }\n        break\n      case fields.company:\n        if (values?.length) {\n          extend('companyIds', values)\n          continue\n        }\n        break\n      case fields.createdAt: {\n        const at = Date.parse(value)\n        if (Number.isFinite(at)) {\n          if (clause.op === 'after') dimensions.createdAfterMs = at + DAY_MS\n          else if (clause.op === 'onOrAfter') dimensions.createdAfterMs = at\n          else if (clause.op === 'before') dimensions.createdBeforeMs = at\n          else if (clause.op === 'onOrBefore') {\n            dimensions.createdBeforeMs = at + DAY_MS\n          } else if (clause.op === 'is') {\n            dimensions.createdAfterMs = at\n            dimensions.createdBeforeMs = at + DAY_MS\n          } else break\n          continue\n        }\n        break\n      }\n      case fields.orders:\n      case fields.ltv: {\n        const amount = Number(value)\n        if (Number.isFinite(amount) && (clause.op === '>=' || clause.op === '>')) {\n          const floor = clause.op === '>' ? amount + 1 : amount\n          if (clause.field === fields.orders) behavior.ordersCountAtLeast = floor\n          else behavior.ltvCentsAtLeast = floor\n          continue\n        }\n        break\n      }\n      default:\n        break\n    }\n    unsupported.push(clause)\n  }\n\n  if (Object.keys(behavior).length) dimensions.behavior = behavior\n  if (custom.length) dimensions.custom = custom\n  return { dimensions, unsupported }\n}\n\n/**\n * The rule the sweep PLANS with once a view is resolved: the rule itself\n * with the view's block beside its branches, so the planners that read\n * every block — does this need the contact facet, an engagement lookup, a\n * list membership — see the view's dimensions too. For planning only; the\n * matcher takes the view as its own option, because a branch is OR and a\n * view is AND.\n */\nexport function dynamicListPlanningRule(\n  rule: DynamicListRule,\n  view: DynamicListDimensions | null,\n): DynamicListRule {\n  if (!view || Object.keys(view).length === 0) return rule\n  return { ...rule, any: [...(rule.any ?? []), view] }\n}\n"],"names":["normalizeCampaignIds","CONTACT_SOURCE_LABELS","contactMatchesSegment","isContactLifecycleStage","normalizeContactFieldKey","CRM_CONTACT_VIEW_FIELDS","crmContactCustomKey","CAMPAIGN_MEMBER_SILOS","DYNAMIC_LIST_CUSTOM_OPS","VALUED_CUSTOM_OPS","Set","DYNAMIC_LIST_MAX_CUSTOM_CLAUSES","asStringArray","value","Array","isArray","map","entry","String","trim","filter","length","slice","asPositiveNumber","parsed","Number","isFinite","undefined","DYNAMIC_LIST_SOURCES","DYNAMIC_LIST_MAX_GROUPS","DYNAMIC_LIST_MAX_LIST_REFERENCES","normalizeCustomClause","raw","key","op","includes","operator","has","trimmed","normalizeDimensions","behavior","normalizedBehavior","ordersCountAtLeast","ltvCentsAtLeast","lastPurchaseWithinDays","noPurchaseForDays","engagement","normalizedEngagement","openedWithinDays","clickedWithinDays","notOpenedForDays","notClickedForDays","tags","captureSources","formNames","campaignIds","createdAfterMs","createdBeforeMs","inListIds","notInListIds","ownerUids","lifecycleStages","companyIds","custom","clause","engagedWithinDays","Object","keys","dimensionsAreEmpty","dimensions","normalizeDynamicListRule","stored","sources","source","segmentId","viewId","groups","negate","group","stripNegate","any","dynamicListRuleIsEmpty","rule","candidateMatchesDynamicListRule","candidate","options","silo","top","matchesDimensions","segment","nowMs","view","some","matched","day","createdAtMs","wanted","name","toLowerCase","formName","filed","campaignId","segmentFilters","ordersCount","ltvCents","last","lastPurchaseAtMs","ownerUid","lifecycleStage","companyId","customValueMatches","lastEmailEngagementAtMs","opened","lastOpenedAtMs","clicked","lastClickedAtMs","memberOf","listIds","every","listId","customValueIsSet","customValueText","present","left","right","numeric","a","b","allDimensions","dynamicListRuleNeedsContactFacet","dynamicListRuleNeedsEngagement","dynamicListRuleNeedsCampaigns","dynamicListRuleWithoutListReference","strip","id","next","stripped","dynamicListRuleListIds","ids","add","DAY_MS","viewClauseValues","split","Boolean","CUSTOM_VIEW_OPS","equals","is","doesNotEqual","contains","isNotEmpty","isEmpty","dynamicListDimensionsForCrmView","filters","fields","unsupported","extend","values","customKey","field","push","tag","owner","stage","company","createdAt","at","Date","parse","orders","ltv","amount","floor","dynamicListPlanningRule"],"mappings":"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"}

package/src/lib/app-utils/element-animation.d.ts

@@ -0,0 +1,200 @@
+/**
+ * @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.
+ */
+/**
+ * Element animation vocabulary (AGL-2486) — the names the renderer, the
+ * besigner attributes panel and the tenant's stylesheet all agree on.
+ *
+ * ## Why there is no animation runtime here
+ *
+ * Published pages ship no animation library, and that is the design, not a
+ * phase one. Motion's smallest useful React surface (`LazyMotion` +
+ * `domAnimation` + `m`) is ~17kB gzipped and the full `motion` import ~34kB —
+ * against the 87,646 B gzipped that came OFF the published page the same week
+ * this landed. What a site builder's authors actually reach for is entrance
+ * and hover emphasis: fade, slide, zoom, played on load, on scroll-in or on
+ * hover. Every one of those is `@keyframes` plus `transition`, which the
+ * compositor runs off the main thread — including during hydration, which is
+ * exactly when an entrance animation plays and exactly when a JS runtime is
+ * least able to keep up. Spring physics, FLIP/layout animation and
+ * gesture-driven interpolation are what a runtime would buy, and none of them
+ * are authorable from a preset dropdown by the audience this is for.
+ *
+ * The single exception is the scroll trigger, which needs an
+ * `IntersectionObserver`. That is ~700 bytes of inline script shipped in the
+ * SSR HTML by `apps/tenant`, only on pages that actually carry a
+ * scroll-triggered node — no module, no chunk, no extra request, and it
+ * gzips with the document. See `@aglyn/tenant-runtime`'s
+ * `element-animation-assets.ts` for the stylesheet and that script.
+ *
+ * This module is reachable from the client bundle (the renderer's `Leaf`
+ * imports it), so it holds constants and two small pure functions and
+ * nothing else. The stylesheet text deliberately lives in the server-only
+ * module so a page that animates nothing pays literally zero bytes for it.
+ */
+/** Preset id prop. Reserved node prop, stripped before the DOM spread. */
+export declare const NODE_ANIMATION_PROP = "aglynAnimation";
+/** Trigger prop: when the preset plays. */
+export declare const NODE_ANIMATION_TRIGGER_PROP = "aglynAnimationTrigger";
+/** Duration prop, in milliseconds. */
+export declare const NODE_ANIMATION_DURATION_PROP = "aglynAnimationDuration";
+/** Delay prop, in milliseconds. */
+export declare const NODE_ANIMATION_DELAY_PROP = "aglynAnimationDelay";
+/** Repeat prop: re-play every time the element scrolls back into view. */
+export declare const NODE_ANIMATION_REPEAT_PROP = "aglynAnimationRepeat";
+/** Easing prop: the shape of the motion curve. */
+export declare const NODE_ANIMATION_EASE_PROP = "aglynAnimationEase";
+/** Stagger prop: animate the children one after another, not the element. */
+export declare const NODE_ANIMATION_STAGGER_PROP = "aglynAnimationStagger";
+/** Stagger step prop: how much later each child starts, in milliseconds. */
+export declare const NODE_ANIMATION_STAGGER_STEP_PROP = "aglynAnimationStaggerStep";
+/** Every reserved animation prop, for the renderer's strip step. */
+export declare const NODE_ANIMATION_PROPS: readonly ["aglynAnimation", "aglynAnimationTrigger", "aglynAnimationDuration", "aglynAnimationDelay", "aglynAnimationRepeat", "aglynAnimationEase", "aglynAnimationStagger", "aglynAnimationStaggerStep"];
+/**
+ * The "no animation" value is a real string, never `''` (AGL-1451): an empty
+ * value cannot persist through the attributes form, so an author who picked a
+ * preset could never switch back off it.
+ */
+export declare const ANIMATION_NONE = "none";
+/** Preset ids. Persisted in screen documents — never rename one. */
+export declare const ANIMATION_PRESETS: readonly ["none", "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-in", "zoom-out"];
+export type AnimationPreset = (typeof ANIMATION_PRESETS)[number];
+/** Trigger ids. Persisted — never rename one. */
+export declare const ANIMATION_TRIGGERS: readonly ["load", "scroll", "hover"];
+export type AnimationTrigger = (typeof ANIMATION_TRIGGERS)[number];
+/**
+ * Easing ids — the SHAPE of the motion, the third dial beside duration and
+ * delay. Persisted; never rename one.
+ *
+ * Only the ids live here. The `cubic-bezier()` curves themselves are in the
+ * server-only stylesheet module, for the same reason the keyframes are: this
+ * file is reachable from the client bundle and six bezier literals is ~200
+ * bytes that every visitor to a still page would otherwise carry. The id
+ * becomes a class, the class sets a custom property, and the curve is read
+ * from the sheet that only an animating page ships.
+ */
+export declare const ANIMATION_EASINGS: readonly ["smooth", "steady", "gentle-start", "gentle-end", "gentle-both", "overshoot"];
+export type AnimationEase = (typeof ANIMATION_EASINGS)[number];
+/** Default when an author picks a preset but leaves the dials alone. */
+export declare const ANIMATION_DEFAULT_TRIGGER: AnimationTrigger;
+export declare const ANIMATION_DEFAULT_DURATION_MS = 600;
+export declare const ANIMATION_DEFAULT_DELAY_MS = 0;
+/**
+ * The curve every animation used before easing was authorable. Keeping it as
+ * the default means every screen authored before this shipped renders byte
+ * for byte the same.
+ */
+export declare const ANIMATION_DEFAULT_EASE: AnimationEase;
+/** Default gap between staggered children. */
+export declare const ANIMATION_DEFAULT_STAGGER_STEP_MS = 90;
+/** Upper bounds. A 30s entrance is an author mistake, not an intent. */
+export declare const ANIMATION_MAX_DURATION_MS = 3000;
+export declare const ANIMATION_MAX_DELAY_MS = 3000;
+/**
+ * A stagger step is capped far lower than a delay, because it MULTIPLIES:
+ * the last of twelve cards waits eleven steps. At the 500ms cap that is
+ * already 5.5s, which is why {@link ANIMATION_STAGGER_MAX_CHILDREN} stops the
+ * ladder climbing rather than letting a long list run off the end.
+ */
+export declare const ANIMATION_MAX_STAGGER_STEP_MS = 500;
+/**
+ * How many children get their own rung of the stagger ladder. Beyond this
+ * every remaining child shares the last rung, so a 200-row collection cannot
+ * leave its tail invisible for a minute — the tail arrives together, which is
+ * the least surprising failure and the one an author can actually see.
+ *
+ * Also the size of the generated rule block, which is why it is a number and
+ * not "all of them": each rung is one selector.
+ */
+export declare const ANIMATION_STAGGER_MAX_CHILDREN = 24;
+/** Base class every animated element carries. */
+export declare const ANIMATION_CLASS = "aglyn-anim";
+/**
+ * Base class of a STAGGER HOST — an element whose children animate one after
+ * another instead of the element itself animating.
+ *
+ * It is a different base class rather than a modifier on {@link
+ * ANIMATION_CLASS} because the two are mutually exclusive by construction: an
+ * element carrying both would play its own entrance AND run its children's,
+ * which is two overlapping fades on the same pixels. The preset and easing
+ * modifiers are shared, and reach the children through custom-property
+ * inheritance — the host sets `--aglyn-anim-name`, every child reads it, and
+ * the stylesheet needs no per-preset child rule.
+ */
+export declare const ANIMATION_GROUP_CLASS = "aglyn-anim-group";
+/** Per-preset modifier, e.g. `aglyn-anim--slide-up`. */
+export declare const ANIMATION_PRESET_CLASS_PREFIX = "aglyn-anim--";
+/** Per-easing modifier, e.g. `aglyn-anim-ease--overshoot`. */
+export declare const ANIMATION_EASE_CLASS_PREFIX = "aglyn-anim-ease--";
+/** Added by the scroll runtime once an element has entered the viewport. */
+export declare const ANIMATION_IN_CLASS = "aglyn-anim--in";
+/**
+ * Set on `<html>` by the inline runtime. Every rule that HIDES a
+ * scroll-triggered element before it plays is scoped under this class, so a
+ * visitor with no JS — and every crawler — sees the un-animated, VISIBLE
+ * state. Nothing is ever hidden by the server.
+ */
+export declare const ANIMATION_READY_CLASS = "aglyn-anim-js";
+/** Trigger attribute the stylesheet and the runtime both select on. */
+export declare const ANIMATION_TRIGGER_ATTR = "data-aglyn-anim-trigger";
+/** Repeat attribute the runtime reads; `'1'` means re-play. */
+export declare const ANIMATION_REPEAT_ATTR = "data-aglyn-anim-repeat";
+/** Custom properties carrying the author's dials. */
+export declare const ANIMATION_DURATION_VAR = "--aglyn-anim-duration";
+export declare const ANIMATION_DELAY_VAR = "--aglyn-anim-delay";
+/** Set on a stagger host; every child reads it through inheritance. */
+export declare const ANIMATION_STAGGER_STEP_VAR = "--aglyn-anim-step";
+/**
+ * Set on each child BY the stylesheet's nth-child ladder, not by the
+ * renderer — the renderer never sees a child's index, and asking it to would
+ * mean the host re-rendering whenever a sibling was inserted.
+ */
+export declare const ANIMATION_STAGGER_OFFSET_VAR = "--aglyn-anim-stagger";
+export interface ResolvedElementAnimation {
+    preset: AnimationPreset;
+    trigger: AnimationTrigger;
+    ease: AnimationEase;
+    durationMs: number;
+    delayMs: number;
+    repeat: boolean;
+    /** True when the CHILDREN animate in sequence rather than this element. */
+    stagger: boolean;
+    staggerStepMs: number;
+    /** Classes to append to the element. */
+    className: string;
+    /** DOM attributes the stylesheet and runtime select on. */
+    attributes: Record<string, string>;
+    /** Custom properties, merged into the element's inline style. */
+    style: Record<string, string>;
+}
+/**
+ * Reads the reserved animation props off a node's resolved props and returns
+ * the class/attribute/style triple the renderer applies — or `undefined` when
+ * the node does not animate, which is the overwhelmingly common case and
+ * costs one property read.
+ *
+ * Unknown preset and trigger values resolve to "no animation" rather than
+ * being passed through: these strings reach a `data-` attribute and a class
+ * name, and a screen document authored against a future preset must degrade
+ * to a static element, never to a broken selector.
+ */
+export declare function resolveElementAnimation(props: Record<string, any> | undefined): ResolvedElementAnimation | undefined;
+/**
+ * True when a node's props ask for a real animation. Cheap enough to run over
+ * every node in a screen's flat node map, which is how the tenant decides
+ * whether to ship the stylesheet at all.
+ */
+export declare function nodePropsAnimate(props: Record<string, any> | undefined): boolean;

package/src/lib/app-utils/element-animation.js

@@ -0,0 +1,233 @@
+/**
+ * @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.
+ */ /**
+ * Element animation vocabulary (AGL-2486) — the names the renderer, the
+ * besigner attributes panel and the tenant's stylesheet all agree on.
+ *
+ * ## Why there is no animation runtime here
+ *
+ * Published pages ship no animation library, and that is the design, not a
+ * phase one. Motion's smallest useful React surface (`LazyMotion` +
+ * `domAnimation` + `m`) is ~17kB gzipped and the full `motion` import ~34kB —
+ * against the 87,646 B gzipped that came OFF the published page the same week
+ * this landed. What a site builder's authors actually reach for is entrance
+ * and hover emphasis: fade, slide, zoom, played on load, on scroll-in or on
+ * hover. Every one of those is `@keyframes` plus `transition`, which the
+ * compositor runs off the main thread — including during hydration, which is
+ * exactly when an entrance animation plays and exactly when a JS runtime is
+ * least able to keep up. Spring physics, FLIP/layout animation and
+ * gesture-driven interpolation are what a runtime would buy, and none of them
+ * are authorable from a preset dropdown by the audience this is for.
+ *
+ * The single exception is the scroll trigger, which needs an
+ * `IntersectionObserver`. That is ~700 bytes of inline script shipped in the
+ * SSR HTML by `apps/tenant`, only on pages that actually carry a
+ * scroll-triggered node — no module, no chunk, no extra request, and it
+ * gzips with the document. See `@aglyn/tenant-runtime`'s
+ * `element-animation-assets.ts` for the stylesheet and that script.
+ *
+ * This module is reachable from the client bundle (the renderer's `Leaf`
+ * imports it), so it holds constants and two small pure functions and
+ * nothing else. The stylesheet text deliberately lives in the server-only
+ * module so a page that animates nothing pays literally zero bytes for it.
+ */ /** Preset id prop. Reserved node prop, stripped before the DOM spread. */ export const NODE_ANIMATION_PROP = 'aglynAnimation';
+/** Trigger prop: when the preset plays. */ export const NODE_ANIMATION_TRIGGER_PROP = 'aglynAnimationTrigger';
+/** Duration prop, in milliseconds. */ export const NODE_ANIMATION_DURATION_PROP = 'aglynAnimationDuration';
+/** Delay prop, in milliseconds. */ export const NODE_ANIMATION_DELAY_PROP = 'aglynAnimationDelay';
+/** Repeat prop: re-play every time the element scrolls back into view. */ export const NODE_ANIMATION_REPEAT_PROP = 'aglynAnimationRepeat';
+/** Easing prop: the shape of the motion curve. */ export const NODE_ANIMATION_EASE_PROP = 'aglynAnimationEase';
+/** Stagger prop: animate the children one after another, not the element. */ export const NODE_ANIMATION_STAGGER_PROP = 'aglynAnimationStagger';
+/** Stagger step prop: how much later each child starts, in milliseconds. */ export const NODE_ANIMATION_STAGGER_STEP_PROP = 'aglynAnimationStaggerStep';
+/** Every reserved animation prop, for the renderer's strip step. */ export const NODE_ANIMATION_PROPS = [
+    NODE_ANIMATION_PROP,
+    NODE_ANIMATION_TRIGGER_PROP,
+    NODE_ANIMATION_DURATION_PROP,
+    NODE_ANIMATION_DELAY_PROP,
+    NODE_ANIMATION_REPEAT_PROP,
+    NODE_ANIMATION_EASE_PROP,
+    NODE_ANIMATION_STAGGER_PROP,
+    NODE_ANIMATION_STAGGER_STEP_PROP
+];
+/**
+ * The "no animation" value is a real string, never `''` (AGL-1451): an empty
+ * value cannot persist through the attributes form, so an author who picked a
+ * preset could never switch back off it.
+ */ export const ANIMATION_NONE = 'none';
+/** Preset ids. Persisted in screen documents — never rename one. */ export const ANIMATION_PRESETS = [
+    ANIMATION_NONE,
+    'fade',
+    'slide-up',
+    'slide-down',
+    'slide-left',
+    'slide-right',
+    'zoom-in',
+    'zoom-out'
+];
+/** Trigger ids. Persisted — never rename one. */ export const ANIMATION_TRIGGERS = [
+    'load',
+    'scroll',
+    'hover'
+];
+/**
+ * Easing ids — the SHAPE of the motion, the third dial beside duration and
+ * delay. Persisted; never rename one.
+ *
+ * Only the ids live here. The `cubic-bezier()` curves themselves are in the
+ * server-only stylesheet module, for the same reason the keyframes are: this
+ * file is reachable from the client bundle and six bezier literals is ~200
+ * bytes that every visitor to a still page would otherwise carry. The id
+ * becomes a class, the class sets a custom property, and the curve is read
+ * from the sheet that only an animating page ships.
+ */ export const ANIMATION_EASINGS = [
+    'smooth',
+    'steady',
+    'gentle-start',
+    'gentle-end',
+    'gentle-both',
+    'overshoot'
+];
+/** Default when an author picks a preset but leaves the dials alone. */ export const ANIMATION_DEFAULT_TRIGGER = 'scroll';
+export const ANIMATION_DEFAULT_DURATION_MS = 600;
+export const ANIMATION_DEFAULT_DELAY_MS = 0;
+/**
+ * The curve every animation used before easing was authorable. Keeping it as
+ * the default means every screen authored before this shipped renders byte
+ * for byte the same.
+ */ export const ANIMATION_DEFAULT_EASE = 'smooth';
+/** Default gap between staggered children. */ export const ANIMATION_DEFAULT_STAGGER_STEP_MS = 90;
+/** Upper bounds. A 30s entrance is an author mistake, not an intent. */ export const ANIMATION_MAX_DURATION_MS = 3000;
+export const ANIMATION_MAX_DELAY_MS = 3000;
+/**
+ * A stagger step is capped far lower than a delay, because it MULTIPLIES:
+ * the last of twelve cards waits eleven steps. At the 500ms cap that is
+ * already 5.5s, which is why {@link ANIMATION_STAGGER_MAX_CHILDREN} stops the
+ * ladder climbing rather than letting a long list run off the end.
+ */ export const ANIMATION_MAX_STAGGER_STEP_MS = 500;
+/**
+ * How many children get their own rung of the stagger ladder. Beyond this
+ * every remaining child shares the last rung, so a 200-row collection cannot
+ * leave its tail invisible for a minute — the tail arrives together, which is
+ * the least surprising failure and the one an author can actually see.
+ *
+ * Also the size of the generated rule block, which is why it is a number and
+ * not "all of them": each rung is one selector.
+ */ export const ANIMATION_STAGGER_MAX_CHILDREN = 24;
+/** Base class every animated element carries. */ export const ANIMATION_CLASS = 'aglyn-anim';
+/**
+ * Base class of a STAGGER HOST — an element whose children animate one after
+ * another instead of the element itself animating.
+ *
+ * It is a different base class rather than a modifier on {@link
+ * ANIMATION_CLASS} because the two are mutually exclusive by construction: an
+ * element carrying both would play its own entrance AND run its children's,
+ * which is two overlapping fades on the same pixels. The preset and easing
+ * modifiers are shared, and reach the children through custom-property
+ * inheritance — the host sets `--aglyn-anim-name`, every child reads it, and
+ * the stylesheet needs no per-preset child rule.
+ */ export const ANIMATION_GROUP_CLASS = 'aglyn-anim-group';
+/** Per-preset modifier, e.g. `aglyn-anim--slide-up`. */ export const ANIMATION_PRESET_CLASS_PREFIX = 'aglyn-anim--';
+/** Per-easing modifier, e.g. `aglyn-anim-ease--overshoot`. */ export const ANIMATION_EASE_CLASS_PREFIX = 'aglyn-anim-ease--';
+/** Added by the scroll runtime once an element has entered the viewport. */ export const ANIMATION_IN_CLASS = 'aglyn-anim--in';
+/**
+ * Set on `<html>` by the inline runtime. Every rule that HIDES a
+ * scroll-triggered element before it plays is scoped under this class, so a
+ * visitor with no JS — and every crawler — sees the un-animated, VISIBLE
+ * state. Nothing is ever hidden by the server.
+ */ export const ANIMATION_READY_CLASS = 'aglyn-anim-js';
+/** Trigger attribute the stylesheet and the runtime both select on. */ export const ANIMATION_TRIGGER_ATTR = 'data-aglyn-anim-trigger';
+/** Repeat attribute the runtime reads; `'1'` means re-play. */ export const ANIMATION_REPEAT_ATTR = 'data-aglyn-anim-repeat';
+/** Custom properties carrying the author's dials. */ export const ANIMATION_DURATION_VAR = '--aglyn-anim-duration';
+export const ANIMATION_DELAY_VAR = '--aglyn-anim-delay';
+/** Set on a stagger host; every child reads it through inheritance. */ export const ANIMATION_STAGGER_STEP_VAR = '--aglyn-anim-step';
+/**
+ * Set on each child BY the stylesheet's nth-child ladder, not by the
+ * renderer — the renderer never sees a child's index, and asking it to would
+ * mean the host re-rendering whenever a sibling was inserted.
+ */ export const ANIMATION_STAGGER_OFFSET_VAR = '--aglyn-anim-stagger';
+/**
+ * Clamp a millisecond dial. `strictNullChecks` is OFF repo-wide and `0` is a
+ * legitimate delay, so this tests for a finite number rather than
+ * truthiness — `if (!delay)` would silently discard a deliberate `0` and,
+ * worse, treat it as "not set" and substitute the default.
+ */ function clampMs(value, fallback, max) {
+    const n = typeof value === 'string' ? Number(value) : value;
+    if (typeof n !== 'number' || !Number.isFinite(n)) return fallback;
+    return Math.min(Math.max(n, 0), max);
+}
+/**
+ * Reads the reserved animation props off a node's resolved props and returns
+ * the class/attribute/style triple the renderer applies — or `undefined` when
+ * the node does not animate, which is the overwhelmingly common case and
+ * costs one property read.
+ *
+ * Unknown preset and trigger values resolve to "no animation" rather than
+ * being passed through: these strings reach a `data-` attribute and a class
+ * name, and a screen document authored against a future preset must degrade
+ * to a static element, never to a broken selector.
+ */ export function resolveElementAnimation(props) {
+    const preset = props == null ? void 0 : props[NODE_ANIMATION_PROP];
+    if (typeof preset !== 'string' || preset === ANIMATION_NONE) return undefined;
+    if (!ANIMATION_PRESETS.includes(preset)) return undefined;
+    const rawTrigger = props == null ? void 0 : props[NODE_ANIMATION_TRIGGER_PROP];
+    const trigger = typeof rawTrigger === 'string' && ANIMATION_TRIGGERS.includes(rawTrigger) ? rawTrigger : ANIMATION_DEFAULT_TRIGGER;
+    const durationMs = clampMs(props == null ? void 0 : props[NODE_ANIMATION_DURATION_PROP], ANIMATION_DEFAULT_DURATION_MS, ANIMATION_MAX_DURATION_MS);
+    const delayMs = clampMs(props == null ? void 0 : props[NODE_ANIMATION_DELAY_PROP], ANIMATION_DEFAULT_DELAY_MS, ANIMATION_MAX_DELAY_MS);
+    const rawEase = props == null ? void 0 : props[NODE_ANIMATION_EASE_PROP];
+    const ease = typeof rawEase === 'string' && ANIMATION_EASINGS.includes(rawEase) ? rawEase : ANIMATION_DEFAULT_EASE;
+    // Repeat only means anything for the scroll trigger — `load` fires once by
+    // definition and `hover` is a transition, not a keyframe run.
+    const repeat = trigger === 'scroll' && Boolean(props == null ? void 0 : props[NODE_ANIMATION_REPEAT_PROP]);
+    // Stagger is refused for `hover` on purpose. A hover effect is a transition
+    // that must reverse the instant the pointer leaves; a staggered one would
+    // leave half a row mid-flight, and the ladder below only ever feeds
+    // `animation-delay`, which a transition does not read.
+    const stagger = trigger !== 'hover' && Boolean(props == null ? void 0 : props[NODE_ANIMATION_STAGGER_PROP]);
+    const staggerStepMs = stagger ? clampMs(props == null ? void 0 : props[NODE_ANIMATION_STAGGER_STEP_PROP], ANIMATION_DEFAULT_STAGGER_STEP_MS, ANIMATION_MAX_STAGGER_STEP_MS) : 0;
+    const attributes = {
+        [ANIMATION_TRIGGER_ATTR]: trigger
+    };
+    if (repeat) attributes[ANIMATION_REPEAT_ATTR] = '1';
+    const style = {
+        [ANIMATION_DURATION_VAR]: `${durationMs}ms`,
+        [ANIMATION_DELAY_VAR]: `${delayMs}ms`
+    };
+    // Written only for a stagger host, so a plain animated element's inline
+    // style is byte for byte what it was before this shipped.
+    if (stagger) style[ANIMATION_STAGGER_STEP_VAR] = `${staggerStepMs}ms`;
+    return {
+        preset: preset,
+        trigger,
+        ease,
+        durationMs,
+        delayMs,
+        repeat,
+        stagger,
+        staggerStepMs,
+        className: `${stagger ? ANIMATION_GROUP_CLASS : ANIMATION_CLASS} ${ANIMATION_PRESET_CLASS_PREFIX}${preset} ${ANIMATION_EASE_CLASS_PREFIX}${ease}`,
+        attributes,
+        style
+    };
+}
+/**
+ * True when a node's props ask for a real animation. Cheap enough to run over
+ * every node in a screen's flat node map, which is how the tenant decides
+ * whether to ship the stylesheet at all.
+ */ export function nodePropsAnimate(props) {
+    const preset = props == null ? void 0 : props[NODE_ANIMATION_PROP];
+    return typeof preset === 'string' && preset !== ANIMATION_NONE && ANIMATION_PRESETS.includes(preset);
+}
+
+//# sourceMappingURL=element-animation.js.map