API

运行时只导出 install、create，公开类型为 InstallOptions、Guard 和 Handler。

install(options?)

interface InstallOptions {
  scope?: (url: URL) => boolean
}

function install(options?: InstallOptions): void

为当前 Window 安装常驻的 pushState、replaceState 包装和捕获阶段 popstate 协调器。必须在 路由器第一次调用 pushState()之前执行。

首次安装时，当前 URL 命中 scope便自动保护当前 entry；默认 scope 匹配所有 URL。scope还会收到后续 pushState()解析后的目标 URL：命中时创建 edge， 不命中时保持原生写入。相对 URL 基于当前 URL 解析；scope 抛错时不会执行 History 写入。若当前业务 entry 已受保护，replaceState()会在原生写入成功后保留 私有锚点；调用方传入对象不会被修改，业务字段和结构化克隆值保持不变。

Guard 在 history.state.__revfanc_guard__维护版本化私有元数据。业务不得读取、 修改或依赖该字段。普通刷新后，install()会从合法业务锚点恢复 token 和逻辑位置， 接管原 edge，不新增 History entry，也不改变 URL。

同一模块实例内重复调用无效，首次成功配置生效；不提供卸载。浏览器或 History API 不可用时抛出 TypeError。

create(handler)

function create(handler: Handler): Guard

将 Handler 压入当前 Window 的 LIFO 栈。未执行 install()或 Handler 不是函数时 直接抛错。

Guard

interface Guard {
  (): void
}

同步移除对应 Handler。允许移除非栈顶，重复调用无效。停止 pending Handler 后， 它持有的 resolve()立即失效。

Handler

type Handler = (
  resolve: () => void,
) => void | PromiseLike<void>

• 只有 Back 调用 Handler；Forward 透明跨过内部 edge；
• Handler 执行时已恢复到用户操作前的业务 URL 和最新 state；
• 未调用 resolve()时拒绝本次穿越并保留当前层；
• 调用 resolve()移除当前层；有下层时停留，无下层时继续原 Back；
• pending 期间的后续单步穿越会被恢复，但不会重复调用 Handler；
• Handler 完成、停止、失去栈顶或首次调用后，旧 resolve()失效。