@mantou/gem 2.2.15 → 2.3.0

package/src/lib/reactive.ts

@@ -1,7 +1,7 @@
 // biome-ignore-all lint/plugin/no_this_effect: 兼容生命周期
 
 import type * as Lit from './lit-html';
-import { isServer } from './server';
+import { isServer, ssrHooks } from './server';
 import type { Store } from './store';
 import { connect } from './store';
 import {
@@ -27,21 +27,9 @@ export function setEngine(h: typeof Lit.html, r: typeof Lit.render) {
   render = r;
 }
 
-let hydrationEngine = (_value: unknown, _container: HTMLElement | DocumentFragment): Lit.RootPart | undefined => {
-  return;
-};
-
-// 在元素首次渲染前恢复 SSR 的状态
-let restoreState: ((ele: GemElement) => void) | undefined;
-
-export function setHydrationEngine(engine: typeof hydrationEngine, restore?: typeof restoreState) {
-  hydrationEngine = engine;
-  restoreState = restore;
-}
-
-/** 渲染元素内容，SSR 时由水合引擎接管 */
+/** 渲染元素内容，SSR 时由 `ssrHooks.render` 接管 */
 export const _renderRoot = (value: unknown, container: HTMLElement | DocumentFragment) =>
-  hydrationEngine(value, container) || render(value, container);
+  ssrHooks.render?.(value, container) || render(value, container);
 
 const { assign, defineProperty } = Object;
 
@@ -59,14 +47,15 @@ export const UpdateToken = Symbol.for('gem@update');
 const BoundaryCSSState = 'gem-style-boundary';
 const ElementCSSState = 'gem-element';
 
-/**@internal */
+/** 渲染出错时在元素上派发，`@fallback` 处理时取消，SSR 时 `@server` 方法出错也会派发 */
 export const _RenderErrorEvent = 'gem@render-error';
 
 // fix modal-factory type error
 const updateTokenAlias = UpdateToken;
 
-const rootStyleSheetInfo = new WeakMap<Document | ShadowRoot, Map<CSSStyleSheet, number>>();
-const rootUpdateFnMap = new WeakMap<Map<CSSStyleSheet, number>, () => void>();
+// 渲染根中 light DOM 元素使用的样式表和使用次数，以及更新渲染根样式表的函数
+type RootSheets = { counts: Map<CSSStyleSheet, number>; update: () => void };
+const rootSheetsMap = new WeakMap<Document | ShadowRoot, RootSheets>();
 
 class GemCSSStyleSheet extends CSSStyleSheet {
   #ele?: HTMLStyleElement;
@@ -96,45 +85,37 @@ class GemCSSSheet {
     this.#content = v;
   }
 
-  // 不需要 GC
-  #record = new Map<any, GemCSSStyleSheet>();
-  #used = new Map<GemCSSStyleSheet, string>();
+  // 对同一类 dom 只使用同一个样式表，key 是元素类或者 `this`，不需要 GC
+  #sheets = new Map<any, { sheet: GemCSSStyleSheet; scope: string }>();
+
+  #apply({ sheet, scope }: { sheet: GemCSSStyleSheet; scope: string }) {
+    sheet.replaceSync(scope ? `${scope}{ ${this.#content} }` : this.#content);
+  }
+
   getStyle(host?: HTMLElement, isEleTheme?: boolean) {
     const isLight = host && !(host as GemElement).internals?.shadowRoot;
-
-    // 对同一类 dom 只使用同一个样式表
     const key = isLight ? host.constructor : this;
-    if (!this.#record.has(key)) {
-      const sheet = new GemCSSStyleSheet({ media: this.#media });
-      this.#record.set(key, sheet);
+    let item = this.#sheets.get(key);
+    if (!item) {
+      // light dom 嵌套时需要选择子元素
+      // `> *` 实际上是多范围？是否存在性能问题
+      // 不能使用 @layer，两个 @layer 不能覆盖，只有顺序起作用
+      // 所以外部不能通过元素名称选择器来覆盖样式，除非样式在之前插入（会自动反转应用到尾部， see `adoptRootStyleSheets`）
+      const scope = !isLight
+        ? ''
+        : isEleTheme
+          ? '@scope'
+          : `@scope (${host.tagName}) to (:state(${BoundaryCSSState}) > *)`;
+      item = { sheet: new GemCSSStyleSheet({ media: this.#media }), scope };
+      this.#sheets.set(key, item);
+      this.#apply(item);
     }
-
-    const sheet = this.#record.get(key)!;
-
-    // 只执行一次
-    if (!this.#used.has(sheet)) {
-      let style = this.#content;
-      let scope = '';
-      if (isLight) {
-        // light dom 嵌套时需要选择子元素
-        // `> *` 实际上是多范围？是否存在性能问题
-        scope = isEleTheme ? '@scope' : `@scope (${host.tagName}) to (:state(${BoundaryCSSState}) > *)`;
-        // 不能使用 @layer，两个 @layer 不能覆盖，只有顺序起作用
-        // 所以外部不能通过元素名称选择器来覆盖样式，除非样式在之前插入（会自动反转应用到尾部， see `appleCSSStyleSheet`）
-        style = `${scope}{ ${style} }`;
-      }
-      sheet.replaceSync(style);
-      this.#used.set(sheet, scope);
-    }
-
-    return sheet;
+    return item.sheet;
   }
 
   // 一般用于主题更新
   updateStyle() {
-    this.#used.forEach((scope, sheet) => {
-      sheet.replaceSync(scope ? `${scope}{${this.#content}}` : this.#content);
-    });
+    this.#sheets.forEach((item) => this.#apply(item));
   }
 }
 
@@ -182,40 +163,38 @@ export function css<T extends Record<string, string>>(
   return sheet as Sheet<T>;
 }
 
-const updateStyleSheets = (map: Map<CSSStyleSheet, number>, sheets: CSSStyleSheet[], value: number) => {
+const updateRootSheets = ({ counts, update }: RootSheets, sheets: CSSStyleSheet[], value: number) => {
   let needUpdate = false;
   sheets.forEach((e) => {
-    const count = map.get(e) || 0;
+    const count = counts.get(e) || 0;
     needUpdate ||= (value === 1 && count === 0) || (value === -1 && count === 1);
     // count 为 0 时不立即删除，以便更新时识别是否外部样式
     // 但是只要挂载 document 的样式表就不会被 GC 了, 是否要在闲时 GC？
-    map.set(e, count + value);
+    counts.set(e, count + value);
   });
-  if (needUpdate) {
-    // 避免重复更新，例如 list 元素增删，全 light dom 时 document 更新
-    // 在 SSR 中应该区别 effect 强制执行
-    addMicrotask(rootUpdateFnMap.get(map)!);
-  }
+  // 避免重复更新，例如 list 元素增删，全 light dom 时 document 更新
+  // 在 SSR 中应该区别 effect 强制执行
+  if (needUpdate) addMicrotask(update);
 };
 
-const appleCSSStyleSheet = (ele: HTMLElement, sheets: CSSStyleSheet[]) => {
+/** light DOM 元素的样式表添加到渲染根中，返回移除函数 */
+const adoptRootStyleSheets = (ele: HTMLElement, sheets: CSSStyleSheet[]) => {
   const root = ele.getRootNode() as ShadowRoot | Document;
-  if (!rootStyleSheetInfo.has(root)) {
-    const map = new Map<CSSStyleSheet, number>();
-    rootStyleSheetInfo.set(root, map);
-    rootUpdateFnMap.set(map, () => {
+  let rootSheets = rootSheetsMap.get(root);
+  if (!rootSheets) {
+    const counts = new Map<CSSStyleSheet, number>();
+    const update = () => {
       // 先找到外部样式表
-      const newSheets = (root.adoptedStyleSheets || []).filter((e) => !map.has(e));
-      map.forEach((count, sheet) => count && newSheets.push(sheet));
+      const newSheets = (root.adoptedStyleSheets || []).filter((e) => !counts.has(e));
+      counts.forEach((count, sheet) => count && newSheets.push(sheet));
       // 外层元素的样式要放到最后，以提升优先级，但是只考虑第一次出现样式表的位置
       root.adoptedStyleSheets = newSheets.reverse();
-    });
+    };
+    rootSheets = { counts, update };
+    rootSheetsMap.set(root, rootSheets);
   }
-
-  const map = rootStyleSheetInfo.get(root)!;
-
-  updateStyleSheets(map, sheets, 1);
-  return () => updateStyleSheets(map, sheets, -1);
+  updateRootSheets(rootSheets, sheets, 1);
+  return () => updateRootSheets(rootSheets, sheets, -1);
 };
 
 /**必须使用在字段中，否则会读取到错误的实例 */
@@ -232,23 +211,25 @@ type EffectItem<T> = {
   preCallback?: any;
 };
 
-function execEffectList(list?: EffectItem<any>[]) {
-  list?.forEach((effectItem) => {
-    const { callback, getDep, values, preCallback } = effectItem;
-    const newValues = getDep?.();
-    if (!getDep || !values || isArrayChange(values, newValues)) {
-      execCallback(preCallback);
-      effectItem.preCallback = callback(newValues, values);
-      effectItem.values = newValues;
-      // 更新时也要设置，避免异步的 `#initEffect` 重复执行
-      effectItem.initialized = true;
-    }
+function runEffect<T>(item: EffectItem<T>, values: T) {
+  execCallback(item.preCallback);
+  item.preCallback = item.callback(values, item.values);
+  item.values = values;
+  // 更新时也要设置，避免异步的 `#initEffect` 重复执行
+  item.initialized = true;
+}
+
+function execEffectList(list: EffectItem<any>[]) {
+  list.forEach((item) => {
+    const values = item.getDep?.();
+    if (!item.getDep || !item.values || isArrayChange(item.values, values)) runEffect(item, values);
   });
 }
 
 function clearEffect(list: EffectItem<any>[]) {
   return list.filter((e) => {
     execCallback(e.preCallback);
+    e.preCallback = undefined;
     e.initialized = false;
     e.values = undefined;
     return e.fixed;
@@ -277,6 +258,8 @@ export type Metadata = Partial<ShadowRootInit> & {
   >;
   // 实例化时使用到，DevTools 需要读取
   observedStores?: Store<any>[];
+  /** attribute 对应的字段名，用于 `setAttribute` 等方法设置字段 */
+  attrProps?: Record<string, string>;
   adoptedStyleSheets?: Sheet<unknown>[];
   // 以下静态字段仅供外部读取，没有实际作用
   observedProperties?: string[];
@@ -341,8 +324,7 @@ export abstract class GemElement extends HTMLElement {
   #clearStyle?: (() => void) | undefined;
 
   [updateTokenAlias]() {
-    // 避免 `connectedCallback` 中的 property 赋值造成多余更新
-    if (this.#isMounted) addMicrotask(this.#update);
+    this.#scheduleUpdate();
   }
 
   static {
@@ -357,9 +339,8 @@ export abstract class GemElement extends HTMLElement {
         }
         assignState(state, payload);
         // 避免无限刷新
-        // 挂载前 set state 不应该触发更新
         // SSR 中渲染 <gem-route>，其他情况的 SSR 应该也可以执行
-        if (!ele.#rendering && ele.#isMounted) addMicrotask(ele.#update);
+        if (!ele.#rendering) ele.#scheduleUpdate();
       });
       ele.#internals.stateList.push(state);
       return state;
@@ -378,6 +359,10 @@ export abstract class GemElement extends HTMLElement {
     // 这里认为 rest 不会有自定义字段和 ShadowRootInit 参数冲突
     this.#renderRoot = !mode ? this : this.shadowRoot || this.attachShadow({ mode, delegatesFocus, ...rest });
     this.#internals = this.attachInternals() as GemElement['internals'];
+    // 定义前添加的 ShadowRoot 对 `ElementInternals` 不可见，例如客户端填充了服务端内容的延时视图元素
+    if (this.#renderRoot !== this && !this.#internals.shadowRoot) {
+      defineProperty(this.#internals, 'shadowRoot', { value: this.#renderRoot });
+    }
     this.#internals.stateList = [];
     this.#internals.sheets = [];
 
@@ -423,10 +408,6 @@ export abstract class GemElement extends HTMLElement {
     execEffectList(this.#effectList);
   };
 
-  #execMemo = () => {
-    execEffectList(this.#memoList);
-  };
-
   /**
    * - 条件渲染
    * - 没有 `render` 时显示子内容
@@ -437,7 +418,7 @@ export abstract class GemElement extends HTMLElement {
   #render = (item?: RenderItem) => {
     try {
       this.#rendering = true;
-      this.#execMemo();
+      execEffectList(this.#memoList);
       const isLight = this.#renderRoot === this;
       const temp = item ? item.render() : isLight ? undefined : html`<slot></slot>`;
       if (temp === undefined) return;
@@ -469,15 +450,22 @@ export abstract class GemElement extends HTMLElement {
     }
   };
 
-  #update = () => {
-    // SSR 需要同步渲染
+  // `@async()` 的元素在空闲时执行，SSR 需要同步执行
+  #schedule = (task: () => void) => {
     if (this.#metadata.noBlocking && !isServer) {
-      noBlockingTaskList.add(this.#updateCallback);
+      noBlockingTaskList.add(task);
     } else {
-      this.#updateCallback();
+      task();
     }
   };
 
+  #update = () => this.#schedule(this.#updateCallback);
+
+  // 挂载前（例如 `connectedCallback` 中的 property 赋值）不需要更新，挂载时会渲染
+  #scheduleUpdate = () => {
+    if (this.#isMounted) addMicrotask(this.#update);
+  };
+
   #prepareStyle = () => {
     const { adoptedStyleSheets = [] } = this.#metadata;
     const { shadowRoot, sheets } = this.#internals;
@@ -487,7 +475,7 @@ export abstract class GemElement extends HTMLElement {
       shadowRoot.adoptedStyleSheets = clsSheets.concat(sheets);
     } else {
       this.prepend(...sheets.map((e) => e.element));
-      return appleCSSStyleSheet(this, clsSheets);
+      return adoptRootStyleSheets(this, clsSheets);
     }
   };
 
@@ -495,14 +483,7 @@ export abstract class GemElement extends HTMLElement {
    * 元素挂载后执行还未初始化的副作用
    * */
   #initEffect = () => {
-    this.#effectList?.forEach((effectItem) => {
-      const { callback, getDep, initialized } = effectItem;
-      if (!initialized) {
-        effectItem.values = getDep?.();
-        effectItem.preCallback = callback(effectItem.values);
-        effectItem.initialized = true;
-      }
-    });
+    this.#effectList.forEach((item) => !item.initialized && runEffect(item, item.getDep?.()));
   };
 
   /** @lifecycle 将来会彻底移除，现在做兼容实现*/ willMount?(): void | Promise<void>;
@@ -534,6 +515,7 @@ export abstract class GemElement extends HTMLElement {
       this.#clearStyle = this.#prepareStyle();
       return;
     }
+    if (ssrHooks.connect?.(this, this.#connectedCallback)) return;
     this.#notInCons = true;
     this.#compat();
 
@@ -546,7 +528,6 @@ export abstract class GemElement extends HTMLElement {
     if (!mode && this.#renderList.length && !penetrable) this.#internals.states.add(BoundaryCSSState);
 
     this.#disconnectStore = observedStores?.map((store) => connect(store, this.#update));
-    restoreState?.(this);
     this.#render(this.#renderItem);
     this.#isMounted = true;
     this.#clearStyle = this.#prepareStyle();
@@ -562,11 +543,7 @@ export abstract class GemElement extends HTMLElement {
    * use `@mounted`
    */
   connectedCallback(): Unique {
-    if (this.#metadata.noBlocking && !isServer) {
-      noBlockingTaskList.add(this.#connectedCallback);
-    } else {
-      this.#connectedCallback();
-    }
+    this.#schedule(this.#connectedCallback);
     return undefined as unknown as Unique;
   }
 
@@ -606,17 +583,9 @@ export abstract class GemElement extends HTMLElement {
    * ```
    * */
   effect = <K = any[] | undefined>(callback: EffectCallback<K>, getDep?: K extends any[] ? () => K : undefined) => {
-    const effectItem: EffectItem<K> = {
-      callback,
-      getDep,
-      initialized: this.#isMounted,
-      fixed: !this.#notInCons,
-    };
+    const effectItem: EffectItem<K> = { callback, getDep, fixed: !this.#notInCons };
     // 已挂载时立即执行副作用，未挂载时等挂载后执行
-    if (this.#isMounted) {
-      effectItem.values = getDep?.() as K;
-      effectItem.preCallback = callback(effectItem.values);
-    }
+    if (this.#isMounted) runEffect(effectItem, getDep?.() as K);
     this.#effectList.push(effectItem);
   };
 
@@ -649,7 +618,7 @@ export abstract class GemElement extends HTMLElement {
    * @helper
    * async
    */
-  update = () => addMicrotask(this.#update);
+  update = () => this.#scheduleUpdate();
 }
 
 // 用来禁止 connectCallback 方法被覆盖而破坏 GemElement 的功能

package/src/lib/server.ts

@@ -3,6 +3,8 @@
 // `@mantou/gem-ssr` 在加载 Gem 前提供 `__GEM_SSR__`，返回当前请求的作用域，
 // 客户端构建时 `unplugin-gem` 把 `globalThis.__GEM_SSR__` 替换成 `undefined`，SSR 代码会被压缩移除
 
+import type { GemElement } from './reactive';
+
 const { get, set, has, deleteProperty, defineProperty, getOwnPropertyDescriptor, ownKeys } = Reflect;
 
 const getRequestScope: (() => WeakMap<object, any> | undefined) | undefined = (globalThis as any).__GEM_SSR__;
@@ -10,6 +12,18 @@ const getRequestScope: (() => WeakMap<object, any> | undefined) | undefined = (g
 /** 服务端渲染时不执行副作用，同步更新 */
 export const isServer = !!getRequestScope;
 
+/** SSR 接入 Gem 的钩子，`@mantou/gem-ssr` 在服务端和客户端分别设置 */
+export const ssrHooks: {
+  /** 渲染元素内容，返回 `true` 时跳过渲染：服务端收集模版，客户端水合 */
+  render?: (value: unknown, container: HTMLElement | DocumentFragment) => boolean;
+  /** 元素挂载前调用，返回 `true` 时推迟挂载，之后调用 `connect` 挂载：客户端恢复状态，等待父模版水合 */
+  connect?: (ele: GemElement, connect: () => void) => boolean;
+  /** 创建有 key 的 store，返回初始值：客户端恢复服务端的值 */
+  createStore?: (key: string) => object | undefined;
+  /** 更新有 key 的 store：服务端记录，渲染后输出到页面中 */
+  updateStore?: (key: string, store: object) => void;
+} = {};
+
 /**
  * SSR 时返回当前请求中 `key` 对应的值，第一次访问时使用 `init` 创建，
  * 不在请求中（包括客户端）时返回 `key` 本身

package/src/lib/store.ts

@@ -1,4 +1,4 @@
-import { getRequestValue, isolate, isServer } from './server';
+import { getRequestValue, isolate, isServer, ssrHooks } from './server';
 import { addMicrotask, assignState, createUpdater, type Updater } from './utils';
 
 export type Store<T = any> = Updater<T>;
@@ -8,20 +8,6 @@ export const _StoreListenerMap = new WeakMap<Store<any>, Set<() => void>>();
 
 const createListeners = () => new Set<() => void>();
 
-// SSR 时当前请求中更新过的有 key 的 store，渲染后输出到页面中
-const updatedStores = new Map<string, Store<any>>();
-
-/** SSR 时当前请求中更新过的有 key 的 store，供 `@mantou/gem-ssr` 使用 */
-export const _getUpdatedStores = () => getRequestValue(updatedStores, () => new Map());
-
-// 客户端读取服务端渲染时 store 的值
-let restoreStore: ((key: string) => object | undefined) | undefined;
-
-/** 设置客户端恢复 store 的方法，供 `@mantou/gem-ssr` 使用 */
-export function _setStoreRestorer(restorer: typeof restoreStore) {
-  restoreStore = restorer;
-}
-
 /**
  * 创建 store，`key` 用来在 SSR 时同步服务端的值，`swc-plugin-gem` 的 `ssr` 选项会为模块顶层的 store 自动添加
  */
@@ -35,12 +21,10 @@ export function createStore<T = any>(originStore: T, key?: string) {
       if (!isServer) return;
       // SSR 时请求中添加的监听器只属于当前请求，其他请求更新 store 时不会触发
       getRequestValue(listeners, createListeners).forEach(addMicrotask);
-      const updated = _getUpdatedStores();
-      // 不在请求中时更新的是全局的值，客户端也一样
-      if (key && updated !== updatedStores) updated.set(key, store);
+      if (key) ssrHooks.updateStore?.(key, store);
     }),
   );
-  if (key && restoreStore) assignState(store, restoreStore(key));
+  if (key) assignState(store, ssrHooks.createStore?.(key));
   _StoreListenerMap.set(store, listeners);
   return store;
 }

package/src/lib/version.ts

@@ -1 +1 @@
-export const version = '2.2.15';
+export const version = '2.3.0';

package/src/test/elements/gesture.test.ts

@@ -1,6 +1,6 @@
 import type { EndEventDetail, GemGestureElement, PanEventDetail, SwipeEventDetail } from '../../elements/gesture';
 import { html } from '../../lib/element';
-import { aTimeout, expect, fixture } from '../utils';
+import { aTimeout, createFakeTimers, expect, fixture } from '../utils';
 
 import '../../elements/gesture';
 
@@ -20,6 +20,12 @@ function pointer(type: string, [timeStamp, clientX, clientY = 0]: Sample, pointe
   return event;
 }
 
+const clock = createFakeTimers();
+
+afterEach(() => {
+  clock.uninstall();
+});
+
 async function setupGesture(touchAction = '') {
   const el: GemGestureElement = await fixture(html`<gem-gesture touch-action=${touchAction}></gem-gesture>`);
   const captured = new Set<number>();
@@ -43,9 +49,9 @@ describe('GemGestureElement end', () => {
       const { el, dispatch } = await setupGesture();
       const ends: EndEventDetail[] = [];
       el.addEventListener('end', (evt: CustomEvent<EndEventDetail>) => ends.push(evt.detail));
-      const pressed = new Promise((resolve) => el.addEventListener('press', resolve, { once: true }));
+      clock.install();
       dispatch('pointerdown', [0, 0]);
-      await pressed;
+      clock.tick(251);
       const event = pointer(type, [300, 10, 20]);
       el.dispatchEvent(event);
       await Promise.resolve();
@@ -68,7 +74,9 @@ describe('GemGestureElement end', () => {
       el.addEventListener('end', (evt: CustomEvent<EndEventDetail>) => resolve(evt.detail), { once: true });
     });
     el.addEventListener('press', () => dispatch('pointerup', [300, 0]), { once: true });
+    clock.install();
     dispatch('pointerdown', [0, 0]);
+    clock.tick(251);
     expect((await ended).pressed).to.equal(true);
   });
 });
@@ -330,9 +338,9 @@ describe('GemGestureElement swipe', () => {
 
   it('does not swipe after a long press', async () => {
     const { el, swipes, dispatch } = await setupGesture();
-    const pressed = new Promise((resolve) => el.addEventListener('press', resolve, { once: true }));
+    clock.install();
     dispatch('pointerdown', [0, 0]);
-    await pressed;
+    clock.tick(251);
     dispatch('pointermove', [300, 0]);
     dispatch('pointermove', [340, 60]);
     dispatch('pointerup', [350, 60]);

package/src/test/elements/route.test.ts

@@ -0,0 +1,102 @@
+import type { GemRouteElement } from '../../elements/route';
+import { html } from '../../lib/element';
+import { history } from '../../lib/history';
+import { expect, fixture, nextFrame, waitForPopState } from '../utils';
+
+import '../../elements/route';
+
+const routes = [{ pattern: '*', content: html`<div style="height: 1000px"></div>` }];
+
+// 滚动位置在路由渲染后更新，恢复位置可能晚一个微任务，等待 `routechange` 后已经更新
+const rendered = (route: GemRouteElement) =>
+  new Promise((resolve) => route.addEventListener('routechange', resolve, { once: true }));
+
+let container: HTMLElement;
+
+async function createRoute() {
+  container = await fixture(
+    html`<div style="height: 100px; overflow: auto"><gem-route .routes=${routes}></gem-route></div>`,
+  );
+  return container.querySelector<GemRouteElement>('gem-route')!;
+}
+
+async function navigate(route: GemRouteElement, action: () => void) {
+  const promise = rendered(route);
+  action();
+  await promise;
+}
+
+describe('<gem-route> scrollContainer', () => {
+  // 所有路由共享滚动位置，避免之前的路由记录位置
+  afterEach(() => container.remove());
+
+  it('导航时滚动到顶部，后退时恢复位置，同一条历史记录重新渲染时保持位置', async () => {
+    const route = await createRoute();
+    route.scrollContainer = container;
+    await nextFrame();
+    await navigate(route, () => history.push({ path: '/scroll-a' }));
+    container.scrollTop = 300;
+    await navigate(route, () => history.push({ path: '/scroll-b' }));
+    expect(container.scrollTop).to.equal(0);
+    container.scrollTop = 100;
+    await navigate(route, () => (route.key = 1));
+    expect(container.scrollTop).to.equal(100);
+    await navigate(route, () => waitForPopState(() => history.back()));
+    expect(container.scrollTop).to.equal(300);
+  });
+
+  it('前进后退时位置未知则滚动到顶部', async () => {
+    const route = await createRoute();
+    await navigate(route, () => history.push({ path: '/scroll-c' }));
+    await navigate(route, () => history.push({ path: '/scroll-d' }));
+    route.scrollContainer = container;
+    await nextFrame();
+    container.scrollTop = 50;
+    await navigate(route, () => waitForPopState(() => history.back()));
+    expect(container.scrollTop).to.equal(0);
+  });
+
+  it('前进后退时位置未知则保持文档的滚动位置', async () => {
+    // 避免浏览器恢复滚动位置
+    window.history.scrollRestoration = 'manual';
+    document.body.style.minHeight = '3000px';
+    const route = await createRoute();
+    await navigate(route, () => history.push({ path: '/scroll-f' }));
+    await navigate(route, () => history.push({ path: '/scroll-g' }));
+    route.scrollContainer = document.scrollingElement!;
+    await nextFrame();
+    scrollTo(0, 50);
+    await navigate(route, () => waitForPopState(() => history.back()));
+    expect(scrollY).to.equal(50);
+    scrollTo(0, 0);
+    document.body.style.minHeight = '';
+    window.history.scrollRestoration = 'auto';
+  });
+
+  it('恢复位置前等待 scrollWait', async () => {
+    const route = await createRoute();
+    route.scrollContainer = container;
+    let resolve = () => {};
+    const ready = new Promise<void>((r) => (resolve = r));
+    route.scrollWait = () => ready;
+    await nextFrame();
+    await navigate(route, () => history.push({ path: '/scroll-h' }));
+    container.scrollTop = 300;
+    await navigate(route, () => history.push({ path: '/scroll-i' }));
+    expect(container.scrollTop).to.equal(0);
+    await navigate(route, () => waitForPopState(() => history.back()));
+    expect(container.scrollTop).to.equal(0);
+    resolve();
+    await ready;
+    expect(container.scrollTop).to.equal(300);
+  });
+
+  it('滚动容器为空时不滚动', async () => {
+    const route = await createRoute();
+    route.scrollContainer = () => null;
+    await nextFrame();
+    container.scrollTop = 80;
+    await navigate(route, () => history.push({ path: '/scroll-e' }));
+    expect(container.scrollTop).to.equal(80);
+  });
+});

package/src/test/elements/title.test.ts

@@ -21,5 +21,12 @@ describe('GemTitleElement', () => {
     await nextFrame();
     expect(document.title).to.equal('prefix-Page');
     expect(ele.shadowRoot!.textContent).to.equal('Page');
+
+    // 只改变 hash 时保持标题，不重复添加前缀
+    location.hash = '#a';
+    await nextFrame();
+    await nextFrame();
+    expect(document.title).to.equal('prefix-Page');
+    expect(ele.shadowRoot!.textContent).to.equal('Page');
   });
 });