@websline/cms-view-utils 1.8.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@websline/cms-view-utils",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "files": [
     "src",

package/src/ads/adPath.js

@@ -0,0 +1,19 @@
+/**
+ * The path the ads endpoint targets against: no leading slash, no language
+ * segment — exactly what the page route takes. A browser knows the page as
+ * `/de/zimmer/suite`, the CMS as `zimmer/suite`, and the start page as `""`.
+ *
+ * Shared by the server-side middleware and the browser helper so the two cannot
+ * drift apart; a mismatch would silently aim page targeting at the wrong entity.
+ */
+const toAdPath = (pathname, locale) => {
+	const segments = String(pathname ?? "")
+		.split("/")
+		.filter(Boolean);
+
+	if (locale && segments[0] === locale) segments.shift();
+
+	return segments.join("/");
+};
+
+export { toAdPath };

package/src/ads/createAdRunner.js

@@ -0,0 +1,252 @@
+import { createDismissals } from "./dismissals.js";
+import { createImpressions } from "./impressions.js";
+import { filterEligibleAds } from "./selectAd.js";
+import { groupIntoSlots, slotOf } from "./slots.js";
+import { countPageView, watchTrigger } from "./triggers.js";
+import { recordAdEvent } from "../client/recordAdEvent.js";
+
+/**
+ * Runs a page's ads: who may appear, where, and when.
+ *
+ * Each slot — overlay, banner, each slide-in, the menu — holds at most one ad at
+ * a time, and the slots are independent of one another. Inside a slot every
+ * eligible candidate waits for its own trigger, and **the first to fire while the
+ * slot is free claims it**. A candidate whose trigger fires against an occupied
+ * slot is passed over silently; it was never shown, so it keeps its chance on the
+ * next page view.
+ *
+ * Because triggers are armed in priority order, two ads that fire at the same
+ * moment — two `immediate` overlays — resolve to the stronger one.
+ *
+ * Rendering stays with the template. So does saying when an ad actually became
+ * visible: `observe` is what turns a rendered ad into a counted view.
+ */
+
+const SESSION_KEY = "wl_ads_session";
+
+/** Half the ad in view is the point where a visitor can be said to have seen it. */
+const VISIBLE_RATIO = 0.5;
+
+const randomId = () =>
+	globalThis.crypto?.randomUUID?.() ??
+	`${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+/**
+ * One id per visit, so a click can be related to the view it came from. Kept in
+ * `sessionStorage`: it must not outlive the visit, and it is not a cookie because
+ * nothing on the server ever reads it back.
+ */
+const resolveSessionId = (storage) => {
+	try {
+		const existing = storage?.getItem(SESSION_KEY);
+		if (existing) return existing;
+
+		const created = randomId();
+		storage?.setItem(SESSION_KEY, created);
+
+		return created;
+	} catch {
+		// No storage: the visit still counts, its events just cannot be grouped.
+		return randomId();
+	}
+};
+
+const parseCookies = (cookieString) =>
+	String(cookieString ?? "")
+		.split(";")
+		.reduce((cookies, part) => {
+			const index = part.indexOf("=");
+			if (index < 0) return cookies;
+
+			const name = part.slice(0, index).trim();
+			if (name) cookies[name] = decodeURIComponent(part.slice(index + 1).trim());
+
+			return cookies;
+		}, {});
+
+/**
+ * @param {object} options
+ * @param {Record<string, object[]>} options.ads The endpoint's answer, from `locals.ads`
+ * @param {(ad: object) => void} options.onShow Render this ad now
+ * @param {() => boolean} [options.isConsentGiven] Defaults to "no consent"
+ * @param {boolean} [options.trackingEnabled] Off until a consent manager can allow it
+ */
+const createAdRunner = ({
+	ads,
+	onShow,
+	isConsentGiven = () => false,
+	trackingEnabled = false,
+	env = {},
+}) => {
+	const {
+		doc = typeof document === "undefined" ? null : document,
+		target = typeof window === "undefined" ? null : window,
+		storage,
+		sessionStore = typeof window === "undefined" ? null : window.sessionStorage,
+		now = Date.now(),
+		report = recordAdEvent,
+		observerFactory = defaultObserverFactory,
+	} = env;
+
+	const dismissals = createDismissals(storage);
+	const impressions = createImpressions(sessionStore);
+
+	// Entries for ads that are gone would otherwise pile up in every browser.
+	dismissals.prune(
+		Object.values(ads ?? {}).flatMap((list) => list.map(({ uuid }) => uuid)),
+	);
+
+	// Once for this page view, then handed to every trigger that needs it.
+	const pageViews = countPageView(sessionStore);
+
+	const sessionId = trackingEnabled ? resolveSessionId(sessionStore) : null;
+	const track = (uuid, type) => {
+		if (trackingEnabled) report({ uuid, type, sessionId });
+	};
+
+	/** Which ad currently holds each slot, and the teardowns to run on stop. */
+	const occupied = new Map();
+	const teardowns = [];
+	const counted = new Set();
+	const shown = [];
+
+	/**
+	 * Takes the ad off the screen, frees its slot for a candidate that fires later,
+	 * and starts its suppression — the same ending whether the visitor followed it
+	 * or closed it.
+	 */
+	const release = (ad) => {
+		const slot = slotOf(ad);
+		if (occupied.get(slot) === ad) occupied.delete(slot);
+
+		const index = shown.indexOf(ad);
+		if (index >= 0) shown.splice(index, 1);
+
+		dismissals.record(ad.uuid, Date.now());
+	};
+
+	const claim = (ad) => {
+		const slot = slotOf(ad);
+
+		// Someone got here first. Passed over rather than queued: it was never
+		// shown, so it may try again on the next page view.
+		if (occupied.has(slot)) return;
+
+		occupied.set(slot, ad);
+		shown.push(ad);
+		onShow(ad);
+	};
+
+	for (const [, candidates] of groupIntoSlots(ads)) {
+		const eligible = filterEligibleAds({
+			candidates,
+			now,
+			dismissedAt: (uuid) => dismissals.dismissedAt(uuid),
+			seenAt: (uuid) => impressions.seenAt(uuid),
+			cookies: parseCookies(doc?.cookie),
+			params: target ? new URLSearchParams(target.location.search) : undefined,
+			isConsentGiven,
+		});
+
+		for (const ad of eligible) {
+			teardowns.push(
+				watchTrigger(ad.trigger, () => claim(ad), {
+					doc,
+					target,
+					sessionStore,
+					pageViews,
+				}),
+			);
+		}
+	}
+
+	return {
+		/**
+		 * The ads currently on screen, in the order they claimed their slot.
+		 *
+		 * A method, not a property: a framework that wraps this object in a deep
+		 * reactive proxy would keep handing out the array as it looked when it was
+		 * wrapped, and the runner mutates its own array from the outside. Calling
+		 * in reads the truth every time.
+		 */
+		shown: () => [...shown],
+
+		/**
+		 * Counts the view once the element is really in front of the visitor. The
+		 * template calls this after rendering; without it an ad is shown but never
+		 * counted, which is the honest default — a number nobody produced should
+		 * not be invented.
+		 */
+		observe(ad, element) {
+			if (!ad || counted.has(ad.uuid)) return () => {};
+
+			const markSeen = () => {
+				if (counted.has(ad.uuid)) return;
+				counted.add(ad.uuid);
+
+				// Recorded whether or not anyone is measuring: how often a visitor is
+				// interrupted is not a statistic, it is the visitor's experience.
+				impressions.record(ad.uuid, Date.now());
+				track(ad.uuid, "view");
+			};
+
+			const observer = observerFactory(markSeen);
+
+			// No IntersectionObserver: the ad was rendered, and guessing it was seen
+			// is closer to the truth than dropping the view entirely.
+			if (!observer) {
+				markSeen();
+				return () => {};
+			}
+
+			observer.observe(element);
+			const stop = () => observer.disconnect();
+			teardowns.push(stop);
+
+			return stop;
+		},
+
+		/**
+		 * Following the ad ends it too: a visitor who acted on it has seen what it
+		 * had to say, and meeting it again on the next page reads as nagging. A
+		 * persistent ad stays until the visitor closes it.
+		 */
+		click(ad) {
+			if (!ad) return;
+
+			track(ad.uuid, "click");
+			if (!ad.persistent) release(ad);
+		},
+
+		/** An ad that is not closable has no close button, so nothing to dismiss. */
+		dismiss(ad) {
+			if (!ad || ad.closable === false) return;
+
+			track(ad.uuid, "close");
+			release(ad);
+		},
+
+		stop() {
+			for (const teardown of teardowns) teardown();
+			teardowns.length = 0;
+		},
+	};
+};
+
+const defaultObserverFactory = (onVisible) => {
+	if (typeof IntersectionObserver === "undefined") return null;
+
+	return new IntersectionObserver(
+		(entries, observer) => {
+			for (const entry of entries) {
+				if (!entry.isIntersecting) continue;
+
+				onVisible();
+				observer.disconnect();
+			}
+		},
+		{ threshold: VISIBLE_RATIO },
+	);
+};
+
+export { createAdRunner, parseCookies, SESSION_KEY, VISIBLE_RATIO };

package/src/ads/dismissals.js

@@ -0,0 +1,77 @@
+/**
+ * Remembers which ads a visitor closed, in `localStorage` and nowhere else: the
+ * value is only ever read in the browser, and as a cookie it would travel with
+ * every request without anyone looking at it.
+ *
+ * Stored is the **moment of the click**, never a computed expiry — the duration
+ * comes from the CMS response on every page view, so shortening it there reaches
+ * visitors who already closed the ad.
+ */
+
+const STORAGE_KEY = "wl_ads_dismissed";
+
+/**
+ * Every access is guarded: `localStorage` throws on a blocked origin and reads
+ * empty in a private window. A visitor who cannot store anything sees every ad
+ * again — annoying, but the page must not break over it.
+ */
+const readAll = (storage) => {
+	try {
+		const raw = storage?.getItem(STORAGE_KEY);
+		const parsed = raw ? JSON.parse(raw) : null;
+
+		return parsed && typeof parsed === "object" ? parsed : {};
+	} catch {
+		return {};
+	}
+};
+
+const writeAll = (storage, entries) => {
+	try {
+		storage?.setItem(STORAGE_KEY, JSON.stringify(entries));
+	} catch {
+		// Storage full, blocked or unavailable — nothing to recover, and the only
+		// consequence is that this ad may show again.
+	}
+};
+
+const resolveStorage = (storage) => {
+	if (storage) return storage;
+
+	return typeof window === "undefined" ? null : window.localStorage;
+};
+
+const createDismissals = (storage) => {
+	const target = resolveStorage(storage);
+
+	return {
+		/** Epoch milliseconds of the visitor's click, or null. */
+		dismissedAt(uuid) {
+			const value = readAll(target)[uuid];
+
+			return typeof value === "number" ? value : null;
+		},
+
+		record(uuid, now = Date.now()) {
+			writeAll(target, { ...readAll(target), [uuid]: now });
+		},
+
+		/**
+		 * Drops entries for ads the response no longer carries, so a site that ran
+		 * campaigns for years does not grow an unbounded record in every browser.
+		 */
+		prune(knownUuids) {
+			const keep = new Set(knownUuids);
+			const entries = readAll(target);
+			const pruned = Object.fromEntries(
+				Object.entries(entries).filter(([uuid]) => keep.has(uuid)),
+			);
+
+			if (Object.keys(pruned).length !== Object.keys(entries).length) {
+				writeAll(target, pruned);
+			}
+		},
+	};
+};
+
+export { createDismissals, STORAGE_KEY };

package/src/ads/impressions.js

@@ -0,0 +1,62 @@
+/**
+ * Remembers which ads this visit has already shown, so a reload does not put the
+ * same overlay back on the screen.
+ *
+ * Deliberately weaker than a dismissal and deliberately in `sessionStorage`:
+ * closing an ad is an explicit "no" and earns the full suppression the editor
+ * configured, while merely having seen one means "not now". It ends with the
+ * visit, so the message still reaches a visitor who comes back next week.
+ */
+
+const STORAGE_KEY = "wl_ads_seen";
+
+/** Keyed by uuid with the moment of the impression, so a reset can undo it. */
+const readAll = (storage) => {
+	try {
+		const raw = storage?.getItem(STORAGE_KEY);
+		const parsed = raw ? JSON.parse(raw) : null;
+
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+
+		return parsed;
+	} catch {
+		return {};
+	}
+};
+
+const resolveStorage = (storage) => {
+	if (storage) return storage;
+
+	return typeof window === "undefined" ? null : window.sessionStorage;
+};
+
+const createImpressions = (storage) => {
+	const target = resolveStorage(storage);
+
+	return {
+		/** Epoch milliseconds of the impression, or null. */
+		seenAt(uuid) {
+			const value = readAll(target)[uuid];
+
+			return typeof value === "number" ? value : null;
+		},
+
+		/**
+		 * Records when the ad was seen *last*. Keeping the first moment would make
+		 * an ad the editor just reset reappear on every page for the rest of the
+		 * visit: its stored impression would stay older than the reset forever.
+		 */
+		record(uuid, now = Date.now()) {
+			const seen = readAll(target);
+
+			try {
+				target?.setItem(STORAGE_KEY, JSON.stringify({ ...seen, [uuid]: now }));
+			} catch {
+				// Nothing to recover: the only consequence is that this ad may appear
+				// once more during the visit.
+			}
+		},
+	};
+};
+
+export { createImpressions, STORAGE_KEY };

package/src/ads/selectAd.js

@@ -0,0 +1,124 @@
+/**
+ * Picks the ad a visitor actually gets to see. The CMS answers with every
+ * candidate that belongs on this page, in order; everything that describes the
+ * visitor rather than the page is decided here.
+ *
+ * Pure on purpose — the browser is passed in, never read. That keeps the rules
+ * testable and is why `document` and `localStorage` appear nowhere in this file.
+ */
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Matches the API's fallback, for an ad saved before the key existed. */
+const DEFAULT_DISMISS_DURATION_DAYS = 7;
+
+const parseTimestamp = (value) => {
+	if (!value) return null;
+
+	const parsed = Date.parse(value);
+
+	return Number.isNaN(parsed) ? null : parsed;
+};
+
+/**
+ * "Show it again" has to mean every reason the ad was being held back, not just
+ * one of them: anything the visitor did before the editor pressed the button is
+ * forgotten. Without this the reset works for a dismissal but not for an ad the
+ * visitor merely saw, and the button looks broken.
+ */
+const survivesReset = (ad, at) => {
+	const resetAt = parseTimestamp(ad.conditions?.dismissResetAt);
+
+	return resetAt === null || at >= resetAt;
+};
+
+/**
+ * Whether the visitor closed this ad recently enough to still be rid of it.
+ *
+ * The duration is read from the response on every page view rather than baked
+ * into the stored entry, so shortening it in the CMS brings the ad back for
+ * everyone whose dismissal is already older.
+ */
+const isSuppressed = (ad, dismissedAt, now) => {
+	if (!dismissedAt) return false;
+	if (!survivesReset(ad, dismissedAt)) return false;
+
+	const days = ad.conditions?.dismissDurationDays ?? DEFAULT_DISMISS_DURATION_DAYS;
+
+	return now < dismissedAt + days * DAY_MS;
+};
+
+/** Seen during this visit, and not before the editor reset it. */
+const wasSeenThisVisit = (ad, seenAt) => Boolean(seenAt) && survivesReset(ad, seenAt);
+
+/**
+ * A condition with no name set is no condition. With a name but no value the
+ * mere presence counts, which is how "only for visitors who have this cookie at
+ * all" is expressed.
+ */
+const matchesNameValue = (name, value, actual) => {
+	if (!name) return true;
+	if (actual === undefined || actual === null) return false;
+
+	return value ? actual === value : true;
+};
+
+/**
+ * An ad the editor marked "only with confirmed consent" while nothing can confirm
+ * it stays hidden. The opposite reading would show exactly those ads that were
+ * singled out as needing permission.
+ */
+const hasConsent = (ad, isConsentGiven) =>
+	ad.conditions?.requireConsent !== true || isConsentGiven() === true;
+
+/**
+ * Every candidate this visitor may be shown, in the order they came in. More than
+ * one survives on purpose: they compete for a slot later, when their triggers
+ * fire, and the one that fires first while the slot is free wins it.
+ *
+ * @param {object} options
+ * @param {object[]} options.candidates Highest priority first
+ * @param {number} options.now Epoch milliseconds
+ * @param {(uuid: string) => number|null} options.dismissedAt When the visitor closed an ad
+ * @param {(uuid: string) => number|null} [options.seenAt] When it was shown during this visit
+ * @param {Record<string, string>} [options.cookies] Parsed cookies
+ * @param {URLSearchParams} [options.params] The current URL's query
+ * @param {() => boolean} [options.isConsentGiven] Defaults to "no consent"
+ * @returns {object[]} The eligible ads
+ */
+const filterEligibleAds = ({
+	candidates = [],
+	now,
+	dismissedAt,
+	seenAt = () => null,
+	cookies = {},
+	params,
+	isConsentGiven = () => false,
+}) =>
+	candidates.filter((ad) => {
+		if (!hasConsent(ad, isConsentGiven)) return false;
+		// Once per visit is the floor; a reload must not put it back on the screen.
+		// A persistent ad has no such floor: it stays on every page until closed.
+		if (!ad.persistent && wasSeenThisVisit(ad, seenAt(ad.uuid))) return false;
+		// `closable: false` has no close button, so no dismissal can hold it back.
+		if (ad.closable !== false && isSuppressed(ad, dismissedAt(ad.uuid), now)) {
+			return false;
+		}
+
+		const { cookieName, cookieValue, paramName, paramValue } = ad.conditions ?? {};
+
+		if (!matchesNameValue(cookieName, cookieValue, cookies[cookieName])) return false;
+
+		return matchesNameValue(
+			paramName,
+			paramValue,
+			paramName ? (params?.get(paramName) ?? undefined) : undefined,
+		);
+	});
+
+export {
+	DEFAULT_DISMISS_DURATION_DAYS,
+	filterEligibleAds,
+	isSuppressed,
+	wasSeenThisVisit,
+};

package/src/ads/slots.js

@@ -0,0 +1,41 @@
+/**
+ * Which ads can share the screen and which cannot.
+ *
+ * The unit is the **slot**, not the placement: a banner sits in the page flow at
+ * the top, an overlay is centred over everything, a slide-in clings to one edge.
+ * Those are different places, so they may run at the same time. Two overlays are
+ * the same place, so only one of them can.
+ */
+
+/** A page ad without a layout renders as an overlay, like the wizard's default. */
+const DEFAULT_PAGE_LAYOUT = "overlay";
+
+const slotOf = (ad) =>
+	ad?.placement === "navigation"
+		? "navigation"
+		: `page:${ad?.layout ?? DEFAULT_PAGE_LAYOUT}`;
+
+/**
+ * Groups the endpoint's answer into slots, keeping the order inside each one —
+ * the API already sorted by priority, and that order decides who claims a free
+ * slot when two candidates fire at the same moment.
+ *
+ * @param {Record<string, object[]>} ads
+ * @returns {Map<string, object[]>}
+ */
+const groupIntoSlots = (ads) => {
+	const slots = new Map();
+
+	for (const candidates of Object.values(ads ?? {})) {
+		for (const ad of candidates ?? []) {
+			const slot = slotOf(ad);
+
+			if (!slots.has(slot)) slots.set(slot, []);
+			slots.get(slot).push(ad);
+		}
+	}
+
+	return slots;
+};
+
+export { DEFAULT_PAGE_LAYOUT, groupIntoSlots, slotOf };

package/src/ads/triggers.js

@@ -0,0 +1,159 @@
+/**
+ * Waits for the single event that reveals an ad. Every watcher answers with its
+ * own teardown, because a slide-in that is still listening after the visitor
+ * navigated away would fire on a page it was never meant for.
+ *
+ * The browser pieces are injected rather than reached for, so the rules can be
+ * tested without a DOM.
+ */
+
+const PAGE_VIEWS_KEY = "wl_ads_page_views";
+
+/**
+ * Counted per session, not forever: "after three page views" describes one visit.
+ * Kept across visits it would fire immediately for every returning visitor.
+ */
+/**
+ * Counted once per page view by the caller, not once per ad: two ads waiting for
+ * the same number would otherwise advance the counter twice, and a page carrying
+ * no such ad would not advance it at all — it would count eligible ads, not views.
+ */
+const countPageView = (storage) => {
+	try {
+		const next = Number(storage?.getItem(PAGE_VIEWS_KEY) ?? 0) + 1;
+		storage?.setItem(PAGE_VIEWS_KEY, String(next));
+
+		return next;
+	} catch {
+		// Without storage every view is the first one, so a page-view trigger
+		// simply never fires rather than firing on every page.
+		return 1;
+	}
+};
+
+const never = () => () => {};
+
+const afterDelay = (seconds, fire, timers) => {
+	const id = timers.setTimeout(fire, Math.max(0, seconds) * 1000);
+
+	return () => timers.clearTimeout(id);
+};
+
+/**
+ * How far down the visitor is, in percent of what the page can scroll. A page
+ * that fits the window cannot be scrolled and so never reaches any share.
+ */
+const scrolledPercent = (target, doc) => {
+	const scrollable =
+		(doc?.documentElement?.scrollHeight ?? 0) - (target.innerHeight ?? 0);
+
+	return scrollable > 0 ? (target.scrollY / scrollable) * 100 : 0;
+};
+
+/**
+ * Fixed rather than set per ad: far enough to mean interest, early enough that
+ * most visitors get there. Not offered in the CMS, since no editor tunes it.
+ */
+const SCROLL_SHARE_PERCENT = 30;
+
+/**
+ * Keeps listening until the share is reached: `once` would drop the listener on
+ * an overscroll bounce back at the top and lose the ad for that visit.
+ */
+const onScrolledPast = (fire, target, doc) => {
+	const reached = () =>
+		target.scrollY > 0 && scrolledPercent(target, doc) >= SCROLL_SHARE_PERCENT;
+
+	// Already that far when the ad arrived — no further event may come.
+	if (reached()) {
+		fire();
+		return () => {};
+	}
+
+	const stop = () => target.removeEventListener("scroll", handler);
+
+	function handler() {
+		if (!reached()) return;
+
+		stop();
+		fire();
+	}
+
+	target.addEventListener("scroll", handler, { passive: true });
+
+	return stop;
+};
+
+/**
+ * Leaving towards the browser chrome, which is the only exit a page can observe.
+ * Deliberately not `beforeunload`: that fires when it is already too late to show
+ * anything, and costs the back/forward cache.
+ */
+const onExitIntent = (fire, doc) => {
+	const handler = (event) => {
+		// `relatedTarget` is empty only when the pointer left the document itself;
+		// without it, moving onto any element near the top edge fires the ad.
+		if (event.clientY <= 0 && !event.relatedTarget) fire();
+	};
+
+	doc.addEventListener("mouseout", handler);
+
+	return () => doc.removeEventListener("mouseout", handler);
+};
+
+/**
+ * @param {{kind: string, amount?: number}} trigger
+ * @param {() => void} onFire Called at most once
+ * @param {object} [env] Injected browser pieces
+ * @returns {() => void} Teardown
+ */
+const watchTrigger = (trigger, onFire, env = {}) => {
+	const {
+		doc = typeof document === "undefined" ? null : document,
+		target = typeof window === "undefined" ? null : window,
+		sessionStore = typeof window === "undefined" ? null : window.sessionStorage,
+		// Wrapped, not handed over: pulling the browser's timer functions off the
+		// window and calling them as a method of a plain object throws "Illegal
+		// invocation". Node does not care, so only a real browser shows it.
+		timers = {
+			setTimeout: (fn, ms) => setTimeout(fn, ms),
+			clearTimeout: (id) => clearTimeout(id),
+		},
+		pageViews,
+	} = env;
+
+	let fired = false;
+	const fire = () => {
+		if (fired) return;
+		fired = true;
+		onFire();
+	};
+
+	switch (trigger?.kind) {
+		case "immediate":
+			fire();
+			return never();
+
+		case "delay":
+			return afterDelay(trigger.amount ?? 0, fire, timers);
+
+		case "page_views": {
+			const views = pageViews ?? countPageView(sessionStore);
+			if (views >= (trigger.amount ?? 1)) fire();
+
+			return never();
+		}
+
+		case "scroll":
+			return target ? onScrolledPast(fire, target, doc) : never();
+
+		case "exit_intent":
+			return doc ? onExitIntent(fire, doc) : never();
+
+		default:
+			// An unknown trigger shows nothing rather than showing everything.
+			return never();
+	}
+};
+
+export { countPageView, PAGE_VIEWS_KEY, SCROLL_SHARE_PERCENT, watchTrigger };

package/src/client/fetchAds.js

@@ -0,0 +1,35 @@
+import { toAdPath } from "../ads/adPath.js";
+
+/**
+ * Fetch the ads that may be shown on the page currently being viewed.
+ *
+ * Answers one sorted candidate list per placement (`page`, `navigation`), both
+ * always present. Render the first candidate whose client-side conditions hold —
+ * consent, cookie, URL parameter and the suppression a visitor earned by closing
+ * it — and fall through to the next when one does not.
+ *
+ * @param {object} options
+ * @param {string} options.locale - Locale code, e.g. `"de"`.
+ * @param {string} [options.path] - Path of the page being viewed, without the leading slash and without the language segment, e.g. `"zimmer/doppelzimmer"`. Defaults to the current browser path; send `""` for the start page.
+ * @returns {Promise<Record<string, object[]>>} Candidates per placement, highest priority first.
+ */
+const fetchAds = async ({ locale, path = currentPath(locale) }) => {
+	const params = new URLSearchParams();
+
+	if (path) {
+		params.set("path", path);
+	}
+
+	const query = params.toString();
+	const url = `/api/cms/api/public/ads/${locale}${query ? `?${query}` : ""}`;
+
+	const response = await fetch(url, { method: "GET" });
+
+	return response.json();
+};
+
+/** Outside a browser there is nothing to read; the caller passes the path itself. */
+const currentPath = (locale) =>
+	typeof window === "undefined" ? "" : toAdPath(window.location.pathname, locale);
+
+export { fetchAds };

package/src/client/recordAdEvent.js

@@ -0,0 +1,37 @@
+/**
+ * Report that a visitor saw, clicked or closed one ad.
+ *
+ * Sent with `navigator.sendBeacon` where available: the `close` event fires while
+ * the page may already be going away, and a normal request would be cancelled
+ * with it. The endpoint answers `204`, so there is nothing to read either way,
+ * and a failed report never reaches the caller — a lost statistic must not take
+ * the page with it.
+ *
+ * @param {object} options
+ * @param {string} options.uuid - UUID of the ad, as delivered in the ad list.
+ * @param {"view"|"click"|"close"} options.type - What the visitor did. Send `view` once per ad that actually became visible, not per candidate the endpoint offered.
+ * @param {string} options.sessionId - Identifier for this visitor's session, 1 to 255 characters. Groups the events of one visit so a click can be related to the view it came from.
+ * @returns {void}
+ */
+const recordAdEvent = ({ uuid, type, sessionId }) => {
+	const url = `/api/cms/api/public/ads/${uuid}/events`;
+	const body = JSON.stringify({ type, sessionId });
+
+	try {
+		if (navigator?.sendBeacon) {
+			navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
+			return;
+		}
+
+		fetch(url, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body,
+			keepalive: true,
+		}).catch(() => {});
+	} catch {
+		// Nothing to recover and nobody to tell.
+	}
+};
+
+export { recordAdEvent };

package/src/cms/fetchAdsForPage.js

@@ -0,0 +1,49 @@
+import { toAdPath } from "../ads/adPath.js";
+import { buildCmsAdsUrl } from "./urlResolver.js";
+import { buildCmsHeaders } from "./headers.js";
+
+/** What every caller gets when there is nothing to show, so no template has to guard. */
+const EMPTY_ADS = { page: [], navigation: [] };
+
+/**
+ * Loads the page's ads while the server renders it, rather than from the browser
+ * afterwards. The response is identical for every visitor of the same page, so
+ * there is nothing to personalise — and the banner layout sits in the page flow,
+ * where arriving late would shift the content that is already painted.
+ *
+ * Runs after the page fetch because only its answer names the locale and the
+ * resolved path; the ads endpoint answers from memory, so the added hop is small.
+ *
+ * **Never fails the page.** Ads are decoration: a CMS hiccup, a disabled module
+ * or a malformed answer leaves the page rendering without them.
+ *
+ * @param {import("astro").APIContext} context
+ * @param {object} page The page the CMS answered with
+ * @param {object} [options]
+ * @param {boolean} [options.skip] Answer empty without asking the CMS
+ */
+const fetchAdsForPage = async (context, page, { skip = false } = {}) => {
+	const locale = page?.locale;
+
+	if (skip || !locale) return EMPTY_ADS;
+
+	try {
+		const response = await fetch(
+			buildCmsAdsUrl({ locale, path: toAdPath(page.path, locale) }),
+			{ method: "GET", headers: buildCmsHeaders(context.request) },
+		);
+
+		if (!response.ok) return EMPTY_ADS;
+
+		const data = await response.json();
+
+		return {
+			page: Array.isArray(data?.page) ? data.page : [],
+			navigation: Array.isArray(data?.navigation) ? data.navigation : [],
+		};
+	} catch {
+		return EMPTY_ADS;
+	}
+};
+
+export { EMPTY_ADS, fetchAdsForPage };

package/src/cms/fetchPage.js

@@ -1,3 +1,4 @@
+import { fetchAdsForPage } from "./fetchAdsForPage.js";
 import { resolveDraftUuidFromToken } from "./editorToken.js";
 import { buildCmsPageUrl } from "./urlResolver.js";
 import { buildCmsHeaders } from "./headers.js";
@@ -42,6 +43,12 @@ const fetchPage = async (context) => {
 	context.locals.languageSwitcher = data?.languageSwitcher ?? [];
 	context.locals.tenant = data?.tenant ?? null;
 	context.locals._cmsRaw = data;
+	// Never in the editor: an overlay covering the page an editor is working on
+	// would block the very content they are editing. The preview deliberately
+	// keeps them — that is where an editor checks what a visitor will get.
+	context.locals.ads = await fetchAdsForPage(context, context.locals.page, {
+		skip: Boolean(isCMSEditRoute),
+	});
 
 	if (isCMSPreviewRoute) {
 		context.locals._preview = true;

package/src/cms/proxyToCms.js

@@ -1,7 +1,10 @@
 import { buildCmsHeaders } from "./headers.js";
 import { HttpError } from "../shared/errors.js";
 
-const proxyToCms = async (context) => {
+/** The events endpoint answers this, and a Response with a body on it throws. */
+const NO_CONTENT = 204;
+
+const proxyToCms = async (context, { allow } = {}) => {
 	const cmsBase = import.meta.env.CMS_URL;
 
 	if (!cmsBase) {
@@ -10,18 +13,39 @@ const proxyToCms = async (context) => {
 
 	const { path = "" } = context.params;
 	const { request } = context;
+
+	// A write forwards the site's CMS token, and that token may carry scopes far
+	// beyond page delivery. Writes therefore reach only the paths named by the
+	// route that opened them, and everything else looks like it is not there.
+	if (allow && !allow(path)) {
+		throw new HttpError(404, "Not Found");
+	}
 	const url = new URL(request.url);
 	const target = `${cmsBase}/${path}${url.search}`;
 
+	// A write needs its body and its content type carried over; a read has neither.
+	// What such a request may reach is decided by the CMS token's scopes, not here.
+	const hasBody = request.method !== "GET" && request.method !== "HEAD";
+
 	const response = await fetch(target, {
 		method: request.method,
-		headers: buildCmsHeaders(request),
+		headers: hasBody
+			? {
+					...buildCmsHeaders(request),
+					"content-type": request.headers.get("content-type") ?? "application/json",
+				}
+			: buildCmsHeaders(request),
+		...(hasBody ? { body: await request.text() } : {}),
 	});
 
 	if (!response.ok) {
 		throw new HttpError(response.status, "CMS Error");
 	}
 
+	if (response.status === NO_CONTENT) {
+		return new Response(null, { status: response.status });
+	}
+
 	const data = await response.text();
 
 	return new Response(data, {
@@ -32,8 +56,8 @@ const proxyToCms = async (context) => {
 	});
 };
 
-const createCmsProxyHandler = () => {
-	return (context) => proxyToCms(context);
+const createCmsProxyHandler = ({ allow } = {}) => {
+	return (context) => proxyToCms(context, { allow });
 };
 
 export { proxyToCms, createCmsProxyHandler };

package/src/cms/urlResolver.js

@@ -10,6 +10,12 @@ const buildCmsPageUrl = ({ draftUuid, path }) => {
 	return `${CMS_BASE_URL}/api/public/pages${normalizedPath}`;
 };
 
+const buildCmsAdsUrl = ({ locale, path }) => {
+	const query = path ? `?path=${encodeURIComponent(path)}` : "";
+
+	return `${CMS_BASE_URL}/api/public/ads/${locale}${query}`;
+};
+
 const buildCmsSiteConfigUrl = () => {
 	return `${CMS_BASE_URL}/api/public/site-config`;
 };
@@ -23,6 +29,7 @@ const buildCmsLlmsTxtUrl = () => {
 };
 
 export {
+	buildCmsAdsUrl,
 	buildCmsPageUrl,
 	buildCmsSiteConfigUrl,
 	buildCmsSitemapUrl,

package/src/index.js

@@ -7,6 +7,13 @@ export { fetchBoards } from "./client/fetchBoards.js";
 export { fetchBoard } from "./client/fetchBoard.js";
 export { fetchPageTeasers } from "./client/fetchPageTeasers.js";
 export { fetchRatings } from "./client/fetchRatings.js";
+export { fetchAds } from "./client/fetchAds.js";
+
+export { recordAdEvent } from "./client/recordAdEvent.js";
+
+export { createAdRunner } from "./ads/createAdRunner.js";
+export { slotOf } from "./ads/slots.js";
+export { toAdPath } from "./ads/adPath.js";
 
 export { default as AddBlockPlaceholder } from "./components/AddBlockPlaceholder.svelte";
 export { default as BlockWrapper } from "./components/BlockWrapper.svelte";

package/src/routes/cmsProxy.js

@@ -2,4 +2,14 @@ import { createCmsProxyHandler } from "../cms/proxyToCms.js";
 
 export const prerender = false;
 
+/** The only write a browser has any business making through this proxy. */
+const AD_EVENT_PATH = /^api\/public\/ads\/[^/]+\/events$/;
+
 export const GET = createCmsProxyHandler();
+
+// Ad events are reported from the browser, which can only reach the CMS through
+// this proxy. Narrowed to that one path on purpose: the forwarded token may hold
+// management scopes, and an open POST would hand them to every visitor.
+export const POST = createCmsProxyHandler({
+	allow: (path) => AD_EVENT_PATH.test(path),
+});