@websline/cms-view-utils 1.7.2 → 1.9.0

package/package.json

@@ -1,43 +1,48 @@
 {
-	"name": "@websline/cms-view-utils",
-	"version": "1.7.2",
-	"type": "module",
-	"files": [
-		"src",
-		"dist"
-	],
-	"exports": {
-		".": "./src/index.js",
-		"./server": "./src/server.js",
-		"./components/*": "./src/components/*",
-		"./preview-bridge": "./dist/previewBridge.global.js",
-		"./edit-scroll": "./dist/editScroll.global.js",
-		"./dist/*": "./dist/*"
-	},
-	"dependencies": {
-		"jsonwebtoken": "^9.0.3",
-		"tailwind-merge": "^3.6.0"
-	},
-	"devDependencies": {
-		"@eslint/compat": "^2.1.0",
-		"@eslint/js": "^10.0.1",
-		"eslint": "^10.9.0",
-		"eslint-config-prettier": "^10.1.8",
-		"eslint-plugin-svelte": "^3.23.0",
-		"globals": "^17.11.0",
-		"prettier": "^3.9.6",
-		"prettier-plugin-svelte": "^4.1.1",
-		"prettier-plugin-tailwindcss": "^0.8.1",
-		"tsup": "^8.5.1"
-	},
-	"peerDependencies": {
-		"svelte": "^5.0.0"
-	},
-	"scripts": {
-		"build": "tsup",
-		"prepublishOnly": "pnpm build",
-		"format": "prettier --write .",
-		"lint": "prettier --check . && eslint ."
-	},
-	"sideEffects": false
-}
+  "name": "@websline/cms-view-utils",
+  "version": "1.9.0",
+  "type": "module",
+  "files": [
+    "src",
+    "dist",
+    "!src/**/*.test.js"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js",
+    "./integration": "./src/integration/cmsRoutes.js",
+    "./routes/*": "./src/routes/*",
+    "./components/*": "./src/components/*",
+    "./preview-bridge": "./dist/previewBridge.global.js",
+    "./edit-scroll": "./dist/editScroll.global.js",
+    "./dist/*": "./dist/*"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.3",
+    "tailwind-merge": "^3.7.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.1",
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.11.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-svelte": "^3.23.0",
+    "globals": "^17.12.0",
+    "prettier": "^3.9.8",
+    "prettier-plugin-svelte": "^4.1.1",
+    "prettier-plugin-tailwindcss": "^0.8.1",
+    "tsup": "^8.5.1",
+    "vitest": "^5.0.1"
+  },
+  "peerDependencies": {
+    "astro": ">=5",
+    "svelte": "^5.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "format": "prettier --write .",
+    "lint": "prettier --check . && eslint .",
+    "test": "vitest run"
+  }
+}

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,250 @@
+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.
+		 */
+		click(ad) {
+			if (!ad) return;
+
+			track(ad.uuid, "click");
+			release(ad);
+		},
+
+		dismiss(ad) {
+			if (!ad) 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,120 @@
+/**
+ * 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.
+		if (wasSeenThisVisit(ad, seenAt(ad.uuid))) return false;
+		if (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,141 @@
+/**
+ * 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);
+};
+
+/**
+ * Keeps listening until the page has really moved. `once` would drop the listener
+ * on the first scroll event even when it arrived back at the top — an overscroll
+ * bounce or a sideways scroll — and the ad would never appear for that visit.
+ */
+const onFirstScroll = (fire, target) => {
+	const stop = () => target.removeEventListener("scroll", handler);
+
+	function handler() {
+		if (target.scrollY <= 0) 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":
+			if (!target) return never();
+			// Already scrolled when the ad arrived — the event will not come again.
+			if (target.scrollY > 0) {
+				fire();
+				return never();
+			}
+
+			return onFirstScroll(fire, target);
+
+		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, 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/integration/cmsRoutes.js

@@ -0,0 +1,62 @@
+import { CMS_ROUTE_PATTERN } from "../shared/routes.js";
+
+/**
+ * Astro integration that ships the CMS-backed routes every website needs, so a
+ * site repository does not have to re-declare them. A project file of the same
+ * pattern wins over the injected route; `exclude` makes that intent explicit.
+ */
+
+const INJECTED_ROUTES = {
+	"/robots.txt": "@websline/cms-view-utils/routes/robots.txt.js",
+	"/sitemap.xml": "@websline/cms-view-utils/routes/sitemap.xml.js",
+	"/llms.txt": "@websline/cms-view-utils/routes/llms.txt.js",
+	"/api/cms/[...path]": "@websline/cms-view-utils/routes/cmsProxy.js",
+};
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.exclude] - route patterns the project provides itself
+ * @param {string} [options.cmsRoutePattern] - route pattern of the CMS catch-all page
+ */
+const cmsRoutes = (options = {}) => {
+	const { exclude = [], cmsRoutePattern = CMS_ROUTE_PATTERN } = options;
+
+	return {
+		name: "@websline/cms-view-utils",
+		hooks: {
+			"astro:config:setup": ({ injectRoute }) => {
+				for (const [pattern, entrypoint] of Object.entries(INJECTED_ROUTES)) {
+					if (exclude.includes(pattern)) continue;
+
+					injectRoute({ pattern, entrypoint });
+				}
+			},
+			"astro:routes:resolved": ({ routes, logger }) => {
+				const hasCmsRoute = routes.some((route) => route.pattern === cmsRoutePattern);
+
+				if (!hasCmsRoute) {
+					throw new Error(
+						`@websline/cms-view-utils: no route matches "${cmsRoutePattern}". ` +
+							"The CMS middleware only runs for that route, so every page would " +
+							"render without CMS data. Add src/pages/[...path].astro or pass " +
+							"cmsRoutePattern to cmsRoutes() and createCmsMiddleware().",
+					);
+				}
+
+				for (const pattern of Object.keys(INJECTED_ROUTES)) {
+					const origins = routes
+						.filter((route) => route.pattern === pattern)
+						.map((route) => route.origin);
+
+					if (origins.includes("project") && origins.includes("external")) {
+						logger.info(
+							`Project route "${pattern}" overrides the injected one. Pass it in cmsRoutes({ exclude }) to make that explicit.`,
+						);
+					}
+				}
+			},
+		},
+	};
+};
+
+export { cmsRoutes };

package/src/middleware/createCmsMiddleware.js

@@ -1,5 +1,7 @@
 import { withRequestFilter } from "./withRequestFilter.js";
 import { withCmsFetch } from "./withCmsFetch.js";
+import { CMS_ROUTE_PATTERN } from "../shared/routes.js";
+import { HttpError } from "../shared/errors.js";
 
 const defaultErrorHandler = (context, error, wrap) => {
 	const status = error?.status ?? 500;
@@ -11,7 +13,12 @@ const defaultErrorHandler = (context, error, wrap) => {
 /**
  * Composes the standard CMS middleware pipeline.
  *
+ * The CMS catch-all route renders CMS data and nothing else, so a request that
+ * reaches it without running the pipeline is answered 404 instead of rendering
+ * an empty page.
+ *
  * @param {object} [options]
+ * @param {string} [options.cmsRoutePattern] - route pattern of the CMS catch-all page
  * @param {(context: import("astro").APIContext) => boolean} [options.shouldSkip] - filter that decides if request bypasses the pipeline
  * @param {(context: import("astro").APIContext) => Promise<void>} [options.fetch] - CMS fetch step
  * @param {(context: import("astro").APIContext, handler: () => any) => Promise<Response>} [options.paraglide] - i18n wrapper (optional)
@@ -21,7 +28,8 @@ const defaultErrorHandler = (context, error, wrap) => {
  */
 const createCmsMiddleware = (options = {}) => {
 	const {
-		shouldSkip = withRequestFilter(),
+		cmsRoutePattern = CMS_ROUTE_PATTERN,
+		shouldSkip = withRequestFilter({ cmsRoutePattern }),
 		fetch = withCmsFetch(),
 		paraglide,
 		beforeFetch,
@@ -33,6 +41,10 @@ const createCmsMiddleware = (options = {}) => {
 
 	return async (context, next) => {
 		if (shouldSkip(context)) {
+			if (context.routePattern === cmsRoutePattern) {
+				return onError(context, new HttpError(404, "Not Found"), wrap);
+			}
+
 			return next();
 		}
 

package/src/middleware/withRequestFilter.js

@@ -1,33 +1,39 @@
+import { CMS_ROUTE_PATTERN } from "../shared/routes.js";
+
 /**
- * Default request filter — skips internal Astro routes, error routes
- * and asset paths (by file extension).
+ * Default request filter — the CMS pipeline runs for the catch-all route only.
+ *
+ * Every other route Astro matched is its own (a project page, an endpoint, an
+ * injected route) and must not be fed CMS data. Static files never get here:
+ * Astro drops them before route matching, and the server in front serves them.
+ *
+ * Requires `context.routePattern` (Astro 5 or newer).
  *
  * @param {object} [options]
+ * @param {string} [options.cmsRoutePattern] - route pattern of the CMS catch-all page
  * @param {string[]} [options.additionalExcludePaths] - extra path prefixes to skip
  * @param {(context: import("astro").APIContext) => boolean} [options.customFilter] - additional skip predicate
  */
-
 const withRequestFilter = (options = {}) => {
-	const { additionalExcludePaths = [], customFilter } = options;
+	const {
+		cmsRoutePattern = CMS_ROUTE_PATTERN,
+		additionalExcludePaths = [],
+		customFilter,
+	} = options;
 
 	return (context) => {
-		const { request, url } = context;
+		const { request, url, routePattern } = context;
 
-		const isAstroInternal = url.pathname.startsWith("/_astro");
-		const isErrorRoute = url.pathname.startsWith("/errors/");
-		const hasFileExtension = /\.[a-zA-Z0-9]+$/.test(url.pathname);
+		const isNonGet = request.method !== "GET";
+		const isOwnAstroRoute = routePattern !== cmsRoutePattern;
 		const isExcludedPath = additionalExcludePaths.some((p) =>
 			url.pathname.startsWith(p),
 		);
-		const isAstroApiCall = url.pathname.startsWith("/api/");
 
 		return (
-			request.method !== "GET" ||
-			isAstroInternal ||
-			isErrorRoute ||
-			hasFileExtension ||
+			isNonGet ||
+			isOwnAstroRoute ||
 			isExcludedPath ||
-			isAstroApiCall ||
 			customFilter?.(context) === true
 		);
 	};

package/src/routes/cmsProxy.js

@@ -0,0 +1,15 @@
+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),
+});

package/src/routes/llms.txt.js

@@ -0,0 +1,5 @@
+import { createLlmsTxtHandler } from "../handlers/llmsTxtHandler.js";
+
+export const prerender = false;
+
+export const GET = createLlmsTxtHandler();

package/src/routes/robots.txt.js

@@ -0,0 +1,5 @@
+import { createRobotsHandler } from "../handlers/robotsHandler.js";
+
+export const prerender = false;
+
+export const GET = createRobotsHandler();

package/src/routes/sitemap.xml.js

@@ -0,0 +1,5 @@
+import { createSitemapHandler } from "../handlers/sitemapHandler.js";
+
+export const prerender = false;
+
+export const GET = createSitemapHandler();

package/src/server.js

@@ -8,3 +8,4 @@ export { createSitemapHandler } from "./handlers/sitemapHandler.js";
 export { createRobotsHandler } from "./handlers/robotsHandler.js";
 export { createLlmsTxtHandler } from "./handlers/llmsTxtHandler.js";
 export { createCmsProxyHandler } from "./cms/proxyToCms.js";
+export { CMS_ROUTE_PATTERN } from "./shared/routes.js";

package/src/shared/routes.js

@@ -0,0 +1,7 @@
+/**
+ * The route pattern of the CMS catch-all page. The middleware pipeline and the
+ * injected routes both key off it, so it lives in one place.
+ */
+const CMS_ROUTE_PATTERN = "/[...path]";
+
+export { CMS_ROUTE_PATTERN };