export type ProjectRestorePage = {
  getByRole(role: 'banner' | 'complementary'): {
    getByText(name: string, options?: { exact?: boolean }): unknown;
    getByTitle(name: string, options?: { exact?: boolean }): unknown;
  };
};

export function requireProjectName(projectName: string): string {
  const name = projectName.trim();
  if (!name) {
    throw new Error('empty_project_name');
  }
  return name;
}

/** 侧栏可见项目入口：complementary 内 exact title，禁止页面级 getByText / .first()。 */
export function visibleProjectEntry(page: ProjectRestorePage, projectName: string) {
  return page.getByRole('complementary').getByTitle(requireProjectName(projectName), { exact: true });
}

/** 顶栏当前项目：banner 内 exact 文本，语义为已激活项目而非侧栏副本。 */
export function currentProjectBannerName(page: ProjectRestorePage, projectName: string) {
  return page.getByRole('banner').getByText(requireProjectName(projectName), { exact: true });
}

export function evaluatePageWideProjectNameHits(hits: number): { ok: boolean; reason: string } {
  if (hits !== 1) {
    return { ok: false, reason: `page_wide_project_name_not_unique:${hits}` };
  }
  return { ok: true, reason: 'unique' };
}