《移动游戏产品的架构·客户端与移动运行时》7.1 UI 栈、弹窗队列与返回键语义

// file: src/ui/screen-stack.ts
// tier: L1
// verify: node --test test/ui/screen-stack.test.ts

export type BackSource = "android-back" | "ios-edge-swipe";

export interface Screen {
  readonly id: string;
  readonly kind: "page" | "modal" | "confirm";
}

export interface Popup {
  readonly key: string;
  readonly priority: number;
  readonly kind: "modal" | "confirm";
  readonly back: "close" | "block";
  readonly preemptive?: boolean;
}

export interface QueuedPopup {
  readonly popup: Popup;
  readonly seq: number;
}

export type EnqueueResult =
  | { readonly kind: "shown" }
  | { readonly kind: "queued"; readonly position: number }
  | { readonly kind: "duplicate" };

export type BackOutcome =
  | { readonly kind: "closed-popup"; readonly key: string }
  | { readonly kind: "popped-page"; readonly id: string }
  | { readonly kind: "exit-armed"; readonly deadlineMs: number }
  | { readonly kind: "exit" }
  | { readonly kind: "ignored"; readonly reason: string };

export const EXIT_WINDOW_MS = 2_000;
export const TOAST_COOLDOWN_MS = 1_500;
export const TAP_WINDOW_MS = 350;

function comparePopup(a: QueuedPopup, b: QueuedPopup): number {
  if (a.popup.priority !== b.popup.priority) {
    return b.popup.priority - a.popup.priority;
  }
  return a.seq - b.seq;
}

export class UiStack {
  #pages: Screen[];
  #queue: QueuedPopup[] = [];
  #active: QueuedPopup | null = null;
  #seq = 0;
  #exitDeadlineMs = 0;

  constructor(root: Screen) {
    this.#pages = [root];
  }

  get depth(): number {
    return this.#pages.length;
  }

  get top(): Screen {
    return this.#pages[this.#pages.length - 1];
  }

  get activePopup(): QueuedPopup | null {
    return this.#active;
  }

  get queuedKeys(): readonly string[] {
    return this.#queue.map((item) => item.popup.key);
  }

  pushPage(screen: Screen): void {
    if (screen.kind !== "page") {
      throw new Error("only page screens belong on the page stack");
    }
    this.#pages.push(screen);
  }

  popPage(): Screen | null {
    if (this.#pages.length <= 1) {
      return null;
    }
    return this.#pages.pop() ?? null;
  }

  enqueue(popup: Popup): EnqueueResult {
    if (this.#active?.popup.key === popup.key) {
      return { kind: "duplicate" };
    }
    if (this.#queue.some((item) => item.popup.key === popup.key)) {
      return { kind: "duplicate" };
    }
    const item: QueuedPopup = { popup, seq: (this.#seq += 1) };
    if (this.#active === null) {
      this.#active = item;
      return { kind: "shown" };
    }
    if (popup.preemptive === true && popup.priority > this.#active.popup.priority) {
      this.#queue.push(this.#active);
      this.#active = item;
      this.#queue.sort(comparePopup);
      return { kind: "shown" };
    }
    this.#queue.push(item);
    this.#queue.sort(comparePopup);
    return { kind: "queued", position: this.#queue.indexOf(item) + 1 };
  }

  dismissActive(): QueuedPopup | null {
    if (this.#active === null) {
      return null;
    }
    const closed = this.#active;
    this.#active = this.#queue.shift() ?? null;
    return closed;
  }

  back(source: BackSource, nowMs: number): BackOutcome {
    if (this.#active !== null) {
      if (source === "ios-edge-swipe") {
        return { kind: "ignored", reason: "edge-swipe-navigates-pages-only" };
      }
      if (this.#active.popup.back === "block") {
        return { kind: "ignored", reason: "popup-blocks-back" };
      }
      const key = this.#active.popup.key;
      this.#active = this.#queue.shift() ?? null;
      return { kind: "closed-popup", key };
    }
    if (source === "ios-edge-swipe") {
      const popped = this.popPage();
      return popped
        ? { kind: "popped-page", id: popped.id }
        : { kind: "ignored", reason: "gesture-at-root" };
    }
    const popped = this.popPage();
    if (popped !== null) {
      return { kind: "popped-page", id: popped.id };
    }
    if (nowMs < this.#exitDeadlineMs) {
      this.#exitDeadlineMs = 0;
      return { kind: "exit" };
    }
    this.#exitDeadlineMs = nowMs + EXIT_WINDOW_MS;
    return { kind: "exit-armed", deadlineMs: this.#exitDeadlineMs };
  }
}

export class ToastCenter {
  #lastShown = new Map<string, number>();

  show(key: string, nowMs: number, cooldownMs: number = TOAST_COOLDOWN_MS): boolean {
    const last = this.#lastShown.get(key);
    if (last !== undefined && nowMs - last < cooldownMs) {
      return false;
    }
    this.#lastShown.set(key, nowMs);
    return true;
  }

  reset(key?: string): void {
    if (key === undefined) {
      this.#lastShown.clear();
      return;
    }
    this.#lastShown.delete(key);
  }
}

export class TapThrottle {
  #lastStarted = new Map<string, number>();

  tryStart(key: string, nowMs: number, windowMs: number = TAP_WINDOW_MS): boolean {
    const last = this.#lastStarted.get(key);
    if (last !== undefined && nowMs - last < windowMs) {
      return false;
    }
    this.#lastStarted.set(key, nowMs);
    return true;
  }

  reset(key?: string): void {
    if (key === undefined) {
      this.#lastStarted.clear();
      return;
    }
    this.#lastStarted.delete(key);
  }
}