# 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>`。

## 命令

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