@shopbb/helium 0.7.7 → 0.9.0

package/dist/page-schema/types.js

@@ -0,0 +1,129 @@
+/**
+ * Page Schema — 装修页面的结构化数据模型
+ *
+ * 一个 Page 是若干 Section 的有序数组。每个 Section 是 (type, data) 的结构化值，
+ * 不是任意 React 代码。这样 agent / 编辑器 / 渲染器都能精准操作。
+ *
+ * 设计原则：
+ *   1. 强 schema：每个 type 的 data 字段固定，agent 不能"乱发挥"
+ *   2. stable id：每个 section 有唯一 id，编辑器选中、agent 引用都靠它
+ *   3. 可演进：新加 section type 只需扩 SectionType 联合 + 实现对应 React 组件
+ *   4. 反规范化：data 是平铺字段而不是嵌套结构，方便 agent 修改单个属性
+ */
+// ============================================================
+// Helper：生成 section ID
+// ============================================================
+export function newSectionId(type) {
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `sec_${type.replace('-', '_')}_${rand}`;
+}
+// ============================================================
+// 默认 data —— 商家新增某 type 的 section 时用作初始值
+// ============================================================
+export const DEFAULT_DATA = {
+    hero: {
+        headline: '欢迎来到我们的店铺',
+        subheadline: '精选商品 全场包邮',
+        height: 'medium',
+        text_align: 'center',
+        background_color: '#0f172a',
+        text_color: '#ffffff',
+        cta_label: '立刻购买',
+        cta_link: '/products',
+    },
+    'product-grid': {
+        title: '精选商品',
+        selection_mode: 'newest',
+        limit: 6,
+        columns: 3,
+    },
+    banner: {
+        text: '满 200 减 20，限时优惠',
+        background_color: '#f97316',
+        text_color: '#ffffff',
+    },
+    'rich-text': {
+        body: '在这里写一段品牌故事或说明文字。',
+        format: 'markdown',
+        max_width: 'normal',
+    },
+    image: {
+        url: 'https://placehold.co/1200x400',
+        alt: '广告图',
+        width: 'full',
+    },
+    spacer: {
+        height: 40,
+    },
+};
+/** 创建一个新 section（带默认 data） */
+export function createSection(type) {
+    return {
+        id: newSectionId(type),
+        type,
+        data: { ...DEFAULT_DATA[type] },
+        visible: true,
+    };
+}
+/** 创建一个空白 page */
+export function createEmptyPage(slug) {
+    return {
+        slug,
+        sections: [],
+        schema_version: 1,
+    };
+}
+// ============================================================
+// 校验
+// ============================================================
+const REQUIRED_FIELDS = {
+    hero: ['headline'],
+    'product-grid': ['selection_mode'],
+    banner: ['text'],
+    'rich-text': ['body'],
+    image: ['url'],
+    spacer: ['height'],
+};
+/** 校验一个 section 数据完整性。返回错误列表，空数组表示合法 */
+export function validateSection(section) {
+    const errs = [];
+    if (!section.id)
+        errs.push('id_required');
+    if (!section.type)
+        errs.push('type_required');
+    const required = REQUIRED_FIELDS[section.type];
+    if (!required) {
+        errs.push(`unknown_section_type:${section.type}`);
+        return errs;
+    }
+    const data = section.data;
+    for (const f of required) {
+        if (data[f] == null || data[f] === '') {
+            errs.push(`missing_field:${section.type}.${f}`);
+        }
+    }
+    return errs;
+}
+/** 校验整个 page */
+export function validatePage(page) {
+    const errs = [];
+    if (!page.slug)
+        errs.push('slug_required');
+    if (page.schema_version !== 1)
+        errs.push(`unknown_schema_version:${page.schema_version}`);
+    if (!Array.isArray(page.sections)) {
+        errs.push('sections_must_be_array');
+        return errs;
+    }
+    const seenIds = new Set();
+    for (let i = 0; i < page.sections.length; i++) {
+        const s = page.sections[i];
+        if (seenIds.has(s.id))
+            errs.push(`duplicate_section_id:${s.id}`);
+        seenIds.add(s.id);
+        const secErrs = validateSection(s);
+        errs.push(...secErrs.map((e) => `section[${i}]:${e}`));
+    }
+    return errs;
+}
+//# sourceMappingURL=types.js.map

package/dist/page-schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/page-schema/types.ts"],"names":[],"mappings":"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"}

package/dist/react.d.ts

@@ -95,4 +95,11 @@ export interface ReactRendererOptions {
     onError?: (err: unknown, request: Request) => Response | Promise<Response>;
 }
 export declare function createReactRenderer(opts: ReactRendererOptions): (request: Request, env: any, executionContext: ExecutionContext) => Promise<Response>;
+/**
+ * 把 head + react stream + tail 拼成一个 ReadableStream<Uint8Array>
+ */
+export { PageRenderer, HeroSection, ProductGridSection, BannerSection, RichTextSection, ImageSection, SpacerSection, createSection, createEmptyPage, validateSection, validatePage, DEFAULT_DATA, newSectionId, } from './page-schema';
+export type { Page, PageGlobalStyle, AnySection, SectionType, HeroData, ProductGridData, BannerData, RichTextData, ImageData, SpacerData, PageRendererProps, } from './page-schema';
+export { TrackingProvider, useTracking, AnalyticsQueue, } from './analytics';
+export type { TrackingProviderProps, AnalyticsEvent, AnalyticsConfig, EventType as AnalyticsEventType, TrackFn, PageViewProps, ProductViewProps, AddToCartProps, CheckoutStartProps, } from './analytics';
 //# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7C,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,6EAMA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAQhD;AAMD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE;QACX,GAAG,EAAE,aAAa,CAAC;QACnB,GAAG,EAAE,GAAG,CAAC;QACT,OAAO,EAAE,OAAO,CAAC;KAClB,KAAK,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,IAE1D,SAAS,OAAO,EAChB,KAAK,GAAG,EACR,kBAAkB,gBAAgB,KACjC,OAAO,CAAC,QAAQ,CAAC,CAkHrB"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ7C,wBAAgB,qBAAqB,CAAC,EACpC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,6EAMA;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAQhD;AAMD,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE;QACX,GAAG,EAAE,aAAa,CAAC;QACnB,GAAG,EAAE,GAAG,CAAC;QACT,OAAO,EAAE,OAAO,CAAC;KAClB,KAAK,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAEvD;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF;;OAEG;IACH,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5E;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,IAE1D,SAAS,OAAO,EAChB,KAAK,GAAG,EACR,kBAAkB,gBAAgB,KACjC,OAAO,CAAC,QAAQ,CAAC,CAkHrB;AAYD;;GAEG;AAKH,OAAO,EACL,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,IAAI,EACJ,eAAe,EACf,UAAU,EACV,WAAW,EACX,QAAQ,EACR,eAAe,EACf,UAAU,EACV,YAAY,EACZ,SAAS,EACT,UAAU,EACV,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAWvB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,SAAS,IAAI,kBAAkB,EAC/B,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,kBAAkB,GACnB,MAAM,aAAa,CAAC"}

package/dist/react.js

@@ -148,6 +148,21 @@ function escapeHtml(s) {
 /**
  * 把 head + react stream + tail 拼成一个 ReadableStream<Uint8Array>
  */
+// ============================================================
+// Page Schema re-export
+// ============================================================
+// 结构化页面渲染。Admin 编辑器与 storefront 共用同一份组件。
+export { PageRenderer, HeroSection, ProductGridSection, BannerSection, RichTextSection, ImageSection, SpacerSection, createSection, createEmptyPage, validateSection, validatePage, DEFAULT_DATA, newSectionId, } from './page-schema';
+// ============================================================
+// Tracking SDK re-export
+// ============================================================
+// 把 5 个核心事件（page_view / product_view / add_to_cart / checkout_start / checkout_paid）
+// 批量发到 platform-api 的 /api/events。
+//
+// 与 components/AnalyticsProvider 解耦：
+//   - AnalyticsProvider 是商家用的事件总线（自定义 reporter）
+//   - TrackingProvider 是平台的标准埋点（发到 platform-api）
+export { TrackingProvider, useTracking, AnalyticsQueue, } from './analytics';
 function composeStream(head, body, tail) {
     const encoder = new TextEncoder();
     return new ReadableStream({

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopbb/helium",
-  "version": "0.7.7",
+  "version": "0.9.0",
   "description": "shopbb storefront framework — components, React SSR, GraphQL client, cart handler, cache for Cloudflare Workers",
   "license": "MIT",
   "type": "module",

package/src/analytics/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @shopbb/helium/analytics — 埋点 SDK 公开 API
+ *
+ * 浏览器侧用法：
+ *   - <TrackingProvider>：包在 root，初始化 session、起 flush 定时器、自动 page_view
+ *   - useTracking()：在组件内拿到 track() 函数
+ *
+ * 服务端不要用本模块——服务端事件（checkout_paid）由 platform-api 直接 INSERT。
+ *
+ * 注意：本模块与 components/AnalyticsProvider 是两个独立产品：
+ *   - AnalyticsProvider（components）：客户端事件总线，挂 GA / 自定义 reporter
+ *   - TrackingProvider（本模块）：把 5 个核心事件批量发到 /api/events，给 agent 用
+ */
+
+export { TrackingProvider, useTracking } from './react';
+export type { TrackingProviderProps } from './react';
+export { AnalyticsQueue } from './queue';
+export type {
+  AnalyticsEvent,
+  AnalyticsConfig,
+  EventType,
+  PageViewProps,
+  ProductViewProps,
+  AddToCartProps,
+  CheckoutStartProps,
+  TrackFn,
+} from './types';

package/src/analytics/queue.ts

@@ -0,0 +1,224 @@
+/**
+ * AnalyticsQueue — 浏览器侧事件缓冲队列
+ *
+ * 职责：
+ *   1. 把 track() 调用收集到内存队列
+ *   2. 定时（3s）或满批（20）触发 flush
+ *   3. flush 调 POST /api/events，失败重试 1 次
+ *   4. beforeunload 时用 navigator.sendBeacon 兜底刷出
+ *
+ * 注意：这是浏览器侧逻辑。SSR 阶段调 track() 会被丢弃（typeof window === 'undefined' 检查）。
+ */
+
+import type { AnalyticsConfig, AnalyticsEvent, QueuedEvent } from './types';
+
+const SESSION_COOKIE = 'sbb_sid';
+const SESSION_TTL_DAYS = 365;
+
+/**
+ * 读 sbb_sid cookie，没有则生成一个新的并 set。
+ * 仅浏览器环境调用。
+ */
+function getOrCreateSessionId(): string {
+  if (typeof document === 'undefined') return '';
+
+  const match = document.cookie.match(/(?:^|;\s*)sbb_sid=([^;]+)/);
+  if (match) return match[1];
+
+  // 生成 UUID（不依赖 crypto.randomUUID 以兼容老浏览器）
+  const sid = crypto?.randomUUID?.() ?? generateFallbackUuid();
+
+  const maxAge = SESSION_TTL_DAYS * 24 * 60 * 60;
+  document.cookie = `${SESSION_COOKIE}=${sid}; max-age=${maxAge}; path=/; samesite=lax`;
+  return sid;
+}
+
+function generateFallbackUuid(): string {
+  // RFC4122 v4 简化版
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export class AnalyticsQueue {
+  private readonly config: Required<Omit<AnalyticsConfig, 'buyerId' | 'debug'>> & {
+    buyerId: string | null;
+    debug: boolean;
+  };
+  private queue: QueuedEvent[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private sessionId = '';
+  private flushing = false;
+
+  constructor(config: AnalyticsConfig) {
+    this.config = {
+      apiBase: config.apiBase.replace(/\/+$/, ''),
+      publicAccessToken: config.publicAccessToken,
+      buyerId: config.buyerId ?? null,
+      debug: !!config.debug,
+      flushIntervalMs: config.flushIntervalMs ?? 3000,
+      flushBatchSize: config.flushBatchSize ?? 20,
+    };
+  }
+
+  start(): void {
+    if (typeof window === 'undefined') return;
+    this.sessionId = getOrCreateSessionId();
+
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.config.flushIntervalMs);
+
+    // 页面卸载兜底
+    window.addEventListener('pagehide', () => this.flushBeacon());
+    window.addEventListener('beforeunload', () => this.flushBeacon());
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') {
+          this.flushBeacon();
+        }
+      });
+    }
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  setBuyerId(id: string | null): void {
+    this.config.buyerId = id;
+  }
+
+  track(event: AnalyticsEvent): void {
+    if (typeof window === 'undefined') {
+      this.log('skip-ssr', event.type);
+      return;
+    }
+
+    if (!this.sessionId) {
+      this.sessionId = getOrCreateSessionId();
+    }
+
+    const queued: QueuedEvent = {
+      type: event.type,
+      occurredAt: event.occurredAt ?? Math.floor(Date.now() / 1000),
+      path:
+        event.path !== undefined
+          ? event.path
+          : typeof location !== 'undefined'
+            ? location.pathname + location.search
+            : null,
+      referrer:
+        event.referrer !== undefined
+          ? event.referrer
+          : typeof document !== 'undefined'
+            ? document.referrer || null
+            : null,
+      props: event.props ?? {},
+    };
+
+    this.queue.push(queued);
+    this.log('queued', queued.type, this.queue.length);
+
+    if (this.queue.length >= this.config.flushBatchSize) {
+      void this.flush();
+    }
+  }
+
+  /** 主动 flush。返回是否实际发送了请求 */
+  async flush(): Promise<boolean> {
+    if (this.flushing) return false;
+    if (this.queue.length === 0) return false;
+    if (!this.config.publicAccessToken) {
+      this.log('skip-no-token');
+      return false;
+    }
+
+    this.flushing = true;
+    const batch = this.queue.splice(0, this.config.flushBatchSize);
+    const body = JSON.stringify({
+      events: batch.map((e) => ({
+        type: e.type,
+        occurredAt: e.occurredAt,
+        path: e.path ?? undefined,
+        referrer: e.referrer ?? undefined,
+        props: e.props,
+      })),
+    });
+
+    try {
+      const res = await fetch(`${this.config.apiBase}/api/events`, {
+        method: 'POST',
+        headers: this.headers(),
+        body,
+        keepalive: true,
+      });
+      if (!res.ok) {
+        this.log('flush-failed-status', res.status);
+        // 失败不重试入队（避免堆积），demo 阶段简化
+        return false;
+      }
+      this.log('flushed', batch.length);
+      return true;
+    } catch (err) {
+      this.log('flush-error', err);
+      return false;
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /** 用 sendBeacon 兜底，页面卸载场景 */
+  private flushBeacon(): void {
+    if (this.queue.length === 0) return;
+    if (typeof navigator === 'undefined' || !navigator.sendBeacon) return;
+    if (!this.config.publicAccessToken) return;
+
+    const batch = this.queue.splice(0, this.config.flushBatchSize);
+    const body = JSON.stringify({
+      events: batch.map((e) => ({
+        type: e.type,
+        occurredAt: e.occurredAt,
+        path: e.path ?? undefined,
+        referrer: e.referrer ?? undefined,
+        props: e.props,
+      })),
+      // sendBeacon 无法设 header，所以把 token / session 塞进 body 作为兜底
+      // platform-api handler 优先认 header；body 字段用于 beacon 场景
+      _auth: {
+        token: this.config.publicAccessToken,
+        sessionId: this.sessionId,
+        buyerId: this.config.buyerId,
+      },
+    });
+
+    const blob = new Blob([body], { type: 'application/json' });
+    const ok = navigator.sendBeacon(`${this.config.apiBase}/api/events?beacon=1`, blob);
+    this.log('beacon', ok, batch.length);
+  }
+
+  private headers(): HeadersInit {
+    const h: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-Storefront-Access-Token': this.config.publicAccessToken,
+      'X-Session-Id': this.sessionId,
+    };
+    if (this.config.buyerId) {
+      h['X-Buyer-Id'] = this.config.buyerId;
+    }
+    return h;
+  }
+
+  private log(...args: unknown[]): void {
+    if (this.config.debug) {
+      // eslint-disable-next-line no-console
+      console.log('[helium-analytics]', ...args);
+    }
+  }
+}

package/src/analytics/react.tsx

@@ -0,0 +1,146 @@
+/**
+ * TrackingProvider + useTracking — React 绑定（后端事件埋点）
+ *
+ * 与 components/AnalyticsProvider 不同：
+ *   - AnalyticsProvider（旧）：客户端事件总线，商家挂 GA / Plausible 等 reporter
+ *   - TrackingProvider（新）：把 5 个核心事件发到 platform-api /api/events
+ *
+ * 用法：
+ *   <TrackingProvider
+ *     apiBase={store.apiBase}
+ *     publicAccessToken={store.publicAccessToken}
+ *     buyerId={buyer?.id}
+ *     debug
+ *   >
+ *     <App />
+ *   </TrackingProvider>
+ *
+ *   const { track } = useTracking();
+ *   track({ type: 'add_to_cart', props: { productId, quantity: 1 } });
+ *
+ * 自动事件：
+ *   - 首次挂载发一次 page_view
+ *   - 监听 history pushState/replaceState/popstate，每次 URL 变化补发 page_view
+ */
+
+import * as React from 'react';
+import { AnalyticsQueue } from './queue';
+import type { AnalyticsEvent, AnalyticsConfig, TrackFn } from './types';
+
+interface ContextValue {
+  track: TrackFn;
+  setBuyerId: (id: string | null) => void;
+}
+
+const TrackingCtx = React.createContext<ContextValue | null>(null);
+
+export interface TrackingProviderProps extends AnalyticsConfig {
+  children: React.ReactNode;
+  /** 是否自动发 page_view（默认 true） */
+  autoPageview?: boolean;
+}
+
+export function TrackingProvider(props: TrackingProviderProps): React.ReactElement {
+  const {
+    children,
+    autoPageview = true,
+    apiBase,
+    publicAccessToken,
+    buyerId,
+    debug,
+    flushIntervalMs,
+    flushBatchSize,
+  } = props;
+
+  // 用 ref 持有 queue，避免每次 re-render 重建
+  const queueRef = React.useRef<AnalyticsQueue | null>(null);
+
+  if (queueRef.current === null) {
+    queueRef.current = new AnalyticsQueue({
+      apiBase,
+      publicAccessToken,
+      buyerId,
+      debug,
+      flushIntervalMs,
+      flushBatchSize,
+    });
+  }
+
+  // buyerId 变化时同步到 queue
+  React.useEffect(() => {
+    queueRef.current?.setBuyerId(buyerId ?? null);
+  }, [buyerId]);
+
+  // 启动 queue（只在浏览器侧）
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const q = queueRef.current;
+    if (!q) return;
+    q.start();
+    return () => q.stop();
+  }, []);
+
+  // 自动 page_view
+  React.useEffect(() => {
+    if (!autoPageview) return;
+    if (typeof window === 'undefined') return;
+    const q = queueRef.current;
+    if (!q) return;
+
+    const send = () => {
+      q.track({
+        type: 'page_view',
+        props: { title: typeof document !== 'undefined' ? document.title : undefined },
+      });
+    };
+
+    // 首次
+    send();
+
+    // patch history methods 以捕获 SPA 导航
+    const origPush = history.pushState;
+    const origReplace = history.replaceState;
+    history.pushState = function (...args) {
+      origPush.apply(this, args as any);
+      send();
+    };
+    history.replaceState = function (...args) {
+      origReplace.apply(this, args as any);
+      send();
+    };
+    const onPop = () => send();
+    window.addEventListener('popstate', onPop);
+
+    return () => {
+      history.pushState = origPush;
+      history.replaceState = origReplace;
+      window.removeEventListener('popstate', onPop);
+    };
+  }, [autoPageview]);
+
+  const value = React.useMemo<ContextValue>(
+    () => ({
+      track: (e: AnalyticsEvent) => queueRef.current?.track(e),
+      setBuyerId: (id) => queueRef.current?.setBuyerId(id),
+    }),
+    [],
+  );
+
+  return <TrackingCtx.Provider value={value}>{children}</TrackingCtx.Provider>;
+}
+
+/**
+ * 在组件里拿到 track 函数。
+ *
+ * 在 TrackingProvider 之外调用会得到一个 no-op，不报错（方便在测试/SSR 中使用）。
+ */
+export function useTracking(): ContextValue {
+  const ctx = React.useContext(TrackingCtx);
+  if (ctx) return ctx;
+  return NOOP;
+}
+
+const NOOP: ContextValue = {
+  track: () => {},
+  setBuyerId: () => {},
+};