jupyterlab-chat 0.25.0-alpha.7 → 0.25.0

package/lib/__tests__/model.spec.js

@@ -39,8 +39,7 @@ describe('LabChatModel', () => {
             sharedModel,
             collaborative: true
         });
-        // Resolve the ready promise so messagesInserted can proceed.
-        model.id = UUID.uuid4();
+        model.markDocumentSynced();
     });
     afterEach(() => {
         Signal.clearData(model);
@@ -126,6 +125,84 @@ describe('LabChatModel', () => {
             expect(model.messages[0].mime_model).toEqual(mimeModel);
         });
     });
+    describe('ready resolves after messages are loaded', () => {
+        it('messages present in sharedModel before sync are buffered, not yet in model', () => {
+            const sm = YChat.create();
+            const m = new LabChatModel({
+                widgetConfig: makeWidgetConfig(),
+                user: TEST_USER,
+                sharedModel: sm,
+                collaborative: true
+            });
+            sm.addMessage({
+                type: 'msg',
+                id: UUID.uuid4(),
+                body: 'pre-sync',
+                time: 1000,
+                sender: TEST_USER.username
+            });
+            // Not yet synced: message must be buffered, not inserted.
+            expect(m.messages).toHaveLength(0);
+            sm.dispose();
+        });
+        it('messages are in model.messages when ready resolves', async () => {
+            const sm = YChat.create();
+            const m = new LabChatModel({
+                widgetConfig: makeWidgetConfig(),
+                user: TEST_USER,
+                sharedModel: sm,
+                collaborative: true
+            });
+            sm.addMessage({
+                type: 'msg',
+                id: UUID.uuid4(),
+                body: 'pre-sync',
+                time: 1000,
+                sender: TEST_USER.username
+            });
+            m.markDocumentSynced();
+            await m.ready;
+            expect(m.messages).toHaveLength(1);
+            expect(m.messages[0].body).toBe('pre-sync');
+            sm.dispose();
+        });
+        it('model.messages is already populated inside the ready .then() callback', async () => {
+            const sm = YChat.create();
+            const m = new LabChatModel({
+                widgetConfig: makeWidgetConfig(),
+                user: TEST_USER,
+                sharedModel: sm,
+                collaborative: true
+            });
+            sm.addMessage({
+                type: 'msg',
+                id: UUID.uuid4(),
+                body: 'pre-sync',
+                time: 1000,
+                sender: TEST_USER.username
+            });
+            let messagesAtReady = -1;
+            const check = m.ready.then(() => {
+                messagesAtReady = m.messages.length;
+            });
+            m.markDocumentSynced();
+            await check;
+            expect(messagesAtReady).toBe(1);
+            sm.dispose();
+        });
+        it('messages added after sync are inserted directly without buffering', async () => {
+            await model.ready;
+            sharedModel.addMessage({
+                type: 'msg',
+                id: UUID.uuid4(),
+                body: 'post-sync',
+                time: 1000,
+                sender: TEST_USER.username
+            });
+            expect(model.messages).toHaveLength(1);
+            expect(model.messages[0].body).toBe('post-sync');
+        });
+    });
     describe('rerender tracking', () => {
         it('should replace renderedDelegate when mime_model changes', async () => {
             const id = UUID.uuid4();

package/lib/model.d.ts

@@ -80,6 +80,7 @@ export declare class LabChatModel extends AbstractChatModel implements DocumentR
     set readOnly(value: boolean);
     get id(): string | undefined;
     set id(value: string | undefined);
+    protected setReady(id: string): void;
     /**
      * Notify the model that its shared document has been synchronized with the
      * server, and give it an ID if the document does not carry one yet.
@@ -97,11 +98,12 @@ export declare class LabChatModel extends AbstractChatModel implements DocumentR
     markDocumentSynced(): void;
     dispose(): void;
     toString(): string;
-    fromString(data: string): void;
+    fromString(_data: string): void;
     toJSON(): PartialJSONObject;
-    fromJSON(data: PartialJSONObject): void;
+    fromJSON(_data: PartialJSONObject): void;
     createChatContext(): IChatContext;
-    messagesInserted(index: number, messages: IMessageContent[]): Promise<void>;
+    messagesInserted(index: number, messages: IMessageContent[]): void;
+    private _flushPreReadyMessages;
     sendMessage(message: INewMessage): string | null;
     /**
      * Override the clear messages method.
@@ -136,10 +138,26 @@ export declare class LabChatModel extends AbstractChatModel implements DocumentR
     broadcastWritingStatus(status: IChatModel.IWritingStatus | null): void;
     /**
      * Handle a writing status pushed by the server (e.g. an AI agent) over the
-     * WebSocket. The sender controls its own lifecycle via explicit start/stop.
+     * WebSocket. The sender fully controls the lifecycle via explicit start/stop
+     * frames: a `state: true` frame shows the indicator and it stays visible
+     * until a `state: false` frame clears it -- no re-broadcasting is required.
      */
     private _onWsWriting;
     private _enforceAutosaveEnabled;
+    /**
+     * Triggered when there is no backend and a change occur in the shared model (e.g.
+     * Jupyterlite). It is used to save the chat content from the frontend.
+     */
+    private _onServerLessChange;
+    /**
+     * Load the chat content when no backend is available (e.g. Jupyterlite).
+     * Should be called once when initializing the chat.
+     */
+    private _loadContent;
+    /**
+     * Save the content to a file when no backend is available (e.g. Jupyterlite).
+     */
+    private _saveContent;
     private _onchange;
     private _onWsUsersChanged;
     private _onWsMetadata;
@@ -148,6 +166,8 @@ export declare class LabChatModel extends AbstractChatModel implements DocumentR
     readonly defaultKernelName: string;
     readonly defaultKernelLanguage: string;
     private _sharedModel;
+    private _documentSynced;
+    private _preReadyMessages;
     private _dirty;
     private _readOnly;
     private _contentChanged;
@@ -155,6 +175,7 @@ export declare class LabChatModel extends AbstractChatModel implements DocumentR
     private _timeoutWriting;
     private _user;
     private _wsHandler;
+    private _saveDebouncer;
 }
 /**
  * The chat context to be sent to the input model.

package/lib/model.js

@@ -4,19 +4,12 @@
  */
 import { AbstractChatModel, AbstractChatContext } from '@jupyter/chat';
 import { UUID } from '@lumino/coreutils';
+import { Debouncer } from '@lumino/polling';
 import { Signal } from '@lumino/signaling';
 import { enforceAutosaveEnabled } from './autosave';
 import { WebSocketHandler } from './websocket-handler';
 import { YChat } from './ychat';
 const WRITING_DELAY = 1000;
-/**
- * How long a server-pushed (e.g. AI persona) writing status stays visible
- * without a refresh. The sender is expected to re-broadcast while still
- * writing and to send an explicit stop when done; this is only a safety net so
- * a crashed or forgetful sender cannot leave a "is writing" indicator stuck
- * forever. An explicit stop clears it immediately, regardless of this value.
- */
-const WS_WRITING_TIMEOUT = 3000;
 /**
  * Coerce an untrusted value to an `IUser`, or `null` if it is not one.
  * Awareness state is written by arbitrary clients, so the only field we rely on
@@ -189,7 +182,9 @@ export class LabChatModel extends AbstractChatModel {
         };
         /**
          * Handle a writing status pushed by the server (e.g. an AI agent) over the
-         * WebSocket. The sender controls its own lifecycle via explicit start/stop.
+         * WebSocket. The sender fully controls the lifecycle via explicit start/stop
+         * frames: a `state: true` frame shows the indicator and it stays visible
+         * until a `state: false` frame clears it -- no re-broadcasting is required.
          */
         this._onWsWriting = (_, writing) => {
             if (writing.user.username === this.user.username) {
@@ -199,7 +194,7 @@ export class LabChatModel extends AbstractChatModel {
                 this.setWritingStatus(writing.user, {
                     messageID: writing.messageID,
                     typingIndicator: writing.typingIndicator
-                }, WS_WRITING_TIMEOUT);
+                });
             }
             else {
                 this.clearWritingStatus(writing.user);
@@ -208,6 +203,14 @@ export class LabChatModel extends AbstractChatModel {
         this._enforceAutosaveEnabled = () => {
             enforceAutosaveEnabled(this.sharedModel.awareness);
         };
+        /**
+         * Triggered when there is no backend and a change occur in the shared model (e.g.
+         * Jupyterlite). It is used to save the chat content from the frontend.
+         */
+        this._onServerLessChange = () => {
+            this.dirty = true;
+            void this._saveDebouncer.invoke();
+        };
         this._onchange = async (_, changes) => {
             if (changes.messageListChanges) {
                 const msgDelta = changes.messageListChanges;
@@ -335,7 +338,9 @@ export class LabChatModel extends AbstractChatModel {
             // Not needed in WS mode — readiness is signalled by the connection message.
             if (changes.stateChange && !this._sharedModel.id && !this._wsHandler) {
                 if (changes.stateChange.some(change => change.name === 'dirty' && !change.newValue)) {
-                    this._sharedModel.id = UUID.uuid4();
+                    const id = UUID.uuid4();
+                    this._sharedModel.id = id;
+                    this.setReady(id);
                 }
             }
         };
@@ -363,12 +368,18 @@ export class LabChatModel extends AbstractChatModel {
         };
         this.defaultKernelName = '';
         this.defaultKernelLanguage = '';
+        this._documentSynced = false;
+        this._preReadyMessages = [];
         this._dirty = false;
         this._readOnly = false;
         this._contentChanged = new Signal(this);
         this._stateChanged = new Signal(this);
         this._timeoutWriting = null;
+        // Web socket to use if RTC is not available
         this._wsHandler = null;
+        // Debouncer used to save file from the frontend if RTC and web socket are not
+        // available (e.g. jupyterlite).
+        this._saveDebouncer = new Debouncer(() => this._saveContent(), 500);
         this.collaborative = (_a = options.collaborative) !== null && _a !== void 0 ? _a : true;
         // initialize current user
         this._user = new LabChatUser(options.user);
@@ -416,7 +427,15 @@ export class LabChatModel extends AbstractChatModel {
         return this._dirty;
     }
     set dirty(value) {
+        const old = this._dirty;
         this._dirty = value;
+        if (old !== value) {
+            this._stateChanged.emit({
+                name: 'dirty',
+                oldValue: old,
+                newValue: value
+            });
+        }
     }
     get readOnly() {
         return this._readOnly;
@@ -432,9 +451,11 @@ export class LabChatModel extends AbstractChatModel {
     }
     set id(value) {
         super.id = value;
-        if (value) {
-            this.setReady(value);
-        }
+    }
+    setReady(id) {
+        this._documentSynced = true;
+        this._flushPreReadyMessages();
+        super.setReady(id);
     }
     /**
      * Notify the model that its shared document has been synchronized with the
@@ -469,15 +490,33 @@ export class LabChatModel extends AbstractChatModel {
                     return;
                 }
                 this._user = new LabChatUser(wsUser);
-                if (!this.id) {
-                    this.id = serverId;
-                }
+                this.id = serverId;
+                this.setReady(serverId);
             })
                 .catch(e => {
-                console.error('WS chat connection failed', e);
-                // Fail `ready` so the hosting widget disposes the chat and notifies
-                // the user, instead of leaving a loading spinner forever.
-                this.setError(e instanceof Error ? e : new Error(String(e)));
+                var _a;
+                (_a = this._wsHandler) === null || _a === void 0 ? void 0 : _a.dispose();
+                this._wsHandler = null;
+                if (e.wsCloseCode !== 1006) {
+                    // The server was reachable but rejected the connection (e.g. invalid
+                    // path): surface the error rather than silently falling back.
+                    this.setError(e);
+                    return;
+                }
+                // Server unreachable (e.g. JupyterLite): fall back to the shared model.
+                console.warn('WS chat connection failed, falling back to shared model', e);
+                // Restore content from disk before wiring the change handler, so the
+                // initial population doesn't itself trigger a save. `ready` is
+                // resolved only after the load completes (see #532).
+                void this._loadContent().then(() => {
+                    if (!this._sharedModel.id) {
+                        this._sharedModel.id = UUID.uuid4();
+                    }
+                    const id = this._sharedModel.id;
+                    // Any subsequent change must be saved by the frontend (no backend).
+                    this._sharedModel.changed.connect(this._onServerLessChange, this);
+                    this.setReady(id);
+                });
             });
             return;
         }
@@ -488,15 +527,17 @@ export class LabChatModel extends AbstractChatModel {
         // sync populates it without emitting an `_onchange` metadata delta, so
         // nothing else would set the model id and `ready` would never resolve.
         if (this._sharedModel.id) {
-            this.id = this._sharedModel.id;
+            const id = this._sharedModel.id;
+            this.id = id; // no _onchange delta fires for the existing id at sync time
+            this.setReady(id);
         }
         else {
-            // Brand-new document with no id yet: assigning the shared id emits a
-            // metadata change that sets the model id - and therefore resolves `ready`
-            // - through `_onchange`. A server-authored id that arrives later is
-            // likewise adopted through `_onchange`. We do NOT mint an id that would
-            // diverge from the server's, since the server reads back this value.
-            this._sharedModel.id = UUID.uuid4();
+            // Brand-new document: writing the id to the shared model fires _onchange
+            // synchronously, which sets this.id (and thus super.id) via metadataChanges.
+            // setReady() then flushes buffered messages and resolves `ready`.
+            const id = UUID.uuid4();
+            this._sharedModel.id = id;
+            this.setReady(id);
         }
     }
     dispose() {
@@ -504,6 +545,7 @@ export class LabChatModel extends AbstractChatModel {
         if (this.isDisposed) {
             return;
         }
+        this._saveDebouncer.dispose();
         (_a = this._wsHandler) === null || _a === void 0 ? void 0 : _a.dispose();
         this._wsHandler = null;
         super.dispose();
@@ -513,26 +555,38 @@ export class LabChatModel extends AbstractChatModel {
         Signal.clearData(this);
     }
     toString() {
-        return JSON.stringify({}, null, 2);
+        return JSON.stringify(this._sharedModel.getSource(), null, 2);
     }
-    fromString(data) {
-        /** */
+    fromString(_data) {
+        // Content is loaded on demand via _loadContent() in the serverless
+        // (JupyterLite) fallback; in RTC/WS modes the transport owns the data.
     }
     toJSON() {
         return JSON.parse(this.toString());
     }
-    fromJSON(data) {
-        // nothing to do
+    fromJSON(_data) {
+        // nothing to do — see fromString
     }
     createChatContext() {
         return new LabChatContext({ model: this });
     }
-    async messagesInserted(index, messages) {
-        // Ensure the chat has an ID before inserting the messages, to properly catch the
-        // unread messages (the last read message is saved using the chat ID).
-        return this.ready.then(() => {
+    messagesInserted(index, messages) {
+        // Buffer messages that arrive before the document is synced. They are
+        // flushed synchronously in markDocumentSynced() so that `ready` resolves
+        // only after all initial messages and metadata are already in the model.
+        // This ensures that the chat has an ID before inserting the messages, to properly
+        // catch the unread messages (the last read message is saved using the chat ID).
+        if (!this._documentSynced) {
+            this._preReadyMessages.push({ index, messages });
+            return;
+        }
+        super.messagesInserted(index, messages);
+    }
+    _flushPreReadyMessages() {
+        for (const { index, messages } of this._preReadyMessages) {
             super.messagesInserted(index, messages);
-        });
+        }
+        this._preReadyMessages = [];
     }
     sendMessage(message) {
         var _a, _b, _c, _d;
@@ -558,7 +612,10 @@ export class LabChatModel extends AbstractChatModel {
             body: (_c = message.body) !== null && _c !== void 0 ? _c : '',
             time: Date.now() / 1000,
             sender: (_d = message.sender) !== null && _d !== void 0 ? _d : this._user,
-            raw_time: true
+            // Set the raw time only if there is a server to update the time to a reference
+            // one (the server time is source of truth). At that stage, without collaboration,
+            // this means that the chat is running without server (jupyterlite).
+            raw_time: this.collaborative ? true : false
         };
         this.sharedModel.addMessage(this._contentToYmessage(content));
         return content.id;
@@ -621,6 +678,46 @@ export class LabChatModel extends AbstractChatModel {
             awareness.setLocalStateField('typingIndicator', (_c = status.typingIndicator) !== null && _c !== void 0 ? _c : null);
         }
     }
+    /**
+     * Load the chat content when no backend is available (e.g. Jupyterlite).
+     * Should be called once when initializing the chat.
+     */
+    async _loadContent() {
+        if (!this.documentManager) {
+            return;
+        }
+        try {
+            const file = await this.documentManager.services.contents.get(this.name, {
+                content: true,
+                format: 'text'
+            });
+            if (typeof file.content === 'string' && file.content) {
+                this._sharedModel.setSource(JSON.parse(file.content));
+            }
+        }
+        catch (_a) {
+            // Missing or invalid file — start with an empty chat.
+        }
+    }
+    /**
+     * Save the content to a file when no backend is available (e.g. Jupyterlite).
+     */
+    async _saveContent() {
+        if (!this.documentManager) {
+            return;
+        }
+        try {
+            await this.documentManager.services.contents.save(this.name, {
+                type: 'file',
+                format: 'text',
+                content: this.toString()
+            });
+            this.dirty = false;
+        }
+        catch (e) {
+            console.error('Failed to save chat file', e);
+        }
+    }
     _contentToYmessage(msg) {
         var _a, _b, _c;
         const sender = msg.sender;

package/lib/websocket-handler.js

@@ -258,12 +258,12 @@ export class WebSocketHandler {
             if (this._disposed) {
                 return;
             }
-            // Closed before the connection frame arrived: the chat could not be
-            // opened (e.g. the server rejected the path). Fail `ready` so the hosting
-            // widget can surface the error, instead of reconnecting into the same
-            // failure or leaving a spinner hanging forever.
+            // Closed before the connection frame arrived: signal failure so callers can
+            // distinguish between an unreachable server (code 1006, e.g. JupyterLite) and
+            // an explicit server-side rejection (any other code, e.g. 1008 for invalid path).
             if (!this._connected) {
-                this._ready.reject(new Error(`Chat WebSocket was closed before opening (code ${event.code})`));
+                this._ready.reject(Object.assign(new Error(event.reason ||
+                    `Chat WebSocket was closed before opening (code ${event.code})`), { wsCloseCode: event.code }));
                 return;
             }
             // An established connection dropped abnormally: try to reconnect.
@@ -275,6 +275,10 @@ export class WebSocketHandler {
                 }, 1000);
             }
         };
-        this._socket.onerror = error => console.error('WS chat connection error:', error);
+        this._socket.onerror = error => {
+            if (this._connected) {
+                console.error('WS chat connection error:', error);
+            }
+        };
     }
 }

package/lib/ychat.js

@@ -205,15 +205,16 @@ export class YChat extends YDocument {
     getSource() {
         const users = this._users.toJSON();
         const messages = this._messages.toJSON();
+        const attachments = this._attachments.toJSON();
         const metadata = this._metadata.toJSON();
-        return { users, messages, metadata };
+        return { users, messages, attachments, metadata };
     }
     setSource(value) {
         if (!value) {
             return;
         }
         this.transact(() => {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             const messages = (_a = value['messages']) !== null && _a !== void 0 ? _a : [];
             const ymessages = [];
             messages.forEach(message => {
@@ -226,7 +227,9 @@ export class YChat extends YDocument {
             this._messages.push(ymessages);
             const users = (_b = value['users']) !== null && _b !== void 0 ? _b : {};
             Object.entries(users).forEach(([key, val]) => this._users.set(key, val));
-            const metadata = (_c = value['metadata']) !== null && _c !== void 0 ? _c : {};
+            const attachments = (_c = value['attachments']) !== null && _c !== void 0 ? _c : {};
+            Object.entries(attachments).forEach(([key, val]) => this._attachments.set(key, val));
+            const metadata = (_d = value['metadata']) !== null && _d !== void 0 ? _d : {};
             Object.entries(metadata).forEach(([key, val]) => this._metadata.set(key, val));
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyterlab-chat",
-  "version": "0.25.0-alpha.7",
+  "version": "0.25.0",
   "description": "The library to build a chat based on shared document",
   "keywords": [
     "jupyter",
@@ -42,7 +42,7 @@
     "watch:src": "tsc -w --sourceMap"
   },
   "dependencies": {
-    "@jupyter/chat": "^0.25.0-alpha.7",
+    "@jupyter/chat": "^0.25.0",
     "@jupyter/collaborative-drive": "^4.4.0 || ^5.0.0",
     "@jupyter/ydoc": "^3.0.0 || ^4.0.0",
     "@jupyterlab/application": "^4.5.0",
@@ -59,6 +59,7 @@
     "@jupyterlab/ui-components": "^4.5.0",
     "@lumino/commands": "^2.3.3",
     "@lumino/coreutils": "^2.2.2",
+    "@lumino/polling": "^2.1.5",
     "@lumino/signaling": "^2.1.5",
     "@lumino/widgets": "^2.8.0",
     "react": "^18.2.0",

package/src/__tests__/model.spec.ts

@@ -48,8 +48,7 @@ describe('LabChatModel', () => {
       sharedModel,
       collaborative: true
     });
-    // Resolve the ready promise so messagesInserted can proceed.
-    model.id = UUID.uuid4();
+    model.markDocumentSynced();
   });
 
   afterEach(() => {
@@ -149,6 +148,95 @@ describe('LabChatModel', () => {
     });
   });
 
+  describe('ready resolves after messages are loaded', () => {
+    it('messages present in sharedModel before sync are buffered, not yet in model', () => {
+      const sm = YChat.create();
+      const m = new LabChatModel({
+        widgetConfig: makeWidgetConfig(),
+        user: TEST_USER,
+        sharedModel: sm,
+        collaborative: true
+      });
+      sm.addMessage({
+        type: 'msg',
+        id: UUID.uuid4(),
+        body: 'pre-sync',
+        time: 1000,
+        sender: TEST_USER.username
+      });
+      // Not yet synced: message must be buffered, not inserted.
+      expect(m.messages).toHaveLength(0);
+      sm.dispose();
+    });
+
+    it('messages are in model.messages when ready resolves', async () => {
+      const sm = YChat.create();
+      const m = new LabChatModel({
+        widgetConfig: makeWidgetConfig(),
+        user: TEST_USER,
+        sharedModel: sm,
+        collaborative: true
+      });
+      sm.addMessage({
+        type: 'msg',
+        id: UUID.uuid4(),
+        body: 'pre-sync',
+        time: 1000,
+        sender: TEST_USER.username
+      });
+
+      m.markDocumentSynced();
+      await m.ready;
+
+      expect(m.messages).toHaveLength(1);
+      expect(m.messages[0].body).toBe('pre-sync');
+      sm.dispose();
+    });
+
+    it('model.messages is already populated inside the ready .then() callback', async () => {
+      const sm = YChat.create();
+      const m = new LabChatModel({
+        widgetConfig: makeWidgetConfig(),
+        user: TEST_USER,
+        sharedModel: sm,
+        collaborative: true
+      });
+      sm.addMessage({
+        type: 'msg',
+        id: UUID.uuid4(),
+        body: 'pre-sync',
+        time: 1000,
+        sender: TEST_USER.username
+      });
+
+      let messagesAtReady = -1;
+      const check = m.ready.then(() => {
+        messagesAtReady = m.messages.length;
+      });
+
+      m.markDocumentSynced();
+      await check;
+
+      expect(messagesAtReady).toBe(1);
+      sm.dispose();
+    });
+
+    it('messages added after sync are inserted directly without buffering', async () => {
+      await model.ready;
+
+      sharedModel.addMessage({
+        type: 'msg',
+        id: UUID.uuid4(),
+        body: 'post-sync',
+        time: 1000,
+        sender: TEST_USER.username
+      });
+
+      expect(model.messages).toHaveLength(1);
+      expect(model.messages[0].body).toBe('post-sync');
+    });
+  });
+
   describe('rerender tracking', () => {
     it('should replace renderedDelegate when mime_model changes', async () => {
       const id = UUID.uuid4();

package/src/model.ts

@@ -19,6 +19,7 @@ import { IChangedArgs } from '@jupyterlab/coreutils';
 import { DocumentRegistry } from '@jupyterlab/docregistry';
 import { ServerConnection, User } from '@jupyterlab/services';
 import { PartialJSONObject, UUID } from '@lumino/coreutils';
+import { Debouncer } from '@lumino/polling';
 import { ISignal, Signal } from '@lumino/signaling';
 
 import { enforceAutosaveEnabled } from './autosave';
@@ -28,15 +29,6 @@ import { IChatChanges, IYmessage, YChat } from './ychat';
 
 const WRITING_DELAY = 1000;
 
-/**
- * How long a server-pushed (e.g. AI persona) writing status stays visible
- * without a refresh. The sender is expected to re-broadcast while still
- * writing and to send an explicit stop when done; this is only a safety net so
- * a crashed or forgetful sender cannot leave a "is writing" indicator stuck
- * forever. An explicit stop clears it immediately, regardless of this value.
- */
-const WS_WRITING_TIMEOUT = 3000;
-
 /**
  * Coerce an untrusted value to an `IUser`, or `null` if it is not one.
  * Awareness state is written by arbitrary clients, so the only field we rely on
@@ -268,7 +260,15 @@ export class LabChatModel
     return this._dirty;
   }
   set dirty(value: boolean) {
+    const old = this._dirty;
     this._dirty = value;
+    if (old !== value) {
+      this._stateChanged.emit({
+        name: 'dirty',
+        oldValue: old,
+        newValue: value
+      });
+    }
   }
 
   get readOnly(): boolean {
@@ -286,9 +286,12 @@ export class LabChatModel
   }
   set id(value: string | undefined) {
     super.id = value;
-    if (value) {
-      this.setReady(value);
-    }
+  }
+
+  protected setReady(id: string): void {
+    this._documentSynced = true;
+    this._flushPreReadyMessages();
+    super.setReady(id);
   }
 
   /**
@@ -326,15 +329,35 @@ export class LabChatModel
             return;
           }
           this._user = new LabChatUser(wsUser);
-          if (!this.id) {
-            this.id = serverId;
-          }
+          this.id = serverId;
+          this.setReady(serverId);
         })
         .catch(e => {
-          console.error('WS chat connection failed', e);
-          // Fail `ready` so the hosting widget disposes the chat and notifies
-          // the user, instead of leaving a loading spinner forever.
-          this.setError(e instanceof Error ? e : new Error(String(e)));
+          this._wsHandler?.dispose();
+          this._wsHandler = null;
+          if ((e as { wsCloseCode?: number }).wsCloseCode !== 1006) {
+            // The server was reachable but rejected the connection (e.g. invalid
+            // path): surface the error rather than silently falling back.
+            this.setError(e);
+            return;
+          }
+          // Server unreachable (e.g. JupyterLite): fall back to the shared model.
+          console.warn(
+            'WS chat connection failed, falling back to shared model',
+            e
+          );
+          // Restore content from disk before wiring the change handler, so the
+          // initial population doesn't itself trigger a save. `ready` is
+          // resolved only after the load completes (see #532).
+          void this._loadContent().then(() => {
+            if (!this._sharedModel.id) {
+              this._sharedModel.id = UUID.uuid4();
+            }
+            const id = this._sharedModel.id;
+            // Any subsequent change must be saved by the frontend (no backend).
+            this._sharedModel.changed.connect(this._onServerLessChange, this);
+            this.setReady(id);
+          });
         });
       return;
     }
@@ -345,14 +368,16 @@ export class LabChatModel
     // sync populates it without emitting an `_onchange` metadata delta, so
     // nothing else would set the model id and `ready` would never resolve.
     if (this._sharedModel.id) {
-      this.id = this._sharedModel.id;
+      const id = this._sharedModel.id;
+      this.id = id; // no _onchange delta fires for the existing id at sync time
+      this.setReady(id);
     } else {
-      // Brand-new document with no id yet: assigning the shared id emits a
-      // metadata change that sets the model id - and therefore resolves `ready`
-      // - through `_onchange`. A server-authored id that arrives later is
-      // likewise adopted through `_onchange`. We do NOT mint an id that would
-      // diverge from the server's, since the server reads back this value.
-      this._sharedModel.id = UUID.uuid4();
+      // Brand-new document: writing the id to the shared model fires _onchange
+      // synchronously, which sets this.id (and thus super.id) via metadataChanges.
+      // setReady() then flushes buffered messages and resolves `ready`.
+      const id = UUID.uuid4();
+      this._sharedModel.id = id;
+      this.setReady(id);
     }
   }
 
@@ -360,6 +385,7 @@ export class LabChatModel
     if (this.isDisposed) {
       return;
     }
+    this._saveDebouncer.dispose();
     this._wsHandler?.dispose();
     this._wsHandler = null;
     super.dispose();
@@ -370,34 +396,44 @@ export class LabChatModel
   }
 
   toString(): string {
-    return JSON.stringify({}, null, 2);
+    return JSON.stringify(this._sharedModel.getSource(), null, 2);
   }
 
-  fromString(data: string): void {
-    /** */
+  fromString(_data: string): void {
+    // Content is loaded on demand via _loadContent() in the serverless
+    // (JupyterLite) fallback; in RTC/WS modes the transport owns the data.
   }
 
   toJSON(): PartialJSONObject {
     return JSON.parse(this.toString());
   }
 
-  fromJSON(data: PartialJSONObject): void {
-    // nothing to do
+  fromJSON(_data: PartialJSONObject): void {
+    // nothing to do — see fromString
   }
 
   createChatContext(): IChatContext {
     return new LabChatContext({ model: this });
   }
 
-  async messagesInserted(
-    index: number,
-    messages: IMessageContent[]
-  ): Promise<void> {
-    // Ensure the chat has an ID before inserting the messages, to properly catch the
-    // unread messages (the last read message is saved using the chat ID).
-    return this.ready.then(() => {
+  messagesInserted(index: number, messages: IMessageContent[]): void {
+    // Buffer messages that arrive before the document is synced. They are
+    // flushed synchronously in markDocumentSynced() so that `ready` resolves
+    // only after all initial messages and metadata are already in the model.
+    // This ensures that the chat has an ID before inserting the messages, to properly
+    // catch the unread messages (the last read message is saved using the chat ID).
+    if (!this._documentSynced) {
+      this._preReadyMessages.push({ index, messages });
+      return;
+    }
+    super.messagesInserted(index, messages);
+  }
+
+  private _flushPreReadyMessages(): void {
+    for (const { index, messages } of this._preReadyMessages) {
       super.messagesInserted(index, messages);
-    });
+    }
+    this._preReadyMessages = [];
   }
 
   sendMessage(message: INewMessage): string | null {
@@ -427,7 +463,10 @@ export class LabChatModel
       body: message.body ?? '',
       time: Date.now() / 1000,
       sender: message.sender ?? this._user,
-      raw_time: true
+      // Set the raw time only if there is a server to update the time to a reference
+      // one (the server time is source of truth). At that stage, without collaboration,
+      // this means that the chat is running without server (jupyterlite).
+      raw_time: this.collaborative ? true : false
     };
 
     this.sharedModel.addMessage(this._contentToYmessage(content));
@@ -562,7 +601,9 @@ export class LabChatModel
 
   /**
    * Handle a writing status pushed by the server (e.g. an AI agent) over the
-   * WebSocket. The sender controls its own lifecycle via explicit start/stop.
+   * WebSocket. The sender fully controls the lifecycle via explicit start/stop
+   * frames: a `state: true` frame shows the indicator and it stays visible
+   * until a `state: false` frame clears it -- no re-broadcasting is required.
    */
   private _onWsWriting = (
     _: WebSocketHandler,
@@ -572,14 +613,10 @@ export class LabChatModel
       return;
     }
     if (writing.state) {
-      this.setWritingStatus(
-        writing.user,
-        {
-          messageID: writing.messageID,
-          typingIndicator: writing.typingIndicator
-        },
-        WS_WRITING_TIMEOUT
-      );
+      this.setWritingStatus(writing.user, {
+        messageID: writing.messageID,
+        typingIndicator: writing.typingIndicator
+      });
     } else {
       this.clearWritingStatus(writing.user);
     }
@@ -589,6 +626,55 @@ export class LabChatModel
     enforceAutosaveEnabled(this.sharedModel.awareness);
   };
 
+  /**
+   * Triggered when there is no backend and a change occur in the shared model (e.g.
+   * Jupyterlite). It is used to save the chat content from the frontend.
+   */
+  private _onServerLessChange = (): void => {
+    this.dirty = true;
+    void this._saveDebouncer.invoke();
+  };
+
+  /**
+   * Load the chat content when no backend is available (e.g. Jupyterlite).
+   * Should be called once when initializing the chat.
+   */
+  private async _loadContent(): Promise<void> {
+    if (!this.documentManager) {
+      return;
+    }
+    try {
+      const file = await this.documentManager.services.contents.get(this.name, {
+        content: true,
+        format: 'text'
+      });
+      if (typeof file.content === 'string' && file.content) {
+        this._sharedModel.setSource(JSON.parse(file.content));
+      }
+    } catch {
+      // Missing or invalid file — start with an empty chat.
+    }
+  }
+
+  /**
+   * Save the content to a file when no backend is available (e.g. Jupyterlite).
+   */
+  private async _saveContent(): Promise<void> {
+    if (!this.documentManager) {
+      return;
+    }
+    try {
+      await this.documentManager.services.contents.save(this.name, {
+        type: 'file',
+        format: 'text',
+        content: this.toString()
+      });
+      this.dirty = false;
+    } catch (e) {
+      console.error('Failed to save chat file', e);
+    }
+  }
+
   private _onchange = async (_: YChat, changes: IChatChanges) => {
     if (changes.messageListChanges) {
       const msgDelta = changes.messageListChanges;
@@ -736,7 +822,9 @@ export class LabChatModel
           change => change.name === 'dirty' && !change.newValue
         )
       ) {
-        this._sharedModel.id = UUID.uuid4();
+        const id = UUID.uuid4();
+        this._sharedModel.id = id;
+        this.setReady(id);
       }
     }
   };
@@ -828,6 +916,11 @@ export class LabChatModel
 
   private _sharedModel: YChat;
 
+  private _documentSynced = false;
+  private _preReadyMessages: Array<{
+    index: number;
+    messages: IMessageContent[];
+  }> = [];
   private _dirty = false;
   private _readOnly = false;
   private _contentChanged = new Signal<this, void>(this);
@@ -835,7 +928,13 @@ export class LabChatModel
   private _timeoutWriting: number | null = null;
 
   private _user: IUser;
+
+  // Web socket to use if RTC is not available
   private _wsHandler: WebSocketHandler | null = null;
+
+  // Debouncer used to save file from the frontend if RTC and web socket are not
+  // available (e.g. jupyterlite).
+  private _saveDebouncer = new Debouncer(() => this._saveContent(), 500);
 }
 
 /**

package/src/websocket-handler.ts

@@ -299,14 +299,17 @@ export class WebSocketHandler {
       if (this._disposed) {
         return;
       }
-      // Closed before the connection frame arrived: the chat could not be
-      // opened (e.g. the server rejected the path). Fail `ready` so the hosting
-      // widget can surface the error, instead of reconnecting into the same
-      // failure or leaving a spinner hanging forever.
+      // Closed before the connection frame arrived: signal failure so callers can
+      // distinguish between an unreachable server (code 1006, e.g. JupyterLite) and
+      // an explicit server-side rejection (any other code, e.g. 1008 for invalid path).
       if (!this._connected) {
         this._ready.reject(
-          new Error(
-            `Chat WebSocket was closed before opening (code ${event.code})`
+          Object.assign(
+            new Error(
+              event.reason ||
+                `Chat WebSocket was closed before opening (code ${event.code})`
+            ),
+            { wsCloseCode: event.code }
           )
         );
         return;
@@ -320,8 +323,11 @@ export class WebSocketHandler {
         }, 1000);
       }
     };
-    this._socket.onerror = error =>
-      console.error('WS chat connection error:', error);
+    this._socket.onerror = error => {
+      if (this._connected) {
+        console.error('WS chat connection error:', error);
+      }
+    };
   }
 
   private _path = '';

package/src/ychat.ts

@@ -137,9 +137,10 @@ export class YChat extends YDocument<IChatChanges> {
   getSource(): JSONObject {
     const users = this._users.toJSON();
     const messages = this._messages.toJSON();
+    const attachments = this._attachments.toJSON();
     const metadata = this._metadata.toJSON();
 
-    return { users, messages, metadata };
+    return { users, messages, attachments, metadata };
   }
 
   setSource(value: JSONObject): void {
@@ -164,6 +165,11 @@ export class YChat extends YDocument<IChatChanges> {
         this._users.set(key, val as IUser)
       );
 
+      const attachments = value['attachments'] ?? {};
+      Object.entries(attachments).forEach(([key, val]) =>
+        this._attachments.set(key, val as IAttachment)
+      );
+
       const metadata = value['metadata'] ?? {};
       Object.entries(metadata).forEach(([key, val]) =>
         this._metadata.set(key, val as any)