feat(diagnostics): Phase 3a — structured ad:error events + Logger wiring

[LockeAG]

Summary

Phase 3a: make every ad failure programmatically observable. Stacked on
top of #3 (feat/gpt-modernization-phase-0-2) — rebase onto main
after #3 lands.

Five additions, all opt-in, none of which existed before:

1. ad:error CustomEvent on the host <dreams-ad-engine> element
   with typed payload: slotId, adUnit, phase, error, recoverable.
2. Activate the dormant Logger — was shipped but imported by
   nothing. Now wired across 9 call sites (8 in ad.component.ts, 1 in
   config.provider.ts).
3. Debug toggle, precedence high → low:
   1. DreamsAdConfig.init({ debug: true | false }) — explicit boolean wins
   2. ?dae-debug=1 URL param — parsed once at module load
   3. window.__dreamsDebug = true — runtime toggleable (auto mode only)
4. DreamsAdConfig.openConsole(slotId?) — wraps googletag.openConsole()
   with cmd queueing and a safe fallback for builds without the API.
5. Auto-bridge ad:error → window.dataLayer as dreams_ad_error.
   Mirrors the existing prebid_bid_won pattern; GTM consumers get
   errors with zero additional wiring.

Wrapped lifecycle phases

Previously-unprotected GPT calls now have granular try/catch:

Phase	Recoverable	Sites
config-resolution	—	reserved for future config-load failures
targeting-resolution	yes	DreamsTargetingService silent timeout, slot.setConfig({ targeting })
slot-define	no	defineSlot().addService(), outer catch-all
slot-display	no	googletag.display(), container-not-in-DOM guard
slot-refresh	no	both pubads().refresh([defineAdSlot]) sites
apstag-init	yes	apstag.init(), apstag.setDisplayBids()
prebid-init	yes	pbjs.que.push, pbjs.setTargetingForGPTAsync, pbjs.requestBids
out-of-page-define	no	interstitial + top/bottom anchor defineOutOfPageSlot()
size-mapping	yes	sizeMapping().addSize().build()

Files touched

• src/features/logging/logger.types.ts (new) — AdErrorPhase, AdErrorEventDetail
• src/features/logging/logger.ts — Logger.dispatchAdError(), __dreamsDebug runtime check
• src/features/logging/index.ts — export new types
• src/features/config/config.types.ts — debug?: boolean on AdConfigInit
• src/features/config/config.provider.ts — debug resolution, openConsole(), URL param parsing, console.warn → Logger.warn
• src/features/dreamsAdEngine/components/ad.component.ts — 8 console.* → Logger.*, 11 try/catch additions, reorder firstUpdated so divId exists before targeting resolution
• src/features/dreamsAdEngine/types/interfaces.ts — __dreamsDebug?: boolean on Window
• dist/, types/ — rebuilt

Build: ✓ pnpm build clean. Bundle 82.86 kB / 20.96 kB gzipped.

Consumer-facing event shape

interface AdErrorEventDetail {
  slotId: string;        // CONTAINER_ID (DOM id)
  adUnit: string;        // /<networkId>/<sitePrefix>-...
  phase: AdErrorPhase;   // one of the 9 above
  error: Error | string;
  recoverable: boolean;
}

window.dataLayer.push({
  event: "dreams_ad_error",
  phase, slotId, adUnit,
  error_message: String(error),
});

Out of scope (deliberate)

• Sentry / Datadog / external error tracking — library stays vendor-agnostic; consumers wire via ad:error.
• Retry logic — recoverable is informational; auto-retry is policy.
• Error rate-limiting — defer until reported as a problem.
• INP/LCP attribution — separate Phase 3b candidate.

Test plan

Combined cobertura360.mx staging verification (with #3) when MVP is ready:

• All original feat: GPT modernization (Phase 0 + 2) — lifecycle events, SRA, collapseDiv, CLS reserve #3 verification sections still pass (slots render, event order, SRA, CLS, empty-slot, SPA nav, APS+Prebid race)
• ad:error fires on injected failures — e.g. pass a malformed ad unit path
• window.dataLayer receives dreams_ad_error events
• DreamsAdConfig.openConsole() opens the GPT console overlay
• ?dae-debug=1 enables verbose logging in prod
• window.__dreamsDebug = true toggles logging at runtime
• Targeting timeout surfaces as ad:error (recoverable: true)