@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/campaign-membership.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-membership.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 ELSE IS IN A CAMPAIGN: the edge between a campaign and the forms,\n * screens and people a push is coordinated across.\n *\n * ## The edge is a field on the RESOURCE, not a list on the campaign\n *\n * A campaign container lives at `hosts/{hostId}/emailCampaigns/{campaignId}`\n * and names nothing outside itself. A send joins one by carrying\n * `emailCampaignId`; every other member joins the same way, through\n * {@link CAMPAIGN_MEMBERSHIP_FIELD} on its own document.\n *\n * Three properties decide it, and all three point the same way:\n *\n *  - **Reading is free where it is asked.** A form's own page reads the form\n *    document to draw anything at all, so the campaign comes with it. A\n *    membership collection under the campaign would make \"which campaign is\n *    this in\" a query issued on mount by every resource page, for a fact one\n *    field already carries.\n *  - **The reduction is already gated this way.** `campaign-manage.ts` clears\n *    `emailCampaignId` from every send before it removes a container, so no\n *    send is left naming one that is gone. Extending that pass to the\n *    membership field is the SAME mechanism; a membership collection would be\n *    a second, different deletion story beside it.\n *  - **Deleting a MEMBER can leave nothing behind.** The campaign holds no\n *    list, so a deleted form takes its own edge with it. This matters most on\n *    a contact: an erasure removes the document, and a membership row stored\n *    anywhere else would survive it holding the id of a person who asked to\n *    be forgotten.\n *\n * ## Plural, because a landing page outlives one campaign\n *\n * The field is an ARRAY. A signup form built for the spring push is the same\n * form the summer push places, and a single-valued field would make the\n * second assignment silently erase the first — a campaign losing a member\n * with nothing on screen to say so. The automation step that has always\n * written this edge (`assignCampaign`) already used `arrayUnion`, so the\n * product has treated it as many-to-many from the start.\n *\n * ## Ids, never names\n *\n * A campaign's name is editable, and every reader here resolves the name from\n * the campaign document at read time. Renaming a campaign therefore moves no\n * membership: the stored value is the container's document id, which nothing\n * rewrites.\n */\n\nimport { contactFacetPath, readContactFacet } from './contacts'\n\n/**\n * The field naming the campaigns a resource belongs to.\n *\n * Not `emailCampaignId`, which is the SEND's field: on a send document the\n * word `campaignId` already means the send's own id — it is what `cid`\n * carries into every unsubscribe footer — so that collection needed a\n * different word. A form, a screen and a contact have no second meaning for\n * it, and the plural says the resource may be in more than one.\n */\nexport const CAMPAIGN_MEMBERSHIP_FIELD = 'campaignIds'\n\n/**\n * How many campaigns one resource may name.\n *\n * A ceiling on the FIELD, not on the product: an array Firestore has to index\n * on every write is not the place to discover that a script has been adding\n * an id a day for a year. Twenty is far past what a person assigns by hand\n * and far short of anything that costs a write.\n */\nexport const CAMPAIGN_MEMBERSHIP_CAP = 20\n\n/**\n * A stored membership array as a clean list of ids.\n *\n * Deduped, trimmed, non-strings dropped, capped. Every reader goes through\n * this because the field is written by three consoles and one automation\n * step, and a surface that trusted the raw value would render `undefined` as\n * a chip the first time one of them wrote a blank.\n */\nexport function normalizeCampaignIds(raw: unknown): string[] {\n  if (!Array.isArray(raw)) return []\n  const seen: string[] = []\n  for (const entry of raw) {\n    if (typeof entry !== 'string') continue\n    const id = entry.trim()\n    if (!id || seen.includes(id)) continue\n    seen.push(id)\n    if (seen.length >= CAMPAIGN_MEMBERSHIP_CAP) break\n  }\n  return seen\n}\n\n/**\n * The campaigns a HOST resource — a form, a screen — belongs to.\n *\n * Host resources carry the field at the top of the document: they belong to\n * one site, which is the same site the campaign belongs to, so there is no\n * second holder to keep the edge away from.\n */\nexport function readCampaignIds(\n  resource: Record<string, unknown> | null | undefined,\n): string[] {\n  return normalizeCampaignIds((resource ?? {})[CAMPAIGN_MEMBERSHIP_FIELD])\n}\n\n/**\n * The dotted path to a contact's membership, inside ONE holder's facet.\n *\n * A contact document is shared by every site in the org — one human who\n * touched two sites is one row — and almost nothing on it is legitimately\n * shared. Which campaigns a merchant has filed a person under is that\n * merchant's business record on exactly the footing their notes and tags are,\n * so it lives at `facets.{groupId}.campaignIds` and not at the top of the\n * document, where every other site in an agency's account could read it.\n */\nexport function contactCampaignFieldPath(groupId: string): string {\n  return contactFacetPath(groupId, CAMPAIGN_MEMBERSHIP_FIELD)\n}\n\n/** The campaigns ONE holder has filed this contact under. */\nexport function readContactCampaignIds(\n  contact: Record<string, unknown> | null | undefined,\n  groupId: string,\n): string[] {\n  return normalizeCampaignIds(readContactFacet(contact, groupId).campaignIds)\n}\n\n/**\n * The membership a save should write, given what is on screen.\n *\n * Pure, and shared by the three consoles that offer the picker, because the\n * decision each of them makes is identical and is not obvious: an EMPTY\n * selection has to be stored as an empty array rather than as a removed\n * field.\n *\n * Removing the field would read the same to every surface here — the readers\n * above answer `[]` either way — and would be wrong for the one reader that\n * is not a surface. `campaign-manage.ts` finds a campaign's members with\n * `array-contains`, which matches on the automatic single-field index; that\n * index has an entry only while the array does, so the two shapes are the\n * same to a reader and different to a writer only in cost. Storing `[]` keeps\n * one shape for \"belongs to no campaign\" across every writer, which is the\n * property the send collection's own detach comment argues for one field\n * over.\n *\n * @returns the value to store under {@link CAMPAIGN_MEMBERSHIP_FIELD}.\n */\nexport function campaignMembershipValue(selected: readonly string[]): string[] {\n  return normalizeCampaignIds(selected)\n}\n\n/**\n * Whether a document's stored membership already says what a save would.\n *\n * Order-insensitive: a picker hands back its options' order and the stored\n * array is in the order it was written, so comparing them literally would\n * report a change on every open and leave Save permanently enabled.\n */\nexport function campaignMembershipUnchanged(\n  stored: readonly string[],\n  selected: readonly string[],\n): boolean {\n  if (stored.length !== selected.length) return false\n  const sortedStored = [...stored].sort()\n  const sortedSelected = [...selected].sort()\n  return sortedStored.every((id, index) => id === sortedSelected[index])\n}\n\n/**\n * The host subcollections whose documents may name a campaign.\n *\n * The list a campaign's deletion walks, and the list this feature's coverage\n * spec reads — so a collection that grows the picker without growing the\n * detach fails the build rather than shipping a campaign whose removal leaves\n * that collection pointing at nothing.\n *\n * Contacts are deliberately NOT here. They live on the org\n * (`orgs/{orgId}/contacts`), not the host, and carry the field inside a\n * per-holder facet — so they are detached by their own pass, against a field\n * path that names the group.\n */\nexport const CAMPAIGN_MEMBER_HOST_COLLECTIONS = ['forms', 'screens'] as const\n\nexport type CampaignMemberHostCollection =\n  (typeof CAMPAIGN_MEMBER_HOST_COLLECTIONS)[number]\n"],"names":["contactFacetPath","readContactFacet","CAMPAIGN_MEMBERSHIP_FIELD","CAMPAIGN_MEMBERSHIP_CAP","normalizeCampaignIds","raw","Array","isArray","seen","entry","id","trim","includes","push","length","readCampaignIds","resource","contactCampaignFieldPath","groupId","readContactCampaignIds","contact","campaignIds","campaignMembershipValue","selected","campaignMembershipUnchanged","stored","sortedStored","sort","sortedSelected","every","index","CAMPAIGN_MEMBER_HOST_COLLECTIONS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CC,GAED,SAASA,gBAAgB,EAAEC,gBAAgB,QAAQ,gBAAY;AAE/D;;;;;;;;CAQC,GACD,OAAO,MAAMC,4BAA4B,cAAa;AAEtD;;;;;;;CAOC,GACD,OAAO,MAAMC,0BAA0B,GAAE;AAEzC;;;;;;;CAOC,GACD,OAAO,SAASC,qBAAqBC,GAAY;IAC/C,IAAI,CAACC,MAAMC,OAAO,CAACF,MAAM,OAAO,EAAE;IAClC,MAAMG,OAAiB,EAAE;IACzB,KAAK,MAAMC,SAASJ,IAAK;QACvB,IAAI,OAAOI,UAAU,UAAU;QAC/B,MAAMC,KAAKD,MAAME,IAAI;QACrB,IAAI,CAACD,MAAMF,KAAKI,QAAQ,CAACF,KAAK;QAC9BF,KAAKK,IAAI,CAACH;QACV,IAAIF,KAAKM,MAAM,IAAIX,yBAAyB;IAC9C;IACA,OAAOK;AACT;AAEA;;;;;;CAMC,GACD,OAAO,SAASO,gBACdC,QAAoD;IAEpD,OAAOZ,qBAAqB,CAACY,mBAAAA,WAAY,CAAC,EAAE,CAACd,0BAA0B;AACzE;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASe,yBAAyBC,OAAe;IACtD,OAAOlB,iBAAiBkB,SAAShB;AACnC;AAEA,2DAA2D,GAC3D,OAAO,SAASiB,uBACdC,OAAmD,EACnDF,OAAe;IAEf,OAAOd,qBAAqBH,iBAAiBmB,SAASF,SAASG,WAAW;AAC5E;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,wBAAwBC,QAA2B;IACjE,OAAOnB,qBAAqBmB;AAC9B;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,4BACdC,MAAyB,EACzBF,QAA2B;IAE3B,IAAIE,OAAOX,MAAM,KAAKS,SAAST,MAAM,EAAE,OAAO;IAC9C,MAAMY,eAAe;WAAID;KAAO,CAACE,IAAI;IACrC,MAAMC,iBAAiB;WAAIL;KAAS,CAACI,IAAI;IACzC,OAAOD,aAAaG,KAAK,CAAC,CAACnB,IAAIoB,QAAUpB,OAAOkB,cAAc,CAACE,MAAM;AACvE;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,MAAMC,mCAAmC;IAAC;IAAS;CAAU,CAAS"}

package/src/lib/app-utils/campaign-touch.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @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.
+ */
+/**
+ * THE VISITOR'S HALF OF CAMPAIGN ATTRIBUTION — the touch that has to survive
+ * the gap between arriving from a campaign and becoming somebody.
+ *
+ * ## The gap this exists to cross
+ *
+ * A known recipient can be joined on their address: they clicked a campaign's
+ * mail, the delivery webhook stamped the click on their person document, and
+ * `email-revenue-attribution.ts` reads it back when their order settles. An
+ * ANONYMOUS visitor has no such handle. They arrive from an ad, a partner
+ * link or a social post, browse for a while, and only become identifiable at
+ * the moment they submit a form, sign up, book or check out. Between the
+ * arrival and that moment there is nothing on the server that connects them.
+ *
+ * The site's own collector already reads `utm_source`/`utm_medium`/
+ * `utm_campaign` off the landing URL and increments a per-day label counter
+ * with them. That answers "how many views did this campaign send us" and
+ * stops there — the labels are never carried to the moment the visitor says
+ * who they are, so every form, lead, contact and booking a campaign caused is
+ * recorded as though nobody caused it.
+ *
+ * This carries them. The touch is held on the VISITOR, and every identify
+ * moment attaches it.
+ *
+ * ## What holds it, and why it outlives the tab
+ *
+ * `localStorage`, expiring at {@link ATTRIBUTION_WINDOW_DAYS}.
+ *
+ * `campaign-forwarding.ts` holds its own campaign in `sessionStorage` and
+ * argues for it: a first touch that outlived the visit would start
+ * attributing next week's organic return to this week's ad. That argument is
+ * correct for the question it answers — which campaign produced THIS SIGNUP,
+ * asked of one uninterrupted visit to the marketing site — and it is the
+ * wrong shape here, because this question already has a stated answer to
+ * "how long may a touch be credited": the attribution window, seven days,
+ * stamped onto every record so the rule is readable off the data.
+ *
+ * A store that dies with the tab cannot express a seven-day window. It would
+ * credit only the visitors who convert without ever closing the tab and
+ * silently record every other conversion as organic — a measured zero, which
+ * is the failure mode this whole area exists to end. So the touch lives as
+ * long as the window says it may and not one millisecond longer: an expired
+ * entry is DELETED on the read that finds it, rather than ignored, so a
+ * device never holds a campaign it can no longer be credited with.
+ *
+ * ## Last touch, not first
+ *
+ * The revenue join credits the LAST click, and a product where a lead and an
+ * order attribute by different rules is worse than one that is uniformly
+ * approximate. So a new campaign arrival OVERWRITES the stored one. This is
+ * the deliberate opposite of {@link rememberVisitCampaign}, which keeps the
+ * first — that one describes a single visit's origin and this one describes
+ * which campaign most recently brought a person back.
+ *
+ * ## Consent
+ *
+ * Two tiers, exactly as the console hop splits them, and the split is the
+ * same because the acts are the same:
+ *
+ *  - **The live URL at the moment of conversion** touches no storage. The
+ *    parameters are already in the page the visitor asked for, nothing is
+ *    written to their device, and there is accordingly nothing to consent to.
+ *    A visitor who converts on the page the ad landed them on is attributed
+ *    with no grant of any kind.
+ *  - **The remembered touch** is written to the visitor's device for an
+ *    analytics purpose, which is `analytics_storage`, and it waits for the
+ *    same grant the analytics tag waits for. The gate is not re-derived here:
+ *    the caller already computed it for the tag and hands the same boolean
+ *    down, so there is one gate and it cannot drift from itself.
+ *
+ * `null` is UNRESOLVED and is not `false`. With `strictNullChecks` off
+ * repo-wide that distinction evaporates unless it is carried explicitly, so
+ * it is: until the visitor's state is actually settled, nothing is read and
+ * nothing is written. Failing closed costs an attribution; failing open
+ * writes to a device before the visitor answered.
+ *
+ * On a WITHDRAWAL the stored touch is removed rather than merely ignored.
+ * Somebody who changes their mind should not leave the thing they withdrew
+ * consent for sitting on their device.
+ *
+ * ⛔ **A host whose posture requires prior consent and whose visitor has not
+ * given it produces no remembered touch at all.** Their conversion attributes
+ * to nothing, exactly as direct traffic does. That is the degradation, stated
+ * rather than worked around: there is no fallback identifier, no fingerprint
+ * and no server-side cookie, because every one of those is the durable
+ * identifier the analytics posture on this runtime deliberately does not set.
+ *
+ * ## What is never carried
+ *
+ * Only the three allowlisted `utm_` labels, scrubbed by
+ * {@link parseCampaignAttribution} — which refuses an email-shaped value
+ * outright. No address, no person's identifier, no click id, nothing that
+ * names the visitor. A campaign link is exactly where putting a recipient in
+ * a query string would be tempting, and the parser is what makes it
+ * impossible rather than merely discouraged: the stored string is re-parsed
+ * through the same allowlist that wrote it, so a hand-edited `localStorage`
+ * entry can claim no more than a hand-edited URL could.
+ *
+ * ⛔ **Nothing here depends on a parameter surviving the mail provider's
+ * click wrapper.** A campaign link is rewritten by the provider and redirects
+ * to the authored URL, so whatever the marketer put on it arrives — but the
+ * email channel does not rely on that, because an email click is already
+ * recorded server-side against the recipient's address hash. The labels below
+ * are the WEB channel's touch, and a campaign that carries none is joined by
+ * address instead.
+ */
+import { type CampaignAttribution } from './campaign-attribution';
+/** Days between a campaign touch and a conversion it may be credited with. */
+export declare const ATTRIBUTION_WINDOW_DAYS = 7;
+/** The same window in milliseconds. */
+export declare const ATTRIBUTION_WINDOW_MS: number;
+/** Where the touch is held. Namespaced like every other key this app sets. */
+export declare const CAMPAIGN_TOUCH_STORAGE_KEY = "aglyn:campaign-touch";
+/**
+ * The parameter the touch's instant rides under inside the wire form.
+ *
+ * Deliberately not a `utm_` name: the wire form is parsed by the same
+ * allowlist that reads a URL, and a fourth `utm_` key would either be dropped
+ * by it or have to widen it. `t` is outside the allowlist and read
+ * separately.
+ */
+export declare const CAMPAIGN_TOUCH_TIME_KEY = "t";
+/** A campaign the visitor arrived from, and when they arrived from it. */
+export interface CampaignTouch extends CampaignAttribution {
+    /** When the visitor followed the campaign link, epoch ms. */
+    atMs: number;
+}
+/**
+ * The canonical stored form of a touch — the ONLY place it is written, so it
+ * cannot drift from what {@link parseCampaignTouch} reads back.
+ */
+export declare function campaignTouchWire(touch: CampaignTouch | null | undefined): string;
+/**
+ * Read a stored or transmitted touch back, or `null`.
+ *
+ * The window is enforced HERE rather than at the call sites, so every reader
+ * — the browser deciding what to send, the server deciding what to credit —
+ * agrees about what an expired touch is: nothing at all. A touch dated in the
+ * future is refused for the reason the revenue join refuses one: a click
+ * after the conversion is the receipt, not the cause.
+ */
+export declare function parseCampaignTouch(wire: unknown, nowMs?: number): CampaignTouch | null;
+/**
+ * Tell this module what the visitor's analytics consent state is.
+ *
+ * Called by whoever already computed it for the tag, on every render, so a
+ * grant remembers the arrival the moment it is given and a withdrawal drops
+ * the stored touch immediately.
+ */
+export declare function setCampaignTouchConsent(allowed: boolean | null): void;
+/**
+ * Remember the campaign on the current URL as this visitor's latest touch.
+ *
+ * Overwrites, because the model is last touch. A URL naming no campaign
+ * writes NOTHING and clears nothing: a visitor who arrives from an ad and
+ * then browses ten organic pages has one touch, not one touch erased by the
+ * second pageview.
+ *
+ * @returns what is now remembered, or `null`.
+ */
+export declare function rememberCampaignTouch(search?: string, nowMs?: number): CampaignTouch | null;
+/**
+ * The touch to credit a conversion happening right now, or `null`.
+ *
+ * ## The order is the model
+ *
+ * The live URL is consulted FIRST and wins whenever it names a campaign,
+ * because a campaign on the address bar at the moment of conversion is by
+ * definition the most recent touch there is. Only when the current page names
+ * none does this fall back to what was remembered.
+ *
+ * ## An expired entry is deleted, not skipped
+ *
+ * A touch past the window can never be credited again, so leaving it on the
+ * device would be keeping a record of where somebody came from for no purpose
+ * anything reads. The read that finds it removes it.
+ */
+export declare function readCampaignTouch(nowMs?: number): CampaignTouch | null;
+/**
+ * The fragment a conversion request spreads into its body, or `{}`.
+ *
+ * One helper rather than four hand-written spreads: a door that forgets it
+ * reports its conversions as organic, which looks exactly like a campaign
+ * that produced none. Empty when there is no touch — never a placeholder,
+ * never `campaignTouch: undefined`, so that "arrived from nowhere" and "this
+ * door does not report" stay distinguishable on the wire.
+ */
+export declare function campaignTouchField(nowMs?: number): {
+    campaignTouch?: string;
+};

package/src/lib/app-utils/campaign-touch.js

@@ -0,0 +1,326 @@
+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.
+ */ /**
+ * THE VISITOR'S HALF OF CAMPAIGN ATTRIBUTION — the touch that has to survive
+ * the gap between arriving from a campaign and becoming somebody.
+ *
+ * ## The gap this exists to cross
+ *
+ * A known recipient can be joined on their address: they clicked a campaign's
+ * mail, the delivery webhook stamped the click on their person document, and
+ * `email-revenue-attribution.ts` reads it back when their order settles. An
+ * ANONYMOUS visitor has no such handle. They arrive from an ad, a partner
+ * link or a social post, browse for a while, and only become identifiable at
+ * the moment they submit a form, sign up, book or check out. Between the
+ * arrival and that moment there is nothing on the server that connects them.
+ *
+ * The site's own collector already reads `utm_source`/`utm_medium`/
+ * `utm_campaign` off the landing URL and increments a per-day label counter
+ * with them. That answers "how many views did this campaign send us" and
+ * stops there — the labels are never carried to the moment the visitor says
+ * who they are, so every form, lead, contact and booking a campaign caused is
+ * recorded as though nobody caused it.
+ *
+ * This carries them. The touch is held on the VISITOR, and every identify
+ * moment attaches it.
+ *
+ * ## What holds it, and why it outlives the tab
+ *
+ * `localStorage`, expiring at {@link ATTRIBUTION_WINDOW_DAYS}.
+ *
+ * `campaign-forwarding.ts` holds its own campaign in `sessionStorage` and
+ * argues for it: a first touch that outlived the visit would start
+ * attributing next week's organic return to this week's ad. That argument is
+ * correct for the question it answers — which campaign produced THIS SIGNUP,
+ * asked of one uninterrupted visit to the marketing site — and it is the
+ * wrong shape here, because this question already has a stated answer to
+ * "how long may a touch be credited": the attribution window, seven days,
+ * stamped onto every record so the rule is readable off the data.
+ *
+ * A store that dies with the tab cannot express a seven-day window. It would
+ * credit only the visitors who convert without ever closing the tab and
+ * silently record every other conversion as organic — a measured zero, which
+ * is the failure mode this whole area exists to end. So the touch lives as
+ * long as the window says it may and not one millisecond longer: an expired
+ * entry is DELETED on the read that finds it, rather than ignored, so a
+ * device never holds a campaign it can no longer be credited with.
+ *
+ * ## Last touch, not first
+ *
+ * The revenue join credits the LAST click, and a product where a lead and an
+ * order attribute by different rules is worse than one that is uniformly
+ * approximate. So a new campaign arrival OVERWRITES the stored one. This is
+ * the deliberate opposite of {@link rememberVisitCampaign}, which keeps the
+ * first — that one describes a single visit's origin and this one describes
+ * which campaign most recently brought a person back.
+ *
+ * ## Consent
+ *
+ * Two tiers, exactly as the console hop splits them, and the split is the
+ * same because the acts are the same:
+ *
+ *  - **The live URL at the moment of conversion** touches no storage. The
+ *    parameters are already in the page the visitor asked for, nothing is
+ *    written to their device, and there is accordingly nothing to consent to.
+ *    A visitor who converts on the page the ad landed them on is attributed
+ *    with no grant of any kind.
+ *  - **The remembered touch** is written to the visitor's device for an
+ *    analytics purpose, which is `analytics_storage`, and it waits for the
+ *    same grant the analytics tag waits for. The gate is not re-derived here:
+ *    the caller already computed it for the tag and hands the same boolean
+ *    down, so there is one gate and it cannot drift from itself.
+ *
+ * `null` is UNRESOLVED and is not `false`. With `strictNullChecks` off
+ * repo-wide that distinction evaporates unless it is carried explicitly, so
+ * it is: until the visitor's state is actually settled, nothing is read and
+ * nothing is written. Failing closed costs an attribution; failing open
+ * writes to a device before the visitor answered.
+ *
+ * On a WITHDRAWAL the stored touch is removed rather than merely ignored.
+ * Somebody who changes their mind should not leave the thing they withdrew
+ * consent for sitting on their device.
+ *
+ * ⛔ **A host whose posture requires prior consent and whose visitor has not
+ * given it produces no remembered touch at all.** Their conversion attributes
+ * to nothing, exactly as direct traffic does. That is the degradation, stated
+ * rather than worked around: there is no fallback identifier, no fingerprint
+ * and no server-side cookie, because every one of those is the durable
+ * identifier the analytics posture on this runtime deliberately does not set.
+ *
+ * ## What is never carried
+ *
+ * Only the three allowlisted `utm_` labels, scrubbed by
+ * {@link parseCampaignAttribution} — which refuses an email-shaped value
+ * outright. No address, no person's identifier, no click id, nothing that
+ * names the visitor. A campaign link is exactly where putting a recipient in
+ * a query string would be tempting, and the parser is what makes it
+ * impossible rather than merely discouraged: the stored string is re-parsed
+ * through the same allowlist that wrote it, so a hand-edited `localStorage`
+ * entry can claim no more than a hand-edited URL could.
+ *
+ * ⛔ **Nothing here depends on a parameter surviving the mail provider's
+ * click wrapper.** A campaign link is rewritten by the provider and redirects
+ * to the authored URL, so whatever the marketer put on it arrives — but the
+ * email channel does not rely on that, because an email click is already
+ * recorded server-side against the recipient's address hash. The labels below
+ * are the WEB channel's touch, and a campaign that carries none is joined by
+ * address instead.
+ */ import { campaignAttributionQuery, parseCampaignAttribution } from "./campaign-attribution.js";
+/*==========================================
+ * THE WINDOW, AND WHY THIS IS THE SECOND COPY OF A NUMBER.
+ *
+ * `email-revenue-window.ts` in `shared-util-email` declares the same seven
+ * days, and its docblock is right that a window defined twice is a window
+ * that drifts. Importing it here is not available: `shared-util-email` is
+ * tagged `scope:shared` and reaches back into `@aglyn/aglyn`, so an edge in
+ * this direction closes a project cycle and the module-boundary rule refuses
+ * it. That is the same wall `email-media-src.ts` hit, and the answer is the
+ * same one it took — a deliberate copy, pinned by a drift guard in an app
+ * spec that can import both sides (`attribution-window-drift.spec.ts`).
+ *
+ * The copy is the WINDOW only. The model name is stamped onto records, which
+ * happens server-side, so it stays in one place and never comes near this
+ * file.
+ *=========================================*/ /** Days between a campaign touch and a conversion it may be credited with. */ export const ATTRIBUTION_WINDOW_DAYS = 7;
+/** The same window in milliseconds. */ export const ATTRIBUTION_WINDOW_MS = ATTRIBUTION_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+/**
+ * Whether a touch may be credited with a conversion at `convertedAtMs`.
+ *
+ * Both bounds matter and they fail differently, exactly as the revenue join
+ * describes them: a touch AFTER the conversion is the receipt rather than the
+ * cause, and a touch older than the window is one nobody can argue caused
+ * anything. Inclusive at both ends.
+ */ function touchIsInWindow(touchedAtMs, convertedAtMs) {
+    if (!Number.isFinite(touchedAtMs) || !Number.isFinite(convertedAtMs)) {
+        return false;
+    }
+    if (touchedAtMs <= 0 || convertedAtMs <= 0) return false;
+    const age = convertedAtMs - touchedAtMs;
+    return age >= 0 && age <= ATTRIBUTION_WINDOW_MS;
+}
+/** Where the touch is held. Namespaced like every other key this app sets. */ export const CAMPAIGN_TOUCH_STORAGE_KEY = 'aglyn:campaign-touch';
+/**
+ * The parameter the touch's instant rides under inside the wire form.
+ *
+ * Deliberately not a `utm_` name: the wire form is parsed by the same
+ * allowlist that reads a URL, and a fourth `utm_` key would either be dropped
+ * by it or have to widen it. `t` is outside the allowlist and read
+ * separately.
+ */ export const CAMPAIGN_TOUCH_TIME_KEY = 't';
+/**
+ * Whether the visitor has granted analytics storage.
+ *
+ * `null` means NOT YET RESOLVED and is not the same as `false` — see the
+ * consent section above.
+ */ let storageConsent = null;
+function localStore() {
+    if (typeof window === 'undefined') return null;
+    // Touching the property itself throws in some privacy modes, not just its
+    // methods.
+    try {
+        var _window_localStorage;
+        return (_window_localStorage = window.localStorage) != null ? _window_localStorage : null;
+    } catch (unused) {
+        return null;
+    }
+}
+/**
+ * The canonical stored form of a touch — the ONLY place it is written, so it
+ * cannot drift from what {@link parseCampaignTouch} reads back.
+ */ export function campaignTouchWire(touch) {
+    if (!touch) return '';
+    const labels = campaignAttributionQuery(touch);
+    if (!labels) return '';
+    const atMs = Math.round(Number(touch.atMs));
+    if (!Number.isFinite(atMs) || atMs <= 0) return '';
+    return `${labels}&${CAMPAIGN_TOUCH_TIME_KEY}=${atMs}`;
+}
+/**
+ * Read a stored or transmitted touch back, or `null`.
+ *
+ * The window is enforced HERE rather than at the call sites, so every reader
+ * — the browser deciding what to send, the server deciding what to credit —
+ * agrees about what an expired touch is: nothing at all. A touch dated in the
+ * future is refused for the reason the revenue join refuses one: a click
+ * after the conversion is the receipt, not the cause.
+ */ export function parseCampaignTouch(wire, nowMs = Date.now()) {
+    if (typeof wire !== 'string' || !wire) return null;
+    let params;
+    try {
+        params = new URLSearchParams(wire);
+    } catch (unused) {
+        return null;
+    }
+    const campaign = parseCampaignAttribution(params);
+    if (!campaign) return null;
+    const atMs = Number(params.get(CAMPAIGN_TOUCH_TIME_KEY));
+    if (!touchIsInWindow(atMs, nowMs)) return null;
+    return _extends({}, campaign, {
+        atMs
+    });
+}
+/**
+ * Tell this module what the visitor's analytics consent state is.
+ *
+ * Called by whoever already computed it for the tag, on every render, so a
+ * grant remembers the arrival the moment it is given and a withdrawal drops
+ * the stored touch immediately.
+ */ export function setCampaignTouchConsent(allowed) {
+    storageConsent = allowed === true ? true : allowed === false ? false : null;
+    if (storageConsent === true) {
+        rememberCampaignTouch();
+        return;
+    }
+    if (storageConsent === false) {
+        const store = localStore();
+        if (!store) return;
+        try {
+            store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY);
+        } catch (unused) {
+        // Nothing else to try, and a failed cleanup must not break the page.
+        }
+    }
+}
+/**
+ * Remember the campaign on the current URL as this visitor's latest touch.
+ *
+ * Overwrites, because the model is last touch. A URL naming no campaign
+ * writes NOTHING and clears nothing: a visitor who arrives from an ad and
+ * then browses ten organic pages has one touch, not one touch erased by the
+ * second pageview.
+ *
+ * @returns what is now remembered, or `null`.
+ */ export function rememberCampaignTouch(search, nowMs = Date.now()) {
+    if (storageConsent !== true) return null;
+    const store = localStore();
+    if (!store) return null;
+    const source = typeof search === 'string' ? search : typeof window === 'undefined' ? '' : window.location.search;
+    const campaign = parseCampaignAttribution(new URLSearchParams(source));
+    if (!campaign) return null;
+    const touch = _extends({}, campaign, {
+        atMs: nowMs
+    });
+    const wire = campaignTouchWire(touch);
+    if (!wire) return null;
+    try {
+        store.setItem(CAMPAIGN_TOUCH_STORAGE_KEY, wire);
+    } catch (unused) {
+        // A store that refuses the write costs the walk from the landing page to
+        // the conversion, never a conversion on the landing page itself — the
+        // live URL below still carries that visitor.
+        return null;
+    }
+    return touch;
+}
+/**
+ * The touch to credit a conversion happening right now, or `null`.
+ *
+ * ## The order is the model
+ *
+ * The live URL is consulted FIRST and wins whenever it names a campaign,
+ * because a campaign on the address bar at the moment of conversion is by
+ * definition the most recent touch there is. Only when the current page names
+ * none does this fall back to what was remembered.
+ *
+ * ## An expired entry is deleted, not skipped
+ *
+ * A touch past the window can never be credited again, so leaving it on the
+ * device would be keeping a record of where somebody came from for no purpose
+ * anything reads. The read that finds it removes it.
+ */ export function readCampaignTouch(nowMs = Date.now()) {
+    const live = typeof window === 'undefined' ? null : parseCampaignAttribution(new URLSearchParams(window.location.search));
+    if (live) return _extends({}, live, {
+        atMs: nowMs
+    });
+    if (storageConsent !== true) return null;
+    const store = localStore();
+    if (!store) return null;
+    let raw;
+    try {
+        raw = store.getItem(CAMPAIGN_TOUCH_STORAGE_KEY);
+    } catch (unused) {
+        return null;
+    }
+    if (!raw) return null;
+    const touch = parseCampaignTouch(raw, nowMs);
+    if (!touch) {
+        try {
+            store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY);
+        } catch (unused) {
+        // The entry stays until the next read finds it again; it is already
+        // uncreditable, so nothing downstream is affected.
+        }
+        return null;
+    }
+    return touch;
+}
+/**
+ * The fragment a conversion request spreads into its body, or `{}`.
+ *
+ * One helper rather than four hand-written spreads: a door that forgets it
+ * reports its conversions as organic, which looks exactly like a campaign
+ * that produced none. Empty when there is no touch — never a placeholder,
+ * never `campaignTouch: undefined`, so that "arrived from nowhere" and "this
+ * door does not report" stay distinguishable on the wire.
+ */ export function campaignTouchField(nowMs = Date.now()) {
+    const wire = campaignTouchWire(readCampaignTouch(nowMs));
+    return wire ? {
+        campaignTouch: wire
+    } : {};
+}
+
+//# sourceMappingURL=campaign-touch.js.map

package/src/lib/app-utils/campaign-touch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-touch.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 VISITOR'S HALF OF CAMPAIGN ATTRIBUTION — the touch that has to survive\n * the gap between arriving from a campaign and becoming somebody.\n *\n * ## The gap this exists to cross\n *\n * A known recipient can be joined on their address: they clicked a campaign's\n * mail, the delivery webhook stamped the click on their person document, and\n * `email-revenue-attribution.ts` reads it back when their order settles. An\n * ANONYMOUS visitor has no such handle. They arrive from an ad, a partner\n * link or a social post, browse for a while, and only become identifiable at\n * the moment they submit a form, sign up, book or check out. Between the\n * arrival and that moment there is nothing on the server that connects them.\n *\n * The site's own collector already reads `utm_source`/`utm_medium`/\n * `utm_campaign` off the landing URL and increments a per-day label counter\n * with them. That answers \"how many views did this campaign send us\" and\n * stops there — the labels are never carried to the moment the visitor says\n * who they are, so every form, lead, contact and booking a campaign caused is\n * recorded as though nobody caused it.\n *\n * This carries them. The touch is held on the VISITOR, and every identify\n * moment attaches it.\n *\n * ## What holds it, and why it outlives the tab\n *\n * `localStorage`, expiring at {@link ATTRIBUTION_WINDOW_DAYS}.\n *\n * `campaign-forwarding.ts` holds its own campaign in `sessionStorage` and\n * argues for it: a first touch that outlived the visit would start\n * attributing next week's organic return to this week's ad. That argument is\n * correct for the question it answers — which campaign produced THIS SIGNUP,\n * asked of one uninterrupted visit to the marketing site — and it is the\n * wrong shape here, because this question already has a stated answer to\n * \"how long may a touch be credited\": the attribution window, seven days,\n * stamped onto every record so the rule is readable off the data.\n *\n * A store that dies with the tab cannot express a seven-day window. It would\n * credit only the visitors who convert without ever closing the tab and\n * silently record every other conversion as organic — a measured zero, which\n * is the failure mode this whole area exists to end. So the touch lives as\n * long as the window says it may and not one millisecond longer: an expired\n * entry is DELETED on the read that finds it, rather than ignored, so a\n * device never holds a campaign it can no longer be credited with.\n *\n * ## Last touch, not first\n *\n * The revenue join credits the LAST click, and a product where a lead and an\n * order attribute by different rules is worse than one that is uniformly\n * approximate. So a new campaign arrival OVERWRITES the stored one. This is\n * the deliberate opposite of {@link rememberVisitCampaign}, which keeps the\n * first — that one describes a single visit's origin and this one describes\n * which campaign most recently brought a person back.\n *\n * ## Consent\n *\n * Two tiers, exactly as the console hop splits them, and the split is the\n * same because the acts are the same:\n *\n *  - **The live URL at the moment of conversion** touches no storage. The\n *    parameters are already in the page the visitor asked for, nothing is\n *    written to their device, and there is accordingly nothing to consent to.\n *    A visitor who converts on the page the ad landed them on is attributed\n *    with no grant of any kind.\n *  - **The remembered touch** is written to the visitor's device for an\n *    analytics purpose, which is `analytics_storage`, and it waits for the\n *    same grant the analytics tag waits for. The gate is not re-derived here:\n *    the caller already computed it for the tag and hands the same boolean\n *    down, so there is one gate and it cannot drift from itself.\n *\n * `null` is UNRESOLVED and is not `false`. With `strictNullChecks` off\n * repo-wide that distinction evaporates unless it is carried explicitly, so\n * it is: until the visitor's state is actually settled, nothing is read and\n * nothing is written. Failing closed costs an attribution; failing open\n * writes to a device before the visitor answered.\n *\n * On a WITHDRAWAL the stored touch is removed rather than merely ignored.\n * Somebody who changes their mind should not leave the thing they withdrew\n * consent for sitting on their device.\n *\n * ⛔ **A host whose posture requires prior consent and whose visitor has not\n * given it produces no remembered touch at all.** Their conversion attributes\n * to nothing, exactly as direct traffic does. That is the degradation, stated\n * rather than worked around: there is no fallback identifier, no fingerprint\n * and no server-side cookie, because every one of those is the durable\n * identifier the analytics posture on this runtime deliberately does not set.\n *\n * ## What is never carried\n *\n * Only the three allowlisted `utm_` labels, scrubbed by\n * {@link parseCampaignAttribution} — which refuses an email-shaped value\n * outright. No address, no person's identifier, no click id, nothing that\n * names the visitor. A campaign link is exactly where putting a recipient in\n * a query string would be tempting, and the parser is what makes it\n * impossible rather than merely discouraged: the stored string is re-parsed\n * through the same allowlist that wrote it, so a hand-edited `localStorage`\n * entry can claim no more than a hand-edited URL could.\n *\n * ⛔ **Nothing here depends on a parameter surviving the mail provider's\n * click wrapper.** A campaign link is rewritten by the provider and redirects\n * to the authored URL, so whatever the marketer put on it arrives — but the\n * email channel does not rely on that, because an email click is already\n * recorded server-side against the recipient's address hash. The labels below\n * are the WEB channel's touch, and a campaign that carries none is joined by\n * address instead.\n */\n\nimport {\n  campaignAttributionQuery,\n  parseCampaignAttribution,\n  type CampaignAttribution,\n} from './campaign-attribution'\n\n/*==========================================\n * THE WINDOW, AND WHY THIS IS THE SECOND COPY OF A NUMBER.\n *\n * `email-revenue-window.ts` in `shared-util-email` declares the same seven\n * days, and its docblock is right that a window defined twice is a window\n * that drifts. Importing it here is not available: `shared-util-email` is\n * tagged `scope:shared` and reaches back into `@aglyn/aglyn`, so an edge in\n * this direction closes a project cycle and the module-boundary rule refuses\n * it. That is the same wall `email-media-src.ts` hit, and the answer is the\n * same one it took — a deliberate copy, pinned by a drift guard in an app\n * spec that can import both sides (`attribution-window-drift.spec.ts`).\n *\n * The copy is the WINDOW only. The model name is stamped onto records, which\n * happens server-side, so it stays in one place and never comes near this\n * file.\n *=========================================*/\n\n/** Days between a campaign touch and a conversion it may be credited with. */\nexport const ATTRIBUTION_WINDOW_DAYS = 7\n\n/** The same window in milliseconds. */\nexport const ATTRIBUTION_WINDOW_MS =\n  ATTRIBUTION_WINDOW_DAYS * 24 * 60 * 60 * 1000\n\n/**\n * Whether a touch may be credited with a conversion at `convertedAtMs`.\n *\n * Both bounds matter and they fail differently, exactly as the revenue join\n * describes them: a touch AFTER the conversion is the receipt rather than the\n * cause, and a touch older than the window is one nobody can argue caused\n * anything. Inclusive at both ends.\n */\nfunction touchIsInWindow(touchedAtMs: number, convertedAtMs: number): boolean {\n  if (!Number.isFinite(touchedAtMs) || !Number.isFinite(convertedAtMs)) {\n    return false\n  }\n  if (touchedAtMs <= 0 || convertedAtMs <= 0) return false\n  const age = convertedAtMs - touchedAtMs\n  return age >= 0 && age <= ATTRIBUTION_WINDOW_MS\n}\n\n/** Where the touch is held. Namespaced like every other key this app sets. */\nexport const CAMPAIGN_TOUCH_STORAGE_KEY = 'aglyn:campaign-touch'\n\n/**\n * The parameter the touch's instant rides under inside the wire form.\n *\n * Deliberately not a `utm_` name: the wire form is parsed by the same\n * allowlist that reads a URL, and a fourth `utm_` key would either be dropped\n * by it or have to widen it. `t` is outside the allowlist and read\n * separately.\n */\nexport const CAMPAIGN_TOUCH_TIME_KEY = 't'\n\n/** A campaign the visitor arrived from, and when they arrived from it. */\nexport interface CampaignTouch extends CampaignAttribution {\n  /** When the visitor followed the campaign link, epoch ms. */\n  atMs: number\n}\n\n/**\n * Whether the visitor has granted analytics storage.\n *\n * `null` means NOT YET RESOLVED and is not the same as `false` — see the\n * consent section above.\n */\nlet storageConsent: boolean | null = null\n\nfunction localStore(): Storage | null {\n  if (typeof window === 'undefined') return null\n  // Touching the property itself throws in some privacy modes, not just its\n  // methods.\n  try {\n    return window.localStorage ?? null\n  } catch {\n    return null\n  }\n}\n\n/**\n * The canonical stored form of a touch — the ONLY place it is written, so it\n * cannot drift from what {@link parseCampaignTouch} reads back.\n */\nexport function campaignTouchWire(touch: CampaignTouch | null | undefined): string {\n  if (!touch) return ''\n  const labels = campaignAttributionQuery(touch)\n  if (!labels) return ''\n  const atMs = Math.round(Number(touch.atMs))\n  if (!Number.isFinite(atMs) || atMs <= 0) return ''\n  return `${labels}&${CAMPAIGN_TOUCH_TIME_KEY}=${atMs}`\n}\n\n/**\n * Read a stored or transmitted touch back, or `null`.\n *\n * The window is enforced HERE rather than at the call sites, so every reader\n * — the browser deciding what to send, the server deciding what to credit —\n * agrees about what an expired touch is: nothing at all. A touch dated in the\n * future is refused for the reason the revenue join refuses one: a click\n * after the conversion is the receipt, not the cause.\n */\nexport function parseCampaignTouch(\n  wire: unknown,\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  if (typeof wire !== 'string' || !wire) return null\n  let params: URLSearchParams\n  try {\n    params = new URLSearchParams(wire)\n  } catch {\n    return null\n  }\n  const campaign = parseCampaignAttribution(params)\n  if (!campaign) return null\n  const atMs = Number(params.get(CAMPAIGN_TOUCH_TIME_KEY))\n  if (!touchIsInWindow(atMs, nowMs)) return null\n  return { ...campaign, atMs }\n}\n\n/**\n * Tell this module what the visitor's analytics consent state is.\n *\n * Called by whoever already computed it for the tag, on every render, so a\n * grant remembers the arrival the moment it is given and a withdrawal drops\n * the stored touch immediately.\n */\nexport function setCampaignTouchConsent(allowed: boolean | null): void {\n  storageConsent = allowed === true ? true : allowed === false ? false : null\n  if (storageConsent === true) {\n    rememberCampaignTouch()\n    return\n  }\n  if (storageConsent === false) {\n    const store = localStore()\n    if (!store) return\n    try {\n      store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n    } catch {\n      // Nothing else to try, and a failed cleanup must not break the page.\n    }\n  }\n}\n\n/**\n * Remember the campaign on the current URL as this visitor's latest touch.\n *\n * Overwrites, because the model is last touch. A URL naming no campaign\n * writes NOTHING and clears nothing: a visitor who arrives from an ad and\n * then browses ten organic pages has one touch, not one touch erased by the\n * second pageview.\n *\n * @returns what is now remembered, or `null`.\n */\nexport function rememberCampaignTouch(\n  search?: string,\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  if (storageConsent !== true) return null\n  const store = localStore()\n  if (!store) return null\n  const source =\n    typeof search === 'string'\n      ? search\n      : typeof window === 'undefined'\n        ? ''\n        : window.location.search\n  const campaign = parseCampaignAttribution(new URLSearchParams(source))\n  if (!campaign) return null\n  const touch: CampaignTouch = { ...campaign, atMs: nowMs }\n  const wire = campaignTouchWire(touch)\n  if (!wire) return null\n  try {\n    store.setItem(CAMPAIGN_TOUCH_STORAGE_KEY, wire)\n  } catch {\n    // A store that refuses the write costs the walk from the landing page to\n    // the conversion, never a conversion on the landing page itself — the\n    // live URL below still carries that visitor.\n    return null\n  }\n  return touch\n}\n\n/**\n * The touch to credit a conversion happening right now, or `null`.\n *\n * ## The order is the model\n *\n * The live URL is consulted FIRST and wins whenever it names a campaign,\n * because a campaign on the address bar at the moment of conversion is by\n * definition the most recent touch there is. Only when the current page names\n * none does this fall back to what was remembered.\n *\n * ## An expired entry is deleted, not skipped\n *\n * A touch past the window can never be credited again, so leaving it on the\n * device would be keeping a record of where somebody came from for no purpose\n * anything reads. The read that finds it removes it.\n */\nexport function readCampaignTouch(\n  nowMs: number = Date.now(),\n): CampaignTouch | null {\n  const live =\n    typeof window === 'undefined'\n      ? null\n      : parseCampaignAttribution(new URLSearchParams(window.location.search))\n  if (live) return { ...live, atMs: nowMs }\n\n  if (storageConsent !== true) return null\n  const store = localStore()\n  if (!store) return null\n  let raw: string | null\n  try {\n    raw = store.getItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n  } catch {\n    return null\n  }\n  if (!raw) return null\n  const touch = parseCampaignTouch(raw, nowMs)\n  if (!touch) {\n    try {\n      store.removeItem(CAMPAIGN_TOUCH_STORAGE_KEY)\n    } catch {\n      // The entry stays until the next read finds it again; it is already\n      // uncreditable, so nothing downstream is affected.\n    }\n    return null\n  }\n  return touch\n}\n\n/**\n * The fragment a conversion request spreads into its body, or `{}`.\n *\n * One helper rather than four hand-written spreads: a door that forgets it\n * reports its conversions as organic, which looks exactly like a campaign\n * that produced none. Empty when there is no touch — never a placeholder,\n * never `campaignTouch: undefined`, so that \"arrived from nowhere\" and \"this\n * door does not report\" stay distinguishable on the wire.\n */\nexport function campaignTouchField(\n  nowMs: number = Date.now(),\n): { campaignTouch?: string } {\n  const wire = campaignTouchWire(readCampaignTouch(nowMs))\n  return wire ? { campaignTouch: wire } : {}\n}\n"],"names":["campaignAttributionQuery","parseCampaignAttribution","ATTRIBUTION_WINDOW_DAYS","ATTRIBUTION_WINDOW_MS","touchIsInWindow","touchedAtMs","convertedAtMs","Number","isFinite","age","CAMPAIGN_TOUCH_STORAGE_KEY","CAMPAIGN_TOUCH_TIME_KEY","storageConsent","localStore","window","localStorage","campaignTouchWire","touch","labels","atMs","Math","round","parseCampaignTouch","wire","nowMs","Date","now","params","URLSearchParams","campaign","get","setCampaignTouchConsent","allowed","rememberCampaignTouch","store","removeItem","search","source","location","setItem","readCampaignTouch","live","raw","getItem","campaignTouchField","campaignTouch"],"mappings":"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"}

package/src/lib/app-utils/child-contract-compose.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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.
+ */
+/**
+ * Every component id whose children a compose pass destroys, as
+ * reviewer-facing lines (empty = the contract holds).
+ *
+ * Call it with the ids the editor accepts a drop into
+ * (`listAcceptingComponentIds`), which is exactly the set for which "the
+ * author put a node here" must survive to a render surface. Ids the editor
+ * already refuses are not probed — a component that cannot receive a drop is
+ * free to rewrite its own child list, which is what `reusableInstance` and
+ * `layoutSlot` do for a living.
+ */
+export declare function auditComposeChildSurvival(acceptingComponentIds: readonly string[]): string[];