《移动游戏产品的架构·客户端与移动运行时》8.3 平板、折叠屏与异形屏

// file: src/input/form-factors.ts
// tier: L1
// verify: node --test test/input/form-factors.test.ts

export type FoldState = "flat" | "folded" | "half-open";
export type WindowMode = "fullscreen" | "split" | "freeform";
export type Breakpoint = "compact" | "medium" | "expanded";
export type FormFactor = "phone" | "foldable-cover" | "foldable-inner" | "tablet";
export type AspectClass = "standard" | "tall" | "ultra-tall";
export type Orientation = "portrait" | "landscape";

export interface InsetsPx { readonly left: number; readonly top: number; readonly right: number; readonly bottom: number; }

export interface DisplaySnapshot {
  readonly widthPx: number; readonly heightPx: number; readonly dpi: number;
  readonly foldState: FoldState; readonly windowMode: WindowMode; readonly insets: InsetsPx;
}

export interface BreakpointConfig {
  readonly mediumMinDp: number; readonly expandedMinDp: number;
  readonly hysteresisDp: number; readonly settleMs: number;
}

export const DEFAULT_BREAKPOINTS: BreakpointConfig = {
  mediumMinDp: 600, expandedMinDp: 840, hysteresisDp: 24, settleMs: 120,
};

export interface LayoutPlan {
  readonly formFactor: FormFactor; readonly breakpoint: Breakpoint;
  readonly orientation: Orientation; readonly aspectClass: AspectClass;
  readonly aspectRatio: number; readonly widthDp: number; readonly heightDp: number;
  readonly columns: number; readonly hudScale: number; readonly hudTopDp: number;
  readonly safeAreaDp: InsetsPx; readonly multiWindow: boolean;
}

function clamp(value: number, min: number, max: number): number {
  return Math.min(max, Math.max(min, value));
}

export function breakpointFor(
  widthDp: number,
  previous: Breakpoint | null,
  config: BreakpointConfig = DEFAULT_BREAKPOINTS,
): Breakpoint {
  const { mediumMinDp, expandedMinDp, hysteresisDp } = config;
  if (previous === null) {
    return widthDp < mediumMinDp ? "compact" : widthDp < expandedMinDp ? "medium" : "expanded";
  }
  if (previous === "compact") {
    return widthDp >= expandedMinDp ? "expanded" : widthDp >= mediumMinDp ? "medium" : "compact";
  }
  if (previous === "medium") {
    return widthDp >= expandedMinDp ? "expanded"
      : widthDp < mediumMinDp - hysteresisDp ? "compact" : "medium";
  }
  return widthDp < mediumMinDp - hysteresisDp ? "compact"
    : widthDp < expandedMinDp - hysteresisDp ? "medium" : "expanded";
}

export function classify(
  snapshot: DisplaySnapshot,
  previous: Breakpoint | null = null,
  config: BreakpointConfig = DEFAULT_BREAKPOINTS,
): LayoutPlan {
  if (snapshot.dpi <= 0 || snapshot.widthPx <= 0 || snapshot.heightPx <= 0) {
    throw new RangeError("display snapshot needs positive size and dpi");
  }
  const widthDp = Math.round((snapshot.widthPx * 160) / snapshot.dpi);
  const heightDp = Math.round((snapshot.heightPx * 160) / snapshot.dpi);
  const orientation: Orientation = widthDp >= heightDp ? "landscape" : "portrait";
  const shortDp = Math.min(widthDp, heightDp);
  const aspectRatio = Math.max(widthDp, heightDp) / shortDp;
  const aspectClass: AspectClass =
    aspectRatio < 1.78 ? "standard" : aspectRatio <= 2.1 ? "tall" : "ultra-tall";
  const formFactor: FormFactor = snapshot.foldState === "folded" ? "foldable-cover"
    : snapshot.foldState === "half-open" ? "foldable-inner"
    : shortDp >= 600 ? "tablet" : "phone";
  const multiWindow = snapshot.windowMode !== "fullscreen";
  const breakpoint = multiWindow ? "compact" : breakpointFor(widthDp, previous, config);
  const columns = breakpoint === "compact" ? 1 : breakpoint === "medium" ? 2 : 3;
  const dpPerPx = 160 / snapshot.dpi;
  const safeAreaDp: InsetsPx = {
    left: Math.round(snapshot.insets.left * dpPerPx),
    top: Math.round(snapshot.insets.top * dpPerPx),
    right: Math.round(snapshot.insets.right * dpPerPx),
    bottom: Math.round(snapshot.insets.bottom * dpPerPx),
  };
  return {
    formFactor, breakpoint, orientation, aspectClass, aspectRatio, widthDp, heightDp, columns,
    hudScale: clamp(widthDp / 375, 0.85, 1.4), hudTopDp: safeAreaDp.top + 12, safeAreaDp, multiWindow,
  };
}

export type ReconcileAction = "relayout" | "defer" | "viewport-only" | "no-op";

export interface ReconcileResult {
  readonly action: ReconcileAction; readonly plan: LayoutPlan;
  readonly reasons: readonly string[]; readonly pending: boolean;
}

interface PendingChange { readonly plan: LayoutPlan; readonly sinceMs: number; }

function structuralKey(plan: LayoutPlan): string {
  return [plan.formFactor, plan.breakpoint, plan.orientation, plan.aspectClass, plan.multiWindow].join("|");
}

function structuralReasons(previous: LayoutPlan, next: LayoutPlan): string[] {
  const reasons: string[] = [];
  if (previous.formFactor !== next.formFactor) {
    reasons.push(`form-factor:${previous.formFactor}->${next.formFactor}`);
  }
  if (previous.breakpoint !== next.breakpoint) {
    reasons.push(`breakpoint:${previous.breakpoint}->${next.breakpoint}`);
  }
  if (previous.orientation !== next.orientation) {
    reasons.push(`orientation:${previous.orientation}->${next.orientation}`);
  }
  if (previous.aspectClass !== next.aspectClass) {
    reasons.push(`aspect:${previous.aspectClass}->${next.aspectClass}`);
  }
  if (previous.multiWindow !== next.multiWindow) {
    reasons.push(`window:${previous.multiWindow}->${next.multiWindow}`);
  }
  return reasons;
}

/** 折叠动画与旋转用稳定窗口合并重排；仅尺寸或安全区变化走 viewport-only。 */
export class DisplayReconciler {
  readonly #config: BreakpointConfig;
  #applied: LayoutPlan | null = null;
  #pending: PendingChange | null = null;

  constructor(config: BreakpointConfig = DEFAULT_BREAKPOINTS) {
    this.#config = config;
  }

  get applied(): LayoutPlan | null {
    return this.#applied;
  }

  submit(snapshot: DisplaySnapshot, tMs: number): ReconcileResult {
    const plan = classify(snapshot, this.#applied?.breakpoint ?? null, this.#config);
    if (!this.#applied) {
      this.#applied = plan;
      return { action: "relayout", plan, reasons: ["initial-layout"], pending: false };
    }
    const applied = this.#applied;
    if (structuralKey(plan) === structuralKey(applied)) {
      this.#pending = null;
      this.#applied = plan;
      const viewportChanged = plan.widthDp !== applied.widthDp || plan.heightDp !== applied.heightDp
        || plan.safeAreaDp.left !== applied.safeAreaDp.left || plan.safeAreaDp.top !== applied.safeAreaDp.top
        || plan.safeAreaDp.right !== applied.safeAreaDp.right || plan.safeAreaDp.bottom !== applied.safeAreaDp.bottom;
      return {
        action: viewportChanged ? "viewport-only" : "no-op", plan,
        reasons: viewportChanged ? ["viewport"] : [], pending: false,
      };
    }
    if (this.#pending && structuralKey(this.#pending.plan) === structuralKey(plan)) {
      if (tMs - this.#pending.sinceMs >= this.#config.settleMs) {
        this.#applied = plan;
        this.#pending = null;
        return { action: "relayout", plan, reasons: structuralReasons(applied, plan), pending: false };
      }
      return { action: "defer", plan, reasons: ["settling"], pending: true };
    }
    this.#pending = { plan, sinceMs: tMs };
    return { action: "defer", plan, reasons: ["settling"], pending: true };
  }

  flush(tMs: number): ReconcileResult {
    if (!this.#applied) {
      throw new Error("no layout has been submitted");
    }
    if (!this.#pending) {
      return { action: "no-op", plan: this.#applied, reasons: [], pending: false };
    }
    const applied = this.#applied;
    const { plan, sinceMs } = this.#pending;
    this.#applied = plan;
    this.#pending = null;
    const reasons = structuralReasons(applied, plan);
    if (tMs - sinceMs < this.#config.settleMs) {
      reasons.push("forced-flush");
    }
    return { action: "relayout", plan, reasons, pending: false };
  }
}

export interface MatrixCase {
  readonly formFactor: FormFactor; readonly foldState: FoldState;
  readonly windowMode: WindowMode; readonly aspectClass: AspectClass;
}

export function matrixCaseOf(plan: LayoutPlan, snapshot: DisplaySnapshot): MatrixCase {
  return {
    formFactor: plan.formFactor, foldState: snapshot.foldState,
    windowMode: snapshot.windowMode, aspectClass: plan.aspectClass,
  };
}

export function matrixKey(item: MatrixCase): string {
  return [item.formFactor, item.foldState, item.windowMode, item.aspectClass].join("/");
}

export function uncoveredMatrixCases(
  cases: readonly MatrixCase[],
  coveredKeys: readonly string[],
): readonly string[] {
  const covered = new Set(coveredKeys);
  const missing = new Set<string>();
  for (const item of cases) {
    const key = matrixKey(item);
    if (!covered.has(key)) {
      missing.add(key);
    }
  }
  return [...missing].sort();
}