@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/src/result/either.ts

@@ -0,0 +1,363 @@
+
+// oxlint-disable-next-line typescript/no-explicit-any
+export type AnyEither = Either<any, any>
+export type GetLeft<T> = T extends Either<infer Left, unknown> ? Left : never
+export type GetRight<T> = T extends Either<unknown, infer Right> ? Right : never
+export type GetRights<Eithers> = Eithers extends []
+  ? []
+  : (
+    Eithers extends [infer Item, ...infer xs]
+    ? (
+      Item extends Either<unknown, infer Right>
+      ? [Right, ...GetRights<xs>]
+      : never
+    )
+    : never
+  )
+export type GetLefts<Eithers> = Eithers extends []
+  ? []
+  : (
+    Eithers extends [infer Item, ...infer xs]
+    ? (
+      Item extends Either<infer Left, unknown>
+      ? [Left, ...GetLefts<xs>]
+      : never
+    )
+    : never
+  )
+type TupleToUnion<Tuple> = Tuple extends unknown[] ? Tuple[number] : never
+
+export abstract class Either<L, R> {
+  static isEither<L, R>(target: unknown): target is Either<L, R> {
+    return target instanceof Either
+  }
+
+  static isLeft<L, R>(target: unknown): target is Left<L, R> {
+    return Left.isLeft(target)
+  }
+
+  static isRight<L, R>(target: unknown): target is Right<L, R> {
+    return Right.isRight(target)
+  }
+
+  static left<L>(value: L): Either<L, never>
+  static left<L, R>(value: L): Either<L, R>
+  static left<L, R>(value: L): Either<L, R> {
+    return new Left(value)
+  }
+
+  static right<R>(value: R): Either<never, R>
+  static right<L, R>(value: R): Either<L, R>
+  static right<L, R>(value: R): Either<L, R> {
+    return new Right(value)
+  }
+
+  static pure<R>(value: R): Either<never, R>
+  static pure<L, R>(value: R): Either<L, R>
+  static pure<L, R>(value: R): Either<L, R> {
+    return new Right(value)
+  }
+
+  static lift<NewR, Eithers extends AnyEither[]>(
+    eithers: [...Eithers],
+    map: (eitherRights: GetRights<Eithers>) => NewR,
+  ): Either<TupleToUnion<GetLefts<Eithers>>, NewR> {
+    const firstLeft = eithers.find(either => either.isLeft())
+    if (firstLeft !== undefined) {
+      return firstLeft as Either<TupleToUnion<GetLefts<Eithers>>, NewR>
+    }
+    const rights = eithers.map(either => {
+      // oxlint-disable-next-line typescript/no-unsafe-return
+      return either.assertRight().getRight()
+    }) as GetRights<Eithers>
+    const newRightValue = map(rights)
+    return Either.pure(newRightValue)
+  }
+
+  abstract getValue(): L | R
+
+  abstract getLeft(): L
+  abstract getRight(): R
+  abstract getRightOr(or: R): R
+
+  abstract isLeft(): this is Left<L, R>
+  abstract isRight(): this is Right<L, R>
+
+  abstract assertLeft(): Left<L, R>
+  abstract assertRight(): Right<L, R>
+
+  abstract tap(effects: {
+    left?: ((value: L) => void) | undefined
+    right?: ((value: R) => void) | undefined
+  }): Either<L, R>
+  abstract tapLeft(effect: (value: L) => void): Either<L, R>
+  abstract tapRight(effect: (value: R) => void): Either<L, R>
+
+  abstract mapLeft<NewL>(map: (value: L) => NewL): Either<NewL, R>
+  abstract mapRight<NewR>(map: (value: R) => NewR): Either<L, NewR>
+  abstract bind<NewL, NewR>(bind: (value: R) => Either<NewL, NewR>): Either<L | NewL, NewR>
+  abstract bindAsync<NewL, NewR>(bind: (value: R) => Promise<Either<NewL, NewR>>): Promise<Either<L | NewL, NewR>>
+
+  abstract match<X>(
+    left: (value: L) => X,
+    right: (value: R) => X
+  ): X
+  abstract matchAsync<X>(
+    left: (value: L) => Promise<X>,
+    right: (value: R) => Promise<X>
+  ): Promise<X>
+
+  abstract mplus(either: Either<L, R>): Either<L, R>
+
+  abstract [Symbol.iterator](): Generator<Either<L, R>, R, R>
+  // Async consumers can fall back to Symbol.iterator, but we still expose the
+  // same semantics explicitly so Either remains self-descriptive as an async iterable.
+  abstract [Symbol.asyncIterator](): AsyncGenerator<Either<L, R>, R, unknown>
+}
+
+export class Left<L, R> extends Either<L, R> {
+  protected value: L
+
+  constructor(value: L) {
+    super()
+    this.value = value
+  }
+
+  getValue(): L | R {
+    return this.value
+  }
+
+  getLeft(): L {
+    return this.value
+  }
+
+  getRight(): R {
+    throw new Error("Cannot get right value from Left")
+  }
+
+  getRightOr(or: R): R {
+    return or
+  }
+
+  isLeft(): this is Left<L, R> {
+    return true
+  }
+
+  isRight(): this is Right<L, R> {
+    return false
+  }
+
+  assertLeft(): this {
+    return this
+  }
+
+  assertRight(): Right<L, R> {
+    throw new Error("Assert failed")
+  }
+
+  tap(effects: {
+    left?: ((value: L) => void) | undefined
+    right?: ((value: R) => void) | undefined
+  }): Either<L, R> {
+    if (effects.left !== undefined) {
+      effects.left(this.value)
+    }
+    return this
+  }
+
+  tapLeft(effect: (value: L) => void): Either<L, R> {
+    effect(this.value)
+    return this
+  }
+
+  tapRight(_effect: (value: R) => void): Either<L, R> {
+    return this
+  }
+
+  mapLeft<NewL>(map: (value: L) => NewL): Either<NewL, R> {
+    return new Left(map(this.value))
+  }
+
+  mapRight<NewR>(_map: (value: R) => NewR): Either<L, NewR> {
+    return new Left(this.value)
+  }
+
+  bind<NewL, NewR>(_map: (value: R) => Either<NewL, NewR>): Either<L | NewL, NewR> {
+    return new Left(this.value) as Either<L | NewL, NewR>
+  }
+
+  async bindAsync<NewL, NewR>(_bind: (value: R) => Promise<Either<NewL, NewR>>): Promise<Either<L | NewL, NewR>> {
+    return await Promise.resolve(new Left(this.value) as Either<L | NewL, NewR>)
+  }
+
+  match<X>(
+    left: (value: L) => X,
+    _right: (value: R) => X
+  ): X {
+    return left(this.value)
+  }
+
+  async matchAsync<X>(
+    left: (value: L) => Promise<X>,
+    _right: (value: R) => Promise<X>
+  ): Promise<X> {
+    return await left(this.value)
+  }
+
+  mplus(either: Either<L, R>): Either<L, R> {
+    return either
+  }
+
+  *[Symbol.iterator](): Generator<Either<L, R>, R, R> {
+    yield this
+    throw new Error("Cannot extract right value from Left")
+  }
+
+  // This mirrors the sync iterator exactly; it is explicit protocol support,
+  // not a requirement for async yield* fallback.
+  async *[Symbol.asyncIterator](): AsyncGenerator<Either<L, R>, R, unknown> {
+    await Promise.resolve()
+    yield this
+    throw new Error("Cannot extract right value from Left")
+  }
+}
+
+export class Right<L, R> extends Either<L, R> {
+  protected value: R
+
+  constructor(value: R) {
+    super()
+    this.value = value
+  }
+
+  getValue(): L | R {
+    return this.value
+  }
+
+  getLeft(): L {
+    throw new Error("Cannot get left value from Right")
+  }
+
+  getRight(): R {
+    return this.value
+  }
+
+  getRightOr(_or: R): R {
+    return this.value
+  }
+
+  isLeft(): this is Left<L, R> {
+    return false
+  }
+
+  isRight(): this is Right<L, R> {
+    return true
+  }
+
+  assertLeft(): Left<L, R> {
+    throw new Error("Assert failed")
+  }
+
+  assertRight(): this {
+    return this
+  }
+
+  tap(effects: {
+    left?: ((value: L) => void) | undefined
+    right?: ((value: R) => void) | undefined
+  }): Either<L, R> {
+    if (effects.right !== undefined) {
+      effects.right(this.value)
+    }
+    return this
+  }
+
+  tapLeft(_effect: (value: L) => void): Either<L, R> {
+    return this
+  }
+
+  tapRight(effect: (value: R) => void): Either<L, R> {
+    effect(this.value)
+    return this
+  }
+
+  mapLeft<NewL>(_map: (value: L) => NewL): Either<NewL, R> {
+    return new Right(this.value)
+  }
+
+  mapRight<NewR>(map: (value: R) => NewR): Either<L, NewR> {
+    return new Right(map(this.value))
+  }
+
+  bind<NewL, NewR>(map: (value: R) => Either<NewL, NewR>): Either<L | NewL, NewR> {
+    return map(this.value) as Either<L | NewL, NewR>
+  }
+
+  async bindAsync<NewL, NewR>(bind: (value: R) => Promise<Either<NewL, NewR>>): Promise<Either<L | NewL, NewR>> {
+    return await bind(this.value) as Either<L | NewL, NewR>
+  }
+
+  match<X>(
+    _left: (value: L) => X,
+    right: (value: R) => X
+  ): X {
+    return right(this.value)
+  }
+
+  async matchAsync<X>(
+    _left: (value: L) => Promise<X>,
+    right: (value: R) => Promise<X>
+  ): Promise<X> {
+    return await right(this.value)
+  }
+
+  mplus(_either: Either<L, R>): Either<L, R> {
+    return this
+  }
+
+  *[Symbol.iterator](): Generator<Either<L, R>, R, R> {
+    return this.value
+  }
+
+  // This mirrors the sync iterator exactly; async consumers could fall back to
+  // Symbol.iterator, but the explicit async form keeps the contract obvious.
+  async *[Symbol.asyncIterator](): AsyncGenerator<Either<L, R>, R, unknown> {
+    await Promise.resolve()
+    return this.value
+  }
+}
+
+export const isEither = <L, R>(target: unknown): target is Either<L, R> => {
+  return Either.isEither(target)
+}
+
+export const isLeft = <L, R>(target: unknown): target is Left<L, R> => {
+  return Left.isLeft(target)
+}
+
+export const isRight = <L, R>(target: unknown): target is Right<L, R> => {
+  return Right.isRight(target)
+}
+
+type LeftFunction = {
+  <L>(value: L): Either<L, never>
+  <L, R>(value: L): Either<L, R>
+}
+export const left = (<L, R>(value: L): Either<L, R> => {
+  return Either.left<L, R>(value)
+}) as LeftFunction
+
+type RightFunction = {
+  <R>(value: R): Either<never, R>
+  <L, R>(value: R): Either<L, R>
+}
+export const right = (<L, R>(value: R): Either<L, R> => {
+  return Either.right<L, R>(value)
+}) as RightFunction
+
+export type TupleOfEither<Left, Right> = [undefined, Right] | [Left, undefined]
+export const eitherToTuple = <L, R>(either: Either<L, R>): TupleOfEither<L, R> => {
+  const left = either.isLeft() ? either.getLeft() : undefined
+  const right = either.isRight() ? either.getRight() : undefined
+  return [left, right] as TupleOfEither<L, R>
+}

package/src/result/generator.ts

@@ -0,0 +1,168 @@
+import { mustFixError } from "#Source/exception/error/must-fix.ts"
+
+import type { AnyEither, GetLeft, GetRight } from "./either.ts"
+import { Either } from "./either.ts"
+
+export type EitherSyncGenerator<Yield extends AnyEither, Return extends AnyEither>
+  = Generator<Yield, Return, unknown>
+export type EitherAsyncGenerator<Yield extends AnyEither, Return extends AnyEither>
+  = AsyncGenerator<Yield, Return, unknown>
+
+export type GetEitherGeneratorResult<Yield extends AnyEither, Return extends AnyEither> = Either<
+  GetLeft<Yield> | GetLeft<Return>,
+  GetRight<Return>
+>
+
+export const runSyncGenerator = <Yield extends AnyEither, Return extends AnyEither>(
+  generator: EitherSyncGenerator<Yield, Return>,
+): GetEitherGeneratorResult<Yield, Return> => {
+  let iteratorResult: IteratorResult<Yield, Return>
+  try {
+    iteratorResult = generator.next()
+  } catch (exception) {
+    throw mustFixError("Generator threw an exception", { cause: exception })
+  }
+
+  if (Either.isEither(iteratorResult.value) === false) {
+    throw mustFixError("Generator yielded a non-Either value", { cause: iteratorResult.value })
+  }
+
+  if (iteratorResult.done === false) {
+    try {
+      generator.return?.(undefined as never)
+    } catch (exception) {
+      throw mustFixError("Generator threw an exception during cleanup", { cause: exception })
+    }
+  }
+
+  return iteratorResult.value
+}
+
+export const runAsyncGenerator = async <Yield extends AnyEither, Return extends AnyEither>(
+  generator: EitherAsyncGenerator<Yield, Return>,
+): Promise<GetEitherGeneratorResult<Yield, Return>> => {
+  let iteratorResult: IteratorResult<Yield, Return>
+  try {
+    iteratorResult = await generator.next()
+  } catch (exception) {
+    throw mustFixError("Generator threw an exception", { cause: exception })
+  }
+
+  if (Either.isEither(iteratorResult.value) === false) {
+    throw mustFixError("Generator yielded a non-Either value", { cause: iteratorResult.value })
+  }
+
+  if (iteratorResult.done === false) {
+    try {
+      await generator.return?.(undefined as never)
+    } catch (exception) {
+      throw mustFixError("Generator threw an exception during cleanup", { cause: exception })
+    }
+  }
+
+  return iteratorResult.value
+}
+
+export interface GenSync {
+  <Yield extends AnyEither, Return extends AnyEither>(
+    generatorFunction: () => EitherSyncGenerator<Yield, Return>,
+  ): GetEitherGeneratorResult<Yield, Return>
+  <Yield extends AnyEither, Return extends AnyEither, This>(
+    generatorFunction: (this: This) => EitherSyncGenerator<Yield, Return>,
+    thisArg: This,
+  ): GetEitherGeneratorResult<Yield, Return>
+}
+export const genSync: GenSync = <Yield extends AnyEither, Return extends AnyEither, This>(
+  generatorFunction:
+    | (() => EitherSyncGenerator<Yield, Return>)
+    | ((this: This) => EitherSyncGenerator<Yield, Return>),
+  thisArg?:
+    | This
+    | undefined,
+): GetEitherGeneratorResult<Yield, Return> => {
+  let generator: EitherSyncGenerator<Yield, Return>
+  if (thisArg !== undefined) {
+    generator = (
+      generatorFunction as ((this: This) => EitherSyncGenerator<Yield, Return>)
+    ).call(thisArg)
+  } else {
+    generator = (
+      generatorFunction as (() => EitherSyncGenerator<Yield, Return>)
+    )()
+  }
+  const result = runSyncGenerator(generator)
+  return result
+}
+
+export interface GenAsync {
+  <Yield extends AnyEither, Return extends AnyEither>(
+    generatorFunction: () => EitherAsyncGenerator<Yield, Return>,
+  ): Promise<GetEitherGeneratorResult<Yield, Return>>
+  <Yield extends AnyEither, Return extends AnyEither, This>(
+    generatorFunction: (this: This) => EitherAsyncGenerator<Yield, Return>,
+    thisArg: This,
+  ): Promise<GetEitherGeneratorResult<Yield, Return>>
+}
+export const genAsync: GenAsync = async <Yield extends AnyEither, Return extends AnyEither, This>(
+  generatorFunction:
+    | (() => EitherAsyncGenerator<Yield, Return>)
+    | ((this: This) => EitherAsyncGenerator<Yield, Return>),
+  thisArg?:
+    | This
+    | undefined,
+): Promise<GetEitherGeneratorResult<Yield, Return>> => {
+  let generator: EitherAsyncGenerator<Yield, Return>
+  if (thisArg !== undefined) {
+    generator = (
+      generatorFunction as ((this: This) => EitherAsyncGenerator<Yield, Return>)
+    ).call(thisArg)
+  } else {
+    generator = (
+      generatorFunction as (() => EitherAsyncGenerator<Yield, Return>)
+    )()
+  }
+  const result = await runAsyncGenerator(generator)
+  return result
+}
+
+export interface Gen extends GenSync, GenAsync {
+}
+export const gen = (<Yield extends AnyEither, Return extends AnyEither, This>(
+  generatorFunction:
+    | (() => EitherSyncGenerator<Yield, Return>)
+    | ((thisArg: This) => EitherSyncGenerator<Yield, Return>)
+    | (() => EitherAsyncGenerator<Yield, Return>)
+    | ((thisArg: This) => EitherAsyncGenerator<Yield, Return>),
+  thisArg?:
+    | This
+    | undefined,
+): (
+    | GetEitherGeneratorResult<Yield, Return>
+    | Promise<GetEitherGeneratorResult<Yield, Return>>
+  ) => {
+  let generator: EitherSyncGenerator<Yield, Return> | EitherAsyncGenerator<Yield, Return>
+  if (thisArg !== undefined) {
+    generator = (generatorFunction as (
+      (this: This) => EitherSyncGenerator<Yield, Return> | EitherAsyncGenerator<Yield, Return>
+    )).call(thisArg)
+  } else {
+    generator = (generatorFunction as (
+      () => EitherSyncGenerator<Yield, Return> | EitherAsyncGenerator<Yield, Return>
+    ))()
+  }
+  if (Symbol.asyncIterator in generator) {
+    return runAsyncGenerator(generator)
+  }
+  if (Symbol.iterator in generator) {
+    return runSyncGenerator(generator)
+  }
+  throw new TypeError("Invalid generator function")
+}) as Gen
+
+export const genAwait = async function* <Left, Right>(
+  promise: Promise<Either<Left, Right>>
+): AsyncGenerator<Either<Left, Right>, Right, unknown> {
+  const either = await promise
+  const result = yield* either
+  return result
+}

package/src/result/index.ts

@@ -0,0 +1,3 @@
+export * from "./either.ts"
+export * from "./generator.ts"
+export * from "./controller.ts"

package/src/route/README.md

@@ -0,0 +1,105 @@
+# Route
+
+## Description
+
+Route 模块提供围绕命中入口表达、地址片段归一化、路由历史推进以及宿主桥接的基础建模能力。
+
+它关注的不是某个框架路由器的页面约定，也不是对浏览器 `location`、`history` 或某个导航 API 的临时封装，而是“一个系统中的当前位置或目标入口，如何被表达为稳定、可比较、可派生、可推进的公共语义”这一更一般的问题。浏览器 URL 是 route 的典型形态，但不是唯一形态。只要某个系统里存在“某个输入命中某个稳定入口，并伴随一组可解释片段或参数”的过程，就存在 route 语义。因此，这个模块更适合被理解为路由领域的基础模型集合，而不是浏览器导航工具箱、前端框架路由方案或零散的 URL 处理函数集合。
+
+## For Understanding
+
+理解 Route 模块时，应优先把它看作“当前命中入口及其变化过程”的建模层，而不是把它缩窄成页面跳转工具。这个模块当前表达的核心问题有三层：一是地址片段如何被归一化为稳定表示；二是当前路由如何作为一个可读取、可比较、可派生的对象存在；三是路由历史如何被推进、替换、漫游、回退，并以清楚语义向上层暴露。
+
+这里的 route 不必被限制在浏览器页面地址中。更一般地说，只要某个系统存在“命中入口”的过程，就可以出现 route 语义。例如浏览器应用中的页面或视图入口、服务端系统中的路径分发入口、CLI 中的命令入口，以及任务系统中的某个目标节点入口，本质上都在回答“输入如何命中某个稳定目标，以及这个目标如何和片段、参数、历史一起被组织起来”这一问题。Route 模块关心的是这个抽象层，而不是某一种宿主上的具体表现。
+
+从当前目录结构看，这个模块由三个子边界构成：
+
+- `uri`：负责 `pathname`、`search`、`hash` 等片段的归一化、转换与比较语义。
+- `router`：负责 `Route`、`Router`、历史记录以及各类导航动作的模型化表达。
+- `adapter`：负责把 Route 模型接到具体宿主上，例如浏览器环境或响应式消费面。
+
+理解这个模块时，还应守住几条边界：
+
+- Route 模块表达的是“入口及其历史”的基础模型，不负责替代页面渲染系统、框架路由约定、服务端业务编排、CLI 参数解析器或权限体系。
+- 它可以和浏览器、服务端、CLI 或响应式系统对接，但不应让某个宿主的临时 API 细节反过来定义模块公共语义。
+- 它适合承载入口片段、标准化路由记录、历史动作以及宿主同步边界，但不应直接承担组件装载、数据预取、业务参数解释、命令执行副作用或框架专属生命周期。
+- `adapter` 更适合作为桥接层理解。它的职责是把既有 Route 模型接入宿主，而不是把宿主细节直接提升为父模块语义。
+
+## For Using
+
+当你希望在应用或库中复用一套不依赖具体页面结构、能够稳定表达“当前命中入口”和“入口历史”的基础能力时，可以使用 Route 模块。
+
+从使用角度看，这个模块大致可以分为三类能力：
+
+- 地址片段能力：把 `pathname`、`search`、`hash` 等结构收束成稳定表示，并支持统一的转换、包含与比较语义。
+- 路由模型能力：把当前地址、标准化记录、历史链路以及导航动作组织为一套清楚的对象模型。
+- 宿主桥接能力：把内部 Router 与浏览器历史或响应式消费面连接起来，使上层系统能够围绕统一的 Route 语义工作。
+
+更合适的接入方式，通常是先判断你的问题是否真的属于 route 边界。如果你需要的是：
+
+- 让地址片段形成稳定且可比较的统一表示；
+- 把当前地址收束到一个可复用的路由对象和标准化记录中；
+- 明确区分 navigate、redirect、replace、go、roaming 等历史动作的语义；
+- 将内部 Router 同浏览器历史或响应式消费面连接起来；
+
+那么这个模块就是合适的边界。
+
+相反，如果你的需求主要是页面组件树装载、业务参数校验、访问权限决策、SEO 约定、框架页面生命周期、命令执行副作用或服务端领域逻辑分派，那么这些通常不应直接成为 Route 模块本身的职责，而应放在更外层系统或具体框架集成层中。
+
+## For Contributing
+
+为 Route 模块贡献内容时，优先判断新增能力是否真的在澄清“入口如何表达、如何标准化、如何形成历史、如何与宿主同步”这一稳定问题域，而不是只是在给某个当前宿主补一层便捷封装。这个模块应长期服务于入口片段、路由对象、历史语义与桥接边界这几个方向，而不是退化成浏览器导航工具目录或某个框架的外围辅助层。
+
+扩展时应特别警惕两类偏差。一类是把 `uri` 层做成只对某组业务参数、某条服务路径或某套 CLI 选项成立的临时工具，导致公共语义不稳定；另一类是让 `adapter` 下沉过多桥接之外的职责，例如页面装载、业务状态解释、命令执行、副作用编排或框架专属生命周期。更稳妥的做法，是先确认新增能力究竟属于片段语义、路由历史语义，还是宿主桥接语义，再把它放到对应子边界中。
+
+当前 `adapter` 下的能力更适合被理解为桥接层，因此不要求为其编写单元测试。这并不是说这些代码永远不可测试，而是因为它们主要依赖浏览器事件或响应式系统等宿主前提；在当前模块边界下，优先保证 `uri` 与 `router` 这些环境中立、语义稳定的核心部分被充分测试，通常比为桥接细节重复编写单元测试更有价值。如果未来某个适配器逐渐沉淀出脱离宿主也成立的稳定公共语义，再考虑为其引入单元测试。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/route/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与 route 相关的实现应优先围绕入口片段语义、路由对象、历史推进动作和宿主桥接边界组织，避免把页面装载、服务端业务处理、CLI 命令执行、业务专属参数解释或框架专属生命周期直接提升为 Route 的长期公共语义。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的路由语义，而不是某段浏览器实现细节、宿主桥接细节或业务约定的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/route`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/route/<sub-module-name>`。
+- `adapter` 目录当前无需编写单元测试，并应在模块文档中明确说明这是因为它主要承担宿主桥接职责，核心语义应优先由 `uri` 与 `router` 层测试覆盖。
+- 对这个模块来说，测试应优先覆盖入口片段归一化、Route 标准化记录、Router 的历史推进与替换语义、回退与漫游边界，以及关键动作产生的历史记录与事件行为。