@classic-homes/agent-chat 0.11.0 → 0.13.0

package/dist/session.svelte.js

@@ -1,5 +1,8 @@
 import { ApiRequestError } from '@classic-homes/agent-client';
-import { applyEvent, newAssistantMessage, newUserMessage, latestTurn, turnForRetry, } from './reducer.js';
+import { applyEvent, isContinuable, newAssistantMessage, newUserMessage, latestTurn, turnForRetry, } from './reducer.js';
+/** Re-attach attempts after a stream ends without `done` (a dropped connection). */
+const RESUME_ATTEMPTS = 2;
+const DEFAULT_CANCEL_GRACE_MS = 3000;
 /**
  * Reactive conversation state (Svelte 5 runes class). Owns the stream lifecycle: one turn at a
  * time, cancel, resume after reload, history load. Rendering is left to the components.
@@ -15,16 +18,35 @@ export class ChatSession {
     agent = $state('classic-agent');
     loadError = $state(undefined);
     pendingFiles = $state([]);
+    /** The unsent composer text, kept here so it survives the view being remounted. */
+    draft = $state('');
     controller;
     /** The request being streamed; differs from the shown answer's id while continuing it. */
     streamRequestId;
+    /** Set once Stop was pressed for the running stream (the server cancel is on its way). */
+    cancelling = false;
+    cancelTimer;
+    /** Bumped by each load and reset, so a superseded load drops its result. */
+    loadToken = 0;
     options;
+    listeners = new Set();
     constructor(options) {
         this.options = options;
         this.conversationId = options.conversationId ?? null;
         this.mode = options.mode;
         this.agent = options.agent ?? 'classic-agent';
     }
+    /**
+     * Observe this session's stream events for as long as a view needs them. A session can
+     * outlive the component showing it (a host moving the chat between surfaces), so views
+     * subscribe instead of owning the `onEvent` option. Returns the unsubscribe.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
     get streaming() {
         return this.status === 'streaming';
     }
@@ -32,12 +54,43 @@ export class ChatSession {
         const last = this.messages[this.messages.length - 1];
         return last?.role === 'assistant' ? last : undefined;
     }
+    /**
+     * Forget the current conversation (the host started a new chat): stops reading a running
+     * stream without cancelling it on the server (the turn finishes there and stays in its
+     * conversation) and clears the transcript.
+     */
+    reset() {
+        this.loadToken += 1;
+        this.detach();
+        this.status = 'idle';
+        this.messages = [];
+        this.conversationId = null;
+        this.loadedConversationId = null;
+        this.loadError = undefined;
+        this.pendingFiles = [];
+    }
+    /** Stop reading the running stream, if any; its `run` then leaves the session alone. */
+    detach() {
+        const controller = this.controller;
+        this.controller = undefined;
+        this.streamRequestId = undefined;
+        this.cancelling = false;
+        clearTimeout(this.cancelTimer);
+        this.cancelTimer = undefined;
+        controller?.abort();
+    }
     /** Load an existing conversation's transcript and re-attach to a running turn if any. */
     async load(conversationId) {
+        // Another conversation's stream must not keep writing into (or finishing) this one.
+        this.detach();
+        const token = ++this.loadToken;
         this.status = 'loading';
         this.loadError = undefined;
         try {
             const detail = await this.options.client.getConversation(conversationId);
+            // A newer load or a reset took over while this one waited.
+            if (token !== this.loadToken)
+                return;
             this.conversationId = conversationId;
             this.loadedConversationId = conversationId;
             this.messages = detail.messages.map((m) => m.role === 'user'
@@ -51,13 +104,9 @@ export class ChatSession {
                 : {
                     ...newAssistantMessage(m.id.replace(/^a-/, ''), m.createdAt),
                     text: m.content.map((c) => c.text).join('\n'),
-                    // An answer that ended early keeps its Continue after a reload.
-                    status: m.finish === 'length'
-                        ? 'incomplete'
-                        : m.finish === 'cancelled'
-                            ? 'cancelled'
-                            : 'done',
-                    ...(m.finish ? { finishReason: m.finish } : {}),
+                    // An answer that ended early keeps its Continue (or, after an error, its Try
+                    // again) after a reload. A finish this client does not know reads as done.
+                    ...loadedFinish(m.finish),
                     ...(detail.feedback?.[m.id.replace(/^a-/, '')]
                         ? { feedback: detail.feedback[m.id.replace(/^a-/, '')] }
                         : {}),
@@ -69,6 +118,8 @@ export class ChatSession {
                 await this.resume(active);
         }
         catch (err) {
+            if (token !== this.loadToken)
+                return;
             this.status = 'idle';
             this.loadError = err instanceof Error ? err.message : 'Could not load the conversation';
         }
@@ -95,10 +146,15 @@ export class ChatSession {
             ...(this.options.clientKind ? { client: this.options.clientKind } : {}),
             ...(options.replaces ? { replaces: options.replaces } : {}),
         };
+        const answer = newAssistantMessage(requestId);
+        // Until the runtime accepts the turn (`start`), remember which stored turn it replaces, so
+        // retrying a turn that never started still replaces the original (see `replacesFor`).
+        if (options.replaces)
+            answer.replaces = options.replaces;
         this.messages = [
             ...this.messages,
             newUserMessage(requestId, message, { attachments: files, context }),
-            newAssistantMessage(requestId),
+            answer,
         ];
         await this.run(requestId, (signal, onEvent) => this.options.client.streamChat(request, { signal, onEvent }));
     }
@@ -112,8 +168,17 @@ export class ChatSession {
         const turn = turnForRetry(this.messages, requestId);
         if (!turn)
             return;
+        const replaces = this.replacesFor(requestId);
         this.messages = turn.rest;
-        await this.send(turn.user.text, { files: turn.user.attachments, replaces: requestId });
+        await this.send(turn.user.text, { files: turn.user.attachments, replaces });
+    }
+    /**
+     * The stored turn a resend of `requestId` replaces: the request itself once the runtime
+     * accepted it, else the turn that request was meant to replace (the runtime never stored it).
+     */
+    replacesFor(requestId) {
+        const answer = this.messages.find((m) => m.role === 'assistant' && m.requestId === requestId);
+        return answer?.replaces ?? requestId;
     }
     /** Ask again for a new answer to the latest question, replacing the current one. */
     async regenerate(requestId) {
@@ -122,8 +187,9 @@ export class ChatSession {
         const turn = latestTurn(this.messages, requestId);
         if (!turn)
             return;
+        const replaces = this.replacesFor(requestId);
         this.messages = turn.rest;
-        await this.send(turn.user.text, { files: turn.user.attachments, replaces: requestId });
+        await this.send(turn.user.text, { files: turn.user.attachments, replaces });
     }
     /** Change the latest question and answer it again, replacing that turn. */
     async edit(requestId, text) {
@@ -132,8 +198,9 @@ export class ChatSession {
         const turn = latestTurn(this.messages, requestId);
         if (!turn)
             return;
+        const replaces = this.replacesFor(requestId);
         this.messages = turn.rest;
-        await this.send(text, { files: turn.user.attachments, replaces: requestId });
+        await this.send(text, { files: turn.user.attachments, replaces });
     }
     /**
      * Carry on the latest answer where it was cut short or stopped. The runtime asks the agent to
@@ -145,10 +212,9 @@ export class ChatSession {
         if (!conversationId || this.status !== 'idle')
             return;
         const last = this.current;
-        if (last?.requestId !== requestId ||
-            (last.status !== 'incomplete' && last.status !== 'cancelled') ||
-            !last.text)
+        if (last?.requestId !== requestId || !isContinuable(last))
             return;
+        const previous = { status: last.status, finishReason: last.finishReason };
         const request = {
             requestId: crypto.randomUUID(),
             conversationId,
@@ -163,7 +229,7 @@ export class ChatSession {
             delete next.error;
             return next;
         });
-        await this.run(requestId, (signal, onEvent) => this.options.client.streamChat(request, { signal, onEvent }), request.requestId);
+        await this.run(requestId, (signal, onEvent) => this.options.client.streamChat(request, { signal, onEvent }), request.requestId, previous);
     }
     /** Re-attach to a turn after reload: replays events after the last seq we hold (none here). */
     async resume(requestId) {
@@ -207,20 +273,40 @@ export class ChatSession {
             throw err;
         }
     }
+    /**
+     * Stop the running answer. The runtime is asked to cancel and the stream is read on until its
+     * `done`, so text produced before the cancel landed still shows (and a later Continue appends
+     * after it); after `cancelGraceMs` the stream is dropped locally. The answer shows as stopped
+     * at once.
+     */
     cancel() {
         const current = this.current;
-        if (!this.controller || !current)
+        const controller = this.controller;
+        if (!controller || !current || this.cancelling)
             return;
-        this.controller.abort();
-        void this.options.client.cancel(this.streamRequestId ?? current.requestId);
+        this.cancelling = true;
+        const answerId = current.requestId;
+        this.update(answerId, (m) => m.status === 'streaming' ? { ...m, status: 'cancelled', finishReason: 'cancelled' } : m);
+        void this.options.client.cancel(this.streamRequestId ?? answerId);
+        this.cancelTimer = setTimeout(() => controller.abort(), this.options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS);
     }
     async run(requestId, start, 
     /** The request streamed, when it is not `requestId` (a continuation of that answer). */
-    streamRequestId = requestId) {
+    streamRequestId = requestId, 
+    /** A continuation: the answer's state before it, restored when the continuation fails. */
+    previous) {
+        this.detach();
         this.status = 'streaming';
-        this.controller = new AbortController();
+        const controller = new AbortController();
+        this.controller = controller;
         this.streamRequestId = streamRequestId;
+        // A reset, a load or a newer turn replaced this stream: leave the session alone.
+        const stale = () => this.controller !== controller;
+        let lastSeq = -1;
         const onEvent = (event) => {
+            if (stale())
+                return;
+            lastSeq = event.seq;
             if (event.type === 'start') {
                 this.mode = event.mode;
                 if (this.conversationId !== event.conversationId) {
@@ -233,15 +319,48 @@ export class ChatSession {
                 this.options.onToolResult?.(this.toolName(requestId, event.callId), event.status);
             this.update(requestId, (m) => applyEvent(m, event));
             this.options.onEvent?.(event);
+            for (const listener of [...this.listeners])
+                listener(event);
         };
         try {
-            const outcome = await start(this.controller.signal, onEvent);
+            let outcome = await start(controller.signal, onEvent);
+            // The connection dropped before `done`: the turn may still be running (or have just
+            // finished) on the server, so re-attach after the last event seen. Continue is not the
+            // answer here; the runtime refuses it while the turn runs.
+            for (let attempt = 0; outcome.kind === 'ended' && attempt < RESUME_ATTEMPTS && !stale() && !this.cancelling; attempt += 1) {
+                const conversationId = this.conversationId;
+                if (!conversationId)
+                    break;
+                try {
+                    outcome = await this.options.client.resumeTurn(conversationId, streamRequestId, lastSeq, {
+                        signal: controller.signal,
+                        onEvent,
+                    });
+                }
+                catch {
+                    // Counts as an attempt; the outcome stays `ended`.
+                }
+            }
+            if (stale())
+                return;
             if (outcome.kind === 'aborted')
                 this.update(requestId, (m) => m.status === 'streaming' ? { ...m, status: 'cancelled', finishReason: 'cancelled' } : m);
             else if (outcome.kind === 'ended')
-                this.update(requestId, (m) => m.status === 'streaming' ? { ...m, status: 'incomplete' } : m);
+                this.update(requestId, (m) => m.status === 'streaming'
+                    ? {
+                        ...m,
+                        status: 'error',
+                        error: {
+                            code: 'network',
+                            message: 'The connection was lost before the answer finished.',
+                            retryable: true,
+                        },
+                    }
+                    : m);
         }
         catch (err) {
+            if (stale())
+                return;
             const code = err instanceof ApiRequestError ? err.code : 'network';
             const text = err instanceof Error ? err.message : 'The request failed';
             this.update(requestId, (m) => ({
@@ -255,6 +374,28 @@ export class ChatSession {
             }));
         }
         finally {
+            if (!stale())
+                this.finish(requestId, previous);
+        }
+    }
+    /** The turn's stream is over: restore a failed continuation, go idle, tell the host. */
+    finish(requestId, previous) {
+        // A failed continuation keeps the text so far continuable; the error shows inline.
+        if (previous)
+            this.update(requestId, (m) => {
+                if (m.status !== 'error')
+                    return m;
+                const next = { ...m, status: previous.status };
+                if (previous.finishReason)
+                    next.finishReason = previous.finishReason;
+                else
+                    delete next.finishReason;
+                return next;
+            });
+        {
+            clearTimeout(this.cancelTimer);
+            this.cancelTimer = undefined;
+            this.cancelling = false;
             this.controller = undefined;
             this.streamRequestId = undefined;
             this.status = 'idle';
@@ -274,6 +415,20 @@ export class ChatSession {
         this.messages = this.messages.map((m) => m.role === 'assistant' && m.requestId === requestId ? fn(m) : m);
     }
 }
+/** Status for a stored answer's `finish` (absent: it finished normally). */
+function loadedFinish(finish) {
+    if (finish === 'length')
+        return { status: 'incomplete', finishReason: 'length' };
+    if (finish === 'cancelled')
+        return { status: 'cancelled', finishReason: 'cancelled' };
+    if (finish === 'error')
+        return {
+            status: 'error',
+            finishReason: 'error',
+            error: { code: 'upstream_error', message: 'The answer did not finish.', retryable: true },
+        };
+    return { status: 'done' };
+}
 export function createChatSession(options) {
     return new ChatSession(options);
 }

package/dist/shortcuts.d.ts

@@ -8,4 +8,11 @@ export interface ChatShortcut {
 }
 /** What the chat itself handles, in the composer. Hosts add their own (e.g. a panel toggle). */
 export declare const CHAT_SHORTCUTS: readonly ChatShortcut[];
+/**
+ * The chat's shortcuts for the dialog: without saved prompts (`AgentChat`'s `prompts`) the `/`
+ * menu is off, so its entry is left out.
+ */
+export declare function chatShortcuts(options?: {
+    savedPrompts?: boolean;
+}): ChatShortcut[];
 //# sourceMappingURL=shortcuts.d.ts.map

package/dist/shortcuts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../src/lib/shortcuts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gGAAgG;AAChG,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAMjD,CAAC"}
+{"version":3,"file":"shortcuts.d.ts","sourceRoot":"","sources":["../src/lib/shortcuts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gGAAgG;AAChG,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAMjD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,YAAY,EAAE,CAItF"}

package/dist/shortcuts.js

@@ -6,3 +6,12 @@ export const CHAT_SHORTCUTS = [
     { keys: ['/'], label: 'Insert a saved prompt' },
     { keys: ['Esc'], label: 'Cancel editing a message' },
 ];
+/**
+ * The chat's shortcuts for the dialog: without saved prompts (`AgentChat`'s `prompts`) the `/`
+ * menu is off, so its entry is left out.
+ */
+export function chatShortcuts(options = {}) {
+    return options.savedPrompts === false
+        ? CHAT_SHORTCUTS.filter((s) => s.label !== 'Insert a saved prompt')
+        : [...CHAT_SHORTCUTS];
+}

package/dist/surface-geometry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Geometry for the detached chat: a floating launcher button that snaps to a viewport corner and
+ * a floating window the user can move and resize. Pure functions in viewport (CSS px,
+ * `position: fixed`) coordinates so they can be tested without layout.
+ *
+ * The drag threshold and the separate launcher/window positions follow the customer chat widget
+ * (Classic-Homes/chat, `packages/widget`), rewritten for this package.
+ */
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Rect extends Point, Size {
+}
+export type Corner = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+export declare const CORNERS: readonly Corner[];
+/** Compass edges a resize handle moves. */
+export type ResizeDirection = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+export declare const RESIZE_DIRECTIONS: readonly ResizeDirection[];
+export declare const FLOAT_LIMITS: {
+    readonly minWidth: 340;
+    readonly minHeight: 420;
+    readonly maxWidth: 900;
+    readonly maxHeight: 1000;
+    /** Gap kept between the window and the viewport edge. */
+    readonly margin: 12;
+};
+export declare const DEFAULT_FLOAT_SIZE: Size;
+export declare const LAUNCHER_SIZE = 56;
+export declare const LAUNCHER_MARGIN = 20;
+/** Pointer travel (px) before a press on the launcher or the window header counts as a drag. */
+export declare const DRAG_THRESHOLD = 3;
+/** Releasing a dragged window with the pointer this close to the right edge docks it. */
+export declare const DOCK_THRESHOLD = 24;
+/** Arrow-key step for moving and resizing the window; Alt makes it fine. */
+export declare const KEY_STEP = 24;
+/** Size within the limits and never larger than the viewport allows. */
+export declare function clampSize(size: Size, viewport: Size): Size;
+/** The rect resized to the limits and moved fully inside the viewport. */
+export declare function clampRect(rect: Rect, viewport: Size): Rect;
+/** Where a new window opens: beside the launcher's corner, clear of the launcher itself. */
+export declare function defaultRect(viewport: Size, corner: Corner, size?: Size): Rect;
+/** Top-left point of the launcher button when it sits in `corner`. */
+export declare function launcherPoint(corner: Corner, viewport: Size): Point;
+/** Keep a freely placed launcher button fully inside the viewport. */
+export declare function clampLauncher(point: Point, viewport: Size): Point;
+/** The corner a dropped launcher snaps to. */
+export declare function nearestCorner(point: Point, viewport: Size): Corner;
+/**
+ * The rect after dragging a resize handle by `(dx, dy)`. The opposite edge stays put, also when
+ * a limit stops the dragged edge.
+ */
+export declare function resizeRect(rect: Rect, direction: ResizeDirection, dx: number, dy: number, viewport: Size): Rect;
+/** Was a dragged window released against the right edge (the dock side)? */
+export declare function isDockDrop(pointer: Point, viewport: Size): boolean;
+//# sourceMappingURL=surface-geometry.d.ts.map

package/dist/surface-geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-geometry.d.ts","sourceRoot":"","sources":["../src/lib/surface-geometry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,KAAK;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AACD,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,IAAK,SAAQ,KAAK,EAAE,IAAI;CAAG;AAE5C,MAAM,MAAM,MAAM,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAC/E,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAA6D,CAAC;AAEnG,2CAA2C;AAC3C,MAAM,MAAM,eAAe,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAChF,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EASvD,CAAC;AAEF,eAAO,MAAM,YAAY;;;;;IAKvB,yDAAyD;;CAEjD,CAAC;AACX,eAAO,MAAM,kBAAkB,EAAE,IAAkC,CAAC;AACpE,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,gGAAgG;AAChG,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,yFAAyF;AACzF,eAAO,MAAM,cAAc,KAAK,CAAC;AACjC,4EAA4E;AAC5E,eAAO,MAAM,QAAQ,KAAK,CAAC;AAK3B,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAG,IAAI,CAS1D;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAG,IAAI,CAQ1D;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,IAAyB,GAAG,IAAI,CAmBjG;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,GAAG,KAAK,CAMnE;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,GAAG,KAAK,CAIjE;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,GAAG,MAAM,CAIlE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,eAAe,EAC1B,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,IAAI,GACb,IAAI,CAaN;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,GAAG,OAAO,CAElE"}

package/dist/surface-geometry.js

@@ -0,0 +1,112 @@
+export const CORNERS = ['bottom-right', 'bottom-left', 'top-right', 'top-left'];
+export const RESIZE_DIRECTIONS = [
+    'n',
+    's',
+    'e',
+    'w',
+    'ne',
+    'nw',
+    'se',
+    'sw',
+];
+export const FLOAT_LIMITS = {
+    minWidth: 340,
+    minHeight: 420,
+    maxWidth: 900,
+    maxHeight: 1000,
+    /** Gap kept between the window and the viewport edge. */
+    margin: 12,
+};
+export const DEFAULT_FLOAT_SIZE = { width: 420, height: 640 };
+export const LAUNCHER_SIZE = 56;
+export const LAUNCHER_MARGIN = 20;
+/** Pointer travel (px) before a press on the launcher or the window header counts as a drag. */
+export const DRAG_THRESHOLD = 3;
+/** Releasing a dragged window with the pointer this close to the right edge docks it. */
+export const DOCK_THRESHOLD = 24;
+/** Arrow-key step for moving and resizing the window; Alt makes it fine. */
+export const KEY_STEP = 24;
+const between = (value, min, max) => Math.min(Math.max(value, min), Math.max(min, max));
+/** Size within the limits and never larger than the viewport allows. */
+export function clampSize(size, viewport) {
+    const { minWidth, minHeight, maxWidth, maxHeight, margin } = FLOAT_LIMITS;
+    const roomX = viewport.width - margin * 2;
+    const roomY = viewport.height - margin * 2;
+    return {
+        // A viewport smaller than the minimum wins: the window must stay fully visible.
+        width: Math.round(Math.min(between(size.width, minWidth, maxWidth), Math.max(roomX, 0))),
+        height: Math.round(Math.min(between(size.height, minHeight, maxHeight), Math.max(roomY, 0))),
+    };
+}
+/** The rect resized to the limits and moved fully inside the viewport. */
+export function clampRect(rect, viewport) {
+    const size = clampSize(rect, viewport);
+    const { margin } = FLOAT_LIMITS;
+    return {
+        ...size,
+        x: Math.round(between(rect.x, margin, viewport.width - size.width - margin)),
+        y: Math.round(between(rect.y, margin, viewport.height - size.height - margin)),
+    };
+}
+/** Where a new window opens: beside the launcher's corner, clear of the launcher itself. */
+export function defaultRect(viewport, corner, size = DEFAULT_FLOAT_SIZE) {
+    const clear = LAUNCHER_MARGIN + LAUNCHER_SIZE + FLOAT_LIMITS.margin;
+    const fitted = clampSize({
+        width: size.width,
+        height: Math.min(size.height, viewport.height - clear - FLOAT_LIMITS.margin),
+    }, viewport);
+    return clampRect({
+        ...fitted,
+        x: corner.endsWith('left')
+            ? LAUNCHER_MARGIN
+            : viewport.width - fitted.width - LAUNCHER_MARGIN,
+        y: corner.startsWith('top') ? clear : viewport.height - fitted.height - clear,
+    }, viewport);
+}
+/** Top-left point of the launcher button when it sits in `corner`. */
+export function launcherPoint(corner, viewport) {
+    const far = (extent) => Math.max(0, extent - LAUNCHER_SIZE - LAUNCHER_MARGIN);
+    return {
+        x: corner.endsWith('left') ? LAUNCHER_MARGIN : far(viewport.width),
+        y: corner.startsWith('top') ? LAUNCHER_MARGIN : far(viewport.height),
+    };
+}
+/** Keep a freely placed launcher button fully inside the viewport. */
+export function clampLauncher(point, viewport) {
+    const within = (value, extent) => Math.min(Math.max(0, value), Math.max(0, extent - LAUNCHER_SIZE));
+    return { x: within(point.x, viewport.width), y: within(point.y, viewport.height) };
+}
+/** The corner a dropped launcher snaps to. */
+export function nearestCorner(point, viewport) {
+    const vertical = point.y < viewport.height / 2 ? 'top' : 'bottom';
+    const horizontal = point.x < viewport.width / 2 ? 'left' : 'right';
+    return `${vertical}-${horizontal}`;
+}
+/**
+ * The rect after dragging a resize handle by `(dx, dy)`. The opposite edge stays put, also when
+ * a limit stops the dragged edge.
+ */
+export function resizeRect(rect, direction, dx, dy, viewport) {
+    const { margin } = FLOAT_LIMITS;
+    let { x, y, width, height } = rect;
+    const right = x + width;
+    const bottom = y + height;
+    if (direction.includes('e'))
+        width = Math.min(width + dx, viewport.width - margin - x);
+    if (direction.includes('s'))
+        height = Math.min(height + dy, viewport.height - margin - y);
+    if (direction.includes('w'))
+        width = Math.min(width - dx, right - margin);
+    if (direction.includes('n'))
+        height = Math.min(height - dy, bottom - margin);
+    ({ width, height } = clampSize({ width, height }, viewport));
+    if (direction.includes('w'))
+        x = right - width;
+    if (direction.includes('n'))
+        y = bottom - height;
+    return clampRect({ x, y, width, height }, viewport);
+}
+/** Was a dragged window released against the right edge (the dock side)? */
+export function isDockDrop(pointer, viewport) {
+    return pointer.x >= viewport.width - DOCK_THRESHOLD;
+}

package/dist/surface.svelte.d.ts

@@ -0,0 +1,79 @@
+import { type Corner, type Point, type Rect, type ResizeDirection, type Size } from './surface-geometry.js';
+/**
+ * How the chat is presented over a host page: collapsed to the launcher button, a floating
+ * window, or docked to the side. The full page is a host route, not a mode here; a host on that
+ * route simply renders none of these.
+ */
+export type SurfaceMode = 'launcher' | 'float' | 'dock';
+export type OpenSurfaceMode = Exclude<SurfaceMode, 'launcher'>;
+/** What the collapsed launcher shows about the chat behind it. */
+export type LauncherStatus = 'idle' | 'streaming' | 'unread' | 'error';
+export interface ChatSurfaceOptions {
+    /** Where layout is remembered, e.g. `classic-agent:surface:<userId>`. Not persisted without it. */
+    storageKey?: string;
+    /** Defaults to `localStorage` when available. */
+    storage?: Pick<Storage, 'getItem' | 'setItem'>;
+    /** Defaults to the window's inner size. */
+    viewport?: () => Size;
+    /** What the launcher opens the first time. */
+    defaultOpen?: OpenSurfaceMode;
+    corner?: Corner;
+}
+/**
+ * Reactive state of the detached chat (Svelte 5 runes class): which presentation is showing,
+ * where the launcher sits, the floating window's geometry and whether an answer arrived unseen.
+ * Layout survives reloads through `storageKey`; a saved window that no longer fits the viewport
+ * is pulled back inside.
+ */
+export declare class ChatSurface {
+    mode: SurfaceMode;
+    /** The open presentation the launcher returns to. */
+    lastOpen: OpenSurfaceMode;
+    corner: Corner;
+    /**
+     * Where the user dropped the launcher (its top-left), or null while it sits in `corner`.
+     * Separate from the window's place: moving one never moves the other.
+     */
+    launcher: Point | null;
+    /** An answer finished while the chat was collapsed. Cleared on open. */
+    unread: boolean;
+    /** True while the user drags or resizes the window. */
+    moving: boolean;
+    private saved;
+    private readonly options;
+    constructor(options?: ChatSurfaceOptions);
+    get isOpen(): boolean;
+    /** The floating window's rect; a default beside the launcher until the user moves it. */
+    get rect(): Rect;
+    open(mode?: OpenSurfaceMode): void;
+    minimize(): void;
+    toggle(): void;
+    dock(): void;
+    float(): void;
+    /** A turn ended; flag it when the user cannot see the answer. */
+    notifyTurnEnd(): void;
+    setCorner(corner: Corner): void;
+    /**
+     * The user dropped the launcher at `point` (top-left). It stays there; `corner` follows the
+     * nearest one, which is where a window that was never moved opens.
+     */
+    setLauncher(point: Point): void;
+    /** Move the window by a pointer or key delta. Call `commit` when the gesture ends. */
+    moveBy(dx: number, dy: number): void;
+    resizeBy(direction: ResizeDirection, dx: number, dy: number): void;
+    /** End of a move or resize: remember the result. */
+    commit(): void;
+    /** Forget the user's geometry and return the window to its default place. */
+    resetRect(): void;
+    /**
+     * Keep the window inside the viewport as it changes size. Returns the cleanup; call from an
+     * effect while the floating window is mounted.
+     */
+    attach(target?: Pick<Window, 'addEventListener' | 'removeEventListener'>): () => void;
+    private viewport;
+    private storage;
+    private restore;
+    private persist;
+}
+export declare function createChatSurface(options?: ChatSurfaceOptions): ChatSurface;
+//# sourceMappingURL=surface.svelte.d.ts.map

package/dist/surface.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface.svelte.d.ts","sourceRoot":"","sources":["../src/lib/surface.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,KAAK,MAAM,EACX,KAAK,KAAK,EACV,KAAK,IAAI,EACT,KAAK,eAAe,EACpB,KAAK,IAAI,EACV,MAAM,uBAAuB,CAAC;AAE/B;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AACxD,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;AAE/D,kEAAkE;AAClE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEvE,MAAM,WAAW,kBAAkB;IACjC,mGAAmG;IACnG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;IAC/C,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAuBD;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,IAAI,cAAmC;IACvC,qDAAqD;IACrD,QAAQ,kBAAoC;IAC5C,MAAM,SAAkC;IACxC;;;OAGG;IACH,QAAQ,eAA8B;IACtC,wEAAwE;IACxE,MAAM,UAAiB;IACvB,uDAAuD;IACvD,MAAM,UAAiB;IACvB,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;gBAEjC,OAAO,GAAE,kBAAuB;IAO5C,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,yFAAyF;IACzF,IAAI,IAAI,IAAI,IAAI,CAGf;IAED,IAAI,CAAC,IAAI,GAAE,eAA+B,GAAG,IAAI;IAMjD,QAAQ,IAAI,IAAI;IAIhB,MAAM,IAAI,IAAI;IAId,IAAI,IAAI,IAAI;IAGZ,KAAK,IAAI,IAAI;IAIb,iEAAiE;IACjE,aAAa,IAAI,IAAI;IAIrB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK/B;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAU/B,sFAAsF;IACtF,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAIpC,QAAQ,CAAC,SAAS,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAGlE,oDAAoD;IACpD,MAAM,IAAI,IAAI;IAId,6EAA6E;IAC7E,SAAS,IAAI,IAAI;IAKjB;;;OAGG;IACH,MAAM,CAAC,MAAM,GAAE,IAAI,CAAC,MAAM,EAAE,kBAAkB,GAAG,qBAAqB,CAAU,GAAG,MAAM,IAAI;IAS7F,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,OAAO;IAkBf,OAAO,CAAC,OAAO;CAehB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,WAAW,CAE/E"}