fancy-ui-svelte 0.9.0 → 0.10.0

package/dist/fancy-ui/_internals/StreamText.test.js

@@ -0,0 +1,77 @@
+import { render, cleanup } from "@testing-library/svelte";
+import { afterEach, describe, it, expect, vi } from "vitest";
+import StreamText from "./StreamText.svelte";
+describe("StreamText", () => {
+    afterEach(() => {
+        cleanup();
+        vi.useRealTimers();
+    });
+    it("renders the whole text as plain content on first paint, with nothing animating", () => {
+        vi.useFakeTimers();
+        const { container } = render(StreamText, { props: { text: "Hello world" } });
+        const wrapper = container.firstElementChild;
+        expect(wrapper.textContent).toBe("Hello world");
+        expect(container.querySelector(".ft-fresh")).toBeFalsy();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("wraps only the appended delta in a fresh span, then folds it in once settled", async () => {
+        vi.useFakeTimers();
+        const { container, rerender } = render(StreamText, {
+            props: { text: "Hello", settleMs: 100 },
+        });
+        const wrapper = container.firstElementChild;
+        await rerender({ text: "Hello, world" });
+        const fresh = container.querySelector(".ft-fresh");
+        expect(fresh).toBeTruthy();
+        expect(fresh?.textContent).toBe(", world");
+        expect(wrapper.textContent).toBe("Hello, world");
+        await vi.advanceTimersByTimeAsync(100);
+        expect(container.querySelector(".ft-fresh")).toBeFalsy();
+        expect(wrapper.textContent).toBe("Hello, world");
+    });
+    it("preserves whitespace and newlines, in the settled text and in the delta", async () => {
+        vi.useFakeTimers();
+        const { container, rerender } = render(StreamText, {
+            props: { text: "line one\n  line two", settleMs: 100 },
+        });
+        const wrapper = container.firstElementChild;
+        expect(wrapper.textContent).toBe("line one\n  line two");
+        expect(wrapper.getAttribute("style")).toContain("pre-wrap");
+        await rerender({ text: "line one\n  line two\n\nline three" });
+        expect(container.querySelector(".ft-fresh")?.textContent).toBe("\n\nline three");
+        expect(wrapper.textContent).toBe("line one\n  line two\n\nline three");
+    });
+    it("swaps the content outright, without animating, when the new text is not a continuation", async () => {
+        vi.useFakeTimers();
+        const { container, rerender } = render(StreamText, {
+            props: { text: "Draft answer", settleMs: 100 },
+        });
+        const wrapper = container.firstElementChild;
+        await rerender({ text: "Draft answer, revised" });
+        expect(container.querySelector(".ft-fresh")).toBeTruthy();
+        await rerender({ text: "A regenerated answer" });
+        expect(wrapper.textContent).toBe("A regenerated answer");
+        expect(container.querySelector(".ft-fresh")).toBeFalsy();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("merges custom classes and exposes the settle duration to the animation", () => {
+        vi.useFakeTimers();
+        const { container } = render(StreamText, {
+            props: { text: "x", settleMs: 900, class: "text-sm" },
+        });
+        const wrapper = container.firstElementChild;
+        expect(wrapper.className).toContain("ft-stream");
+        expect(wrapper.className).toContain("text-sm");
+        expect(wrapper.getAttribute("style")).toContain("--ft-settle: 900ms");
+    });
+    it("tears down a pending settle on unmount", async () => {
+        vi.useFakeTimers();
+        const { unmount, rerender } = render(StreamText, {
+            props: { text: "Hello", settleMs: 100 },
+        });
+        await rerender({ text: "Hello there" });
+        expect(vi.getTimerCount()).toBe(1);
+        expect(() => unmount()).not.toThrow();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+});

package/dist/fancy-ui/_internals/ai-types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Shared data model for the AI component family.
+ *
+ * Every conversational and agent-activity component reads from these shapes, so
+ * one message object can flow from a thread list into a transcript, a tool
+ * timeline, or a citation card without translation at each boundary. Types only:
+ * nothing here runs, imports, or touches the DOM.
+ */
+/** Who produced a turn in a conversation. */
+export type ChatRole = "user" | "assistant" | "system";
+/** Lifecycle of a token stream, from the first chunk to its terminal state. */
+export type StreamStatus = "idle" | "streaming" | "done" | "error";
+/** Lifecycle of anything the model kicks off and can finish, fail, or abandon. */
+export type RunStatus = "pending" | "running" | "done" | "error" | "cancelled";
+/** One conversation turn — consumed by message bubbles, transcripts, and branch switchers. */
+export interface ChatMessageData {
+    id: string;
+    role: ChatRole;
+    content: string;
+    status?: StreamStatus;
+    createdAt?: Date | number;
+    branchIndex?: number;
+    branchCount?: number;
+}
+/** A single tool invocation — consumed by tool-call cards and their input/output panels. */
+export interface ToolCallData {
+    id: string;
+    name: string;
+    status: RunStatus;
+    input?: unknown;
+    output?: unknown;
+    error?: string;
+    durationMs?: number;
+}
+/** A document backing an answer — consumed by source lists and inline citations. */
+export interface SourceData {
+    id: string;
+    title: string;
+    url: string;
+    snippet?: string;
+    domain?: string;
+}
+/** One hit from a web lookup — consumed by search-result surfaces. */
+export interface SearchResultData {
+    id: string;
+    title: string;
+    url: string;
+    snippet?: string;
+}
+/** A file riding along with a turn — consumed by composer attachment chips and previews. */
+export interface AttachmentData {
+    id: string;
+    name: string;
+    size?: number;
+    type?: string;
+    previewUrl?: string;
+    progress?: number;
+    status?: "uploading" | "done" | "error";
+}
+/** A node in an agent's plan — consumed by plan trees and task checklists, nests via `substeps`. */
+export interface PlanStepData {
+    id: string;
+    label: string;
+    status: RunStatus;
+    detail?: string;
+    substeps?: PlanStepData[];
+}
+/** A delegated worker — consumed by subagent cards and fan-out activity views. */
+export interface SubagentData {
+    id: string;
+    name: string;
+    task: string;
+    status: RunStatus;
+    progress?: number;
+    model?: string;
+}
+/** A conversation in the sidebar — consumed by thread lists and history pickers. */
+export interface ThreadData {
+    id: string;
+    title: string;
+    preview?: string;
+    updatedAt: Date | number;
+    unread?: boolean;
+}
+/** A selectable action — consumed by slash-command menus and command palettes. */
+export interface CommandItemData {
+    id: string;
+    label: string;
+    description?: string;
+    hint?: string;
+}
+/** A model the user can switch to — consumed by model pickers in the composer. */
+export interface ModelOptionData {
+    id: string;
+    label: string;
+    badge?: string;
+    description?: string;
+}
+/** Context-window consumption — consumed by token meters and context rings. */
+export interface TokenUsageData {
+    used: number;
+    max: number;
+    breakdown?: Array<{
+        label: string;
+        tokens: number;
+    }>;
+}
+/** One line of agent activity — consumed by tool timelines that read as an action log. */
+export interface ToolTimelineItemData {
+    id: string;
+    verb: string;
+    target: string;
+    detail?: string;
+    additions?: number;
+    deletions?: number;
+    timestamp?: Date | number;
+}

package/dist/fancy-ui/_internals/ai-types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared data model for the AI component family.
+ *
+ * Every conversational and agent-activity component reads from these shapes, so
+ * one message object can flow from a thread list into a transcript, a tool
+ * timeline, or a citation card without translation at each boundary. Types only:
+ * nothing here runs, imports, or touches the DOM.
+ */
+export {};

package/dist/fancy-ui/_internals/anchor-position.d.ts

@@ -0,0 +1,61 @@
+import type { Action } from "svelte/action";
+export type Side = "top" | "bottom" | "left" | "right";
+export type Align = "start" | "center" | "end";
+export interface ComputePositionOptions {
+    /** Side of the anchor to place the floating element on. Defaults to "bottom". */
+    side?: Side;
+    /** Alignment along the cross axis of `side`. Defaults to "center". */
+    align?: Align;
+    /** Gap in pixels between the anchor and the floating element. Defaults to 8. */
+    offset?: number;
+    /** Viewport bounds used for flip/clamp. Defaults to `window` when available, otherwise unbounded (SSR). */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Flip to the opposite side when the requested side would overflow the viewport. Defaults to true. */
+    flip?: boolean;
+}
+export interface ComputePositionResult {
+    x: number;
+    y: number;
+    /** The side actually used, which may differ from the requested one when flipped. */
+    side: Side;
+}
+/**
+ * Computes where to place a floating element relative to an anchor rect.
+ *
+ * Pure function — no DOM access, so it is testable with plain objects that
+ * satisfy the `DOMRect` shape.
+ */
+export declare function computePosition(anchor: DOMRect, floating: {
+    width: number;
+    height: number;
+}, opts?: ComputePositionOptions): ComputePositionResult;
+export interface AnchorPositionOptions {
+    /** Resolves the current anchor element. Called on every recompute so it can track a moving target. */
+    anchor: () => HTMLElement | null;
+    side?: Side;
+    align?: Align;
+    offset?: number;
+    /**
+     * Called with the side the element was actually placed on, which differs
+     * from the requested `side` whenever a flip occurred. Fires once on the
+     * initial placement and thereafter only when the resolved side changes,
+     * so a consumer can react (move a caret, mirror a submenu's open
+     * direction) without re-rendering on every scroll frame.
+     *
+     * Without this, `computePosition`'s resolved side is computed and
+     * discarded here, and a consumer has no way to learn a flip happened.
+     */
+    onPlacement?: (side: Side) => void;
+}
+/**
+ * Svelte action that positions `node` with `position: fixed` against a live
+ * anchor element, using `computePosition`. Recomputes on scroll and resize
+ * (passive, capturing listeners so nested scroll containers are caught too)
+ * and cleans up its listeners on destroy.
+ *
+ * SSR-safe: does nothing when `window` is unavailable.
+ */
+export declare const anchorPosition: Action<HTMLElement, AnchorPositionOptions>;

package/dist/fancy-ui/_internals/anchor-position.js

@@ -0,0 +1,158 @@
+// Framework-agnostic floating-element positioning: given an anchor rect and
+// the size of a floating element (popover / tooltip / menu), computes the
+// x/y coordinates that place it on the requested side, aligned against the
+// anchor, offset away from it, flipped to the opposite side when it would
+// overflow the viewport, and clamped so it never renders off-screen.
+//
+// `computePosition` is a pure function: it takes a DOMRect-shaped anchor and
+// plain dimensions, so it is fully testable without a DOM. `anchorPosition`
+// is the Svelte action that wires it up to a live anchor element.
+//
+// Usage:
+//   const { x, y, side } = computePosition(anchorEl.getBoundingClientRect(), { width: 200, height: 40 });
+//
+//   <div use:anchorPosition={{ anchor: () => anchorEl, side: "bottom" }}>...</div>
+const OPPOSITE_SIDE = {
+    top: "bottom",
+    bottom: "top",
+    left: "right",
+    right: "left",
+};
+function isHorizontalSide(side) {
+    return side === "top" || side === "bottom";
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(value, max));
+}
+function getDefaultViewport() {
+    if (typeof window !== "undefined") {
+        return { width: window.innerWidth, height: window.innerHeight };
+    }
+    // SSR fallback: no viewport to overflow against, so flip/clamp become no-ops.
+    return { width: Number.POSITIVE_INFINITY, height: Number.POSITIVE_INFINITY };
+}
+/** Whether placing the floating element on `side` would overflow the viewport. */
+function overflows(side, anchor, floating, offset, viewport) {
+    switch (side) {
+        case "top":
+            return anchor.top - floating.height - offset < 0;
+        case "bottom":
+            return anchor.bottom + offset + floating.height > viewport.height;
+        case "left":
+            return anchor.left - floating.width - offset < 0;
+        case "right":
+            return anchor.right + offset + floating.width > viewport.width;
+    }
+}
+/** Computes the raw (unclamped) x/y for `side` + `align`, before flip/clamp are applied. */
+function placeAt(side, anchor, floating, align, offset) {
+    if (isHorizontalSide(side)) {
+        const y = side === "top" ? anchor.top - floating.height - offset : anchor.bottom + offset;
+        let x;
+        switch (align) {
+            case "start":
+                x = anchor.left;
+                break;
+            case "end":
+                x = anchor.right - floating.width;
+                break;
+            default:
+                x = anchor.left + anchor.width / 2 - floating.width / 2;
+        }
+        return { x, y };
+    }
+    const x = side === "left" ? anchor.left - floating.width - offset : anchor.right + offset;
+    let y;
+    switch (align) {
+        case "start":
+            y = anchor.top;
+            break;
+        case "end":
+            y = anchor.bottom - floating.height;
+            break;
+        default:
+            y = anchor.top + anchor.height / 2 - floating.height / 2;
+    }
+    return { x, y };
+}
+/**
+ * Computes where to place a floating element relative to an anchor rect.
+ *
+ * Pure function — no DOM access, so it is testable with plain objects that
+ * satisfy the `DOMRect` shape.
+ */
+export function computePosition(anchor, floating, opts = {}) {
+    const { side = "bottom", align = "center", offset = 8, flip = true } = opts;
+    const viewport = opts.viewport ?? getDefaultViewport();
+    const resolvedSide = flip && overflows(side, anchor, floating, offset, viewport) ? OPPOSITE_SIDE[side] : side;
+    const { x, y } = placeAt(resolvedSide, anchor, floating, align, offset);
+    const maxX = Math.max(0, viewport.width - floating.width);
+    const maxY = Math.max(0, viewport.height - floating.height);
+    return {
+        x: clamp(x, 0, maxX),
+        y: clamp(y, 0, maxY),
+        side: resolvedSide,
+    };
+}
+/**
+ * Svelte action that positions `node` with `position: fixed` against a live
+ * anchor element, using `computePosition`. Recomputes on scroll and resize
+ * (passive, capturing listeners so nested scroll containers are caught too)
+ * and cleans up its listeners on destroy.
+ *
+ * SSR-safe: does nothing when `window` is unavailable.
+ */
+export const anchorPosition = (node, opts) => {
+    if (typeof window === "undefined") {
+        return {};
+    }
+    let options = opts;
+    // The last side reported through `onPlacement`, so a scroll or resize that
+    // recomputes to the same side stays silent. `null` means "nothing reported
+    // yet", which is distinct from any real side and makes the first placement
+    // always fire.
+    let reportedSide = null;
+    function update() {
+        const anchorEl = options.anchor();
+        if (!anchorEl)
+            return;
+        const anchorRect = anchorEl.getBoundingClientRect();
+        const floatingRect = node.getBoundingClientRect();
+        const { x, y, side } = computePosition(anchorRect, { width: floatingRect.width, height: floatingRect.height }, {
+            side: options.side,
+            align: options.align,
+            offset: options.offset,
+            viewport: { width: window.innerWidth, height: window.innerHeight },
+        });
+        node.style.position = "fixed";
+        node.style.left = `${x}px`;
+        node.style.top = `${y}px`;
+        if (side !== reportedSide) {
+            reportedSide = side;
+            options.onPlacement?.(side);
+        }
+    }
+    update();
+    window.addEventListener("scroll", update, { passive: true, capture: true });
+    window.addEventListener("resize", update, { passive: true });
+    return {
+        update(newOpts) {
+            // A new `onPlacement` is a new listener that has never been told
+            // anything, so it gets a report even if the side did not move.
+            // Without this, the idiomatic Svelte call site — an inline arrow
+            // in the action's options object, rebuilt on every re-render —
+            // silently never fires after the first one: `reportedSide` is
+            // scoped to the node, not to the callback, so the gate that exists
+            // to suppress duplicate reports to the *same* listener ends up
+            // suppressing the first report to a *different* one.
+            if (newOpts.onPlacement !== options.onPlacement)
+                reportedSide = null;
+            options = newOpts;
+            update();
+        },
+        destroy() {
+            window.removeEventListener("scroll", update, { capture: true });
+            window.removeEventListener("resize", update);
+        },
+    };
+};

package/dist/fancy-ui/_internals/anchor-position.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fancy-ui/_internals/anchor-position.test.js

@@ -0,0 +1,205 @@
+import { afterEach, describe, it, expect, vi } from "vitest";
+import { anchorPosition, computePosition } from "./anchor-position";
+function rect(partial) {
+    const { x = 0, y = 0, width = 0, height = 0 } = partial;
+    return {
+        x,
+        y,
+        width,
+        height,
+        top: y,
+        left: x,
+        right: x + width,
+        bottom: y + height,
+        toJSON() {
+            return this;
+        },
+    };
+}
+const viewport = { width: 1024, height: 768 };
+describe("computePosition", () => {
+    it("places the floating element below the anchor by default", () => {
+        const anchor = rect({ x: 100, y: 100, width: 50, height: 20 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { viewport });
+        expect(result.side).toBe("bottom");
+        expect(result.y).toBe(anchor.bottom + 8); // default offset
+        expect(result.x).toBe(anchor.left + anchor.width / 2 - 100); // centered
+    });
+    it("places the floating element above the anchor when side is 'top'", () => {
+        const anchor = rect({ x: 100, y: 300, width: 50, height: 20 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { side: "top", viewport });
+        expect(result.side).toBe("top");
+        expect(result.y).toBe(anchor.top - 40 - 8);
+    });
+    it("respects a custom offset", () => {
+        const anchor = rect({ x: 100, y: 100, width: 50, height: 20 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { side: "bottom", offset: 16, viewport });
+        expect(result.y).toBe(anchor.bottom + 16);
+    });
+    it("aligns to start / end along the cross axis for a horizontal side", () => {
+        const anchor = rect({ x: 700, y: 100, width: 50, height: 20 });
+        const floating = { width: 100, height: 40 };
+        const start = computePosition(anchor, floating, { side: "bottom", align: "start", viewport });
+        expect(start.x).toBe(anchor.left);
+        const end = computePosition(anchor, floating, { side: "bottom", align: "end", viewport });
+        expect(end.x).toBe(anchor.right - floating.width);
+    });
+    it("aligns to start / end along the cross axis for a vertical side", () => {
+        const anchor = rect({ x: 300, y: 100, width: 50, height: 20 });
+        const floating = { width: 120, height: 60 };
+        const start = computePosition(anchor, floating, { side: "right", align: "start", viewport });
+        expect(start.y).toBe(anchor.top);
+        const end = computePosition(anchor, floating, { side: "right", align: "end", viewport });
+        expect(end.y).toBe(anchor.bottom - floating.height);
+    });
+    it("flips from bottom to top when there is no room below", () => {
+        const anchor = rect({ x: 100, y: 700, width: 50, height: 20 }); // near the bottom edge
+        const result = computePosition(anchor, { width: 200, height: 100 }, { side: "bottom", viewport });
+        expect(result.side).toBe("top");
+        expect(result.y).toBe(anchor.top - 100 - 8);
+    });
+    it("flips from top to bottom when there is no room above", () => {
+        const anchor = rect({ x: 100, y: 10, width: 50, height: 20 }); // near the top edge
+        const result = computePosition(anchor, { width: 200, height: 100 }, { side: "top", viewport });
+        expect(result.side).toBe("bottom");
+        expect(result.y).toBe(anchor.bottom + 8);
+    });
+    it("does not flip when flip is disabled, even if it overflows", () => {
+        const anchor = rect({ x: 100, y: 700, width: 50, height: 20 });
+        const result = computePosition(anchor, { width: 200, height: 100 }, { side: "bottom", flip: false, viewport });
+        expect(result.side).toBe("bottom");
+    });
+    it("clamps horizontally so the floating element never renders off the left edge", () => {
+        const anchor = rect({ x: 5, y: 100, width: 20, height: 20 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { side: "bottom", align: "center", viewport });
+        expect(result.x).toBe(0);
+    });
+    it("clamps horizontally so the floating element never renders off the right edge", () => {
+        const anchor = rect({ x: 1000, y: 100, width: 20, height: 20 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { side: "bottom", align: "center", viewport });
+        expect(result.x).toBe(viewport.width - 200);
+    });
+    it("clamps vertically within the viewport", () => {
+        const anchor = rect({ x: 100, y: -50, width: 50, height: 20 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { side: "top", flip: false, viewport });
+        expect(result.y).toBe(0);
+    });
+    it("is a pure function that does not require a real DOM", () => {
+        const anchor = rect({ x: 0, y: 0, width: 10, height: 10 });
+        expect(() => computePosition(anchor, { width: 10, height: 10 }, { viewport: { width: 100, height: 100 } })).not.toThrow();
+    });
+});
+describe("anchorPosition — onPlacement", () => {
+    afterEach(() => {
+        document.body.innerHTML = "";
+    });
+    /**
+     * jsdom gives every element a zero rect, so both the anchor and the
+     * floating node need stubbed geometry for a flip to be reachable at all.
+     * The viewport is jsdom's default 1024x768.
+     */
+    function setup(anchorRect, floating) {
+        const anchorEl = document.createElement("button");
+        const node = document.createElement("div");
+        document.body.append(anchorEl, node);
+        anchorEl.getBoundingClientRect = () => rect(anchorRect);
+        node.getBoundingClientRect = () => rect({ width: floating.width, height: floating.height });
+        return { anchorEl, node };
+    }
+    it("reports the requested side when nothing flips", () => {
+        const { anchorEl, node } = setup({ x: 100, y: 100, width: 50, height: 20 }, {
+            width: 200,
+            height: 100,
+        });
+        const seen = [];
+        const action = anchorPosition(node, {
+            anchor: () => anchorEl,
+            side: "bottom",
+            onPlacement: (side) => seen.push(side),
+        });
+        expect(seen).toEqual(["bottom"]);
+        action?.destroy?.();
+    });
+    it("reports the opposite side when the requested one overflows", () => {
+        // 740 + 8 offset + 100 tall = 848, past jsdom's 768-high viewport.
+        const { anchorEl, node } = setup({ x: 100, y: 720, width: 50, height: 20 }, {
+            width: 200,
+            height: 100,
+        });
+        const seen = [];
+        const action = anchorPosition(node, {
+            anchor: () => anchorEl,
+            side: "bottom",
+            onPlacement: (side) => seen.push(side),
+        });
+        expect(seen).toEqual(["top"]);
+        action?.destroy?.();
+    });
+    it("does not re-report while the resolved side stays the same", () => {
+        const { anchorEl, node } = setup({ x: 100, y: 100, width: 50, height: 20 }, {
+            width: 200,
+            height: 100,
+        });
+        const onPlacement = vi.fn();
+        const action = anchorPosition(node, { anchor: () => anchorEl, onPlacement });
+        window.dispatchEvent(new Event("scroll"));
+        window.dispatchEvent(new Event("resize"));
+        // One initial placement, and silence for recomputes that land on the
+        // same side — otherwise every scroll frame would re-render a caret.
+        expect(onPlacement).toHaveBeenCalledTimes(1);
+        action?.destroy?.();
+    });
+    it("reports again once the resolved side actually changes", () => {
+        const anchorEl = document.createElement("button");
+        const node = document.createElement("div");
+        document.body.append(anchorEl, node);
+        node.getBoundingClientRect = () => rect({ width: 200, height: 100 });
+        let anchorTop = 100;
+        anchorEl.getBoundingClientRect = () => rect({ x: 100, y: anchorTop, width: 50, height: 20 });
+        const seen = [];
+        const action = anchorPosition(node, {
+            anchor: () => anchorEl,
+            side: "bottom",
+            onPlacement: (side) => seen.push(side),
+        });
+        // The anchor scrolls down far enough that "bottom" no longer fits.
+        anchorTop = 720;
+        window.dispatchEvent(new Event("scroll"));
+        expect(seen).toEqual(["bottom", "top"]);
+        action?.destroy?.();
+    });
+    it("reports to a replacement callback even though the side has not moved", () => {
+        const { anchorEl, node } = setup({ x: 100, y: 100, width: 50, height: 20 }, { width: 200, height: 100 });
+        const first = vi.fn();
+        const second = vi.fn();
+        const action = anchorPosition(node, {
+            anchor: () => anchorEl,
+            side: "bottom",
+            onPlacement: first,
+        });
+        expect(first).toHaveBeenCalledTimes(1);
+        // What an inline arrow in the action's options object produces on every
+        // re-render: identical geometry, a brand-new function. It has never
+        // been told the side, so silence here would leave it permanently
+        // uninformed — the gate exists to suppress duplicate reports to the
+        // same listener, not the first report to a new one.
+        action?.update?.({
+            anchor: () => anchorEl,
+            side: "bottom",
+            onPlacement: second,
+        });
+        expect(second).toHaveBeenCalledTimes(1);
+        expect(second).toHaveBeenCalledWith("bottom");
+        expect(first).toHaveBeenCalledTimes(1);
+        action?.destroy?.();
+    });
+    it("still stays silent for a same-callback update with an unchanged side", () => {
+        const { anchorEl, node } = setup({ x: 100, y: 100, width: 50, height: 20 }, { width: 200, height: 100 });
+        const onPlacement = vi.fn();
+        const opts = { anchor: () => anchorEl, side: "bottom", onPlacement };
+        const action = anchorPosition(node, opts);
+        action?.update?.({ ...opts, offset: 12 });
+        expect(onPlacement).toHaveBeenCalledTimes(1);
+        action?.destroy?.();
+    });
+});

package/dist/fancy-ui/_internals/autoscroll.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Autoscroll (scroll anchor)
+ *
+ * Keeps a scrollable container pinned to its bottom edge while new content
+ * streams in, and lets go the moment the reader scrolls up to look back.
+ *
+ * "Stuck" is a pure function of the distance from the bottom, recomputed on
+ * every scroll event. There is no programmatic-scroll flag to get out of sync:
+ * whatever the scrollbar says is the truth.
+ */
+import type { ActionReturn } from "svelte/action";
+export interface AutoscrollOptions {
+    /** Set to false to release the container and disconnect every listener. */
+    enabled?: boolean;
+    /** How close to the bottom (px) still counts as pinned. */
+    bottomThreshold?: number;
+    /**
+     * Start pinned and jump to the bottom on connect, whatever the container's
+     * scroll position says. For a region that mounts with content already in it —
+     * a reasoning trace joined mid-stream, a replayed transcript — a fresh
+     * container sits at scrollTop 0, which reads as "the reader scrolled up" and
+     * would leave every later chunk stranded at the top.
+     */
+    pinOnConnect?: boolean;
+    /** Called only when the pinned state flips, never on every scroll. */
+    onStickChange?: (stuck: boolean) => void;
+}
+/** Jump a container to its bottom. Smooth by default. */
+export declare function scrollToBottom(node: HTMLElement, behavior?: ScrollBehavior): void;
+export declare function autoscroll(node: HTMLElement, opts?: AutoscrollOptions): ActionReturn<AutoscrollOptions>;