《互联网产品的客户端架构·内容、社交与实时互动》3.3 媒体懒加载与占位：CLS 的端上来源

高度 = ceil(容器宽度 ÷ (固有宽度 ÷ 固有高度))

top <= scrollY + viewportHeight + rootMargin
bottom >= scrollY - rootMargin

// file: src/render/lazy-media.ts
// tier: L1
// verify: node --test test/render/lazy-media.test.ts

export interface IntrinsicSize {
  width: number;
  height: number;
}

export type MediaRole = "cover" | "inline" | "video" | "avatar";

export interface MediaSlot {
  id: string;
  intrinsic: IntrinsicSize;
  role: MediaRole;
  offsetTop: number;
  alt: string;
}

export interface ReservedBox {
  width: number;
  height: number;
  aspectRatio: number;
}

export interface Viewport {
  scrollY: number;
  height: number;
}

export interface LoadHint {
  id: string;
  loading: "eager" | "lazy";
  fetchPriority: "high" | "auto" | "low";
  estimatedHeight: number;
}

export interface FailurePlan {
  keepReservedBox: boolean;
  fallback: "gradient" | "poster" | "initial";
  height: number;
  label: string;
  retryAfterMs: number | null;
  exhausted: boolean;
}

export const FALLBACK_RATIO = 16 / 9;
export const RETRY_DELAYS: readonly number[] = [500, 2000];

export function aspectRatio(size: IntrinsicSize): number {
  if (!Number.isFinite(size.width) || !Number.isFinite(size.height)) return FALLBACK_RATIO;
  if (size.width <= 0 || size.height <= 0) return FALLBACK_RATIO;
  return size.width / size.height;
}

export function reserveBox(
  size: IntrinsicSize,
  containerWidth: number,
  maxHeight = Number.POSITIVE_INFINITY,
): ReservedBox {
  const safeWidth = Number.isFinite(containerWidth) ? Math.max(0, Math.floor(containerWidth)) : 0;
  const ratio = aspectRatio(size);
  const natural = safeWidth / ratio;
  const cap = Number.isFinite(maxHeight) ? Math.max(0, Math.floor(maxHeight)) : Number.POSITIVE_INFINITY;
  const height = Math.min(Math.ceil(natural), cap);
  return { width: safeWidth, height, aspectRatio: Number(ratio.toFixed(4)) };
}

export function estimatedHeightFor(slot: MediaSlot, containerWidth: number): number {
  if (slot.role === "avatar") return Math.max(0, Math.floor(containerWidth));
  return reserveBox(slot.intrinsic, containerWidth).height;
}

export interface ShiftInput {
  viewportHeight: number;
  rectTop: number;
  heightBefore: number;
  heightAfter: number;
}

export function layoutShiftScore(input: ShiftInput): number {
  const viewportHeight = Math.max(1, input.viewportHeight);
  const top = Math.max(0, input.rectTop);
  const before = top + Math.max(0, input.heightBefore);
  const after = top + Math.max(0, input.heightAfter);
  if (before === after) return 0;
  const visibleTop = Math.min(top, viewportHeight);
  const visibleBottom = Math.min(Math.max(before, after), viewportHeight);
  const impact = Math.max(0, visibleBottom - visibleTop) / viewportHeight;
  const distance = Math.min(1, Math.abs(after - before) / viewportHeight);
  return Number((impact * distance).toFixed(6));
}

export function planMediaLoad(
  slots: MediaSlot[],
  viewport: Viewport,
  containerWidth: number,
  eagerMargin = 0.5,
): LoadHint[] {
  const eagerUntil = viewport.scrollY + viewport.height * (1 + eagerMargin);
  let firstEager = true;
  return slots.map((slot) => {
    const isEager = slot.offsetTop <= eagerUntil;
    const fetchPriority = isEager && firstEager ? "high" : isEager ? "auto" : "low";
    if (isEager) firstEager = false;
    return {
      id: slot.id,
      loading: isEager ? "eager" : "lazy",
      fetchPriority,
      estimatedHeight: estimatedHeightFor(slot, containerWidth),
    };
  });
}

export function shouldLoad(
  slot: MediaSlot,
  viewport: Viewport,
  containerWidth: number,
  rootMargin = 200,
): boolean {
  const top = slot.offsetTop;
  const bottom = top + estimatedHeightFor(slot, containerWidth);
  return top <= viewport.scrollY + viewport.height + rootMargin
    && bottom >= viewport.scrollY - rootMargin;
}

export function failurePlan(
  slot: MediaSlot,
  containerWidth: number,
  attempt: number,
): FailurePlan {
  const index = Math.max(0, Math.floor(Number.isFinite(attempt) ? attempt : 0));
  const retryAfterMs = index < RETRY_DELAYS.length ? RETRY_DELAYS[index] : null;
  const fallback = slot.role === "avatar" ? "initial" : slot.role === "video" ? "poster" : "gradient";
  return {
    keepReservedBox: true,
    fallback,
    height: estimatedHeightFor(slot, containerWidth),
    label: slot.alt.trim() === "" ? "媒体加载失败" : slot.alt.trim(),
    retryAfterMs,
    exhausted: retryAfterMs === null,
  };
}

$ node --test test/render/lazy-media.test.ts
✔ 宽高比正常计算，非法尺寸回退到 16:9 (0.476542ms)
✔ 占位盒按容器宽度换算高度，并可被最大高度截断 (0.148166ms)
✔ 占位高度与最终高度一致时 CLS 为 0 (0.088125ms)
✔ 没有占位时按可视比例与位移比例计算 CLS (0.554667ms)
✔ 首屏媒体 eager 且首张高优先级，屏幕外保持 lazy (0.681ms)
✔ 懒加载触发条件尊重 rootMargin 与上下边界 (0.148709ms)
✔ 加载失败保留占位盒，并按次数给出重试节奏 (0.143333ms)
ℹ tests 7
ℹ suites 0
ℹ pass 7
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 122.7625