2 files changed, 196 insertions, 0 deletions
diff --git a/src/features/smart-scroll/logic/smart-scroll.test.ts b/src/features/smart-scroll/logic/smart-scroll.test.ts
new file mode 100644
index 0000000..fc3e3d1
--- /dev/null
+++ b/src/features/smart-scroll/logic/smart-scroll.test.ts
@@ -0,0 +1,103 @@
+import { describe, expect, it } from "vitest";
+import {
+	createSmartScrollState,
+	isNearBottom,
+	NEAR_BOTTOM_THRESHOLD,
+	onContentChange,
+	onReset,
+	onResume,
+	onScroll,
+	type ScrollGeometry,
+} from "./smart-scroll";
+
+// A viewport 100px tall over 1000px of content: scrollTop 900 == pinned to bottom.
+const atBottom: ScrollGeometry = { scrollTop: 900, scrollHeight: 1000, clientHeight: 100 };
+const nearBottom: ScrollGeometry = {
+	scrollTop: 900 - NEAR_BOTTOM_THRESHOLD,
+	scrollHeight: 1000,
+	clientHeight: 100,
+};
+const scrolledUp: ScrollGeometry = { scrollTop: 200, scrollHeight: 1000, clientHeight: 100 };
+
+describe("isNearBottom", () => {
+	it("is true exactly at the bottom", () => {
+		expect(isNearBottom(atBottom)).toBe(true);
+	});
+
+	it("is true within the threshold of the bottom", () => {
+		expect(isNearBottom(nearBottom)).toBe(true);
+	});
+
+	it("is false just beyond the threshold", () => {
+		expect(
+			isNearBottom({
+				scrollTop: 900 - NEAR_BOTTOM_THRESHOLD - 1,
+				scrollHeight: 1000,
+				clientHeight: 100,
+			}),
+		).toBe(false);
+	});
+
+	it("is false when scrolled well up", () => {
+		expect(isNearBottom(scrolledUp)).toBe(false);
+	});
+
+	it("honours a custom threshold", () => {
+		const geom: ScrollGeometry = { scrollTop: 800, scrollHeight: 1000, clientHeight: 100 };
+		expect(isNearBottom(geom, 50)).toBe(false);
+		expect(isNearBottom(geom, 150)).toBe(true);
+	});
+});
+
+describe("smart-scroll reducer", () => {
+	it("starts stuck and hides the button", () => {
+		const s = createSmartScrollState();
+		expect(s.stuck).toBe(true);
+	});
+
+	it("onScroll up unsticks and shows the button, with no command", () => {
+		const r = onScroll(createSmartScrollState(), scrolledUp);
+		expect(r.state.stuck).toBe(false);
+		expect(r.showButton).toBe(true);
+		expect(r.command).toBeNull();
+	});
+
+	it("onScroll back to the bottom re-sticks and hides the button", () => {
+		const up = onScroll(createSmartScrollState(), scrolledUp).state;
+		const r = onScroll(up, atBottom);
+		expect(r.state.stuck).toBe(true);
+		expect(r.showButton).toBe(false);
+		expect(r.command).toBeNull();
+	});
+
+	it("onContentChange while stuck emits a NON-animated scroll (keep up with the stream)", () => {
+		const r = onContentChange(createSmartScrollState(), atBottom);
+		expect(r.command).toEqual({ kind: "scroll-to-bottom", animate: false });
+		expect(r.state.stuck).toBe(true);
+	});
+
+	it("onContentChange while unstuck emits NO command (leave the reader in place)", () => {
+		const up = onScroll(createSmartScrollState(), scrolledUp).state;
+		const r = onContentChange(up, scrolledUp);
+		expect(r.command).toBeNull();
+		expect(r.state.stuck).toBe(false);
+		expect(r.showButton).toBe(true);
+	});
+
+	it("onResume re-sticks and emits an ANIMATED scroll", () => {
+		const up = onScroll(createSmartScrollState(), scrolledUp).state;
+		const r = onResume(up);
+		expect(r.state.stuck).toBe(true);
+		expect(r.showButton).toBe(false);
+		expect(r.command).toEqual({ kind: "scroll-to-bottom", animate: true });
+	});
+
+	it("onReset returns to stuck and snaps (non-animated) to the bottom", () => {
+		const up = onScroll(createSmartScrollState(), scrolledUp).state;
+		const r = onReset();
+		void up;
+		expect(r.state.stuck).toBe(true);
+		expect(r.command).toEqual({ kind: "scroll-to-bottom", animate: false });
+		expect(r.showButton).toBe(false);
+	});
+});
diff --git a/src/features/smart-scroll/logic/smart-scroll.ts b/src/features/smart-scroll/logic/smart-scroll.ts
new file mode 100644
index 0000000..021b3fe
--- /dev/null
+++ b/src/features/smart-scroll/logic/smart-scroll.ts
@@ -0,0 +1,93 @@
+// Pure smart-scroll reducer — "stick the transcript to the bottom while it grows,
+// unless the user has scrolled up". Zero DOM, zero Svelte: it takes scroll
+// GEOMETRY snapshots in and returns the next state plus an optional scroll
+// COMMAND for the shell to execute. The injected shell (the Svelte action) reads
+// the geometry off a real element and runs the commands.
+
+/** A snapshot of a scroll container's vertical geometry (in CSS pixels). */
+export interface ScrollGeometry {
+	/** Current scroll offset from the top. */
+	readonly scrollTop: number;
+	/** Total scrollable content height. */
+	readonly scrollHeight: number;
+	/** Visible viewport height. */
+	readonly clientHeight: number;
+}
+
+/** Distance (px) from the bottom within which we still consider the view "at bottom". */
+export const NEAR_BOTTOM_THRESHOLD = 64;
+
+/** True when the viewport is within `threshold` px of the content's bottom edge. */
+export function isNearBottom(
+	geom: ScrollGeometry,
+	threshold: number = NEAR_BOTTOM_THRESHOLD,
+): boolean {
+	return geom.scrollHeight - geom.scrollTop - geom.clientHeight <= threshold;
+}
+
+/** A scroll the shell should perform on the real element. */
+export interface ScrollCommand {
+	readonly kind: "scroll-to-bottom";
+	/** Smooth-scroll (a deliberate resume) vs. jump (keeping up with a stream). */
+	readonly animate: boolean;
+}
+
+export interface SmartScrollState {
+	/**
+	 * Whether the view is currently following the bottom. While `stuck`, new
+	 * content keeps the view pinned to the bottom; once the user scrolls up it
+	 * goes false and stays false until they return to the bottom (or resume).
+	 */
+	readonly stuck: boolean;
+}
+
+/** A reducer step's result: the next state, an optional command, and whether to show the button. */
+export interface SmartScrollResult {
+	readonly state: SmartScrollState;
+	readonly command: ScrollCommand | null;
+	/** Show the "scroll to bottom" affordance exactly when not stuck. */
+	readonly showButton: boolean;
+}
+
+/** Initial state — start stuck so the first content snaps to the bottom. */
+export function createSmartScrollState(): SmartScrollState {
+	return { stuck: true };
+}
+
+function result(state: SmartScrollState, command: ScrollCommand | null): SmartScrollResult {
+	return { state, command, showButton: !state.stuck };
+}
+
+/**
+ * The user scrolled (or the viewport resized). Re-derive `stuck` purely from
+ * geometry: near the bottom ⇒ stuck (follow), otherwise unstuck. Never emits a
+ * command — reacting to the user's own scroll with a scroll would fight them.
+ */
+export function onScroll(_state: SmartScrollState, geom: ScrollGeometry): SmartScrollResult {
+	return result({ stuck: isNearBottom(geom) }, null);
+}
+
+/**
+ * Content changed (a streamed delta, a new message, history loaded). If we're
+ * stuck, emit a non-animated scroll to keep up; otherwise leave the user where
+ * they are. State is unchanged — content growth alone never flips `stuck`.
+ */
+export function onContentChange(state: SmartScrollState, _geom: ScrollGeometry): SmartScrollResult {
+	return result(state, state.stuck ? { kind: "scroll-to-bottom", animate: false } : null);
+}
+
+/**
+ * The user asked to return to the bottom (clicked the button). Force-stick and
+ * emit an animated scroll.
+ */
+export function onResume(_state: SmartScrollState): SmartScrollResult {
+	return result({ stuck: true }, { kind: "scroll-to-bottom", animate: true });
+}
+
+/**
+ * The transcript context changed entirely (e.g. a conversation/tab switch).
+ * Reset to stuck and snap (non-animated) to the bottom of the new content.
+ */
+export function onReset(): SmartScrollResult {
+	return result(createSmartScrollState(), { kind: "scroll-to-bottom", animate: false });
+}