@neut/ui 0.0.17 → 0.0.18

package/dist/components/message-scroller/message-scroller.anchoring.d.ts

@@ -0,0 +1,60 @@
+import { Accessor } from 'solid-js';
+import { DomMeasure } from './message-scroller.dom-measure';
+import { ScrollCommands } from './message-scroller.commands';
+import { ScrollState } from './message-scroller.scroll-state';
+import { MessageScrollerProviderProps, MessageScrollerScrollOptions } from './message-scroller.types';
+type EngineOptions = Required<Omit<MessageScrollerProviderProps, "children">>;
+/**
+ * 锚定与保位。
+ *
+ * 单一职责：决定"内容变了之后该滚到哪里"——初次定位、prepend 保位、
+ * 新回合锚定、回复生长的原地重锚定、以及 `scrollToMessage` 的排队补滚。
+ * 它只调用 `ScrollCommands` 的命令，自己不写 `scrollTop`、不读 IO。
+ *
+ * 之所以独立成块：这 200 行里全是**判断**（行数变没变、首个可见行是否被挤下去、
+ * 新锚点是一个还是一批、锚点是否已处理过），而几何与模式迁移都在别的模块里，
+ * 拆开后这些判断可以单独表述。
+ */
+export interface AnchoringOptions {
+    viewport: Accessor<HTMLElement | undefined>;
+    content: Accessor<HTMLElement | undefined>;
+    options: () => EngineOptions;
+    measure: DomMeasure;
+    commands: ScrollCommands;
+    state: ScrollState;
+    /** 分帧提交滚动状态（`scroll-state.schedule`） */
+    scheduleState: () => void;
+    /** 立即提交滚动状态（`scroll-state.commit`） */
+    commitState: () => void;
+    /** 同步一次可见性 */
+    scheduleVisibility: () => void;
+    /** Viewport 的 prop：上方插入历史时是否保持可见行 */
+    preserveScrollOnPrepend: Accessor<boolean>;
+    /** 查询某个 id 是否已挂载（行注册表由引擎持有） */
+    getMessageElement: (id: string) => HTMLElement | undefined;
+}
+export interface Anchoring {
+    /** 是否要在应用定位前用 `data-pending-scroll` 遮住视口 */
+    pendingScroll: Accessor<boolean>;
+    scrollToStart: (command?: MessageScrollerScrollOptions) => boolean;
+    scrollToEnd: (command?: MessageScrollerScrollOptions) => boolean;
+    scrollToElement: (element: HTMLElement, command?: MessageScrollerScrollOptions, options?: {
+        keepPreviousPeek?: boolean;
+    }) => boolean;
+    scrollToMessage: (messageId: string, command?: MessageScrollerScrollOptions) => boolean;
+    /** 回复生长时把锚定行原地固定回阅读线 */
+    reanchorToAnchoredMessage: () => boolean;
+    /** 内容子元素变化（MutationObserver / 初次挂载） */
+    handleContentChange: () => void;
+    /** 尺寸变化（ResizeObserver） */
+    handleResize: () => void;
+    /** 滚动之后：提交状态 + 同步可见性 + 重记 prepend 锚点 */
+    syncAfterScroll: () => void;
+    /** 记忆首个可见行（prepend 保位用） */
+    capturePrependAnchor: () => void;
+    /** 某一行注册进来时调用：若正在等它，排一次补滚 */
+    notifyMessageRegistered: (id: string) => void;
+    dispose: () => void;
+}
+export declare function createAnchoring(options: AnchoringOptions): Anchoring;
+export {};

package/dist/components/message-scroller/message-scroller.anchoring.js

@@ -0,0 +1,139 @@
+import { firstAnchorFrom as e, firstUnhandledAnchor as t, hasMultipleAnchorsFrom as n } from "./message-scroller.anchors.js";
+import "./message-scroller.utils.js";
+import { createSignal as r } from "solid-js";
+//#region src/components/message-scroller/message-scroller.anchoring.ts
+function i(i) {
+	let [a, o] = r(i.options().defaultScrollPosition !== "start"), s = /* @__PURE__ */ new WeakSet(), c = 0, l = null, u = !1, d = null, f = null, p = null, m = null, h = () => {
+		let e = i.viewport();
+		if (!e) {
+			p = null;
+			return;
+		}
+		let t = e.getBoundingClientRect(), n = i.measure.items().find((e) => {
+			if (!e.dataset.messageId) return !1;
+			let n = e.getBoundingClientRect();
+			return n.bottom > t.top && n.top < t.bottom;
+		}) ?? null;
+		p = n ? {
+			element: n,
+			viewportTop: i.measure.itemTopInViewport(n)
+		} : null;
+	}, g = () => {
+		let e = p, t = i.viewport();
+		if (!e || !t || !e.element.isConnected) return !1;
+		let n = i.measure.itemTopInViewport(e.element) - e.viewportTop;
+		return Math.abs(n) <= .5 ? !1 : (t.scrollTop += n, e.viewportTop = i.measure.itemTopInViewport(e.element), i.scheduleState(), i.scheduleVisibility(), !0);
+	}, _ = (e) => (d = null, i.commands.scrollToStart(e)), v = (e) => (d = null, i.commands.scrollToEnd(e)), y = (e, t, { keepPreviousPeek: n = !1 } = {}) => i.commands.scrollToElement(e, t, { keepPreviousPeek: n }) ? (p = {
+		element: e,
+		viewportTop: i.measure.itemTopInViewport(e)
+	}, d = n ? e : null, !0) : !1, b = () => {
+		let e = d;
+		return !e?.isConnected || !i.state.isAnchored() ? !1 : y(e, { align: "start" }, { keepPreviousPeek: !0 });
+	}, x = () => {
+		let e = i.viewport();
+		if (!e || u || c === 0) return !1;
+		let t = i.options().defaultScrollPosition, n = !1;
+		if (t === "last-anchor") {
+			let t = [...i.measure.items()].reverse().find((e) => e.dataset.scrollAnchor === "true") ?? null;
+			n = t ? i.measure.contentBottom() - i.measure.itemOffsetTop(t) <= e.clientHeight ? v({ behavior: "auto" }) : y(t, { align: "start" }, { keepPreviousPeek: !0 }) : v({ behavior: "auto" });
+		} else n = t === "end" ? v({ behavior: "auto" }) : _({ behavior: "auto" });
+		return n && (u = !0, o(!1)), n;
+	}, S = () => {
+		let e = f;
+		if (!e) return !1;
+		let t = i.getMessageElement(e.id);
+		return !t || !y(t, e.options) ? !1 : (f = null, u = !0, o(!1), !0);
+	}, C = () => {
+		m === null && (m = window.requestAnimationFrame(() => {
+			m = null, S() && h();
+		}));
+	};
+	return {
+		pendingScroll: a,
+		scrollToStart: _,
+		scrollToEnd: v,
+		scrollToElement: y,
+		scrollToMessage: (e, t) => {
+			let n = i.getMessageElement(e);
+			return n ? y(n, t) ? (f = null, !0) : (f = {
+				id: e,
+				options: t
+			}, !0) : c === 0 && (f = {
+				id: e,
+				options: t
+			}, o(!1), !0);
+		},
+		reanchorToAnchoredMessage: b,
+		handleContentChange: () => {
+			if (!i.content()) return;
+			let r = i.measure.items(), a = c, u = l;
+			if (c = r.length, l = r[0] ?? null, r.length === 0 && o(!1), S()) {
+				h();
+				return;
+			}
+			if (a === 0) {
+				for (let e of r) e.dataset.scrollAnchor === "true" && s.add(e);
+				if (x()) {
+					h();
+					return;
+				}
+				if (r.length > 0 && i.options().autoScroll && v({ behavior: "auto" })) {
+					h();
+					return;
+				}
+				i.commitState(), i.scheduleVisibility(), h();
+				return;
+			}
+			let d = r.indexOf(u);
+			if (i.preserveScrollOnPrepend() && d > 0) {
+				g(), h();
+				return;
+			}
+			if (r.length > a) {
+				let t = e(r, a);
+				if (t) {
+					if (i.options().autoScroll && i.state.isFollowing() && n(r, a)) {
+						v({ behavior: "auto" }), h();
+						return;
+					}
+					y(t, { align: "start" }, { keepPreviousPeek: !0 }), s.add(t), h();
+					return;
+				}
+			}
+			if (r.length === a) {
+				let e = t(r, s);
+				if (e) {
+					y(e, { align: "start" }, { keepPreviousPeek: !0 }), s.add(e), h();
+					return;
+				}
+			}
+			i.state.isFollowing() && i.options().autoScroll ? v({ behavior: "auto" }) : (i.commitState(), i.scheduleVisibility()), h();
+		},
+		handleResize: () => {
+			if (i.state.isFollowing() && i.options().autoScroll) {
+				v({ behavior: "auto" });
+				return;
+			}
+			let e = i.commands.spacerHeight();
+			if (b()) {
+				i.options().autoScroll && e > 0 && i.commands.spacerHeight() === 0 && v({ behavior: "auto" });
+				return;
+			}
+			i.scheduleState(), i.scheduleVisibility();
+		},
+		syncAfterScroll: () => {
+			i.commitState(), i.scheduleVisibility(), h();
+		},
+		capturePrependAnchor: h,
+		notifyMessageRegistered(e) {
+			f?.id === e && C();
+		},
+		dispose() {
+			m !== null && (window.cancelAnimationFrame(m), m = null);
+		}
+	};
+}
+//#endregion
+export { i as createAnchoring };
+
+//# sourceMappingURL=message-scroller.anchoring.js.map

package/dist/components/message-scroller/message-scroller.anchoring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.anchoring.js","names":["createAnchoring","pendingScroll","setPendingScroll","createSignal","options","handledScrollAnchors","itemCount","firstItem","defaultApplied","streamingTurn","pendingMessage","prependAnchor","pendingFrame","capturePrependAnchor","viewport","viewportRect","firstVisible","element","rect","restorePrependAnchor","anchor","delta","scrollToStart","command","scrollToEnd","scrollToElement","keepPreviousPeek","reanchorToAnchoredMessage","applyDefaultScrollPosition","position","applied","lastAnchor","el","flushPendingScrollToMessage","pending","schedulePendingFlush","messageId","list","previousCount","previousFirst","previousFirstIndex","firstNewAnchor","firstAnchorFrom","hasMultipleAnchorsFrom","unhandled","firstUnhandledAnchor","before","id"],"sources":["../../../src/components/message-scroller/message-scroller.anchoring.ts"],"sourcesContent":["import { createSignal, type Accessor } from \"solid-js\";\nimport {\n  firstAnchorFrom,\n  firstUnhandledAnchor,\n  hasMultipleAnchorsFrom,\n} from \"./message-scroller.anchors\";\nimport type { DomMeasure } from \"./message-scroller.dom-measure\";\nimport type { ScrollCommands } from \"./message-scroller.commands\";\nimport type { ScrollState } from \"./message-scroller.scroll-state\";\nimport type {\n  MessageScrollerProviderProps,\n  MessageScrollerScrollOptions,\n} from \"./message-scroller.types\";\nimport { AT_EDGE_TOLERANCE } from \"./message-scroller.utils\";\n\ntype EngineOptions = Required<Omit<MessageScrollerProviderProps, \"children\">>;\n\n/**\n * 锚定与保位。\n *\n * 单一职责：决定\"内容变了之后该滚到哪里\"——初次定位、prepend 保位、\n * 新回合锚定、回复生长的原地重锚定、以及 `scrollToMessage` 的排队补滚。\n * 它只调用 `ScrollCommands` 的命令，自己不写 `scrollTop`、不读 IO。\n *\n * 之所以独立成块：这 200 行里全是**判断**（行数变没变、首个可见行是否被挤下去、\n * 新锚点是一个还是一批、锚点是否已处理过），而几何与模式迁移都在别的模块里，\n * 拆开后这些判断可以单独表述。\n */\nexport interface AnchoringOptions {\n  viewport: Accessor<HTMLElement | undefined>;\n  content: Accessor<HTMLElement | undefined>;\n  options: () => EngineOptions;\n  measure: DomMeasure;\n  commands: ScrollCommands;\n  state: ScrollState;\n  /** 分帧提交滚动状态（`scroll-state.schedule`） */\n  scheduleState: () => void;\n  /** 立即提交滚动状态（`scroll-state.commit`） */\n  commitState: () => void;\n  /** 同步一次可见性 */\n  scheduleVisibility: () => void;\n  /** Viewport 的 prop：上方插入历史时是否保持可见行 */\n  preserveScrollOnPrepend: Accessor<boolean>;\n  /** 查询某个 id 是否已挂载（行注册表由引擎持有） */\n  getMessageElement: (id: string) => HTMLElement | undefined;\n}\n\nexport interface Anchoring {\n  /** 是否要在应用定位前用 `data-pending-scroll` 遮住视口 */\n  pendingScroll: Accessor<boolean>;\n  scrollToStart: (command?: MessageScrollerScrollOptions) => boolean;\n  scrollToEnd: (command?: MessageScrollerScrollOptions) => boolean;\n  scrollToElement: (\n    element: HTMLElement,\n    command?: MessageScrollerScrollOptions,\n    options?: { keepPreviousPeek?: boolean },\n  ) => boolean;\n  scrollToMessage: (\n    messageId: string,\n    command?: MessageScrollerScrollOptions,\n  ) => boolean;\n  /** 回复生长时把锚定行原地固定回阅读线 */\n  reanchorToAnchoredMessage: () => boolean;\n  /** 内容子元素变化（MutationObserver / 初次挂载） */\n  handleContentChange: () => void;\n  /** 尺寸变化（ResizeObserver） */\n  handleResize: () => void;\n  /** 滚动之后：提交状态 + 同步可见性 + 重记 prepend 锚点 */\n  syncAfterScroll: () => void;\n  /** 记忆首个可见行（prepend 保位用） */\n  capturePrependAnchor: () => void;\n  /** 某一行注册进来时调用：若正在等它，排一次补滚 */\n  notifyMessageRegistered: (id: string) => void;\n  dispose: () => void;\n}\n\nexport function createAnchoring(options: AnchoringOptions): Anchoring {\n  const [pendingScroll, setPendingScroll] = createSignal(\n    options.options().defaultScrollPosition !== \"start\",\n  );\n\n  const handledScrollAnchors = new WeakSet<HTMLElement>();\n  let itemCount = 0;\n  let firstItem: HTMLElement | null = null;\n  let defaultApplied = false;\n  /** 当前\"锚定/正在生长\"的那一行（原地重锚定的目标） */\n  let streamingTurn: HTMLElement | null = null;\n  let pendingMessage: {\n    id: string;\n    options?: MessageScrollerScrollOptions;\n  } | null = null;\n  /** 首个可见行及其视口位置（prepend 保位用） */\n  let prependAnchor: { element: HTMLElement; viewportTop: number } | null =\n    null;\n  let pendingFrame: number | null = null;\n\n  const capturePrependAnchor = () => {\n    const viewport = options.viewport();\n    if (!viewport) {\n      prependAnchor = null;\n      return;\n    }\n    const viewportRect = viewport.getBoundingClientRect();\n    const firstVisible =\n      options.measure.items().find((element) => {\n        if (!element.dataset.messageId) return false;\n        const rect = element.getBoundingClientRect();\n        return rect.bottom > viewportRect.top && rect.top < viewportRect.bottom;\n      }) ?? null;\n    prependAnchor = firstVisible\n      ? {\n          element: firstVisible,\n          viewportTop: options.measure.itemTopInViewport(firstVisible),\n        }\n      : null;\n  };\n\n  const restorePrependAnchor = () => {\n    const anchor = prependAnchor;\n    const viewport = options.viewport();\n    if (!anchor || !viewport || !anchor.element.isConnected) return false;\n\n    // 按\"首个可见行相对视口的位移\"补偿，而不是猜测高度差\n    const delta =\n      options.measure.itemTopInViewport(anchor.element) - anchor.viewportTop;\n    if (Math.abs(delta) <= AT_EDGE_TOLERANCE) return false;\n\n    viewport.scrollTop += delta;\n    anchor.viewportTop = options.measure.itemTopInViewport(anchor.element);\n    options.scheduleState();\n    options.scheduleVisibility();\n    return true;\n  };\n\n  /** 命令包装：命令负责滚动与 spacer，这里负责锚定状态（prependAnchor / streamingTurn） */\n  const scrollToStart = (command?: MessageScrollerScrollOptions) => {\n    streamingTurn = null;\n    return options.commands.scrollToStart(command);\n  };\n\n  const scrollToEnd = (command?: MessageScrollerScrollOptions) => {\n    streamingTurn = null;\n    return options.commands.scrollToEnd(command);\n  };\n\n  const scrollToElement: Anchoring[\"scrollToElement\"] = (\n    element,\n    command,\n    { keepPreviousPeek = false } = {},\n  ) => {\n    const ok = options.commands.scrollToElement(element, command, {\n      keepPreviousPeek,\n    });\n    if (!ok) return false;\n\n    prependAnchor = {\n      element,\n      viewportTop: options.measure.itemTopInViewport(element),\n    };\n    streamingTurn = keepPreviousPeek ? element : null;\n    return true;\n  };\n\n  const reanchorToAnchoredMessage = () => {\n    const element = streamingTurn;\n    if (!element?.isConnected || !options.state.isAnchored()) return false;\n    return scrollToElement(\n      element,\n      { align: \"start\" },\n      { keepPreviousPeek: true },\n    );\n  };\n\n  const applyDefaultScrollPosition = () => {\n    const viewport = options.viewport();\n    if (!viewport || defaultApplied || itemCount === 0) return false;\n\n    const position = options.options().defaultScrollPosition;\n    let applied = false;\n    if (position === \"last-anchor\") {\n      const list = options.measure.items();\n      const lastAnchor =\n        [...list].reverse().find((el) => el.dataset.scrollAnchor === \"true\") ??\n        null;\n      if (!lastAnchor) {\n        applied = scrollToEnd({ behavior: \"auto\" });\n      } else if (\n        options.measure.contentBottom() -\n          options.measure.itemOffsetTop(lastAnchor) <=\n        viewport.clientHeight\n      ) {\n        // 该回合完全放得下 → 直接到底\n        applied = scrollToEnd({ behavior: \"auto\" });\n      } else {\n        applied = scrollToElement(\n          lastAnchor,\n          { align: \"start\" },\n          { keepPreviousPeek: true },\n        );\n      }\n    } else if (position === \"end\") {\n      applied = scrollToEnd({ behavior: \"auto\" });\n    } else {\n      applied = scrollToStart({ behavior: \"auto\" });\n    }\n\n    if (applied) {\n      defaultApplied = true;\n      setPendingScroll(false);\n    }\n    return applied;\n  };\n\n  const flushPendingScrollToMessage = () => {\n    const pending = pendingMessage;\n    if (!pending) return false;\n\n    const element = options.getMessageElement(pending.id);\n    if (!element || !scrollToElement(element, pending.options)) return false;\n\n    pendingMessage = null;\n    defaultApplied = true;\n    setPendingScroll(false);\n    return true;\n  };\n\n  const schedulePendingFlush = () => {\n    if (pendingFrame !== null) return;\n    pendingFrame = window.requestAnimationFrame(() => {\n      pendingFrame = null;\n      if (flushPendingScrollToMessage()) capturePrependAnchor();\n    });\n  };\n\n  const scrollToMessage: Anchoring[\"scrollToMessage\"] = (\n    messageId,\n    command,\n  ) => {\n    const element = options.getMessageElement(messageId);\n    if (element) {\n      if (scrollToElement(element, command)) {\n        pendingMessage = null;\n        return true;\n      }\n      pendingMessage = { id: messageId, options: command };\n      return true;\n    }\n    // 会话尚未挂载任何行时可排队（客户端解析永久链接）；已挂载但缺失则返回 false\n    if (itemCount === 0) {\n      pendingMessage = { id: messageId, options: command };\n      setPendingScroll(false);\n      return true;\n    }\n    return false;\n  };\n\n  const handleContentChange = () => {\n    const content = options.content();\n    if (!content) return;\n\n    const list = options.measure.items();\n    const previousCount = itemCount;\n    const previousFirst = firstItem;\n    itemCount = list.length;\n    firstItem = list[0] ?? null;\n\n    // 空会话不隐藏视口（data-pending-scroll 跳过）\n    if (list.length === 0) setPendingScroll(false);\n\n    if (flushPendingScrollToMessage()) {\n      capturePrependAnchor();\n      return;\n    }\n\n    if (previousCount === 0) {\n      // 初次定位时把已存在的锚点标记为已处理，避免后续 resize/属性变化误触发重锚定\n      for (const element of list) {\n        if (element.dataset.scrollAnchor === \"true\") {\n          handledScrollAnchors.add(element);\n        }\n      }\n      if (applyDefaultScrollPosition()) {\n        capturePrependAnchor();\n        return;\n      }\n      if (\n        list.length > 0 &&\n        options.options().autoScroll &&\n        scrollToEnd({ behavior: \"auto\" })\n      ) {\n        capturePrependAnchor();\n        return;\n      }\n      options.commitState();\n      options.scheduleVisibility();\n      capturePrependAnchor();\n      return;\n    }\n\n    // 走到这里说明 previousCount > 0：上一次测量时列表非空，而那次已经把\n    // firstItem 设成了当时的首项，因此 previousFirst 必然非空，无需再兜底。\n    const previousFirstIndex = list.indexOf(previousFirst as HTMLElement);\n    if (options.preserveScrollOnPrepend() && previousFirstIndex > 0) {\n      restorePrependAnchor();\n      capturePrependAnchor();\n      return;\n    }\n\n    if (list.length > previousCount) {\n      const firstNewAnchor = firstAnchorFrom(list, previousCount);\n      if (firstNewAnchor) {\n        // 同批新增多个锚点：跟随底部，避免在多个锚点间跳来跳去\n        if (\n          options.options().autoScroll &&\n          options.state.isFollowing() &&\n          hasMultipleAnchorsFrom(list, previousCount)\n        ) {\n          scrollToEnd({ behavior: \"auto\" });\n          capturePrependAnchor();\n          return;\n        }\n        scrollToElement(\n          firstNewAnchor,\n          { align: \"start\" },\n          { keepPreviousPeek: true },\n        );\n        handledScrollAnchors.add(firstNewAnchor);\n        capturePrependAnchor();\n        return;\n      }\n    }\n\n    // 行数没变但出现了未处理的新锚点（例如给已有行打开 scrollAnchor）\n    if (list.length === previousCount) {\n      const unhandled = firstUnhandledAnchor(list, handledScrollAnchors);\n      if (unhandled) {\n        scrollToElement(\n          unhandled,\n          { align: \"start\" },\n          { keepPreviousPeek: true },\n        );\n        handledScrollAnchors.add(unhandled);\n        capturePrependAnchor();\n        return;\n      }\n    }\n\n    if (options.state.isFollowing() && options.options().autoScroll) {\n      scrollToEnd({ behavior: \"auto\" });\n    } else {\n      options.commitState();\n      options.scheduleVisibility();\n    }\n    capturePrependAnchor();\n  };\n\n  const handleResize = () => {\n    if (options.state.isFollowing() && options.options().autoScroll) {\n      scrollToEnd({ behavior: \"auto\" });\n      return;\n    }\n    const before = options.commands.spacerHeight();\n    if (reanchorToAnchoredMessage()) {\n      if (\n        options.options().autoScroll &&\n        before > 0 &&\n        options.commands.spacerHeight() === 0\n      ) {\n        scrollToEnd({ behavior: \"auto\" });\n      }\n      return;\n    }\n    options.scheduleState();\n    options.scheduleVisibility();\n  };\n\n  const syncAfterScroll = () => {\n    options.commitState();\n    options.scheduleVisibility();\n    capturePrependAnchor();\n  };\n\n  return {\n    pendingScroll,\n    scrollToStart,\n    scrollToEnd,\n    scrollToElement,\n    scrollToMessage,\n    reanchorToAnchoredMessage,\n    handleContentChange,\n    handleResize,\n    syncAfterScroll,\n    capturePrependAnchor,\n    notifyMessageRegistered(id) {\n      if (pendingMessage?.id === id) schedulePendingFlush();\n    },\n    dispose() {\n      if (pendingFrame !== null) {\n        window.cancelAnimationFrame(pendingFrame);\n        pendingFrame = null;\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/components/message-scroller/message-scroller.anchors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MessageScroller 的滚动锚点查找。
+ *
+ * 单一职责：在「已知的行列表」上判断哪些行是锚点（`data-scroll-anchor="true"`）。
+ * 纯函数、不碰 DOM 读写，因此可独立单测。
+ */
+/** 从 `from` 开始往后找第一个锚点行（找不到返回 null） */
+export declare function firstAnchorFrom(list: HTMLElement[], from: number): HTMLElement | null;
+/** 从前往后找第一个「还没被处理过」的锚点行（找不到返回 null） */
+export declare function firstUnhandledAnchor(list: HTMLElement[], handled: WeakSet<HTMLElement>): HTMLElement | null;
+/** 从 `from` 开始，后面是否还有第二个锚点（用于「同批多个新锚点 → 直接跟随底部」） */
+export declare function hasMultipleAnchorsFrom(list: HTMLElement[], from: number): boolean;

package/dist/components/message-scroller/message-scroller.anchors.js

@@ -0,0 +1,23 @@
+//#region src/components/message-scroller/message-scroller.anchors.ts
+function e(e) {
+	return e.dataset.scrollAnchor === "true";
+}
+function t(t, n) {
+	for (let r = n; r < t.length; r += 1) {
+		let n = t[r];
+		if (n && e(n)) return n;
+	}
+	return null;
+}
+function n(t, n) {
+	return t.find((t) => e(t) && !n.has(t)) ?? null;
+}
+function r(t, n) {
+	let r = 0;
+	for (let i = n; i < t.length; i += 1) if (t[i] && e(t[i]) && (r += 1, r > 1)) return !0;
+	return !1;
+}
+//#endregion
+export { t as firstAnchorFrom, n as firstUnhandledAnchor, r as hasMultipleAnchorsFrom };
+
+//# sourceMappingURL=message-scroller.anchors.js.map

package/dist/components/message-scroller/message-scroller.anchors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.anchors.js","names":["isAnchor","element","firstAnchorFrom","index","from","list","firstUnhandledAnchor","handled","hasMultipleAnchorsFrom","count"],"sources":["../../../src/components/message-scroller/message-scroller.anchors.ts"],"sourcesContent":["/**\n * MessageScroller 的滚动锚点查找。\n *\n * 单一职责：在「已知的行列表」上判断哪些行是锚点（`data-scroll-anchor=\"true\"`）。\n * 纯函数、不碰 DOM 读写，因此可独立单测。\n */\n\n/** 行的 `data-scroll-anchor` 是否为 true */\nfunction isAnchor(element: HTMLElement): boolean {\n  return element.dataset.scrollAnchor === \"true\";\n}\n\n/** 从 `from` 开始往后找第一个锚点行（找不到返回 null） */\nexport function firstAnchorFrom(\n  list: HTMLElement[],\n  from: number,\n): HTMLElement | null {\n  for (let index = from; index < list.length; index += 1) {\n    const element = list[index];\n    if (element && isAnchor(element)) return element;\n  }\n  return null;\n}\n\n/** 从前往后找第一个「还没被处理过」的锚点行（找不到返回 null） */\nexport function firstUnhandledAnchor(\n  list: HTMLElement[],\n  handled: WeakSet<HTMLElement>,\n): HTMLElement | null {\n  return (\n    list.find((element) => isAnchor(element) && !handled.has(element)) ?? null\n  );\n}\n\n/** 从 `from` 开始，后面是否还有第二个锚点（用于「同批多个新锚点 → 直接跟随底部」） */\nexport function hasMultipleAnchorsFrom(\n  list: HTMLElement[],\n  from: number,\n): boolean {\n  let count = 0;\n  for (let index = from; index < list.length; index += 1) {\n    if (list[index] && isAnchor(list[index])) {\n      count += 1;\n      if (count > 1) return true;\n    }\n  }\n  return false;\n}\n"],"mappings":";AAQA,SAASA,EAAS,GAA+B;CAC/C,OAAOC,EAAQ,QAAQ,iBAAiB;AAC1C;AAGA,SAAgBC,EACd,GACA,GACoB;CACpB,KAAK,IAAIC,IAAQC,GAAMD,IAAQE,EAAK,QAAQ,KAAS,GAAG;EACtD,IAAMJ,IAAUI,EAAKF;EACrB,IAAIF,KAAWD,EAASC,CAAO,GAAG,OAAOA;CAC3C;CACA,OAAO;AACT;AAGA,SAAgBK,EACd,GACA,GACoB;CACpB,OACED,EAAK,MAAM,MAAYL,EAASC,CAAO,KAAK,CAACM,EAAQ,IAAIN,CAAO,CAAC,KAAK;AAE1E;AAGA,SAAgBO,EACd,GACA,GACS;CACT,IAAIC,IAAQ;CACZ,KAAK,IAAIN,IAAQC,GAAMD,IAAQE,EAAK,QAAQ,KAAS,GACnD,IAAIA,EAAKF,MAAUH,EAASK,EAAKF,EAAM,MACrC,KAAS,GACLM,IAAQ,IAAG,OAAO;CAG1B,OAAO;AACT"}

package/dist/components/message-scroller/message-scroller.commands.d.ts

@@ -0,0 +1,43 @@
+import { Accessor } from 'solid-js';
+import { DomMeasure } from './message-scroller.dom-measure';
+import { ScrollState } from './message-scroller.scroll-state';
+import { MessageScrollerProviderProps, MessageScrollerScrollOptions } from './message-scroller.types';
+type EngineOptions = Required<Omit<MessageScrollerProviderProps, "children">>;
+/**
+ * 滚动命令与尾部 spacer。
+ *
+ * 单一职责：把"滚到哪里"变成一次 `scrollTop` 写入，并按需设置尾部 spacer
+ * （让靠近结尾的行也能滚到顶部）。模式的迁移通过 `ScrollState` 的语义化方法
+ * 表达；锚定状态（prependAnchor / streamingTurn）不在本模块里，由调用方
+ * （anchoring）在命令返回后自行记录。
+ *
+ * `setScrollTop` 的两条路径对应上游语义：位移在容差内就直接赋值（避免一次毫无
+ * 意义的滚动动画），否则交给浏览器滚动并在下一帧提交状态。
+ */
+export interface ScrollCommandsOptions {
+    viewport: Accessor<HTMLElement | undefined>;
+    content: Accessor<HTMLElement | undefined>;
+    /** 尾部 spacer 元素（信号由引擎持有，与 `dom-measure` 共用） */
+    spacer: Accessor<HTMLElement | undefined>;
+    options: () => EngineOptions;
+    measure: DomMeasure;
+    state: ScrollState;
+    /** 同步一次可见性（滚动后阅读行会变） */
+    scheduleVisibility: () => void;
+}
+export interface ScrollCommands {
+    spacerHeight: () => number;
+    setScrollTop: (top: number, options?: {
+        behavior?: ScrollBehavior;
+        auto?: boolean;
+    }) => void;
+    /** 计算"滚到某一行"的目标位置（供外部换算，如初始定位的放得下判断） */
+    targetTopFor: (element: HTMLElement, command: MessageScrollerScrollOptions | undefined, margin: number) => number;
+    scrollToStart: (command?: MessageScrollerScrollOptions) => boolean;
+    scrollToEnd: (command?: MessageScrollerScrollOptions) => boolean;
+    scrollToElement: (element: HTMLElement, command?: MessageScrollerScrollOptions, options?: {
+        keepPreviousPeek?: boolean;
+    }) => boolean;
+}
+export declare function createScrollCommands(options: ScrollCommandsOptions): ScrollCommands;
+export {};

package/dist/components/message-scroller/message-scroller.commands.js

@@ -0,0 +1,51 @@
+import { rowGap as e } from "./message-scroller.measure.js";
+import "./message-scroller.utils.js";
+import { targetTopFor as t } from "./message-scroller.scroll-target.js";
+//#region src/components/message-scroller/message-scroller.commands.ts
+function n(n) {
+	let r = 0, i = () => e(n.spacer()?.parentElement ?? null), a = (e) => {
+		let t = n.spacer();
+		if (!t) return;
+		let a = Math.max(0, Math.ceil(e));
+		r !== a && (r = a, t.hidden = a === 0, t.style.height = `${a}px`, t.style.marginTop = a > 0 ? `${-i()}px` : "");
+	}, o = (e, { behavior: t = "auto", auto: r = !1 } = {}) => {
+		let i = n.viewport();
+		if (!i) return;
+		let a = Math.max(0, e);
+		if (Math.abs(i.scrollTop - a) <= .5) {
+			i.scrollTop = a, n.state.commit();
+			return;
+		}
+		r && n.state.beginAutoScroll(), i.scrollTo({
+			top: a,
+			behavior: t
+		}), n.state.schedule();
+	}, s = (e, r, i) => {
+		let a = n.viewport();
+		return a ? t(e, r, i, a, n.content(), n.measure.itemOffsetTop) : 0;
+	};
+	return {
+		spacerHeight: () => r,
+		setScrollTop: o,
+		targetTopFor: s,
+		scrollToStart(e) {
+			return n.viewport() ? (a(0), n.state.setFree(), o(0, { behavior: e?.behavior ?? "auto" }), n.scheduleVisibility(), !0) : !1;
+		},
+		scrollToEnd(e) {
+			return n.viewport() ? (a(0), n.options().autoScroll ? n.state.setFollowing() : n.state.setFree(), o(n.measure.maxScrollTop(), {
+				behavior: e?.behavior ?? "auto",
+				auto: !0
+			}), n.scheduleVisibility(), !0) : !1;
+		},
+		scrollToElement(e, t, { keepPreviousPeek: r = !1 } = {}) {
+			let i = n.viewport(), c = n.content();
+			if (!i || !c?.contains(e)) return !1;
+			let l = (t?.scrollMargin ?? n.options().scrollMargin) + (r ? n.options().scrollPreviousItemPeek : 0), u = s(e, t, l);
+			return a(Math.max(0, u + i.clientHeight - n.measure.contentBottom())), r ? n.state.anchorTo() : n.state.settleJump(), o(u, { behavior: t?.behavior ?? "auto" }), n.scheduleVisibility(), !0;
+		}
+	};
+}
+//#endregion
+export { n as createScrollCommands };
+
+//# sourceMappingURL=message-scroller.commands.js.map

package/dist/components/message-scroller/message-scroller.commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.commands.js","names":["targetTopFor","computeTargetTopFor","createScrollCommands","spacerHeightValue","spacerGap","rowGap","options","setSpacerHeight","spacer","next","height","setScrollTop","viewport","top","auto","targetTopFor$1","targetTopFor","element","command","margin","content","keepPreviousPeek","target"],"sources":["../../../src/components/message-scroller/message-scroller.commands.ts"],"sourcesContent":["import type { Accessor } from \"solid-js\";\nimport type { DomMeasure } from \"./message-scroller.dom-measure\";\nimport { rowGap } from \"./message-scroller.measure\";\nimport type { ScrollState } from \"./message-scroller.scroll-state\";\nimport { targetTopFor as computeTargetTopFor } from \"./message-scroller.scroll-target\";\nimport type {\n  MessageScrollerProviderProps,\n  MessageScrollerScrollOptions,\n} from \"./message-scroller.types\";\nimport { AT_EDGE_TOLERANCE } from \"./message-scroller.utils\";\n\ntype EngineOptions = Required<Omit<MessageScrollerProviderProps, \"children\">>;\n\n/**\n * 滚动命令与尾部 spacer。\n *\n * 单一职责：把\"滚到哪里\"变成一次 `scrollTop` 写入，并按需设置尾部 spacer\n * （让靠近结尾的行也能滚到顶部）。模式的迁移通过 `ScrollState` 的语义化方法\n * 表达；锚定状态（prependAnchor / streamingTurn）不在本模块里，由调用方\n * （anchoring）在命令返回后自行记录。\n *\n * `setScrollTop` 的两条路径对应上游语义：位移在容差内就直接赋值（避免一次毫无\n * 意义的滚动动画），否则交给浏览器滚动并在下一帧提交状态。\n */\nexport interface ScrollCommandsOptions {\n  viewport: Accessor<HTMLElement | undefined>;\n  content: Accessor<HTMLElement | undefined>;\n  /** 尾部 spacer 元素（信号由引擎持有，与 `dom-measure` 共用） */\n  spacer: Accessor<HTMLElement | undefined>;\n  options: () => EngineOptions;\n  measure: DomMeasure;\n  state: ScrollState;\n  /** 同步一次可见性（滚动后阅读行会变） */\n  scheduleVisibility: () => void;\n}\n\nexport interface ScrollCommands {\n  spacerHeight: () => number;\n  setScrollTop: (\n    top: number,\n    options?: { behavior?: ScrollBehavior; auto?: boolean },\n  ) => void;\n  /** 计算\"滚到某一行\"的目标位置（供外部换算，如初始定位的放得下判断） */\n  targetTopFor: (\n    element: HTMLElement,\n    command: MessageScrollerScrollOptions | undefined,\n    margin: number,\n  ) => number;\n  scrollToStart: (command?: MessageScrollerScrollOptions) => boolean;\n  scrollToEnd: (command?: MessageScrollerScrollOptions) => boolean;\n  scrollToElement: (\n    element: HTMLElement,\n    command?: MessageScrollerScrollOptions,\n    options?: { keepPreviousPeek?: boolean },\n  ) => boolean;\n}\n\nexport function createScrollCommands(\n  options: ScrollCommandsOptions,\n): ScrollCommands {\n  let spacerHeightValue = 0;\n\n  /**\n   * 行间距在**用到时**才读：ref 回调可能早于元素插入文档，\n   * 而游离节点在部分环境（jsdom）读计算样式会抛错；\n   * 真正要写 spacer 高度时树一定已经挂好，此时读到的才是有效值。\n   */\n  const spacerGap = () => rowGap(options.spacer()?.parentElement ?? null);\n\n  /** 设置尾部 spacer：让目标行有空间滚到指定位置；0 时隐藏 */\n  const setSpacerHeight = (height: number) => {\n    const spacer = options.spacer();\n    if (!spacer) return;\n\n    const next = Math.max(0, Math.ceil(height));\n    if (spacerHeightValue === next) return;\n\n    spacerHeightValue = next;\n    spacer.hidden = next === 0;\n    spacer.style.height = `${next}px`;\n    // 用负 margin 抵消内容的行间距，否则 spacer 会多出一段空隙\n    spacer.style.marginTop = next > 0 ? `${-spacerGap()}px` : \"\";\n  };\n\n  const setScrollTop: ScrollCommands[\"setScrollTop\"] = (\n    top,\n    { behavior = \"auto\", auto = false } = {},\n  ) => {\n    const viewport = options.viewport();\n    if (!viewport) return;\n\n    const next = Math.max(0, top);\n    if (Math.abs(viewport.scrollTop - next) <= AT_EDGE_TOLERANCE) {\n      // 已经在目标位置：直接落位，不做动画\n      viewport.scrollTop = next;\n      options.state.commit();\n      return;\n    }\n    if (auto) options.state.beginAutoScroll();\n    viewport.scrollTo({ top: next, behavior });\n    options.state.schedule();\n  };\n\n  const targetTopFor: ScrollCommands[\"targetTopFor\"] = (\n    element,\n    command,\n    margin,\n  ) => {\n    const viewport = options.viewport();\n    if (!viewport) return 0;\n    return computeTargetTopFor(\n      element,\n      command,\n      margin,\n      viewport,\n      options.content(),\n      options.measure.itemOffsetTop,\n    );\n  };\n\n  return {\n    spacerHeight: () => spacerHeightValue,\n    setScrollTop,\n    targetTopFor,\n    scrollToStart(command) {\n      if (!options.viewport()) return false;\n      setSpacerHeight(0);\n      options.state.setFree();\n      setScrollTop(0, { behavior: command?.behavior ?? \"auto\" });\n      options.scheduleVisibility();\n      return true;\n    },\n    scrollToEnd(command) {\n      if (!options.viewport()) return false;\n      setSpacerHeight(0);\n      if (options.options().autoScroll) options.state.setFollowing();\n      else options.state.setFree();\n      setScrollTop(options.measure.maxScrollTop(), {\n        behavior: command?.behavior ?? \"auto\",\n        auto: true,\n      });\n      options.scheduleVisibility();\n      return true;\n    },\n    scrollToElement(element, command, { keepPreviousPeek = false } = {}) {\n      const viewport = options.viewport();\n      const content = options.content();\n      if (!viewport || !content?.contains(element)) return false;\n\n      const margin =\n        (command?.scrollMargin ?? options.options().scrollMargin) +\n        (keepPreviousPeek ? options.options().scrollPreviousItemPeek : 0);\n      const target = targetTopFor(element, command, margin);\n      // 让目标行有足够空间滚到目标位置（内容不够高时补一段 spacer）\n      setSpacerHeight(\n        Math.max(\n          0,\n          target + viewport.clientHeight - options.measure.contentBottom(),\n        ),\n      );\n\n      if (keepPreviousPeek) options.state.anchorTo();\n      else options.state.settleJump();\n\n      setScrollTop(target, { behavior: command?.behavior ?? \"auto\" });\n      options.scheduleVisibility();\n      return true;\n    },\n  };\n}\n"],"mappings":";;;;AAyDA,SAAgBE,EACd,GACgB;CAChB,IAAIC,IAAoB,GAOlBC,UAAkBC,EAAOC,EAAQ,OAAO,CAAC,EAAE,iBAAiB,IAAI,GAGhEC,KAAmB,MAAmB;EAC1C,IAAMC,IAASF,EAAQ,OAAO;EAC9B,IAAI,CAACE,GAAQ;EAEb,IAAMC,IAAO,KAAK,IAAI,GAAG,KAAK,KAAKC,CAAM,CAAC;EAC1C,AAAIP,MAAsBM,MAE1B,IAAoBA,GACpB,EAAO,SAASA,MAAS,GACzB,EAAO,MAAM,SAAS,GAAGA,EAAK,KAE9B,EAAO,MAAM,YAAYA,IAAO,IAAI,GAAG,CAACL,EAAU,EAAE,MAAM;CAC5D,GAEMO,KACJ,GACA,EAAE,cAAW,QAAQ,UAAO,OAAU,CAAC,MACpC;EACH,IAAMC,IAAWN,EAAQ,SAAS;EAClC,IAAI,CAACM,GAAU;EAEf,IAAMH,IAAO,KAAK,IAAI,GAAGI,CAAG;EAC5B,IAAI,KAAK,IAAID,EAAS,YAAYH,CAAI,KAAA,IAAwB;GAG5D,AADA,EAAS,YAAYA,GACrBH,EAAQ,MAAM,OAAO;GACrB;EACF;EAGA,AAFIQ,KAAMR,EAAQ,MAAM,gBAAgB,GACxCM,EAAS,SAAS;GAAE,KAAKH;GAAM;EAAS,CAAC,GACzCH,EAAQ,MAAM,SAAS;CACzB,GAEMN,KACJ,GACA,GACA,MACG;EACH,IAAMY,IAAWN,EAAQ,SAAS;EAElC,OADKM,IACEX,EACLgB,GACAC,GACAC,GACAP,GACAN,EAAQ,QAAQ,GAChBA,EAAQ,QAAQ,aAClB,IARsB;CASxB;CAEA,OAAO;EACL,oBAAoBH;EACpB;EACA,cAAAY;EACA,cAAc,GAAS;GAMrB,OALKT,EAAQ,SAAS,KACtBC,EAAgB,CAAC,GACjBD,EAAQ,MAAM,QAAQ,GACtBK,EAAa,GAAG,EAAE,UAAUO,GAAS,YAAY,OAAO,CAAC,GACzDZ,EAAQ,mBAAmB,GACpB,MALyB;EAMlC;EACA,YAAY,GAAS;GAUnB,OATKA,EAAQ,SAAS,KACtBC,EAAgB,CAAC,GACbD,EAAQ,QAAQ,CAAC,CAAC,aAAYA,EAAQ,MAAM,aAAa,IACxDA,EAAQ,MAAM,QAAQ,GAC3BK,EAAaL,EAAQ,QAAQ,aAAa,GAAG;IAC3C,UAAUY,GAAS,YAAY;IAC/B,MAAM;GACR,CAAC,GACDZ,EAAQ,mBAAmB,GACpB,MATyB;EAUlC;EACA,gBAAgB,GAAS,GAAS,EAAE,sBAAmB,OAAU,CAAC,GAAG;GACnE,IAAMM,IAAWN,EAAQ,SAAS,GAC5Bc,IAAUd,EAAQ,QAAQ;GAChC,IAAI,CAACM,KAAY,CAACQ,GAAS,SAASH,CAAO,GAAG,OAAO;GAErD,IAAME,KACHD,GAAS,gBAAgBZ,EAAQ,QAAQ,CAAC,CAAC,iBAC3Ce,IAAmBf,EAAQ,QAAQ,CAAC,CAAC,yBAAyB,IAC3DgB,IAAStB,EAAaiB,GAASC,GAASC,CAAM;GAcpD,OAZAZ,EACE,KAAK,IACH,GACAe,IAASV,EAAS,eAAeN,EAAQ,QAAQ,cAAc,CACjE,CACF,GAEIe,IAAkBf,EAAQ,MAAM,SAAS,IACxCA,EAAQ,MAAM,WAAW,GAE9BK,EAAaW,GAAQ,EAAE,UAAUJ,GAAS,YAAY,OAAO,CAAC,GAC9DZ,EAAQ,mBAAmB,GACpB;EACT;CACF;AACF"}

package/dist/components/message-scroller/message-scroller.dom-measure.d.ts

@@ -0,0 +1,29 @@
+import { Accessor } from 'solid-js';
+/**
+ * MessageScroller 的 DOM 几何测量。
+ *
+ * 单一职责：只回答"行在哪里""内容有多高""还能滚多远"。不读 props、不写任何状态、
+ * 不订阅事件——所有输入都是元素 accessor，因此可以脱离引擎单独驱动
+ * （jsdom 不做布局，测试里用可控坐标系 stub 矩形即可）。
+ */
+export interface DomMeasureOptions {
+    /** 滚动容器 */
+    viewport: Accessor<HTMLElement | undefined>;
+    /** 会话容器（`role="log"` 的那一层） */
+    content: Accessor<HTMLElement | undefined>;
+    /** 内部尾部 spacer（不属于内容，测量时必须排除） */
+    spacer: Accessor<HTMLElement | undefined>;
+}
+export interface DomMeasure {
+    /** content 的直接子元素，排除内部 spacer */
+    items: () => HTMLElement[];
+    /** 行相对滚动容器内容顶部的偏移（用测量，避免 offsetParent 不确定） */
+    itemOffsetTop: (element: HTMLElement) => number;
+    /** 行相对视口顶部的偏移 */
+    itemTopInViewport: (element: HTMLElement) => number;
+    /** 内容底部（不含 spacer），即内容真实滚动高度 */
+    contentBottom: () => number;
+    /** 最大可滚动距离 */
+    maxScrollTop: () => number;
+}
+export declare function createDomMeasure(options: DomMeasureOptions): DomMeasure;

package/dist/components/message-scroller/message-scroller.dom-measure.js

@@ -0,0 +1,37 @@
+import { paddingBox as e } from "./message-scroller.measure.js";
+//#region src/components/message-scroller/message-scroller.dom-measure.ts
+function t(t) {
+	let n = () => {
+		let e = t.content(), n = t.spacer();
+		return e ? Array.from(e.children).filter((e) => e instanceof HTMLElement && e !== n) : [];
+	};
+	return {
+		items: n,
+		itemOffsetTop: (e) => {
+			let n = t.viewport();
+			return n ? e.getBoundingClientRect().top - n.getBoundingClientRect().top + n.scrollTop : 0;
+		},
+		itemTopInViewport: (e) => {
+			let n = t.viewport();
+			return n ? e.getBoundingClientRect().top - n.getBoundingClientRect().top : 0;
+		},
+		contentBottom: () => {
+			let r = t.viewport(), i = t.content();
+			if (!r || !i) return 0;
+			let a = e(i), o = r.getBoundingClientRect(), s = a.start + a.end;
+			for (let e of n()) {
+				let t = e.getBoundingClientRect();
+				s = Math.max(s, t.bottom - o.top + r.scrollTop + a.end);
+			}
+			return s;
+		},
+		maxScrollTop: () => {
+			let e = t.viewport();
+			return e ? Math.max(0, e.scrollHeight - e.clientHeight) : 0;
+		}
+	};
+}
+//#endregion
+export { t as createDomMeasure };
+
+//# sourceMappingURL=message-scroller.dom-measure.js.map

package/dist/components/message-scroller/message-scroller.dom-measure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.dom-measure.js","names":["createDomMeasure","items","root","options","spacer","child","viewport","element","pad","paddingBox","viewportRect","bottom","item","rect"],"sources":["../../../src/components/message-scroller/message-scroller.dom-measure.ts"],"sourcesContent":["import type { Accessor } from \"solid-js\";\nimport { paddingBox } from \"./message-scroller.measure\";\n\n/**\n * MessageScroller 的 DOM 几何测量。\n *\n * 单一职责：只回答\"行在哪里\"\"内容有多高\"\"还能滚多远\"。不读 props、不写任何状态、\n * 不订阅事件——所有输入都是元素 accessor，因此可以脱离引擎单独驱动\n * （jsdom 不做布局，测试里用可控坐标系 stub 矩形即可）。\n */\n\nexport interface DomMeasureOptions {\n  /** 滚动容器 */\n  viewport: Accessor<HTMLElement | undefined>;\n  /** 会话容器（`role=\"log\"` 的那一层） */\n  content: Accessor<HTMLElement | undefined>;\n  /** 内部尾部 spacer（不属于内容，测量时必须排除） */\n  spacer: Accessor<HTMLElement | undefined>;\n}\n\nexport interface DomMeasure {\n  /** content 的直接子元素，排除内部 spacer */\n  items: () => HTMLElement[];\n  /** 行相对滚动容器内容顶部的偏移（用测量，避免 offsetParent 不确定） */\n  itemOffsetTop: (element: HTMLElement) => number;\n  /** 行相对视口顶部的偏移 */\n  itemTopInViewport: (element: HTMLElement) => number;\n  /** 内容底部（不含 spacer），即内容真实滚动高度 */\n  contentBottom: () => number;\n  /** 最大可滚动距离 */\n  maxScrollTop: () => number;\n}\n\nexport function createDomMeasure(options: DomMeasureOptions): DomMeasure {\n  const items = (): HTMLElement[] => {\n    const root = options.content();\n    const spacer = options.spacer();\n    if (!root) return [];\n    return Array.from(root.children).filter(\n      (child): child is HTMLElement =>\n        child instanceof HTMLElement && child !== spacer,\n    );\n  };\n\n  const itemOffsetTop = (element: HTMLElement) => {\n    const viewport = options.viewport();\n    if (!viewport) return 0;\n    return (\n      element.getBoundingClientRect().top -\n      viewport.getBoundingClientRect().top +\n      viewport.scrollTop\n    );\n  };\n\n  const itemTopInViewport = (element: HTMLElement) => {\n    const viewport = options.viewport();\n    if (!viewport) return 0;\n    return (\n      element.getBoundingClientRect().top - viewport.getBoundingClientRect().top\n    );\n  };\n\n  const contentBottom = () => {\n    const viewport = options.viewport();\n    const root = options.content();\n    if (!viewport || !root) return 0;\n\n    const pad = paddingBox(root);\n    const viewportRect = viewport.getBoundingClientRect();\n    let bottom = pad.start + pad.end;\n    for (const item of items()) {\n      const rect = item.getBoundingClientRect();\n      bottom = Math.max(\n        bottom,\n        rect.bottom - viewportRect.top + viewport.scrollTop + pad.end,\n      );\n    }\n    return bottom;\n  };\n\n  const maxScrollTop = () => {\n    const viewport = options.viewport();\n    return viewport\n      ? Math.max(0, viewport.scrollHeight - viewport.clientHeight)\n      : 0;\n  };\n\n  return {\n    items,\n    itemOffsetTop,\n    itemTopInViewport,\n    contentBottom,\n    maxScrollTop,\n  };\n}\n"],"mappings":";;AAiCA,SAAgBA,EAAiB,GAAwC;CACvE,IAAMC,UAA6B;EACjC,IAAMC,IAAOC,EAAQ,QAAQ,GACvBC,IAASD,EAAQ,OAAO;EAE9B,OADKD,IACE,MAAM,KAAKA,EAAK,QAAQ,CAAC,CAAC,QAC9B,MACCG,aAAiB,eAAeA,MAAUD,CAC9C,IAJkB,CAAC;CAKrB;CA6CA,OAAO;EACL;EACA,gBA7CqB,MAAyB;GAC9C,IAAME,IAAWH,EAAQ,SAAS;GAElC,OADKG,IAEHC,EAAQ,sBAAsB,CAAC,CAAC,MAChCD,EAAS,sBAAsB,CAAC,CAAC,MACjCA,EAAS,YAJW;EAMxB;EAsCE,oBApCyB,MAAyB;GAClD,IAAMA,IAAWH,EAAQ,SAAS;GAElC,OADKG,IAEHC,EAAQ,sBAAsB,CAAC,CAAC,MAAMD,EAAS,sBAAsB,CAAC,CAAC,MAFnD;EAIxB;EA+BE,qBA7B0B;GAC1B,IAAMA,IAAWH,EAAQ,SAAS,GAC5BD,IAAOC,EAAQ,QAAQ;GAC7B,IAAI,CAACG,KAAY,CAACJ,GAAM,OAAO;GAE/B,IAAMM,IAAMC,EAAWP,CAAI,GACrBQ,IAAeJ,EAAS,sBAAsB,GAChDK,IAASH,EAAI,QAAQA,EAAI;GAC7B,KAAK,IAAMI,KAAQX,EAAM,GAAG;IAC1B,IAAMY,IAAOD,EAAK,sBAAsB;IACxC,IAAS,KAAK,IACZD,GACAE,EAAK,SAASH,EAAa,MAAMJ,EAAS,YAAYE,EAAI,GAC5D;GACF;GACA,OAAOG;EACT;EAcE,oBAZyB;GACzB,IAAML,IAAWH,EAAQ,SAAS;GAClC,OAAOG,IACH,KAAK,IAAI,GAAGA,EAAS,eAAeA,EAAS,YAAY,IACzD;EACN;CAQA;AACF"}

package/dist/components/message-scroller/message-scroller.measure.d.ts

@@ -0,0 +1,27 @@
+/**
+ * MessageScroller 的 CSS 尺寸测量。
+ *
+ * 单一职责：把 `getComputedStyle` 的字符串值解析成可运算的数字。
+ * 不持有信号、不订阅事件、不做滚动决策，因此可以脱离 jsdom 布局限制直接单测。
+ */
+/** 一个元素在主轴方向上的内边距 */
+export interface PaddingBox {
+    /** 逻辑块起始内边距（`padding-block-start`，回退到 `padding-top`） */
+    start: number;
+    /** 逻辑块结束内边距（`padding-block-end`，回退到 `padding-bottom`） */
+    end: number;
+}
+/** 把 `"12px"` 之类的 CSS 长度解析成数字；非法值一律当 0 */
+export declare function parsePx(value: string): number;
+/**
+ * 读取元素的块级内边距。
+ * 优先用逻辑属性（`paddingBlockStart`），因为它能正确处理书写方向；
+ * 不支持时回退到物理属性（`paddingTop`）。
+ */
+export declare function paddingBox(element: HTMLElement): PaddingBox;
+/**
+ * 读取容器的行间距。
+ * 显式设置过行间距时 `rowGap` 有值，否则它是 `"normal"`——此时应读 `gap`
+ * 简写（`gap: 8px` 不会展开到 `rowGap`）。
+ */
+export declare function rowGap(element: HTMLElement | null): number;

package/dist/components/message-scroller/message-scroller.measure.js

@@ -0,0 +1,21 @@
+//#region src/components/message-scroller/message-scroller.measure.ts
+function e(e) {
+	let t = Number.parseFloat(e);
+	return Number.isFinite(t) ? t : 0;
+}
+function t(t) {
+	let n = window.getComputedStyle(t);
+	return {
+		start: e(n.paddingBlockStart || n.paddingTop),
+		end: e(n.paddingBlockEnd || n.paddingBottom)
+	};
+}
+function n(t) {
+	if (!t) return 0;
+	let n = window.getComputedStyle(t);
+	return e(n.rowGap === "normal" ? n.gap : n.rowGap);
+}
+//#endregion
+export { t as paddingBox, e as parsePx, n as rowGap };
+
+//# sourceMappingURL=message-scroller.measure.js.map

package/dist/components/message-scroller/message-scroller.measure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-scroller.measure.js","names":["parsePx","parsed","value","paddingBox","style","element","rowGap"],"sources":["../../../src/components/message-scroller/message-scroller.measure.ts"],"sourcesContent":["/**\n * MessageScroller 的 CSS 尺寸测量。\n *\n * 单一职责：把 `getComputedStyle` 的字符串值解析成可运算的数字。\n * 不持有信号、不订阅事件、不做滚动决策，因此可以脱离 jsdom 布局限制直接单测。\n */\n\n/** 一个元素在主轴方向上的内边距 */\nexport interface PaddingBox {\n  /** 逻辑块起始内边距（`padding-block-start`，回退到 `padding-top`） */\n  start: number;\n  /** 逻辑块结束内边距（`padding-block-end`，回退到 `padding-bottom`） */\n  end: number;\n}\n\n/** 把 `\"12px\"` 之类的 CSS 长度解析成数字；非法值一律当 0 */\nexport function parsePx(value: string): number {\n  const parsed = Number.parseFloat(value);\n  return Number.isFinite(parsed) ? parsed : 0;\n}\n\n/**\n * 读取元素的块级内边距。\n * 优先用逻辑属性（`paddingBlockStart`），因为它能正确处理书写方向；\n * 不支持时回退到物理属性（`paddingTop`）。\n */\nexport function paddingBox(element: HTMLElement): PaddingBox {\n  const style = window.getComputedStyle(element);\n  return {\n    start: parsePx(style.paddingBlockStart || style.paddingTop),\n    end: parsePx(style.paddingBlockEnd || style.paddingBottom),\n  };\n}\n\n/**\n * 读取容器的行间距。\n * 显式设置过行间距时 `rowGap` 有值，否则它是 `\"normal\"`——此时应读 `gap`\n * 简写（`gap: 8px` 不会展开到 `rowGap`）。\n */\nexport function rowGap(element: HTMLElement | null): number {\n  if (!element) return 0;\n  const style = window.getComputedStyle(element);\n  return parsePx(style.rowGap === \"normal\" ? style.gap : style.rowGap);\n}\n"],"mappings":";AAgBA,SAAgBA,EAAQ,GAAuB;CAC7C,IAAMC,IAAS,OAAO,WAAWC,CAAK;CACtC,OAAO,OAAO,SAASD,CAAM,IAAIA,IAAS;AAC5C;AAOA,SAAgBE,EAAW,GAAkC;CAC3D,IAAMC,IAAQ,OAAO,iBAAiBC,CAAO;CAC7C,OAAO;EACL,OAAOL,EAAQI,EAAM,qBAAqBA,EAAM,UAAU;EAC1D,KAAKJ,EAAQI,EAAM,mBAAmBA,EAAM,aAAa;CAC3D;AACF;AAOA,SAAgBE,EAAO,GAAqC;CAC1D,IAAI,CAACD,GAAS,OAAO;CACrB,IAAMD,IAAQ,OAAO,iBAAiBC,CAAO;CAC7C,OAAOL,EAAQI,EAAM,WAAW,WAAWA,EAAM,MAAMA,EAAM,MAAM;AACrE"}

package/dist/components/message-scroller/message-scroller.scroll-state.d.ts

@@ -0,0 +1,54 @@
+import { Accessor } from 'solid-js';
+import { MessageScrollerProviderProps } from './message-scroller.types';
+type EngineOptions = Required<Omit<MessageScrollerProviderProps, "children">>;
+/**
+ * 滚动模式。
+ * - `following-bottom`：跟随实时边缘（新内容自动滚到底）
+ * - `free-scrolling`：读者自己控制位置，内容变化不再抢滚动
+ * - `anchored-to-message`：把某个锚点行固定在阅读线上（新回合锚定）
+ * - `settling-jump`：一次显式跳转后的过渡态
+ */
+export type ScrollMode = "following-bottom" | "free-scrolling" | "anchored-to-message" | "settling-jump";
+export interface ScrollStateOptions {
+    viewport: Accessor<HTMLElement | undefined>;
+    options: () => EngineOptions;
+    /** 内容底部（不含 spacer），由 `dom-measure` 提供 */
+    contentBottom: () => number;
+}
+export interface ScrollState {
+    /** 是否处于"跟随实时边缘"（迁移一律走下面的语义化方法，避免散落的直接赋值） */
+    isFollowing: () => boolean;
+    isAnchored: () => boolean;
+    /** 是否可向两侧滚动（注意：跟随时对外把 `end` 强制为 false） */
+    scrollableStart: Accessor<boolean>;
+    scrollableEnd: Accessor<boolean>;
+    autoscrolling: Accessor<boolean>;
+    setFollowing: () => void;
+    setFree: () => void;
+    anchorTo: () => void;
+    settleJump: () => void;
+    /** 立即计算可滚动状态并按当前位置迁移模式 */
+    commit: () => void;
+    /** 分帧提交（滚动热路径） */
+    schedule: () => void;
+    /** 开启「正在自动滚动」态，到期自动复位 */
+    beginAutoScroll: () => void;
+    /** 关闭该状态并清掉计时器 */
+    endAutoScroll: () => void;
+    /** 滚轮/触摸/键盘滚动：立刻把位置交还读者 */
+    releaseFollow: () => void;
+    dispose: () => void;
+}
+/**
+ * 滚动状态机。
+ *
+ * 单一职责：维护滚动模式与"能否向两侧滚动""是否正在自动滚动"这三个对外状态，
+ * 并按测量结果迁移模式。它不写 `scrollTop`、不做锚定决策——那些是 commands /
+ * anchoring 的事；本模块只回答"现在是什么模式"。
+ *
+ * `mode` 的**唯一写入者**是本模块：外部只能通过 `setFollowing` / `setFree` /
+ * `anchorTo` / `settleJump` 表达意图，`releaseFollow` 与滚动事件带来的迁移
+ * 也收在这里，避免"多个模块各自记住模式"的隐性耦合。
+ */
+export declare function createScrollState(options: ScrollStateOptions): ScrollState;
+export {};