@leisuresaas/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) LeisureSaaS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,14 @@
+# @leisuresaas/react
+
+浏览器产品前端 SDK：产品账号、OAuth PKCE、Public Ads、Drive。
+
+没有 Expo，也没有 Integration Key。App 用 `@leisuresaas/react-native`。
+
+```ts
+import { loginProductAccount } from "@leisuresaas/react/auth";
+import { beginPlatformLogin } from "@leisuresaas/react/oauth";
+```
+
+环境变量：`NEXT_PUBLIC_GATEWAY_URL`、`NEXT_PUBLIC_PUBLISHABLE_KEY`、`NEXT_PUBLIC_OAUTH_ISSUER`。
+
+说明见 `AGENTS.md`。

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@leisuresaas/react",
+  "version": "0.1.0",
+  "description": "Browser SDK for LeisureSaas: product auth, OAuth PKCE, Public Ads, Drive. No Expo or Integration Key.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leisuresaas/react.git"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./auth": "./src/auth.ts",
+    "./oauth": "./src/oauth.ts",
+    "./ads": "./src/ads-ui.tsx",
+    "./drive": "./src/drive.ts",
+    "./app-config": "./src/app-config.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "@types/react": "~19.2.2",
+    "typescript": "~5.9.2"
+  }
+}

package/src/ads-constants.ts

@@ -0,0 +1,55 @@
+export type AdType = "text" | "image";
+
+export type TextLayout = "text_inline" | "text_callout" | "text_footer" | "text_sidebar" | "text_minimal";
+
+export type ImageLayout = "image_hero" | "image_card" | "image_strip" | "image_thumbnail" | "image_inline";
+
+export type AdLayout = TextLayout | ImageLayout;
+
+export type AdRotationMode = "none" | "fade" | "slide" | "stack";
+
+export const AD_TYPES: readonly AdType[] = ["text", "image"] as const;
+export const TEXT_LAYOUTS: readonly TextLayout[] = [
+  "text_inline", "text_callout", "text_footer", "text_sidebar", "text_minimal",
+] as const;
+export const IMAGE_LAYOUTS: readonly ImageLayout[] = [
+  "image_hero", "image_card", "image_strip", "image_thumbnail", "image_inline",
+] as const;
+export const AD_ROTATION_MODES: readonly AdRotationMode[] = ["none", "fade", "slide", "stack"] as const;
+
+export const IMPRESSION_MIN_DWELL_MS = 300;
+
+export function layoutsForType(type: AdType): readonly AdLayout[] {
+  return type === "text" ? TEXT_LAYOUTS : IMAGE_LAYOUTS;
+}
+
+export function defaultLayoutForType(type: AdType): AdLayout {
+  return type === "text" ? "text_inline" : "image_hero";
+}
+
+export function normalizeAdType(raw?: string): AdType {
+  return (raw ?? "").trim() === "image" ? "image" : "text";
+}
+
+export function normalizeLayout(type: AdType, raw?: string): AdLayout {
+  const key = (raw ?? "").trim();
+  const allowed = layoutsForType(type);
+  if (allowed.includes(key as AdLayout)) {
+    return key as AdLayout;
+  }
+  return defaultLayoutForType(type);
+}
+
+export function normalizeRotationMode(raw?: string, enabled?: boolean): AdRotationMode {
+  if (!enabled) return "none";
+  const key = (raw ?? "").trim() as AdRotationMode;
+  return AD_ROTATION_MODES.includes(key) ? key : "fade";
+}
+
+export function effectiveRotationMode(
+  rotation?: { enabled?: boolean; mode?: string },
+  adCount = 0,
+): AdRotationMode {
+  if (adCount <= 1 || !rotation?.enabled) return "none";
+  return normalizeRotationMode(rotation.mode, true);
+}

package/src/ads-context.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+import type { PublicAdsRequestContext } from "./ads-http";
+import { resolveGatewayUrlFromEnv } from "./gateway-url";
+import { resolvePublishableKeyFromEnv } from "./publishable-key";
+
+export type InAppNavigate = (path: string) => void;
+
+export type AdsProviderProps = {
+  publishableKey?: string;
+  gatewayUrl?: string;
+  origin?: string;
+  resolveAccessToken?: () => Promise<string | null>;
+  onInAppNavigate?: InAppNavigate;
+  children: ReactNode;
+};
+
+type AdsContextValue = {
+  resolveAccessToken?: () => Promise<string | null>;
+  onInAppNavigate?: InAppNavigate;
+  publicAds?: PublicAdsRequestContext;
+};
+
+const AdsContext = createContext<AdsContextValue | null>(null);
+
+export function AdsProvider({
+  publishableKey,
+  gatewayUrl,
+  origin,
+  resolveAccessToken,
+  onInAppNavigate,
+  children,
+}: AdsProviderProps) {
+  const value = useMemo((): AdsContextValue => {
+    const key = publishableKey?.trim() || resolvePublishableKeyFromEnv();
+    const base = gatewayUrl?.trim() || resolveGatewayUrlFromEnv() || "";
+    const site = origin?.trim()
+      || (typeof window !== "undefined" ? window.location.origin : "")
+      || process.env.NEXT_PUBLIC_APP_URL?.trim()
+      || "";
+    const publicAds = key && base && site
+      ? { gatewayUrl: base, publishableKey: key, origin: site }
+      : undefined;
+    return { resolveAccessToken, onInAppNavigate, publicAds };
+  }, [publishableKey, gatewayUrl, origin, resolveAccessToken, onInAppNavigate]);
+
+  return <AdsContext.Provider value={value}>{children}</AdsContext.Provider>;
+}
+
+export function useAdsContext(): AdsContextValue {
+  const ctx = useContext(AdsContext);
+  if (!ctx) {
+    throw new Error("useAdsContext must be used within AdsProvider");
+  }
+  return ctx;
+}
+
+export function useOptionalAdsContext(): AdsContextValue | null {
+  return useContext(AdsContext);
+}

package/src/ads-hooks.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { getPublicAdsFeed, recordPublicAdEvents, type AdFeedItem, type AdFeedRotation, type AdsFeedResponse } from "./ads-http";
+import { IMPRESSION_MIN_DWELL_MS } from "./ads-constants";
+import { useAdsContext, useOptionalAdsContext } from "./ads-context";
+
+const SESSION_KEY = "leisuresaas_ads_session_id";
+const impressionRecorded = new Set<string>();
+
+function adsSessionId(): string {
+  if (typeof sessionStorage === "undefined") {
+    return "web";
+  }
+  const existing = sessionStorage.getItem(SESSION_KEY)?.trim();
+  if (existing) return existing;
+  const id = crypto.randomUUID();
+  sessionStorage.setItem(SESSION_KEY, id);
+  return id;
+}
+
+export type UseAdsFeedResult = {
+  feed: AdsFeedResponse | null;
+  ad: AdFeedItem | null;
+  ads: AdFeedItem[];
+  layout?: string;
+  rotation?: AdFeedRotation;
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+};
+
+export function useAdsFeed(options: { placement?: string; enabled?: boolean } = {}): UseAdsFeedResult {
+  const { publicAds } = useAdsContext();
+  const placement = options.placement ?? "home_banner";
+  const enabled = options.enabled ?? true;
+  const [feed, setFeed] = useState<AdsFeedResponse | null>(null);
+  const [loading, setLoading] = useState(enabled);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refresh = useCallback(async () => {
+    if (!enabled) {
+      setFeed(null);
+      setLoading(false);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      if (!publicAds) {
+        setFeed(null);
+        setError(new Error("AdsProvider: publishableKey, gatewayUrl, and origin are required"));
+        return;
+      }
+      setFeed(await getPublicAdsFeed(publicAds, placement));
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setFeed(null);
+    } finally {
+      setLoading(false);
+    }
+  }, [publicAds, placement, enabled]);
+
+  useEffect(() => {
+    void refresh();
+  }, [refresh]);
+
+  const ads = feed?.ads ?? [];
+  return {
+    feed, ad: ads[0] ?? null, ads, layout: feed?.layout, rotation: feed?.rotation,
+    loading, error, refresh,
+  };
+}
+
+export function useAdRotation(ads: AdFeedItem[], rotation?: AdFeedRotation) {
+  const [index, setIndex] = useState(0);
+  const paused = useRef(false);
+  const autoplay = Boolean(rotation?.enabled) && rotation?.autoplay !== false && ads.length > 1;
+  const intervalMs = Math.max(1000, (rotation?.interval_sec ?? 5) * 1000);
+
+  useEffect(() => {
+    setIndex(0);
+  }, [ads]);
+
+  useEffect(() => {
+    if (!autoplay) return;
+    const timer = setInterval(() => {
+      if (paused.current) return;
+      setIndex((prev) => {
+        const next = prev + 1;
+        if (next >= ads.length) return rotation?.loop === false ? prev : 0;
+        return next;
+      });
+    }, intervalMs);
+    return () => clearInterval(timer);
+  }, [ads, autoplay, intervalMs, rotation?.loop]);
+
+  useEffect(() => {
+    const onVis = () => {
+      paused.current = document.hidden;
+    };
+    document.addEventListener("visibilitychange", onVis);
+    return () => document.removeEventListener("visibilitychange", onVis);
+  }, []);
+
+  return { index, setIndex, current: ads[index] ?? null, count: ads.length };
+}
+
+export function useAdImpression(ad: AdFeedItem | null, placement: string, lineupId: string, element: HTMLElement | null) {
+  const optional = useOptionalAdsContext();
+  const resolveAccessToken = optional?.resolveAccessToken;
+  const publicAds = optional?.publicAds;
+  useEffect(() => {
+    if (!ad || !publicAds || !element || typeof IntersectionObserver === "undefined") return;
+    const key = `${placement}:${lineupId}:${ad.id}`;
+    if (impressionRecorded.has(key)) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const observer = new IntersectionObserver((entries) => {
+      const visible = entries.some((entry) => entry.isIntersecting);
+      if (!visible) {
+        if (timer) clearTimeout(timer);
+        timer = null;
+        return;
+      }
+      if (timer || impressionRecorded.has(key)) return;
+      timer = setTimeout(() => {
+        impressionRecorded.add(key);
+        void (async () => {
+          const token = resolveAccessToken ? await resolveAccessToken() : null;
+          await recordPublicAdEvents(publicAds, adsSessionId(), [{
+            adId: ad.id, eventType: "impression", placementKey: placement, lineupId,
+          }], token);
+        })();
+      }, IMPRESSION_MIN_DWELL_MS);
+    }, { threshold: 0.5 });
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+      if (timer) clearTimeout(timer);
+    };
+  }, [ad, placement, lineupId, element, publicAds, resolveAccessToken]);
+}

package/src/ads-http.ts

@@ -0,0 +1,134 @@
+import { LeisureSaasHttpError } from "./errors";
+import { applyPublishableKeyHeaders } from "./publishable-key";
+
+export type AdFeedItem = {
+  id: string;
+  scope?: string;
+  type: string;
+  placement?: string;
+  priority?: number;
+  title?: string;
+  body_text?: string;
+  image_url?: string;
+  click_url?: string;
+};
+
+export type AdFeedRotation = {
+  enabled: boolean;
+  mode: string;
+  interval_sec: number;
+  loop: boolean;
+  autoplay: boolean;
+  show_indicators: boolean;
+};
+
+export type AdFeedSource = {
+  kind: string;
+  lineup_id?: string;
+  scope: string;
+  overridden?: boolean;
+};
+
+export type AdsFeedResponse = {
+  placement: string;
+  surface_key?: string;
+  type?: string;
+  layout?: string;
+  source?: AdFeedSource;
+  rotation?: AdFeedRotation;
+  ads: AdFeedItem[];
+};
+
+export type AdEventInput = {
+  adId: string;
+  eventType: "impression";
+  placementKey?: string;
+  lineupId?: string;
+};
+
+export type PublicAdsRequestContext = {
+  gatewayUrl: string;
+  publishableKey: string;
+  origin: string;
+};
+
+function trimSlash(url: string): string {
+  return url.replace(/\/$/, "");
+}
+
+function publicAdsHeaders(ctx: PublicAdsRequestContext, accessToken?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+    "X-Ads-Surface-Key": "web",
+    "X-Client-Platform": "web",
+  };
+  applyPublishableKeyHeaders(headers, ctx.publishableKey);
+  if (ctx.origin.trim()) {
+    headers.Origin = ctx.origin.trim();
+  }
+  if (accessToken?.trim()) {
+    headers.Authorization = `Bearer ${accessToken.trim()}`;
+  }
+  return headers;
+}
+
+async function publicAdsRequest<T>(
+  ctx: PublicAdsRequestContext,
+  method: "GET" | "POST",
+  path: string,
+  body?: unknown,
+  accessToken?: string,
+): Promise<T> {
+  const base = `${trimSlash(ctx.gatewayUrl)}/v1/public/ads`;
+  const url = `${base}${path.startsWith("/") ? path : `/${path}`}`;
+  const headers = publicAdsHeaders(ctx, accessToken);
+  let payload: string | undefined;
+  if (body !== undefined) {
+    headers["Content-Type"] = "application/json";
+    payload = JSON.stringify(body);
+  }
+  const res = await fetch(url, { method, headers, body: payload });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new LeisureSaasHttpError(res.status, text.trim());
+  }
+  if (!text) {
+    return {} as T;
+  }
+  return JSON.parse(text) as T;
+}
+
+export async function getPublicAdsFeed(ctx: PublicAdsRequestContext, placement = "home_banner"): Promise<AdsFeedResponse> {
+  const q = encodeURIComponent(placement.trim());
+  const resp = await publicAdsRequest<AdsFeedResponse>(ctx, "GET", `/feed?placement=${q}`);
+  return { ...resp, ads: resp.ads ?? [] };
+}
+
+export async function recordPublicAdEvents(
+  ctx: PublicAdsRequestContext,
+  sessionId: string,
+  events: AdEventInput[],
+  accessToken?: string | null,
+): Promise<number> {
+  if (events.length === 0) {
+    return 0;
+  }
+  const payload = {
+    session_id: sessionId.trim(),
+    events: events.map((ev) => {
+      const lineupId = ev.lineupId?.trim() ?? "";
+      return {
+        ad_id: ev.adId,
+        event_type: ev.eventType,
+        ...(ev.placementKey ? { placement_key: ev.placementKey } : {}),
+        ...(lineupId ? { lineup_id: lineupId } : {}),
+      };
+    }),
+  };
+  const resp = await publicAdsRequest<{ recorded: number }>(ctx, "POST", "/events", payload, accessToken ?? undefined);
+  return resp.recorded ?? 0;
+}
+
+export function lineupIdFromSource(source?: AdFeedSource | null): string {
+  return source?.lineup_id?.trim() ?? "";
+}

package/src/ads-ui.tsx

@@ -0,0 +1,215 @@
+"use client";
+
+import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
+
+import {
+  effectiveRotationMode,
+  normalizeAdType,
+  normalizeLayout,
+  type AdLayout,
+  type AdType,
+} from "./ads-constants";
+import { useAdsContext, type InAppNavigate } from "./ads-context";
+import { useAdImpression, useAdRotation, useAdsFeed } from "./ads-hooks";
+import { lineupIdFromSource, type AdFeedItem, type AdsFeedResponse } from "./ads-http";
+
+export { AdsProvider, useAdsContext } from "./ads-context";
+export type { AdsProviderProps, InAppNavigate } from "./ads-context";
+export { useAdsFeed, useAdRotation } from "./ads-hooks";
+export {
+  AD_TYPES,
+  IMAGE_LAYOUTS,
+  TEXT_LAYOUTS,
+  defaultLayoutForType,
+  effectiveRotationMode,
+  layoutsForType,
+  normalizeAdType,
+  normalizeLayout,
+  normalizeRotationMode,
+} from "./ads-constants";
+export type { AdLayout, AdRotationMode, AdType, ImageLayout, TextLayout } from "./ads-constants";
+export { getPublicAdsFeed, lineupIdFromSource, recordPublicAdEvents } from "./ads-http";
+export type { AdEventInput, AdFeedItem, AdFeedRotation, AdFeedSource, AdsFeedResponse, PublicAdsRequestContext } from "./ads-http";
+
+async function openAdClick(url: string, onInAppNavigate?: InAppNavigate) {
+  if (!url) return;
+  try {
+    const res = await fetch(url, {
+      method: "GET",
+      headers: { Accept: "application/json", "X-Ads-Click": "resolve" },
+    });
+    const contentType = res.headers.get("content-type") ?? "";
+    if (res.ok && contentType.includes("application/json")) {
+      const data = (await res.json()) as { kind?: string; path?: string; url?: string };
+      if (data.kind === "in_app" && data.path?.startsWith("/")) {
+        onInAppNavigate?.(data.path);
+        return;
+      }
+      if (data.kind === "external" && data.url?.startsWith("https://")) {
+        window.open(data.url, "_blank", "noopener,noreferrer");
+        return;
+      }
+    }
+  } catch {
+    /* fall through */
+  }
+  window.open(url, "_blank", "noopener,noreferrer");
+}
+
+function layoutStyle(layout: AdLayout): CSSProperties {
+  if (layout === "text_footer" || layout === "image_strip") {
+    return { display: "flex", gap: 12, alignItems: "center" };
+  }
+  if (layout === "text_sidebar" || layout === "image_thumbnail") {
+    return { display: "grid", gridTemplateColumns: "72px 1fr", gap: 12, alignItems: "center" };
+  }
+  if (layout === "text_minimal") {
+    return { fontSize: 13 };
+  }
+  return { display: "grid", gap: 8 };
+}
+
+function Creative({
+  ad,
+  layout,
+  onClick,
+}: {
+  ad: AdFeedItem;
+  layout: AdLayout;
+  onClick: () => void;
+}) {
+  const image = ad.image_url?.trim();
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      style={{
+        ...layoutStyle(layout),
+        width: "100%",
+        textAlign: "left",
+        border: "1px solid #e2e8f0",
+        borderRadius: 12,
+        background: "#fff",
+        padding: layout === "text_minimal" ? 8 : 12,
+        cursor: "pointer",
+      }}
+    >
+      {image ? (
+        <img
+          src={image}
+          alt=""
+          style={{
+            width: layout === "image_thumbnail" || layout === "text_sidebar" ? 72 : "100%",
+            height: layout === "image_hero" ? 160 : layout === "image_strip" ? 72 : 96,
+            objectFit: "cover",
+            borderRadius: 8,
+          }}
+        />
+      ) : null}
+      <span>
+        {ad.title ? <strong style={{ display: "block" }}>{ad.title}</strong> : null}
+        {ad.body_text ? <span style={{ display: "block", color: "#64748b" }}>{ad.body_text}</span> : null}
+      </span>
+    </button>
+  );
+}
+
+export type AdPreviewProps = {
+  ad: AdFeedItem;
+  placement?: string;
+  type?: string;
+  layout?: string;
+  lineupId?: string;
+  onInAppNavigate?: InAppNavigate;
+};
+
+export function AdPreview({ ad, placement = "home_banner", type, layout, lineupId = "", onInAppNavigate }: AdPreviewProps) {
+  const adType = normalizeAdType(type ?? ad.type);
+  const resolved = normalizeLayout(adType, layout);
+  const [node, setNode] = useState<HTMLDivElement | null>(null);
+  useAdImpression(ad, placement, lineupId, node);
+  return (
+    <div ref={setNode}>
+      <Creative ad={ad} layout={resolved} onClick={() => void openAdClick(ad.click_url ?? "", onInAppNavigate)} />
+    </div>
+  );
+}
+
+export function AdSlotView({
+  feed,
+  placement,
+  showIndicators,
+}: {
+  feed: AdsFeedResponse;
+  placement: string;
+  showIndicators?: boolean;
+}) {
+  const { onInAppNavigate } = useAdsContext();
+  const ads = feed.ads ?? [];
+  const rotation = useAdRotation(ads, feed.rotation);
+  const ad = rotation.current;
+  const adType = normalizeAdType(feed.type ?? ad?.type);
+  const layout = normalizeLayout(adType, feed.layout);
+  const lineupId = lineupIdFromSource(feed.source);
+  const [node, setNode] = useState<HTMLDivElement | null>(null);
+  useAdImpression(ad, placement, lineupId, node);
+  const mode = effectiveRotationMode(feed.rotation, ads.length);
+  const indicators = showIndicators ?? feed.rotation?.show_indicators ?? mode !== "none";
+  if (!ad) return null;
+  return (
+    <div ref={setNode}>
+      <Creative ad={ad} layout={layout} onClick={() => void openAdClick(ad.click_url ?? "", onInAppNavigate)} />
+      {indicators && rotation.count > 1 ? (
+        <div style={{ display: "flex", gap: 6, marginTop: 8 }}>
+          {ads.map((item, i) => (
+            <button
+              key={item.id}
+              type="button"
+              aria-label={`广告 ${i + 1}`}
+              onClick={() => rotation.setIndex(i)}
+              style={{
+                width: 8, height: 8, borderRadius: 99, border: 0, padding: 0,
+                background: i === rotation.index ? "#2563eb" : "#cbd5e1",
+              }}
+            />
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export type AdProps = {
+  placement?: string;
+  showEmpty?: boolean;
+  showIndicators?: boolean;
+  onError?: (error: Error) => void;
+  renderAd?: (ad: AdFeedItem) => ReactNode;
+};
+
+export function Ad({ placement = "home_banner", showEmpty = false, showIndicators, onError, renderAd }: AdProps) {
+  const { feed, loading, error } = useAdsFeed({ placement });
+  useEffect(() => {
+    if (error) onError?.(error);
+  }, [error, onError]);
+  if (loading) return null;
+  if (error) return <p style={{ color: "#dc2626", fontSize: 13 }}>广告加载失败: {error.message}</p>;
+  if (!feed?.ads?.length) {
+    return showEmpty ? <p style={{ color: "#64748b", fontSize: 13 }}>（当前无 {placement} 广告）</p> : null;
+  }
+  if (renderAd && feed.ads[0]) return <>{renderAd(feed.ads[0])}</>;
+  return <AdSlotView feed={feed} placement={placement} showIndicators={showIndicators} />;
+}
+
+export function AdBanner(props: Omit<AdProps, "placement">) {
+  return <Ad placement="home_banner" {...props} />;
+}
+export function AdSidebar(props: Omit<AdProps, "placement">) {
+  return <Ad placement="sidebar" {...props} />;
+}
+export function AdFooter(props: Omit<AdProps, "placement">) {
+  return <Ad placement="footer" {...props} />;
+}
+export function AdInline(props: Omit<AdProps, "placement">) {
+  return <Ad placement="inline" {...props} />;
+}