app-template/packages/adsense/AGENTS.md

AGENTS.md — @app/adsense

职责

Google AdSense 接入：幂等脚本加载 + React 广告位组件。与业务/框架解耦，可被 Astro island 或纯 React 使用。

结构

src/
  loader.ts         # loadAdSense / pushAdSense
  types.ts          # AdSensePushCommand + Window.adsbygoogle
  react/AdSlot.tsx  # <ins class="adsbygoogle"> 组件
  index.ts          # 核心导出
  react/index.ts    # React 入口（exports: "@app/adsense/react"）

导出

• @app/adsense：loadAdSense、pushAdSense、类型
• @app/adsense/react：AdSlot

行为要点

• loadAdSense(adClient)：仅浏览器生效；SSR no-op。同一 adClient 复用 Promise；页面已有脚本会识别复用；不支持同时加载多个发布商 ID。
• pushAdSense()：向 window.adsbygoogle 队列 push，渲染已挂载的 <ins>。
• AdSlot 属性用 adSlot / adClient（刻意避开 Astro 的 slot / client:* 保留字）。挂载后自动 load + push，按 adClient#adSlot 去重。

修改指南

• 保持加载幂等；失败时重置 scriptPromise 以便重试（见 loader.ts）。
• 不要在本包读 env 或写死 publisher ID——由调用方传入 adClient。
• SSR 安全：凡触碰 document / window 先判 typeof。
• 新广告格式优先扩展 AdSlot props（format / layout / layoutKey…），不要让调用方手写 <ins>。

命令

yarn workspace @app/adsense typecheck
yarn workspace @app/adsense lint
yarn workspace @app/adsense build