@astronox/core 0.3.1 → 0.4.0

package/README.md

@@ -63,7 +63,7 @@ component labels can extend `defaultCoreMessages` through
   claims, Firestore, and app-owned mappings.
 - [`R2 publication`](docs/integrations/r2-publication.md): full provider
   snapshots and build-time public projection.
-- [`AdSense`](docs/integrations/adsense.md): provider setup, consent, slots, and
-  fallback canvas.
+- [`AdSense`](docs/integrations/adsense.md): typed configuration, responsive
+  units, host policy, Privacy & Messaging, and deployment.
 - [`release workflow`](docs/release-workflow.md): local links, verification, and
   consumer pinning order.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/ads/adsense/AdsenseHead.astro

@@ -0,0 +1,55 @@
+---
+import type { AdsenseAdsConfig } from '../contracts';
+import {
+  renderAdsenseControlledMessagingScript,
+  renderAdsenseErrorProtectionScript,
+  toAdsenseClientId,
+} from './provider';
+
+type Props = {
+  config: AdsenseAdsConfig;
+  offerwallEligible: boolean;
+};
+
+const { config, offerwallEligible }: Props = Astro.props;
+const clientId = toAdsenseClientId(config.publisherId);
+const runtimeConfig = JSON.stringify({
+  allowedHosts: config.allowedHosts,
+  clientId,
+  messaging: {
+    adBlockingRecovery: config.messaging.adBlockingRecovery,
+    offerwall: config.messaging.offerwall,
+    offerwallEligible,
+  },
+  publisherId: config.publisherId,
+}).replaceAll('<', '\\u003c');
+const errorProtectionScript = config.messaging.errorProtectionCode
+  ? renderAdsenseErrorProtectionScript({
+      allowedHosts: config.allowedHosts,
+      code: config.messaging.errorProtectionCode,
+    })
+  : undefined;
+const controlledMessagingScript = renderAdsenseControlledMessagingScript(
+  config.messaging.offerwall && offerwallEligible,
+);
+---
+
+<meta name="google-adsense-account" content={clientId} />
+<script
+  is:inline
+  type="application/json"
+  data-astronox-adsense-config
+  set:html={runtimeConfig}
+/>
+<script is:inline set:html={controlledMessagingScript} />
+{
+  errorProtectionScript ? (
+    <script is:inline set:html={errorProtectionScript} />
+  ) : null
+}
+
+<script>
+  import { initAdsenseFromDocument } from './runtime';
+
+  initAdsenseFromDocument();
+</script>

package/src/ads/adsense/AdsenseUnit.astro

@@ -0,0 +1,45 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import AdSlot from '../../components/monetization/AdSlot/AdSlot.astro';
+import { toAdsenseClientId } from './provider';
+
+type Props = Omit<HTMLAttributes<'aside'>, 'aria-label'> & {
+  format: 'display' | 'multiplex';
+  label: string;
+  publisherId: string;
+  size?: 'compact' | 'standard' | 'tall';
+  slotId: string;
+};
+
+const {
+  format,
+  label,
+  publisherId,
+  size = 'standard',
+  slotId,
+  ...attrs
+}: Props = Astro.props;
+const unitAttributes =
+  format === 'multiplex'
+    ? { 'data-ad-format': 'autorelaxed' }
+    : {
+        'data-ad-format': 'auto',
+        'data-full-width-responsive': 'true',
+      };
+---
+
+<AdSlot
+  {...attrs}
+  data-adsense-format={format}
+  data-adsense-unit
+  label={label}
+  size={size}
+  state="loading"
+>
+  <ins
+    {...unitAttributes}
+    class="adsbygoogle"
+    style="display:block"
+    data-ad-client={toAdsenseClientId(publisherId)}
+    data-ad-slot={slotId}></ins>
+</AdSlot>

package/src/ads/adsense/index.ts

@@ -1 +1,3 @@
-export * from '../adsense';
+export { default as AdsenseHead } from './AdsenseHead.astro';
+export { default as AdsenseUnit } from './AdsenseUnit.astro';
+export * from './provider';

package/src/ads/adsense/provider.ts

@@ -0,0 +1,41 @@
+const adsenseSellerId = 'f08c47fec0942fa0';
+
+export function toAdsenseClientId(publisherId: string): string {
+  return `ca-${publisherId}`;
+}
+
+export function renderAdsenseAdsTxt(publisherId: string): string {
+  return `google.com, ${publisherId}, DIRECT, ${adsenseSellerId}\n`;
+}
+
+export function renderAdsenseErrorProtectionScript({
+  allowedHosts,
+  code,
+}: {
+  allowedHosts: readonly string[];
+  code: string;
+}): string {
+  const hosts = JSON.stringify(
+    allowedHosts.map((host) => host.toLowerCase()),
+  ).replaceAll('<', '\\u003c');
+
+  return `if (${hosts}.includes(window.location.hostname.toLowerCase())) {\n${code}\n}`;
+}
+
+export function renderAdsenseControlledMessagingScript(
+  offerwallAllowed: boolean,
+): string {
+  return `window.googlefc = window.googlefc || {};
+window.googlefc.controlledMessagingFunction = function (message) {
+  if (${String(offerwallAllowed)}) {
+    message.proceed(true);
+    return;
+  }
+  var offerwall = window.googlefc.MessageTypeEnum && window.googlefc.MessageTypeEnum.OFFERWALL;
+  if (typeof offerwall === 'number') {
+    message.proceed(false, [offerwall]);
+    return;
+  }
+  message.proceed(true);
+};`;
+}

package/src/ads/adsense/runtime.ts

@@ -0,0 +1,284 @@
+import { setAdSlotState } from '../slot';
+
+const adsenseScriptTimeoutMs = 12_000;
+const adsenseUnitTimeoutMs = 30_000;
+
+type ControlledMessage = {
+  proceed(allowed: boolean, messageTypes?: readonly number[]): void;
+};
+
+type GoogleFundingChoicesCallback =
+  (() => void) | { CONSENT_API_READY: () => void };
+
+type GoogleFundingChoices = {
+  callbackQueue?: {
+    push(callback: GoogleFundingChoicesCallback): number;
+  };
+  controlledMessagingFunction?: (message: ControlledMessage) => void;
+  MessageTypeEnum?: {
+    OFFERWALL: number;
+  };
+  showRevocationMessage?: () => void;
+};
+
+type AdsenseRuntimeConfig = {
+  allowedHosts: readonly string[];
+  clientId: string;
+  messaging: {
+    adBlockingRecovery: boolean;
+    offerwall: boolean;
+    offerwallEligible: boolean;
+  };
+  publisherId: string;
+};
+
+declare global {
+  interface Window {
+    adsbygoogle?: Record<string, unknown>[];
+    googlefc?: GoogleFundingChoices;
+  }
+}
+
+let adsenseScript: Promise<void> | undefined;
+
+export function initAdsenseFromDocument(): void {
+  const config = readRuntimeConfig();
+  if (!config || !isAllowedHost(config.allowedHosts)) {
+    setAllAdUnitsState('unavailable');
+    return;
+  }
+
+  protectAdAnnotations();
+  configureControlledMessaging(config);
+  initPrivacySettingsControls();
+  if (config.messaging.adBlockingRecovery) {
+    loadAdBlockingRecovery(config.publisherId);
+  }
+
+  void loadAdsenseScript(config.clientId)
+    .then(initAdUnits)
+    .catch(() => setAllAdUnitsState('blocked'));
+}
+
+function readRuntimeConfig(): AdsenseRuntimeConfig | undefined {
+  const element = document.querySelector<HTMLScriptElement>(
+    'script[data-astronox-adsense-config]',
+  );
+  if (!element?.textContent) return undefined;
+
+  try {
+    return JSON.parse(element.textContent) as AdsenseRuntimeConfig;
+  } catch {
+    return undefined;
+  }
+}
+
+function isAllowedHost(allowedHosts: readonly string[]): boolean {
+  const hostname = window.location.hostname.toLowerCase();
+  if (
+    hostname === 'localhost' ||
+    hostname.endsWith('.localhost') ||
+    hostname === '127.0.0.1' ||
+    hostname === '::1'
+  ) {
+    return false;
+  }
+  return allowedHosts.some((host) => host.toLowerCase() === hostname);
+}
+
+function protectAdAnnotations(): void {
+  const protect = (root: ParentNode): void => {
+    if (
+      root instanceof HTMLElement &&
+      root.dataset.adAnnotation === 'exclude'
+    ) {
+      root.classList.add('google-anno-skip');
+    }
+    for (const element of root.querySelectorAll<HTMLElement>(
+      '[data-ad-annotation="exclude"]',
+    )) {
+      element.classList.add('google-anno-skip');
+    }
+  };
+
+  protect(document);
+  new MutationObserver((records) => {
+    for (const record of records) {
+      for (const node of record.addedNodes) {
+        if (node instanceof HTMLElement) protect(node);
+      }
+    }
+  }).observe(document.documentElement, { childList: true, subtree: true });
+}
+
+function configureControlledMessaging(config: AdsenseRuntimeConfig): void {
+  const googlefc = (window.googlefc ??= {});
+  googlefc.controlledMessagingFunction = (message) => {
+    const allowOfferwall =
+      config.messaging.offerwall && config.messaging.offerwallEligible;
+    if (allowOfferwall) {
+      message.proceed(true);
+      return;
+    }
+
+    const offerwallType = window.googlefc?.MessageTypeEnum?.OFFERWALL;
+    if (typeof offerwallType === 'number') {
+      message.proceed(false, [offerwallType]);
+      return;
+    }
+
+    message.proceed(true);
+  };
+}
+
+function initPrivacySettingsControls(): void {
+  const googlefc = (window.googlefc ??= {});
+  googlefc.callbackQueue ??= [];
+  googlefc.callbackQueue.push({
+    CONSENT_API_READY: () => {
+      for (const control of document.querySelectorAll<HTMLButtonElement>(
+        '[data-ads-consent-settings]:not([data-ads-consent-initialized])',
+      )) {
+        control.dataset.adsConsentInitialized = 'true';
+        control.hidden = false;
+        control.addEventListener('click', () => {
+          const showRevocationMessage = window.googlefc?.showRevocationMessage;
+          if (showRevocationMessage) {
+            window.googlefc?.callbackQueue?.push(showRevocationMessage);
+          }
+        });
+      }
+    },
+  });
+}
+
+function loadAdBlockingRecovery(publisherId: string): void {
+  if (document.querySelector('script[data-astronox-ad-recovery]')) return;
+
+  const script = document.createElement('script');
+  script.async = true;
+  script.dataset.astronoxAdRecovery = '';
+  script.src = `https://fundingchoicesmessages.google.com/i/${encodeURIComponent(publisherId)}?ers=1`;
+  document.head.append(script);
+  signalFundingChoicesPresence();
+}
+
+function signalFundingChoicesPresence(): void {
+  if (document.querySelector('iframe[name="googlefcPresent"]')) return;
+  if (!document.body) {
+    window.setTimeout(signalFundingChoicesPresence, 0);
+    return;
+  }
+
+  const frame = document.createElement('iframe');
+  frame.name = 'googlefcPresent';
+  frame.hidden = true;
+  frame.style.display = 'none';
+  document.body.append(frame);
+}
+
+function loadAdsenseScript(clientId: string): Promise<void> {
+  if (adsenseScript) return adsenseScript;
+
+  const loading = new Promise<void>((resolve, reject) => {
+    const existing = document.querySelector<HTMLScriptElement>(
+      'script[data-astronox-adsense]',
+    );
+    if (existing?.dataset.loaded === 'true') {
+      resolve();
+      return;
+    }
+
+    const script = existing ?? document.createElement('script');
+    const timeout = window.setTimeout(() => {
+      reject(new Error('AdSense loading timed out'));
+    }, adsenseScriptTimeoutMs);
+    script.addEventListener(
+      'load',
+      () => {
+        window.clearTimeout(timeout);
+        script.dataset.loaded = 'true';
+        resolve();
+      },
+      { once: true },
+    );
+    script.addEventListener(
+      'error',
+      () => {
+        window.clearTimeout(timeout);
+        reject(new Error('AdSense failed to load'));
+      },
+      { once: true },
+    );
+
+    if (!existing) {
+      script.async = true;
+      script.crossOrigin = 'anonymous';
+      script.dataset.astronoxAdsense = '';
+      script.src = `https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${encodeURIComponent(clientId)}`;
+      document.head.append(script);
+    }
+  });
+  adsenseScript = loading;
+  void loading.catch(() => {
+    if (adsenseScript === loading) adsenseScript = undefined;
+  });
+
+  return loading;
+}
+
+function initAdUnits(): void {
+  for (const slot of document.querySelectorAll<HTMLElement>(
+    '[data-adsense-unit]:not([data-adsense-initialized])',
+  )) {
+    initAdUnit(slot);
+  }
+}
+
+function initAdUnit(slot: HTMLElement): void {
+  slot.dataset.adsenseInitialized = 'true';
+  setAdSlotState(slot, 'loading');
+  const advertisement = slot.querySelector<HTMLElement>('.adsbygoogle');
+  if (!advertisement) {
+    setAdSlotState(slot, 'unavailable');
+    return;
+  }
+
+  const timeout = window.setTimeout(() => {
+    setAdSlotState(slot, 'unavailable');
+  }, adsenseUnitTimeoutMs);
+  const sync = (): void => {
+    if (advertisement.dataset.adStatus === 'filled') {
+      window.clearTimeout(timeout);
+      observer.disconnect();
+      setAdSlotState(slot, 'filled');
+    } else if (advertisement.dataset.adStatus === 'unfilled') {
+      window.clearTimeout(timeout);
+      observer.disconnect();
+      setAdSlotState(slot, 'unavailable');
+    }
+  };
+  const observer = new MutationObserver(sync);
+  observer.observe(advertisement, {
+    attributes: true,
+    attributeFilter: ['data-ad-status'],
+  });
+
+  try {
+    window.adsbygoogle ??= [];
+    window.adsbygoogle.push({});
+    sync();
+  } catch {
+    window.clearTimeout(timeout);
+    observer.disconnect();
+    setAdSlotState(slot, 'unavailable');
+  }
+}
+
+function setAllAdUnitsState(state: 'blocked' | 'unavailable'): void {
+  for (const slot of document.querySelectorAll<HTMLElement>(
+    '[data-adsense-unit]',
+  )) {
+    setAdSlotState(slot, state);
+  }
+}

package/src/ads/contracts.ts

@@ -1,11 +1,73 @@
 export type AdSlotState =
   'idle' | 'loading' | 'filled' | 'blocked' | 'unavailable';
 
-export type AdConsentProvider = {
-  canLoadAds(): boolean | Promise<boolean>;
+export type DisabledAdsConfig = {
+  enabled: false;
 };
 
-export interface AdProvider {
-  load(): Promise<void>;
-  request(slot: HTMLElement): Promise<void>;
+export type AdsenseAdsConfig = {
+  enabled: true;
+  provider: 'adsense';
+  allowedHosts: readonly string[];
+  publisherId: string;
+  units: {
+    pageEnd: string;
+  };
+  messaging: {
+    adBlockingRecovery: boolean;
+    offerwall: boolean;
+    errorProtectionCode?: string;
+  };
+};
+
+export type AdsConfig = DisabledAdsConfig | AdsenseAdsConfig;
+
+export const adAnnotationExclusionAttributes = {
+  'data-ad-annotation': 'exclude',
+} as const;
+
+export function defineAdsConfig<const TConfig extends AdsConfig>(
+  config: TConfig,
+): TConfig {
+  if (!config.enabled) return config;
+
+  if (config.allowedHosts.length === 0) {
+    throw new Error('Ad configuration requires at least one allowed hostname');
+  }
+  for (const host of config.allowedHosts) {
+    if (!isValidHostname(host)) {
+      throw new Error(`Invalid advertising hostname: ${host}`);
+    }
+  }
+  if (!/^pub-\d+$/.test(config.publisherId)) {
+    throw new Error('Invalid AdSense publisher id');
+  }
+  if (!/^\d+$/.test(config.units.pageEnd)) {
+    throw new Error('Invalid AdSense page-end slot id');
+  }
+  if (/<\/script/i.test(config.messaging.errorProtectionCode ?? '')) {
+    throw new Error(
+      'AdSense error protection must contain the script body only',
+    );
+  }
+
+  return config;
+}
+
+function isValidHostname(host: string): boolean {
+  if (!host || host !== host.trim() || host.includes('/')) return false;
+  if (
+    host.toLowerCase() === 'localhost' ||
+    host.toLowerCase().endsWith('.localhost') ||
+    host === '127.0.0.1' ||
+    host === '::1'
+  ) {
+    return false;
+  }
+
+  try {
+    return new URL(`https://${host}`).hostname === host.toLowerCase();
+  } catch {
+    return false;
+  }
 }

package/src/components/monetization/AdSlot/AdSlot.astro

@@ -27,7 +27,4 @@ const {
   aria-busy={state === 'loading' ? 'true' : 'false'}
 >
   <div class="ad-slot__content"><slot /></div>
-  <div class="ad-slot__fallback">
-    <slot name="fallback"><div class="ad-slot__fallback-canvas"></div></slot>
-  </div>
 </aside>

package/src/components/monetization/AdSlot/AdSlot.css

@@ -16,38 +16,15 @@
   --ad-slot-min-block-size: 15rem;
 }
 
-.ad-slot__content,
-.ad-slot__fallback {
-  grid-area: 1 / 1;
+.ad-slot__content {
   inline-size: 100%;
 }
 
-.ad-slot__fallback {
-  display: none;
-  block-size: 100%;
+.ad-slot[data-ad-state='filled'] {
+  min-block-size: 0;
 }
 
-.ad-slot__fallback-canvas {
-  block-size: 100%;
-  min-block-size: var(--ad-slot-min-block-size);
-  background:
-    linear-gradient(
-      135deg,
-      transparent 0 46%,
-      color-mix(in srgb, var(--nox-theme-border-base) 55%, transparent) 46% 54%,
-      transparent 54% 100%
-    ),
-    var(--nox-surface-muted);
-  border: 1px solid var(--nox-theme-border-base);
-  inline-size: 100%;
-}
-
-.ad-slot[data-ad-state='blocked'] .ad-slot__content,
-.ad-slot[data-ad-state='unavailable'] .ad-slot__content {
+.ad-slot[data-ad-state='blocked'],
+.ad-slot[data-ad-state='unavailable'] {
   display: none;
 }
-
-.ad-slot[data-ad-state='blocked'] .ad-slot__fallback,
-.ad-slot[data-ad-state='unavailable'] .ad-slot__fallback {
-  display: block;
-}

package/src/components/navigation/Footer/Footer.astro

@@ -46,6 +46,7 @@ const resolveRel = (target: FooterItem['target'], rel?: FooterItem['rel']) =>
           {items.map(
             (
               {
+                button,
                 href,
                 label: itemLabel,
                 marker,
@@ -83,6 +84,13 @@ const resolveRel = (target: FooterItem['target'], rel?: FooterItem['rel']) =>
                       ) : null}
                       <span>{itemLabel}</span>
                     </a>
+                  ) : button ? (
+                    <button {...button} type="button" data-tone={itemTone}>
+                      {marker === 'arrow' ? (
+                        <ArrowRightIcon class="site-footer__marker" />
+                      ) : null}
+                      <span>{itemLabel}</span>
+                    </button>
                   ) : (
                     <span class="site-footer__label" data-tone={itemTone}>
                       {marker === 'arrow' ? (

package/src/components/navigation/Footer/Footer.css

@@ -78,11 +78,12 @@
   flex: 0 0 auto;
 }
 
-.site-footer__prefix + :is(a, .site-footer__label) {
+.site-footer__prefix + :is(a, button, .site-footer__label) {
   margin-inline-start: var(--nox-space-1);
 }
 
 .site-footer a,
+.site-footer button,
 .site-footer__label {
   display: inline-flex;
   min-width: 0;
@@ -98,35 +99,48 @@
   color: var(--nox-text-muted);
 }
 
-.site-footer a {
+.site-footer :is(a, button) {
   color: var(--nox-content-link-color);
   font-weight: var(--nox-content-link-emphasis-font-weight);
   text-decoration: none;
 }
 
+.site-footer button {
+  padding: 0;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  font: inherit;
+}
+
 .site-footer a[data-tone],
+.site-footer button[data-tone],
 .site-footer__label[data-tone] {
   color: var(--nox-tone-color);
 }
 
-.site-footer a:focus-visible {
+.site-footer :is(a, button):focus-visible {
   border-radius: var(--nox-radius-sm);
   outline: var(--nox-focus-ring-width) solid var(--nox-tone-focus-ring);
   outline-offset: var(--nox-focus-ring-offset);
   color: var(--nox-content-link-color);
 }
 
-.site-footer a[data-tone]:focus-visible {
+.site-footer :is(a, button)[data-tone]:focus-visible {
   color: var(--nox-tone-color);
 }
 
+.site-footer button[hidden] {
+  display: none;
+}
+
 @media (hover: hover) and (pointer: fine) {
-  .site-footer a:hover {
+  .site-footer :is(a, button):hover {
     color: var(--nox-content-link-color);
     text-decoration-line: underline;
   }
 
-  .site-footer a[data-tone]:hover {
+  .site-footer :is(a, button)[data-tone]:hover {
     color: var(--nox-tone-color);
   }
 }

package/src/components/navigation/Footer/contracts.ts

@@ -2,6 +2,7 @@ import type { HTMLAttributes } from 'astro/types';
 import type { Tone } from '../../../theme/contracts';
 
 export type FooterItem = {
+  button?: Omit<HTMLAttributes<'button'>, 'type'>;
   href?: HTMLAttributes<'a'>['href'];
   label: string;
   marker?: 'arrow';

package/src/composition/SurfaceGroup/SurfaceGroup.astro

@@ -2,8 +2,9 @@
 import type { HTMLAttributes } from 'astro/types';
 import type { Tone } from '../../theme/contracts';
 
-type SurfaceGroupElement = 'div' | 'section' | 'nav';
+type SurfaceGroupElement = 'article' | 'div' | 'section' | 'nav';
 type SurfaceGroupAttributes = HTMLAttributes<'div'> &
+  HTMLAttributes<'article'> &
   HTMLAttributes<'section'> &
   HTMLAttributes<'nav'>;
 

package/src/config/environment.ts

@@ -14,14 +14,64 @@ export function readOptionalEnvironmentValue(
   return resolved || undefined;
 }
 
+export function readRequiredEnvironmentBoolean(
+  name: string,
+  value: string | undefined,
+): boolean {
+  const resolved = readRequiredEnvironmentValue(name, value);
+  if (resolved === 'true') return true;
+  if (resolved === 'false') return false;
+  throw new Error(`Invalid environment boolean: ${name}`);
+}
+
+export function readEnvironmentStringArray(
+  name: string,
+  value: string | undefined,
+): readonly string[] {
+  const resolved = readRequiredEnvironmentValue(name, value);
+  let entries: unknown[];
+
+  if (resolved.startsWith('[')) {
+    try {
+      const parsed: unknown = JSON.parse(resolved);
+      if (!Array.isArray(parsed)) throw new Error();
+      entries = parsed;
+    } catch {
+      throw new Error(`Invalid environment string array: ${name}`);
+    }
+  } else {
+    entries = [resolved];
+  }
+
+  if (
+    entries.length === 0 ||
+    entries.some((entry) => typeof entry !== 'string' || !entry.trim())
+  ) {
+    throw new Error(`Invalid environment string array: ${name}`);
+  }
+
+  return [...new Set(entries.map((entry) => (entry as string).trim()))];
+}
+
 export function readRequiredEnvironmentUrl(
   name: string,
   value: string | undefined,
 ): string {
   const resolved = readRequiredEnvironmentValue(name, value);
+  return parseEnvironmentUrl(name, resolved);
+}
+
+export function readOptionalEnvironmentUrl(
+  name: string,
+  value: string | undefined,
+): string | undefined {
+  const resolved = readOptionalEnvironmentValue(value);
+  return resolved ? parseEnvironmentUrl(name, resolved) : undefined;
+}
 
+function parseEnvironmentUrl(name: string, value: string): string {
   try {
-    const url = new URL(resolved);
+    const url = new URL(value);
     if (url.protocol !== 'http:' && url.protocol !== 'https:')
       throw new Error();
     return url.toString();
@@ -35,9 +85,23 @@ export function readEnvironmentRecord(
   value: string | undefined,
 ): Readonly<Record<string, string>> {
   const resolved = readRequiredEnvironmentValue(name, value);
+  return parseEnvironmentRecord(name, resolved);
+}
 
+export function readOptionalEnvironmentRecord(
+  name: string,
+  value: string | undefined,
+): Readonly<Record<string, string>> | undefined {
+  const resolved = readOptionalEnvironmentValue(value);
+  return resolved ? parseEnvironmentRecord(name, resolved) : undefined;
+}
+
+function parseEnvironmentRecord(
+  name: string,
+  value: string,
+): Readonly<Record<string, string>> {
   try {
-    const parsed: unknown = JSON.parse(resolved);
+    const parsed: unknown = JSON.parse(value);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
       throw new Error();
     }

package/src/layouts/BaseLayout.astro

@@ -6,6 +6,7 @@ import type { PageMeta } from '../config/pageMeta';
 import type { SiteConfig } from '../config/siteConfig';
 import type { JsonLdNode } from '../seo/structuredData';
 import type { Tone } from '../theme/contracts';
+import { adAnnotationExclusionAttributes } from '../ads/contracts';
 import PageSurface from './PageSurface.astro';
 import Breadcrumbs from '../components/navigation/Breadcrumbs/Breadcrumbs.astro';
 import ScrollToTop from '../components/actions/ScrollToTop/ScrollToTop.astro';
@@ -15,6 +16,7 @@ import { defaultThemeStorageKey } from '../theme/storage';
 type Props = HTMLAttributes<'html'> & {
   meta: PageMeta;
   site: SiteConfig;
+  pageSurfaceAttributes?: HTMLAttributes<'div'>;
   currentPath?: string;
   breadcrumbs?: readonly BreadcrumbItem[];
   breadcrumbLabel: string;
@@ -32,6 +34,7 @@ const {
   currentPath = Astro.url.pathname,
   'data-tone': dataTone,
   meta,
+  pageSurfaceAttributes,
   scrollToTopLabel,
   site,
   structuredData,
@@ -67,6 +70,7 @@ const resolvedTone = tone ?? dataTone;
           {
             breadcrumbs?.length ? (
               <Breadcrumbs
+                {...adAnnotationExclusionAttributes}
                 items={breadcrumbs}
                 label={breadcrumbLabel}
                 tone={breadcrumbTone}
@@ -74,8 +78,9 @@ const resolvedTone = tone ?? dataTone;
             ) : null
           }
 
-          <PageSurface>
+          <PageSurface {...pageSurfaceAttributes}>
             <slot />
+            <slot name="page-end" />
           </PageSurface>
         </div>
       </main>

package/src/ads/adsense.ts

@@ -1,112 +0,0 @@
-import type { AdConsentProvider, AdProvider } from './contracts';
-import { setAdSlotState } from './slot';
-
-declare global {
-  interface Window {
-    adsbygoogle?: Record<string, unknown>[];
-  }
-}
-
-export function createAdsenseProvider({
-  clientId,
-  consent,
-  loadTimeoutMs,
-}: {
-  clientId: string;
-  consent: AdConsentProvider;
-  loadTimeoutMs: number;
-}): AdProvider {
-  let loading: Promise<void> | null = null;
-
-  const load = async (): Promise<void> => {
-    if (!(await consent.canLoadAds())) {
-      throw new Error('Advertising consent was not granted');
-    }
-    loading ??= loadAdsenseScript(clientId, loadTimeoutMs).catch((reason) => {
-      loading = null;
-      throw reason;
-    });
-    return loading;
-  };
-
-  return {
-    load,
-    async request(slot) {
-      setAdSlotState(slot, 'loading');
-      try {
-        await load();
-        window.adsbygoogle ??= [];
-        window.adsbygoogle.push({});
-        observeAdsenseSlot(slot);
-      } catch (reason) {
-        setAdSlotState(slot, 'blocked');
-        throw reason;
-      }
-    },
-  };
-}
-
-function loadAdsenseScript(
-  clientId: string,
-  loadTimeoutMs: number,
-): Promise<void> {
-  const existing = document.querySelector<HTMLScriptElement>(
-    'script[data-astronox-adsense]',
-  );
-  if (existing?.dataset.loaded === 'true') return Promise.resolve();
-
-  return new Promise((resolve, reject) => {
-    const script = existing ?? document.createElement('script');
-    script.async = true;
-    script.crossOrigin = 'anonymous';
-    script.dataset.astronoxAdsense = '';
-    script.src = `https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${encodeURIComponent(clientId)}`;
-    const timeout = window.setTimeout(
-      () => reject(new Error('AdSense loading timed out')),
-      loadTimeoutMs,
-    );
-    script.addEventListener(
-      'load',
-      () => {
-        window.clearTimeout(timeout);
-        script.dataset.loaded = 'true';
-        resolve();
-      },
-      { once: true },
-    );
-    script.addEventListener(
-      'error',
-      () => {
-        window.clearTimeout(timeout);
-        reject(new Error('AdSense failed to load'));
-      },
-      { once: true },
-    );
-    if (!existing) document.head.append(script);
-  });
-}
-
-function observeAdsenseSlot(slot: HTMLElement): void {
-  const advertisement = slot.querySelector<HTMLElement>('.adsbygoogle');
-  if (!advertisement) {
-    setAdSlotState(slot, 'unavailable');
-    return;
-  }
-
-  const sync = (): void => {
-    const status = advertisement.dataset.adStatus;
-    if (status === 'filled') setAdSlotState(slot, 'filled');
-    if (status === 'unfilled') setAdSlotState(slot, 'unavailable');
-  };
-  sync();
-  if (advertisement.dataset.adStatus) return;
-
-  const observer = new MutationObserver(() => {
-    sync();
-    if (advertisement.dataset.adStatus) observer.disconnect();
-  });
-  observer.observe(advertisement, {
-    attributeFilter: ['data-ad-status'],
-    attributes: true,
-  });
-}