@jupyter/chat 0.24.1 → 0.25.0-alpha.1

package/lib/__tests__/writers.spec.d.ts

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

package/lib/__tests__/writers.spec.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { MockChatModel } from './mocks';
+const userA = { username: 'a', name: 'Alice', display_name: 'Alice' };
+const userB = { username: 'b', name: 'Bob', display_name: 'Bob' };
+describe('writers state', () => {
+    let model;
+    let changes;
+    beforeEach(() => {
+        var _a;
+        model = new MockChatModel();
+        changes = [];
+        (_a = model.writersChanged) === null || _a === void 0 ? void 0 : _a.connect((_, writers) => changes.push(writers));
+    });
+    afterEach(() => {
+        model.dispose();
+    });
+    it('adds and removes a writer per user', () => {
+        model.setWritingStatus(userA);
+        expect(model.writers.map(w => w.user.username)).toEqual(['a']);
+        model.setWritingStatus(userB);
+        expect(model.writers.map(w => w.user.username).sort()).toEqual(['a', 'b']);
+        model.clearWritingStatus(userA);
+        expect(model.writers.map(w => w.user.username)).toEqual(['b']);
+    });
+    it('carries a custom typingIndicator', () => {
+        model.setWritingStatus(userA, { typingIndicator: 'is running ripgrep' });
+        expect(model.writers[0].typingIndicator).toBe('is running ripgrep');
+    });
+    it('does not re-emit when the status is unchanged', () => {
+        model.setWritingStatus(userA, { typingIndicator: 'x' });
+        const count = changes.length;
+        model.setWritingStatus(userA, { typingIndicator: 'x' });
+        expect(changes.length).toBe(count);
+    });
+    it('auto-clears a writer after the timeout unless refreshed', () => {
+        jest.useFakeTimers();
+        try {
+            model.setWritingStatus(userA, undefined, 2000);
+            expect(model.writers).toHaveLength(1);
+            // Refresh before expiry keeps it alive.
+            jest.advanceTimersByTime(1500);
+            model.setWritingStatus(userA, undefined, 2000);
+            jest.advanceTimersByTime(1500);
+            expect(model.writers).toHaveLength(1);
+            // No refresh -> auto-cleared after the timeout (the WS anti-stuck path).
+            jest.advanceTimersByTime(2000);
+            expect(model.writers).toHaveLength(0);
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+    it('updateWriters replaces the whole list', () => {
+        model.setWritingStatus(userA);
+        model.updateWriters([{ user: userB }]);
+        expect(model.writers.map(w => w.user.username)).toEqual(['b']);
+    });
+});

package/lib/__tests__/writing-indicator.spec.d.ts

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

package/lib/__tests__/writing-indicator.spec.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+// React 18 asks test environments to declare themselves, otherwise every
+// `act` call warns.
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+import { WritingIndicator } from '../components/writing-indicator';
+const alice = { username: 'a', name: 'Alice', display_name: 'Alice' };
+const writer = (user, typingIndicator) => ({ user, typingIndicator });
+describe('WritingIndicator accessibility', () => {
+    let container;
+    let root;
+    const render = (writers) => {
+        act(() => {
+            root.render(React.createElement(WritingIndicator, { writers: writers }));
+        });
+        return container.querySelector('.jp-chat-writers');
+    };
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+    });
+    afterEach(() => {
+        act(() => root.unmount());
+        container.remove();
+    });
+    it('is a polite live region, so a reply on its way is announced', () => {
+        // The indicator is the only signal that someone is replying. Without a
+        // live region it is visible text that assistive technology never speaks.
+        const el = render([]);
+        expect(el.getAttribute('role')).toBe('status');
+        expect(el.getAttribute('aria-live')).toBe('polite');
+    });
+    it('reads the whole phrase rather than a fragment of it', () => {
+        // Without aria-atomic, a change to part of the text can be announced on
+        // its own, so a reader hears a bare name with no context.
+        expect(render([]).getAttribute('aria-atomic')).toBe('true');
+    });
+    it('announces who is writing', () => {
+        expect(render([writer(alice)]).textContent).toContain('Alice is typing');
+    });
+    it('announces a custom indicator, not just a generic one', () => {
+        const el = render([writer(alice, 'is running `ripgrep`')]);
+        expect(el.textContent).toContain('Alice is running `ripgrep`');
+    });
+    it('says nothing when nobody is writing', () => {
+        var _a;
+        // The container is always rendered to reserve space, and holds a
+        // non-breaking space as a placeholder. That placeholder must not be
+        // announced as if it were a message.
+        const text = ((_a = render([]).textContent) !== null && _a !== void 0 ? _a : '').replace(/ /g, '').trim();
+        expect(text).toBe('');
+    });
+});

package/lib/components/writing-indicator.js

@@ -17,10 +17,26 @@ function formatWritersText(writers, trans) {
     if (writers.length === 0) {
         return '';
     }
-    const names = writers.map(w => {
+    const nameOf = (w) => {
         var _a, _b, _c;
         return (_c = (_b = (_a = w.user.display_name) !== null && _a !== void 0 ? _a : w.user.name) !== null && _b !== void 0 ? _b : w.user.username) !== null && _c !== void 0 ? _c : trans.__('Unknown');
-    });
+    };
+    // When any writer supplies a custom typing indicator, render per-writer
+    // phrases ("<name> <indicator>"), so e.g. "Jupyternaut is running `ripgrep`".
+    if (writers.some(w => w.typingIndicator)) {
+        const phrases = writers.map(w => { var _a; return `${nameOf(w)} ${(_a = w.typingIndicator) !== null && _a !== void 0 ? _a : trans.__('is typing...')}`; });
+        if (phrases.length === 1) {
+            return phrases[0];
+        }
+        else if (phrases.length === 2) {
+            return trans.__('%1 and %2', phrases[0], phrases[1]);
+        }
+        else {
+            const allButLast = phrases.slice(0, -1).join(', ');
+            return trans.__('%1, and %2', allButLast, phrases[phrases.length - 1]);
+        }
+    }
+    const names = writers.map(nameOf);
     if (names.length === 1) {
         return trans.__('%1 is typing...', names[0]);
     }
@@ -41,7 +57,17 @@ export function WritingIndicator(props) {
     const trans = useTranslator();
     // Always render the container to reserve space, even if no writers
     const writersText = writers.length > 0 ? formatWritersText(writers, trans) : '';
-    return (React.createElement(Box, { className: WRITERS_ELEMENT_CLASSNAME, sx: {
+    return (React.createElement(Box, { className: WRITERS_ELEMENT_CLASSNAME, 
+        // The indicator already says something useful, "Alice is typing..." or
+        // "Jupyternaut is running `ripgrep`", but only on screen. Announcing it
+        // politely means a screen reader user learns a reply is coming without
+        // being interrupted mid-sentence.
+        //
+        // The region is the container rather than the text, so it is present in
+        // the accessibility tree before a writer appears and the change is
+        // announced. `aria-atomic` keeps the phrase together: without it a name
+        // change alone can be read out on its own, stripped of its context.
+        role: "status", "aria-live": "polite", "aria-atomic": "true", sx: {
             ...props.sx,
             minHeight: '16px'
         } },

package/lib/model.d.ts

@@ -160,6 +160,27 @@ export interface IChatModel extends IDisposable {
      * Update the current writers list.
      */
     updateWriters(writers: IChatModel.IWriter[]): void;
+    /**
+     * Mark a user as currently writing (add or update their writer entry).
+     *
+     * @param user - the writing user.
+     * @param status - optional writing status (messageID, custom typingIndicator).
+     * @param timeout - optional auto-clear delay in ms. When set, the user is
+     *   automatically cleared after `timeout` unless refreshed by another call.
+     *   Used by transports without their own liveness signal (e.g. WebSocket) to
+     *   avoid a stuck "is typing" if a clear message is never received.
+     */
+    setWritingStatus(user: IUser, status?: IChatModel.IWritingStatus, timeout?: number): void;
+    /**
+     * Remove a user from the writers list.
+     */
+    clearWritingStatus(user: IUser): void;
+    /**
+     * Broadcast the *current user's* writing status to other clients, or clear it
+     * with `null`. Implemented per transport (RTC sets awareness; WebSocket sends
+     * a periodic writing frame). Default implementation is a no-op.
+     */
+    broadcastWritingStatus(status: IChatModel.IWritingStatus | null): void;
     /**
      * Create the chat context that will be passed to the input model.
      */
@@ -332,6 +353,22 @@ export declare abstract class AbstractChatModel implements IChatModel {
      * This implementation only propagate the list via a signal.
      */
     updateWriters(writers: IChatModel.IWriter[]): void;
+    /**
+     * Mark a user as currently writing. See IChatModel.setWritingStatus.
+     */
+    setWritingStatus(user: IUser, status?: IChatModel.IWritingStatus, timeout?: number): void;
+    /**
+     * Remove a user from the writers list. See IChatModel.clearWritingStatus.
+     */
+    clearWritingStatus(user: IUser): void;
+    /**
+     * Broadcast the current user's writing status. Default no-op; transports
+     * override this (RTC awareness, WebSocket frame).
+     */
+    broadcastWritingStatus(_status: IChatModel.IWritingStatus | null): void;
+    private _removeWriter;
+    private _clearWriterTimer;
+    private _clearAllWriterTimers;
     /**
      * Create the chat context that will be passed to the input model.
      */
@@ -382,6 +419,7 @@ export declare abstract class AbstractChatModel implements IChatModel {
     private _documentManager;
     private _notificationId;
     private _writers;
+    private _writerTimers;
     private _messageEditions;
     private _messagesUpdated;
     private _messageChanged;
@@ -453,6 +491,24 @@ export declare namespace IChatModel {
          * The message ID (optional)
          */
         messageID?: string;
+        /**
+         * Custom status text to display instead of the default "is typing…",
+         * e.g. "is running `ripgrep …`". Falls back to the default when unset.
+         */
+        typingIndicator?: string;
+    }
+    /**
+     * The writing status broadcast by (or on behalf of) a user.
+     */
+    interface IWritingStatus {
+        /**
+         * The ID of the message being edited, if any.
+         */
+        messageID?: string;
+        /**
+         * Optional custom typing-indicator text (see IWriter.typingIndicator).
+         */
+        typingIndicator?: string;
     }
 }
 /**

package/lib/model.js

@@ -3,7 +3,6 @@
  * Distributed under the terms of the Modified BSD License.
  */
 import { nullTranslator } from '@jupyterlab/translation';
-import { ArrayExt } from '@lumino/algorithm';
 import { PromiseDelegate } from '@lumino/coreutils';
 import { Signal } from '@lumino/signaling';
 import { TRANSLATION_DOMAIN } from './context';
@@ -30,7 +29,8 @@ export class AbstractChatModel {
         this._disposed = new Signal(this);
         this._isDisposed = false;
         this._notificationId = null;
-        this._writers = [];
+        this._writers = new Map();
+        this._writerTimers = new Map();
         this._messageEditions = new Map();
         this._messagesUpdated = new Signal(this);
         this._messageChanged = new Signal(this);
@@ -114,7 +114,7 @@ export class AbstractChatModel {
      * The current writer list.
      */
     get writers() {
-        return this._writers;
+        return [...this._writers.values()];
     }
     /**
      * Get the active cell manager.
@@ -381,16 +381,70 @@ export class AbstractChatModel {
      * This implementation only propagate the list via a signal.
      */
     updateWriters(writers) {
-        const compareWriters = (a, b) => {
-            return (a.user.username === b.user.username &&
-                a.user.display_name === b.user.display_name &&
-                a.messageID === b.messageID);
+        // Reconcile the writers map with the provided snapshot (used by
+        // snapshot-style transports such as RTC awareness). Any auto-clear timers
+        // are dropped, since the snapshot is authoritative.
+        this._clearAllWriterTimers();
+        const next = new Map();
+        for (const writer of writers) {
+            next.set(writer.user.username, writer);
+        }
+        if (!Private.writersEqual(this._writers, next)) {
+            this._writers = next;
+            this._writersChanged.emit(this.writers);
+        }
+    }
+    /**
+     * Mark a user as currently writing. See IChatModel.setWritingStatus.
+     */
+    setWritingStatus(user, status, timeout) {
+        const writer = {
+            user,
+            messageID: status === null || status === void 0 ? void 0 : status.messageID,
+            typingIndicator: status === null || status === void 0 ? void 0 : status.typingIndicator
         };
-        if (!ArrayExt.shallowEqual(this._writers, writers, compareWriters)) {
-            this._writers = writers;
-            this._writersChanged.emit(writers);
+        this._clearWriterTimer(user.username);
+        if (timeout !== undefined) {
+            this._writerTimers.set(user.username, window.setTimeout(() => this._removeWriter(user.username), timeout));
+        }
+        const previous = this._writers.get(user.username);
+        this._writers.set(user.username, writer);
+        if (!previous || !Private.writerEqual(previous, writer)) {
+            this._writersChanged.emit(this.writers);
         }
     }
+    /**
+     * Remove a user from the writers list. See IChatModel.clearWritingStatus.
+     */
+    clearWritingStatus(user) {
+        this._removeWriter(user.username);
+    }
+    /**
+     * Broadcast the current user's writing status. Default no-op; transports
+     * override this (RTC awareness, WebSocket frame).
+     */
+    broadcastWritingStatus(_status) {
+        // no-op by default
+    }
+    _removeWriter(username) {
+        this._clearWriterTimer(username);
+        if (this._writers.delete(username)) {
+            this._writersChanged.emit(this.writers);
+        }
+    }
+    _clearWriterTimer(username) {
+        const timer = this._writerTimers.get(username);
+        if (timer !== undefined) {
+            window.clearTimeout(timer);
+            this._writerTimers.delete(username);
+        }
+    }
+    _clearAllWriterTimers() {
+        for (const timer of this._writerTimers.values()) {
+            window.clearTimeout(timer);
+        }
+        this._writerTimers.clear();
+    }
     /**
      * Get the input model of the edited message, given its id.
      */
@@ -492,3 +546,35 @@ export class AbstractChatContext {
         return this._model.awareness;
     }
 }
+/**
+ * A namespace for private functionality.
+ */
+var Private;
+(function (Private) {
+    /**
+     * Whether two writers are equivalent for change-detection purposes.
+     */
+    function writerEqual(a, b) {
+        return (a.user.username === b.user.username &&
+            a.user.display_name === b.user.display_name &&
+            a.messageID === b.messageID &&
+            a.typingIndicator === b.typingIndicator);
+    }
+    Private.writerEqual = writerEqual;
+    /**
+     * Whether two writer maps are equivalent.
+     */
+    function writersEqual(a, b) {
+        if (a.size !== b.size) {
+            return false;
+        }
+        for (const [username, writer] of a) {
+            const other = b.get(username);
+            if (!other || !writerEqual(writer, other)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    Private.writersEqual = writersEqual;
+})(Private || (Private = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupyter/chat",
-  "version": "0.24.1",
+  "version": "0.25.0-alpha.1",
   "description": "A package that provides UI components that can be used to create a chat in a Jupyterlab extension.",
   "keywords": [
     "jupyter",

package/src/__tests__/writers.spec.ts

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { IChatModel } from '../model';
+import { IUser } from '../types';
+import { MockChatModel } from './mocks';
+
+const userA: IUser = { username: 'a', name: 'Alice', display_name: 'Alice' };
+const userB: IUser = { username: 'b', name: 'Bob', display_name: 'Bob' };
+
+describe('writers state', () => {
+  let model: MockChatModel;
+  let changes: IChatModel.IWriter[][];
+
+  beforeEach(() => {
+    model = new MockChatModel();
+    changes = [];
+    model.writersChanged?.connect((_, writers) => changes.push(writers));
+  });
+
+  afterEach(() => {
+    model.dispose();
+  });
+
+  it('adds and removes a writer per user', () => {
+    model.setWritingStatus(userA);
+    expect(model.writers.map(w => w.user.username)).toEqual(['a']);
+
+    model.setWritingStatus(userB);
+    expect(model.writers.map(w => w.user.username).sort()).toEqual(['a', 'b']);
+
+    model.clearWritingStatus(userA);
+    expect(model.writers.map(w => w.user.username)).toEqual(['b']);
+  });
+
+  it('carries a custom typingIndicator', () => {
+    model.setWritingStatus(userA, { typingIndicator: 'is running ripgrep' });
+    expect(model.writers[0].typingIndicator).toBe('is running ripgrep');
+  });
+
+  it('does not re-emit when the status is unchanged', () => {
+    model.setWritingStatus(userA, { typingIndicator: 'x' });
+    const count = changes.length;
+    model.setWritingStatus(userA, { typingIndicator: 'x' });
+    expect(changes.length).toBe(count);
+  });
+
+  it('auto-clears a writer after the timeout unless refreshed', () => {
+    jest.useFakeTimers();
+    try {
+      model.setWritingStatus(userA, undefined, 2000);
+      expect(model.writers).toHaveLength(1);
+
+      // Refresh before expiry keeps it alive.
+      jest.advanceTimersByTime(1500);
+      model.setWritingStatus(userA, undefined, 2000);
+      jest.advanceTimersByTime(1500);
+      expect(model.writers).toHaveLength(1);
+
+      // No refresh -> auto-cleared after the timeout (the WS anti-stuck path).
+      jest.advanceTimersByTime(2000);
+      expect(model.writers).toHaveLength(0);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('updateWriters replaces the whole list', () => {
+    model.setWritingStatus(userA);
+    model.updateWriters([{ user: userB }]);
+    expect(model.writers.map(w => w.user.username)).toEqual(['b']);
+  });
+});

package/src/__tests__/writing-indicator.spec.tsx

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import React, { act } from 'react';
+import { createRoot, Root } from 'react-dom/client';
+
+// React 18 asks test environments to declare themselves, otherwise every
+// `act` call warns.
+(
+  globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+import { WritingIndicator } from '../components/writing-indicator';
+import { IChatModel } from '../model';
+import { IUser } from '../types';
+
+const alice: IUser = { username: 'a', name: 'Alice', display_name: 'Alice' };
+
+const writer = (user: IUser, typingIndicator?: string): IChatModel.IWriter =>
+  ({ user, typingIndicator }) as IChatModel.IWriter;
+
+describe('WritingIndicator accessibility', () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  const render = (writers: IChatModel.IWriter[]) => {
+    act(() => {
+      root.render(<WritingIndicator writers={writers} />);
+    });
+    return container.querySelector('.jp-chat-writers') as HTMLElement;
+  };
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+
+  it('is a polite live region, so a reply on its way is announced', () => {
+    // The indicator is the only signal that someone is replying. Without a
+    // live region it is visible text that assistive technology never speaks.
+    const el = render([]);
+    expect(el.getAttribute('role')).toBe('status');
+    expect(el.getAttribute('aria-live')).toBe('polite');
+  });
+
+  it('reads the whole phrase rather than a fragment of it', () => {
+    // Without aria-atomic, a change to part of the text can be announced on
+    // its own, so a reader hears a bare name with no context.
+    expect(render([]).getAttribute('aria-atomic')).toBe('true');
+  });
+
+  it('announces who is writing', () => {
+    expect(render([writer(alice)]).textContent).toContain('Alice is typing');
+  });
+
+  it('announces a custom indicator, not just a generic one', () => {
+    const el = render([writer(alice, 'is running `ripgrep`')]);
+    expect(el.textContent).toContain('Alice is running `ripgrep`');
+  });
+
+  it('says nothing when nobody is writing', () => {
+    // The container is always rendered to reserve space, and holds a
+    // non-breaking space as a placeholder. That placeholder must not be
+    // announced as if it were a message.
+    const text = (render([]).textContent ?? '').replace(/ /g, '').trim();
+    expect(text).toBe('');
+  });
+});

package/src/components/writing-indicator.tsx

@@ -41,13 +41,29 @@ function formatWritersText(
     return '';
   }
 
-  const names = writers.map(
-    w =>
-      w.user.display_name ??
-      w.user.name ??
-      w.user.username ??
-      trans.__('Unknown')
-  );
+  const nameOf = (w: IChatModel.IWriter) =>
+    w.user.display_name ??
+    w.user.name ??
+    w.user.username ??
+    trans.__('Unknown');
+
+  // When any writer supplies a custom typing indicator, render per-writer
+  // phrases ("<name> <indicator>"), so e.g. "Jupyternaut is running `ripgrep`".
+  if (writers.some(w => w.typingIndicator)) {
+    const phrases = writers.map(
+      w => `${nameOf(w)} ${w.typingIndicator ?? trans.__('is typing...')}`
+    );
+    if (phrases.length === 1) {
+      return phrases[0];
+    } else if (phrases.length === 2) {
+      return trans.__('%1 and %2', phrases[0], phrases[1]);
+    } else {
+      const allButLast = phrases.slice(0, -1).join(', ');
+      return trans.__('%1, and %2', allButLast, phrases[phrases.length - 1]);
+    }
+  }
+
+  const names = writers.map(nameOf);
 
   if (names.length === 1) {
     return trans.__('%1 is typing...', names[0]);
@@ -76,6 +92,18 @@ export function WritingIndicator(
   return (
     <Box
       className={WRITERS_ELEMENT_CLASSNAME}
+      // The indicator already says something useful, "Alice is typing..." or
+      // "Jupyternaut is running `ripgrep`", but only on screen. Announcing it
+      // politely means a screen reader user learns a reply is coming without
+      // being interrupted mid-sentence.
+      //
+      // The region is the container rather than the text, so it is present in
+      // the accessibility tree before a writer appears and the change is
+      // announced. `aria-atomic` keeps the phrase together: without it a name
+      // change alone can be read out on its own, stripped of its context.
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
       sx={{
         ...props.sx,
         minHeight: '16px'

package/src/model.ts

@@ -10,7 +10,6 @@ import {
   TranslationBundle
 } from '@jupyterlab/translation';
 import type { IAwareness } from '@jupyter/ydoc';
-import { ArrayExt } from '@lumino/algorithm';
 import { CommandRegistry } from '@lumino/commands';
 import { PromiseDelegate } from '@lumino/coreutils';
 import { IDisposable } from '@lumino/disposable';
@@ -217,6 +216,34 @@ export interface IChatModel extends IDisposable {
    */
   updateWriters(writers: IChatModel.IWriter[]): void;
 
+  /**
+   * Mark a user as currently writing (add or update their writer entry).
+   *
+   * @param user - the writing user.
+   * @param status - optional writing status (messageID, custom typingIndicator).
+   * @param timeout - optional auto-clear delay in ms. When set, the user is
+   *   automatically cleared after `timeout` unless refreshed by another call.
+   *   Used by transports without their own liveness signal (e.g. WebSocket) to
+   *   avoid a stuck "is typing" if a clear message is never received.
+   */
+  setWritingStatus(
+    user: IUser,
+    status?: IChatModel.IWritingStatus,
+    timeout?: number
+  ): void;
+
+  /**
+   * Remove a user from the writers list.
+   */
+  clearWritingStatus(user: IUser): void;
+
+  /**
+   * Broadcast the *current user's* writing status to other clients, or clear it
+   * with `null`. Implemented per transport (RTC sets awareness; WebSocket sends
+   * a periodic writing frame). Default implementation is a no-op.
+   */
+  broadcastWritingStatus(status: IChatModel.IWritingStatus | null): void;
+
   /**
    * Create the chat context that will be passed to the input model.
    */
@@ -345,7 +372,7 @@ export abstract class AbstractChatModel implements IChatModel {
    * The current writer list.
    */
   get writers(): IChatModel.IWriter[] {
-    return this._writers;
+    return [...this._writers.values()];
   }
 
   /**
@@ -666,19 +693,84 @@ export abstract class AbstractChatModel implements IChatModel {
    * This implementation only propagate the list via a signal.
    */
   updateWriters(writers: IChatModel.IWriter[]): void {
-    const compareWriters = (a: IChatModel.IWriter, b: IChatModel.IWriter) => {
-      return (
-        a.user.username === b.user.username &&
-        a.user.display_name === b.user.display_name &&
-        a.messageID === b.messageID
-      );
+    // Reconcile the writers map with the provided snapshot (used by
+    // snapshot-style transports such as RTC awareness). Any auto-clear timers
+    // are dropped, since the snapshot is authoritative.
+    this._clearAllWriterTimers();
+    const next = new Map<string, IChatModel.IWriter>();
+    for (const writer of writers) {
+      next.set(writer.user.username, writer);
+    }
+    if (!Private.writersEqual(this._writers, next)) {
+      this._writers = next;
+      this._writersChanged.emit(this.writers);
+    }
+  }
+
+  /**
+   * Mark a user as currently writing. See IChatModel.setWritingStatus.
+   */
+  setWritingStatus(
+    user: IUser,
+    status?: IChatModel.IWritingStatus,
+    timeout?: number
+  ): void {
+    const writer: IChatModel.IWriter = {
+      user,
+      messageID: status?.messageID,
+      typingIndicator: status?.typingIndicator
     };
-    if (!ArrayExt.shallowEqual(this._writers, writers, compareWriters)) {
-      this._writers = writers;
-      this._writersChanged.emit(writers);
+    this._clearWriterTimer(user.username);
+    if (timeout !== undefined) {
+      this._writerTimers.set(
+        user.username,
+        window.setTimeout(() => this._removeWriter(user.username), timeout)
+      );
+    }
+    const previous = this._writers.get(user.username);
+    this._writers.set(user.username, writer);
+    if (!previous || !Private.writerEqual(previous, writer)) {
+      this._writersChanged.emit(this.writers);
+    }
+  }
+
+  /**
+   * Remove a user from the writers list. See IChatModel.clearWritingStatus.
+   */
+  clearWritingStatus(user: IUser): void {
+    this._removeWriter(user.username);
+  }
+
+  /**
+   * Broadcast the current user's writing status. Default no-op; transports
+   * override this (RTC awareness, WebSocket frame).
+   */
+  broadcastWritingStatus(_status: IChatModel.IWritingStatus | null): void {
+    // no-op by default
+  }
+
+  private _removeWriter(username: string): void {
+    this._clearWriterTimer(username);
+    if (this._writers.delete(username)) {
+      this._writersChanged.emit(this.writers);
     }
   }
 
+  private _clearWriterTimer(username: string): void {
+    const timer = this._writerTimers.get(username);
+    if (timer !== undefined) {
+      window.clearTimeout(timer);
+      this._writerTimers.delete(username);
+    }
+  }
+
+  private _clearAllWriterTimers(): void {
+    for (const timer of this._writerTimers.values()) {
+      window.clearTimeout(timer);
+    }
+    this._writerTimers.clear();
+  }
+
   /**
    * Create the chat context that will be passed to the input model.
    */
@@ -793,7 +885,8 @@ export abstract class AbstractChatModel implements IChatModel {
   private _selectionWatcher: ISelectionWatcher | null;
   private _documentManager: IDocumentManager | null;
   private _notificationId: string | null = null;
-  private _writers: IChatModel.IWriter[] = [];
+  private _writers = new Map<string, IChatModel.IWriter>();
+  private _writerTimers = new Map<string, number>();
   private _messageEditions = new Map<string, IInputModel>();
   private _messagesUpdated = new Signal<IChatModel, void>(this);
   private _messageChanged = new Signal<IChatModel, IMessage>(this);
@@ -877,6 +970,25 @@ export namespace IChatModel {
      * The message ID (optional)
      */
     messageID?: string;
+    /**
+     * Custom status text to display instead of the default "is typing…",
+     * e.g. "is running `ripgrep …`". Falls back to the default when unset.
+     */
+    typingIndicator?: string;
+  }
+
+  /**
+   * The writing status broadcast by (or on behalf of) a user.
+   */
+  export interface IWritingStatus {
+    /**
+     * The ID of the message being edited, if any.
+     */
+    messageID?: string;
+    /**
+     * Optional custom typing-indicator text (see IWriter.typingIndicator).
+     */
+    typingIndicator?: string;
   }
 }
 
@@ -942,3 +1054,42 @@ export abstract class AbstractChatContext implements IChatContext {
 
   protected _model: IChatModel;
 }
+
+/**
+ * A namespace for private functionality.
+ */
+namespace Private {
+  /**
+   * Whether two writers are equivalent for change-detection purposes.
+   */
+  export function writerEqual(
+    a: IChatModel.IWriter,
+    b: IChatModel.IWriter
+  ): boolean {
+    return (
+      a.user.username === b.user.username &&
+      a.user.display_name === b.user.display_name &&
+      a.messageID === b.messageID &&
+      a.typingIndicator === b.typingIndicator
+    );
+  }
+
+  /**
+   * Whether two writer maps are equivalent.
+   */
+  export function writersEqual(
+    a: Map<string, IChatModel.IWriter>,
+    b: Map<string, IChatModel.IWriter>
+  ): boolean {
+    if (a.size !== b.size) {
+      return false;
+    }
+    for (const [username, writer] of a) {
+      const other = b.get(username);
+      if (!other || !writerEqual(writer, other)) {
+        return false;
+      }
+    }
+    return true;
+  }
+}