@kispi/chat 0.2.2 → 0.2.3

package/README.en.md

@@ -87,7 +87,7 @@ off()
 | `loadOlder({limit?})` | Reads the page before the oldest message (default 100) and **prepends it to `messages`.** Returns `{messages, hasMore}`. Use it when scrolling up. If the list is empty (before subscribing), it reads nothing |
 | `history({before?, after?, limit?, view?})` | Reads the past directly. **Independent of `messages`.** `view` is `'main'`, `'all'`, or `{thread: id}` |
 | `reload()` | Re-reads the latest page |
-| `react(messageId, emoji)` / `unreact(...)` | Reactions. Idempotent. The ack updates that row's `myReactions` |
+| `react(messageId, emoji)` / `unreact(...)` | Reactions. Idempotent. Updates that row's `myReactions` **before the frame goes out**, and rolls it back if the server refuses. Never touches the count |
 | `reactionsOf(messageId, {emoji?, cursor?, limit?})` | Who reacted. **Each row is a (user, emoji) pair**, so one person can appear on several rows. `limit` defaults to 50, max 100; the last page's `cursor` is an empty string |
 | `markRead(seq, {threadId?})` | Read cursor |
 | `typing()` | Typing indicator. Does not throw |
@@ -139,10 +139,30 @@ the screen froze.
 **Reactions: `reactions` is everyone's counts, `myReactions` is the emoji you pressed.**
 The SDK keeps both live — counts from the `count` on `reaction.*` events, `myReactions` from
 those events when their `userId` is `chat.user.id` (including presses from your other tabs and
-devices) and from the ack of your own `react()`/`unreact()`. Both are overwrites, not
+devices) and from your own `react()`/`unreact()`. Both are overwrites, not
 increments, so getting the event and the ack never counts twice. Only the changed row is a new
 object.
 
+**`myReactions` moves the moment you press.** `react()`/`unreact()` update that row's
+`myReactions` and emit `messages` **before** the frame goes out, so the press does not feel a
+round trip late — the value is already determined by (you, emoji) and the server is idempotent,
+so the ack has nothing new to say. If the server refuses (a limit, permissions) or the ack never
+arrives (timeout, a dropped connection), the SDK rolls it back — unless something newer has
+taken that spot in the meantime. A later press, a `reaction.*` event carrying your own `userId`,
+and a page from `reload()` or a reconnect all beat a pending optimistic value, and a refusal
+never resurrects a stale one. **The SDK owns this field**: an optimistic layer of your own on
+top of it would give it two owners.
+
+**The count (`reactions[].count`) is always the server's.** It is never moved locally. If
+somebody else presses the same emoji while your ack is in flight, a local ±1 disagrees with the
+number the server sends, and the event that would have corrected it has already gone by. Counts
+move on `reaction.*` events only.
+
+**Publishing (`send()`) is deliberately not optimistic.** A `before_publish` hook may rewrite
+the body (an emoji filter, a link rewrite), so there is no value on the client to draw ahead of
+time. A message joins the list when its `message.created` arrives. A "sending…" indicator is
+your own view state, and unlike a reaction the SDK cannot decide it for you.
+
 **Attach the past to the same list with `loadOlder()`.** `history()` is a direct read that
 doesn't touch the list, so merging its results with the live list, filtering duplicates, and
 handling `reset` and reconnects all fall to the consumer. `loadOlder()` puts those rows into
@@ -151,6 +171,12 @@ like any other row. Calling it several times concurrently still makes one reques
 `hasMore` is `false` you're at the start of the room (or of the retention period).
 `reset` or `reload()` discards the attached past as well.
 
+**`hasOlder` and `loadOlder()` describe the SDK's list, not your window.** The SDK never trims
+`room.messages` — if it holds 500 rows, all 500 are there. So if you render a 100-row slice of
+the array you were handed, the other 400 are in `room.messages`, not on the server, and
+`hasOlder === false` is the right answer (it means you are at the start of the room). Widening
+the window is a re-read of `room.messages`; asking the server comes after that.
+
 ```ts
 showLoadMore(room.hasOlder)
 const { hasMore } = await room.loadOlder()

package/README.md

@@ -87,7 +87,7 @@ off()
 | `loadOlder({limit?})` | 가장 오래된 메시지 앞 페이지(기본 100)를 읽어 **`messages` 앞에 붙인다.** `{messages, hasMore}`. 스크롤을 올릴 때 쓴다. 목록이 비어 있으면(구독 전) 아무것도 읽지 않는다 |
 | `history({before?, after?, limit?, view?})` | 과거를 직접 읽는다. **`messages`와 따로 논다.** `view`는 `'main'`, `'all'`, `{thread: id}` |
 | `reload()` | 최근 페이지를 다시 읽는다 |
-| `react(messageId, emoji)` / `unreact(...)` | 리액션. 멱등. ack가 그 행의 `myReactions`를 고친다 |
+| `react(messageId, emoji)` / `unreact(...)` | 리액션. 멱등. **프레임보다 먼저** 그 행의 `myReactions`를 고치고, 서버가 거절하면 되돌린다. 개수는 건드리지 않는다 |
 | `reactionsOf(messageId, {emoji?, cursor?, limit?})` | 누가 눌렀는지. **한 행은 (유저, 이모지) 쌍**이라 한 사람이 여러 줄일 수 있다. `limit` 기본 50 최대 100, 마지막 페이지의 `cursor`는 빈 문자열 |
 | `markRead(seq, {threadId?})` | 읽음 커서 |
 | `typing()` | 입력 중. 던지지 않는다 |
@@ -137,9 +137,27 @@ room.on('messages', m => (messages.value = m))
 **리액션: `reactions`는 모두의 개수, `myReactions`는 내가 누른 이모지다.** 둘 다
 SDK가 라이브로 맞춘다 — 개수는 `reaction.*` 이벤트의 `count`로, `myReactions`는 그
 이벤트의 `userId`가 `chat.user.id`일 때(다른 탭·기기에서 누른 것 포함)와 내
-`react()`/`unreact()`의 ack로. 둘 다 더하기가 아니라 덮어쓰기라 이벤트와 ack가 모두
+`react()`/`unreact()`로. 둘 다 더하기가 아니라 덮어쓰기라 이벤트와 ack가 모두
 와도 두 번 세지 않는다. 바뀐 행만 새 객체다.
 
+**`myReactions`는 누른 즉시 바뀐다.** `react()`/`unreact()`는 프레임을 보내기 **전에**
+그 행의 `myReactions`를 고치고 `messages`를 내보낸다. 그래서 누른 느낌이 왕복만큼
+늦지 않는다 — 누른 값은 (나, 이모지)로 이미 정해져 있고 서버는 멱등이라, ack가
+새로 알려 줄 것이 없다. 서버가 거절하거나(한도, 권한) ack가 못 오면(타임아웃,
+끊김) 되돌린다. 단, 그 사이 더 새로운 값이 자리를 차지했으면 그대로 둔다: 뒤에 누른
+값, 내 `userId`가 실린 `reaction.*` 이벤트, `reload()`나 재접속이 가져온 페이지가
+모두 대기 중인 낙관값을 이긴다. 거절이 낡은 값을 되살리는 일은 없다.
+**이 필드의 주인은 SDK다** — 위에 자기 낙관 계층을 덧대면 주인이 둘이 된다.
+
+**개수(`reactions[].count`)는 늘 서버 값이다.** 로컬에서 ±1하지 않는다. ack를
+기다리는 사이 남이 같은 이모지를 누르면 로컬 계산은 서버가 보낼 수와 어긋나고,
+그 차이를 고쳐 줄 이벤트는 이미 지나갔다. 개수는 `reaction.*` 이벤트가 옮긴다.
+
+**발행(`send()`)은 일부러 낙관적이지 않다.** `before_publish` 훅이 본문을 바꿀 수
+있어서(이모지 필터, 링크 치환) 미리 그릴 값이 클라이언트에 없다. 메시지는
+`message.created`가 올 때 목록에 들어간다. 보내는 중 표시가 필요하면 그것은 소비자의
+화면 상태이고, 리액션과 달리 SDK가 대신 정해 줄 수 없다.
+
 **과거는 `loadOlder()`로 같은 목록에 붙인다.** `history()`는 목록을 건드리지 않는
 직접 읽기라, 그 결과를 라이브 목록과 합치고 중복을 거르고 `reset`과 재접속을
 처리하는 일이 전부 소비자 몫이 된다. `loadOlder()`는 그 행들을 `messages`에 넣으므로
@@ -147,6 +165,13 @@ SDK가 라이브로 맞춘다 — 개수는 `reaction.*` 이벤트의 `count`로
 불러도 요청은 하나이고, `hasMore`가 `false`면 방(또는 보존 기간)의 맨 앞이다.
 `reset`이나 `reload()`는 붙인 과거도 함께 버린다.
 
+**`hasOlder`와 `loadOlder()`는 SDK의 목록을 말한다, 당신의 창이 아니라.** SDK는
+`room.messages`를 줄이지 않는다 — 500건을 들고 있으면 500건이 다 거기 있다. 화면
+성능 때문에 받은 배열을 100건으로 잘라 그리고 있다면, 더 보여 줄 400건은 서버가
+아니라 `room.messages`에 있다. 그때 `hasOlder`가 `false`인 것은 맞는 답이다(방의
+맨 앞이라는 뜻이다). 창을 넓히는 일은 `room.messages`를 다시 읽는 것이고, 서버에
+묻는 것은 그 다음이다.
+
 ```ts
 showLoadMore(room.hasOlder)
 const { hasMore } = await room.loadOlder()

package/dist/index.cjs

@@ -211,6 +211,18 @@ var Timeline = class {
   floor = 1;
   /** A `loadOlder` came back short: the top of what the server keeps was reached. */
   exhausted = false;
+  /**
+   * Presses this client has made and the server has not answered yet, one
+   * entry per (message, emoji) pair, each remembering the last value the
+   * **server** gave for that pair.
+   *
+   * 되돌릴 자리로 "누르기 직전 화면값"을 쓰면 안 된다. 눌렀다 곧바로 취소하고
+   * 두 거절이 차례로 오면, 두 번째 거절이 첫 번째의 낙관값 — 서버가 한 번도
+   * 가진 적 없는 값 — 을 화면에 되살린다. 마지막으로 서버가 말한 값만이
+   * 되돌릴 자리다.
+   */
+  presses = /* @__PURE__ */ new Map();
+  pressSeq = 0;
   constructor(options) {
     this.options = options;
   }
@@ -278,6 +290,7 @@ var Timeline = class {
     this.epoch++;
     this.fills.clear();
     this.pendingDeletes.clear();
+    this.presses.clear();
     this.items = [];
     this.exhausted = false;
     this.shared = false;
@@ -305,6 +318,7 @@ var Timeline = class {
     this.epoch++;
     this.fills.clear();
     const page = [...messages].sort((a, b) => a.seq - b.seq);
+    for (const m of page) this.serverRendered(m.id);
     const top = page.at(-1)?.seq ?? 0;
     this.items = [...page, ...this.items.filter((m) => m.seq > top)];
     this.exhausted = false;
@@ -361,8 +375,57 @@ var Timeline = class {
    * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
    * aggregate alone (the react ack path); `mine` undefined leaves
    * `myReactions` alone (somebody else's event).
+   *
+   * This is the **authoritative** entry point: a value the server sent.
+   * So a press still waiting on an answer for the same pair is finished
+   * here -- a refusal landing afterwards must not push this value back
+   * to the older one it was going to restore.
    */
   reaction(messageId, emoji, count, mine) {
+    if (mine !== void 0) this.presses.delete(pairKey(messageId, emoji));
+    this.applyReaction(messageId, emoji, count, mine);
+  }
+  /**
+   * Applies this client's own react/unreact to `myReactions` **before the
+   * frame goes out**, and returns the press so its answer can settle it.
+   *
+   * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로, 미리
+   * 적용해도 ack가 새로 알려 줄 것이 없다. `count`는 일부러 건드리지 않는다 —
+   * 그 사이 남이 같은 이모지를 누르면 로컬 +1/-1은 서버가 보낼 수와 다르고,
+   * 그 차이를 고칠 이벤트는 이미 지나갔다.
+   *
+   * Undefined when the row is not held: there is nothing to show now and
+   * nothing to put back later.
+   */
+  pressReaction(messageId, emoji, mine) {
+    const at = this.items.findIndex((m) => m.id === messageId);
+    if (at === -1) return void 0;
+    const key = pairKey(messageId, emoji);
+    const base = this.presses.get(key)?.base ?? (this.items[at].myReactions ?? []).includes(emoji);
+    const press = { messageId, emoji, mine, seq: ++this.pressSeq };
+    this.presses.set(key, { seq: press.seq, base });
+    this.applyReaction(messageId, emoji, void 0, mine);
+    return press;
+  }
+  /**
+   * Settles a press with what the server said.
+   *
+   * `accepted` re-asserts the value the press asked for; a refusal puts
+   * the last server-given value back. Either way it does nothing once
+   * this press no longer owns the pair -- a newer press took it over
+   * (and that one's answer decides), or something authoritative already
+   * landed on it (a `reaction.*` event carrying this user's id, a
+   * `reload()`, a reconnect's catch-up page). Reverting there would
+   * resurrect a value older than what is on screen.
+   */
+  settleReaction(press, accepted) {
+    const key = pairKey(press.messageId, press.emoji);
+    const held = this.presses.get(key);
+    if (held === void 0 || held.seq !== press.seq) return;
+    this.presses.delete(key);
+    this.applyReaction(press.messageId, press.emoji, void 0, accepted ? press.mine : held.base);
+  }
+  applyReaction(messageId, emoji, count, mine) {
     const at = this.items.findIndex((m) => m.id === messageId);
     if (at === -1) return;
     const current = this.items[at];
@@ -479,6 +542,7 @@ var Timeline = class {
   }
   /** Inserts at the seq position, replacing an existing row with that seq. */
   insert(message, notify = true) {
+    this.serverRendered(message.id);
     const pending = this.pendingDeletes.has(message.id);
     if (pending) this.pendingDeletes.delete(message.id);
     const withDelete = pending ? emptied(message) : message;
@@ -503,6 +567,21 @@ var Timeline = class {
     this.changed();
     return true;
   }
+  /**
+   * Forgets the presses on a row the server has just re-rendered.
+   *
+   * 히스토리 응답의 행은 뷰어별 `myReactions`를 싣고 오므로 그 값이 서버의
+   * 값이다. 누름을 남겨 두면 그 뒤에 온 거절이 더 새로운 진실 위에 옛 값을
+   * 덮어쓴다. 행 전체 단위인 것은 페이지가 그 행의 이모지 전부를 다시 그려
+   * 주기 때문이다.
+   */
+  serverRendered(messageId) {
+    if (this.presses.size === 0) return;
+    const prefix = `${messageId}\0`;
+    for (const key of this.presses.keys()) {
+      if (key.startsWith(prefix)) this.presses.delete(key);
+    }
+  }
   /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
   own() {
     if (!this.shared) return;
@@ -517,6 +596,9 @@ var Timeline = class {
 function emptied(message) {
   return { ...message, body: {}, deletedAt: message.deletedAt ?? Date.now() };
 }
+function pairKey(messageId, emoji) {
+  return `${messageId}\0${emoji}`;
+}
 function createTimeline(options) {
   return new Timeline(options);
 }
@@ -716,17 +798,49 @@ var Room = class extends Emitter {
   /**
    * Adds a reaction. Idempotent, like the frame.
    *
-   * The ack updates the row's `myReactions` (not its count -- see below),
-   * so the "I reacted" state is right even if the broadcast is missed.
+   * The row's `myReactions` moves **before the frame goes out** and rolls
+   * back if the server refuses; its count stays the server's. See
+   * `toggleReaction`.
    */
   async react(messageId, emoji) {
-    await this.chat.send("react", { roomId: await this.resolveId("reacting"), messageId, emoji, op: "add" });
-    this.timeline.reaction(messageId, emoji, void 0, true);
+    await this.toggleReaction(messageId, emoji, true);
   }
-  /** Removes a reaction. Idempotent; the ack clears it from `myReactions`. */
+  /** Removes a reaction. Idempotent, and optimistic the same way `react` is. */
   async unreact(messageId, emoji) {
-    await this.chat.send("react", { roomId: await this.resolveId("reacting"), messageId, emoji, op: "remove" });
-    this.timeline.reaction(messageId, emoji, void 0, false);
+    await this.toggleReaction(messageId, emoji, false);
+  }
+  /**
+   * Moves `myReactions` now, sends the frame after.
+   *
+   * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로 ack를
+   * 기다릴 이유가 없다 — 기다리면 누른 느낌이 왕복 시간만큼 늦는다. 소비자가
+   * 자기 낙관 계층을 덧대면 이 필드의 주인이 둘이 되므로, SDK가 한다.
+   * **발행은 다르다**: `before_publish` 훅이 본문을 바꿀 수 있어 미리 그릴 값이
+   * 로컬에 없다. 그래서 `send()`는 낙관적이지 않다.
+   *
+   * 개수는 옮기지 않는다. ack가 오기 전에 남이 같은 이모지를 누르면 로컬
+   * +1/-1은 서버가 보낸 수와 다른 값이 되고, 그것을 고칠 이벤트는 이미
+   * 지나갔다. 또 ack와 방 프레임은 다른 길로 와 순서가 없으므로, 늦게 온 내
+   * ack(count 1)가 앞서 온 남의 이벤트(count 2)를 되돌린다.
+   *
+   * 거절·타임아웃·끊김이면 되돌리지만, 그 사이 더 새로운 값이 자리를 차지했다면
+   * 두고 나온다(`Timeline.settleReaction`).
+   */
+  async toggleReaction(messageId, emoji, mine) {
+    const press = this.timeline.pressReaction(messageId, emoji, mine);
+    try {
+      await this.chat.send("react", {
+        roomId: await this.resolveId("reacting"),
+        messageId,
+        emoji,
+        op: mine ? "add" : "remove"
+      });
+    } catch (err) {
+      if (press !== void 0) this.timeline.settleReaction(press, false);
+      throw err;
+    }
+    if (press !== void 0) this.timeline.settleReaction(press, true);
+    else this.timeline.reaction(messageId, emoji, void 0, mine);
   }
   /**
    * Moves this user's read cursor.

package/dist/index.d.cts

@@ -146,10 +146,15 @@ type Message = {
      * The emoji this client's user has on the message.
      *
      * Filled by history reads and kept in step by the SDK afterwards: a
-     * `reaction.*` event whose `userId` is `chat.user.id`, and the ack of
-     * this client's own `react()`/`unreact()`, update it. Absent on a row
-     * the server rendered without a viewer (a live `message.created` has
-     * none yet, which is the same as empty).
+     * `reaction.*` event whose `userId` is `chat.user.id` updates it, and
+     * this client's own `react()`/`unreact()` update it **before the frame
+     * goes out**, rolling back if the server refuses. Absent on a row the
+     * server rendered without a viewer (a live `message.created` has none
+     * yet, which is the same as empty).
+     *
+     * The SDK owns this field, so a consumer does not need -- and should
+     * not add -- an optimistic layer of its own on top of it. The count in
+     * `reactions` is the opposite: always the server's, never moved locally.
      */
     myReactions?: string[];
     thread?: {
@@ -370,12 +375,31 @@ declare class Room extends Emitter<RoomEvents> {
     /**
      * Adds a reaction. Idempotent, like the frame.
      *
-     * The ack updates the row's `myReactions` (not its count -- see below),
-     * so the "I reacted" state is right even if the broadcast is missed.
+     * The row's `myReactions` moves **before the frame goes out** and rolls
+     * back if the server refuses; its count stays the server's. See
+     * `toggleReaction`.
      */
     react(messageId: string, emoji: string): Promise<void>;
-    /** Removes a reaction. Idempotent; the ack clears it from `myReactions`. */
+    /** Removes a reaction. Idempotent, and optimistic the same way `react` is. */
     unreact(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Moves `myReactions` now, sends the frame after.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로 ack를
+     * 기다릴 이유가 없다 — 기다리면 누른 느낌이 왕복 시간만큼 늦는다. 소비자가
+     * 자기 낙관 계층을 덧대면 이 필드의 주인이 둘이 되므로, SDK가 한다.
+     * **발행은 다르다**: `before_publish` 훅이 본문을 바꿀 수 있어 미리 그릴 값이
+     * 로컬에 없다. 그래서 `send()`는 낙관적이지 않다.
+     *
+     * 개수는 옮기지 않는다. ack가 오기 전에 남이 같은 이모지를 누르면 로컬
+     * +1/-1은 서버가 보낸 수와 다른 값이 되고, 그것을 고칠 이벤트는 이미
+     * 지나갔다. 또 ack와 방 프레임은 다른 길로 와 순서가 없으므로, 늦게 온 내
+     * ack(count 1)가 앞서 온 남의 이벤트(count 2)를 되돌린다.
+     *
+     * 거절·타임아웃·끊김이면 되돌리지만, 그 사이 더 새로운 값이 자리를 차지했다면
+     * 두고 나온다(`Timeline.settleReaction`).
+     */
+    private toggleReaction;
     /**
      * Moves this user's read cursor.
      *
@@ -847,6 +871,21 @@ type FetchRange = (range: {
     before: number;
     limit: number;
 }) => Promise<Message[]>;
+/**
+ * A press of this client's own that the server has not answered yet.
+ *
+ * Carries its own sequence number, which is the whole point: by the time
+ * an answer comes back the (message, emoji) pair may belong to a newer
+ * press, and settling this one then would put a value nobody is showing
+ * any more back on screen.
+ */
+type PendingReaction = {
+    messageId: string;
+    emoji: string;
+    /** What the press asked for: in `myReactions`, or out of it. */
+    mine: boolean;
+    seq: number;
+};
 type TimelineOptions = {
     fetchRange: FetchRange;
     /** Called whenever the list changes. */
@@ -897,6 +936,18 @@ declare class Timeline {
     private floor;
     /** A `loadOlder` came back short: the top of what the server keeps was reached. */
     private exhausted;
+    /**
+     * Presses this client has made and the server has not answered yet, one
+     * entry per (message, emoji) pair, each remembering the last value the
+     * **server** gave for that pair.
+     *
+     * 되돌릴 자리로 "누르기 직전 화면값"을 쓰면 안 된다. 눌렀다 곧바로 취소하고
+     * 두 거절이 차례로 오면, 두 번째 거절이 첫 번째의 낙관값 — 서버가 한 번도
+     * 가진 적 없는 값 — 을 화면에 되살린다. 마지막으로 서버가 말한 값만이
+     * 되돌릴 자리다.
+     */
+    private readonly presses;
+    private pressSeq;
     constructor(options: TimelineOptions);
     /** A new array whenever the list changes; never mutated once returned. */
     get messages(): Message[];
@@ -988,8 +1039,39 @@ declare class Timeline {
      * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
      * aggregate alone (the react ack path); `mine` undefined leaves
      * `myReactions` alone (somebody else's event).
+     *
+     * This is the **authoritative** entry point: a value the server sent.
+     * So a press still waiting on an answer for the same pair is finished
+     * here -- a refusal landing afterwards must not push this value back
+     * to the older one it was going to restore.
      */
     reaction(messageId: string, emoji: string, count: number | undefined, mine?: boolean): void;
+    /**
+     * Applies this client's own react/unreact to `myReactions` **before the
+     * frame goes out**, and returns the press so its answer can settle it.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로, 미리
+     * 적용해도 ack가 새로 알려 줄 것이 없다. `count`는 일부러 건드리지 않는다 —
+     * 그 사이 남이 같은 이모지를 누르면 로컬 +1/-1은 서버가 보낼 수와 다르고,
+     * 그 차이를 고칠 이벤트는 이미 지나갔다.
+     *
+     * Undefined when the row is not held: there is nothing to show now and
+     * nothing to put back later.
+     */
+    pressReaction(messageId: string, emoji: string, mine: boolean): PendingReaction | undefined;
+    /**
+     * Settles a press with what the server said.
+     *
+     * `accepted` re-asserts the value the press asked for; a refusal puts
+     * the last server-given value back. Either way it does nothing once
+     * this press no longer owns the pair -- a newer press took it over
+     * (and that one's answer decides), or something authoritative already
+     * landed on it (a `reaction.*` event carrying this user's id, a
+     * `reload()`, a reconnect's catch-up page). Reverting there would
+     * resurrect a value older than what is on screen.
+     */
+    settleReaction(press: PendingReaction, accepted: boolean): void;
+    private applyReaction;
     /** Applies a `thread.updated` to the root message's aggregate. */
     thread(rootId: string, count: number, lastSeq?: number): void;
     /** Applies a `message.deleted`, remembering it if the row is not here. */
@@ -1032,10 +1114,19 @@ declare class Timeline {
     /** Inserts at the seq position, replacing an existing row with that seq. */
     private insert;
     private applyDelete;
+    /**
+     * Forgets the presses on a row the server has just re-rendered.
+     *
+     * 히스토리 응답의 행은 뷰어별 `myReactions`를 싣고 오므로 그 값이 서버의
+     * 값이다. 누름을 남겨 두면 그 뒤에 온 거절이 더 새로운 진실 위에 옛 값을
+     * 덮어쓴다. 행 전체 단위인 것은 페이지가 그 행의 이모지 전부를 다시 그려
+     * 주기 때문이다.
+     */
+    private serverRendered;
     /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
     private own;
     private changed;
 }
 declare function createTimeline(options: TimelineOptions): Timeline;
 
-export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PublishAck, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };
+export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PendingReaction, type PublishAck, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };

package/dist/index.d.ts

@@ -146,10 +146,15 @@ type Message = {
      * The emoji this client's user has on the message.
      *
      * Filled by history reads and kept in step by the SDK afterwards: a
-     * `reaction.*` event whose `userId` is `chat.user.id`, and the ack of
-     * this client's own `react()`/`unreact()`, update it. Absent on a row
-     * the server rendered without a viewer (a live `message.created` has
-     * none yet, which is the same as empty).
+     * `reaction.*` event whose `userId` is `chat.user.id` updates it, and
+     * this client's own `react()`/`unreact()` update it **before the frame
+     * goes out**, rolling back if the server refuses. Absent on a row the
+     * server rendered without a viewer (a live `message.created` has none
+     * yet, which is the same as empty).
+     *
+     * The SDK owns this field, so a consumer does not need -- and should
+     * not add -- an optimistic layer of its own on top of it. The count in
+     * `reactions` is the opposite: always the server's, never moved locally.
      */
     myReactions?: string[];
     thread?: {
@@ -370,12 +375,31 @@ declare class Room extends Emitter<RoomEvents> {
     /**
      * Adds a reaction. Idempotent, like the frame.
      *
-     * The ack updates the row's `myReactions` (not its count -- see below),
-     * so the "I reacted" state is right even if the broadcast is missed.
+     * The row's `myReactions` moves **before the frame goes out** and rolls
+     * back if the server refuses; its count stays the server's. See
+     * `toggleReaction`.
      */
     react(messageId: string, emoji: string): Promise<void>;
-    /** Removes a reaction. Idempotent; the ack clears it from `myReactions`. */
+    /** Removes a reaction. Idempotent, and optimistic the same way `react` is. */
     unreact(messageId: string, emoji: string): Promise<void>;
+    /**
+     * Moves `myReactions` now, sends the frame after.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로 ack를
+     * 기다릴 이유가 없다 — 기다리면 누른 느낌이 왕복 시간만큼 늦는다. 소비자가
+     * 자기 낙관 계층을 덧대면 이 필드의 주인이 둘이 되므로, SDK가 한다.
+     * **발행은 다르다**: `before_publish` 훅이 본문을 바꿀 수 있어 미리 그릴 값이
+     * 로컬에 없다. 그래서 `send()`는 낙관적이지 않다.
+     *
+     * 개수는 옮기지 않는다. ack가 오기 전에 남이 같은 이모지를 누르면 로컬
+     * +1/-1은 서버가 보낸 수와 다른 값이 되고, 그것을 고칠 이벤트는 이미
+     * 지나갔다. 또 ack와 방 프레임은 다른 길로 와 순서가 없으므로, 늦게 온 내
+     * ack(count 1)가 앞서 온 남의 이벤트(count 2)를 되돌린다.
+     *
+     * 거절·타임아웃·끊김이면 되돌리지만, 그 사이 더 새로운 값이 자리를 차지했다면
+     * 두고 나온다(`Timeline.settleReaction`).
+     */
+    private toggleReaction;
     /**
      * Moves this user's read cursor.
      *
@@ -847,6 +871,21 @@ type FetchRange = (range: {
     before: number;
     limit: number;
 }) => Promise<Message[]>;
+/**
+ * A press of this client's own that the server has not answered yet.
+ *
+ * Carries its own sequence number, which is the whole point: by the time
+ * an answer comes back the (message, emoji) pair may belong to a newer
+ * press, and settling this one then would put a value nobody is showing
+ * any more back on screen.
+ */
+type PendingReaction = {
+    messageId: string;
+    emoji: string;
+    /** What the press asked for: in `myReactions`, or out of it. */
+    mine: boolean;
+    seq: number;
+};
 type TimelineOptions = {
     fetchRange: FetchRange;
     /** Called whenever the list changes. */
@@ -897,6 +936,18 @@ declare class Timeline {
     private floor;
     /** A `loadOlder` came back short: the top of what the server keeps was reached. */
     private exhausted;
+    /**
+     * Presses this client has made and the server has not answered yet, one
+     * entry per (message, emoji) pair, each remembering the last value the
+     * **server** gave for that pair.
+     *
+     * 되돌릴 자리로 "누르기 직전 화면값"을 쓰면 안 된다. 눌렀다 곧바로 취소하고
+     * 두 거절이 차례로 오면, 두 번째 거절이 첫 번째의 낙관값 — 서버가 한 번도
+     * 가진 적 없는 값 — 을 화면에 되살린다. 마지막으로 서버가 말한 값만이
+     * 되돌릴 자리다.
+     */
+    private readonly presses;
+    private pressSeq;
     constructor(options: TimelineOptions);
     /** A new array whenever the list changes; never mutated once returned. */
     get messages(): Message[];
@@ -988,8 +1039,39 @@ declare class Timeline {
      * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
      * aggregate alone (the react ack path); `mine` undefined leaves
      * `myReactions` alone (somebody else's event).
+     *
+     * This is the **authoritative** entry point: a value the server sent.
+     * So a press still waiting on an answer for the same pair is finished
+     * here -- a refusal landing afterwards must not push this value back
+     * to the older one it was going to restore.
      */
     reaction(messageId: string, emoji: string, count: number | undefined, mine?: boolean): void;
+    /**
+     * Applies this client's own react/unreact to `myReactions` **before the
+     * frame goes out**, and returns the press so its answer can settle it.
+     *
+     * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로, 미리
+     * 적용해도 ack가 새로 알려 줄 것이 없다. `count`는 일부러 건드리지 않는다 —
+     * 그 사이 남이 같은 이모지를 누르면 로컬 +1/-1은 서버가 보낼 수와 다르고,
+     * 그 차이를 고칠 이벤트는 이미 지나갔다.
+     *
+     * Undefined when the row is not held: there is nothing to show now and
+     * nothing to put back later.
+     */
+    pressReaction(messageId: string, emoji: string, mine: boolean): PendingReaction | undefined;
+    /**
+     * Settles a press with what the server said.
+     *
+     * `accepted` re-asserts the value the press asked for; a refusal puts
+     * the last server-given value back. Either way it does nothing once
+     * this press no longer owns the pair -- a newer press took it over
+     * (and that one's answer decides), or something authoritative already
+     * landed on it (a `reaction.*` event carrying this user's id, a
+     * `reload()`, a reconnect's catch-up page). Reverting there would
+     * resurrect a value older than what is on screen.
+     */
+    settleReaction(press: PendingReaction, accepted: boolean): void;
+    private applyReaction;
     /** Applies a `thread.updated` to the root message's aggregate. */
     thread(rootId: string, count: number, lastSeq?: number): void;
     /** Applies a `message.deleted`, remembering it if the row is not here. */
@@ -1032,10 +1114,19 @@ declare class Timeline {
     /** Inserts at the seq position, replacing an existing row with that seq. */
     private insert;
     private applyDelete;
+    /**
+     * Forgets the presses on a row the server has just re-rendered.
+     *
+     * 히스토리 응답의 행은 뷰어별 `myReactions`를 싣고 오므로 그 값이 서버의
+     * 값이다. 누름을 남겨 두면 그 뒤에 온 거절이 더 새로운 진실 위에 옛 값을
+     * 덮어쓴다. 행 전체 단위인 것은 페이지가 그 행의 이모지 전부를 다시 그려
+     * 주기 때문이다.
+     */
+    private serverRendered;
     /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
     private own;
     private changed;
 }
 declare function createTimeline(options: TimelineOptions): Timeline;
 
-export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PublishAck, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };
+export { type AuthUser, ChatClient, type ChatClientEvents, type ChatClientOptions, ChatError, type ConnectionState, type FetchRange, type Frame, type Hello, type Message, type PendingReaction, type PublishAck, type ReactionUser, type ReactionsPage, Room, type RoomEvents, type SendInput, type SendOptions, Timeline, type TimelineOptions, type WebSocketFactory, type WebSocketLike, createChatClient, createTimeline };

package/dist/index.js

@@ -154,6 +154,18 @@ var Timeline = class {
   floor = 1;
   /** A `loadOlder` came back short: the top of what the server keeps was reached. */
   exhausted = false;
+  /**
+   * Presses this client has made and the server has not answered yet, one
+   * entry per (message, emoji) pair, each remembering the last value the
+   * **server** gave for that pair.
+   *
+   * 되돌릴 자리로 "누르기 직전 화면값"을 쓰면 안 된다. 눌렀다 곧바로 취소하고
+   * 두 거절이 차례로 오면, 두 번째 거절이 첫 번째의 낙관값 — 서버가 한 번도
+   * 가진 적 없는 값 — 을 화면에 되살린다. 마지막으로 서버가 말한 값만이
+   * 되돌릴 자리다.
+   */
+  presses = /* @__PURE__ */ new Map();
+  pressSeq = 0;
   constructor(options) {
     this.options = options;
   }
@@ -221,6 +233,7 @@ var Timeline = class {
     this.epoch++;
     this.fills.clear();
     this.pendingDeletes.clear();
+    this.presses.clear();
     this.items = [];
     this.exhausted = false;
     this.shared = false;
@@ -248,6 +261,7 @@ var Timeline = class {
     this.epoch++;
     this.fills.clear();
     const page = [...messages].sort((a, b) => a.seq - b.seq);
+    for (const m of page) this.serverRendered(m.id);
     const top = page.at(-1)?.seq ?? 0;
     this.items = [...page, ...this.items.filter((m) => m.seq > top)];
     this.exhausted = false;
@@ -304,8 +318,57 @@ var Timeline = class {
    * cannot drift the way `+1`/`-1` would. `count` undefined leaves the
    * aggregate alone (the react ack path); `mine` undefined leaves
    * `myReactions` alone (somebody else's event).
+   *
+   * This is the **authoritative** entry point: a value the server sent.
+   * So a press still waiting on an answer for the same pair is finished
+   * here -- a refusal landing afterwards must not push this value back
+   * to the older one it was going to restore.
    */
   reaction(messageId, emoji, count, mine) {
+    if (mine !== void 0) this.presses.delete(pairKey(messageId, emoji));
+    this.applyReaction(messageId, emoji, count, mine);
+  }
+  /**
+   * Applies this client's own react/unreact to `myReactions` **before the
+   * frame goes out**, and returns the press so its answer can settle it.
+   *
+   * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로, 미리
+   * 적용해도 ack가 새로 알려 줄 것이 없다. `count`는 일부러 건드리지 않는다 —
+   * 그 사이 남이 같은 이모지를 누르면 로컬 +1/-1은 서버가 보낼 수와 다르고,
+   * 그 차이를 고칠 이벤트는 이미 지나갔다.
+   *
+   * Undefined when the row is not held: there is nothing to show now and
+   * nothing to put back later.
+   */
+  pressReaction(messageId, emoji, mine) {
+    const at = this.items.findIndex((m) => m.id === messageId);
+    if (at === -1) return void 0;
+    const key = pairKey(messageId, emoji);
+    const base = this.presses.get(key)?.base ?? (this.items[at].myReactions ?? []).includes(emoji);
+    const press = { messageId, emoji, mine, seq: ++this.pressSeq };
+    this.presses.set(key, { seq: press.seq, base });
+    this.applyReaction(messageId, emoji, void 0, mine);
+    return press;
+  }
+  /**
+   * Settles a press with what the server said.
+   *
+   * `accepted` re-asserts the value the press asked for; a refusal puts
+   * the last server-given value back. Either way it does nothing once
+   * this press no longer owns the pair -- a newer press took it over
+   * (and that one's answer decides), or something authoritative already
+   * landed on it (a `reaction.*` event carrying this user's id, a
+   * `reload()`, a reconnect's catch-up page). Reverting there would
+   * resurrect a value older than what is on screen.
+   */
+  settleReaction(press, accepted) {
+    const key = pairKey(press.messageId, press.emoji);
+    const held = this.presses.get(key);
+    if (held === void 0 || held.seq !== press.seq) return;
+    this.presses.delete(key);
+    this.applyReaction(press.messageId, press.emoji, void 0, accepted ? press.mine : held.base);
+  }
+  applyReaction(messageId, emoji, count, mine) {
     const at = this.items.findIndex((m) => m.id === messageId);
     if (at === -1) return;
     const current = this.items[at];
@@ -422,6 +485,7 @@ var Timeline = class {
   }
   /** Inserts at the seq position, replacing an existing row with that seq. */
   insert(message, notify = true) {
+    this.serverRendered(message.id);
     const pending = this.pendingDeletes.has(message.id);
     if (pending) this.pendingDeletes.delete(message.id);
     const withDelete = pending ? emptied(message) : message;
@@ -446,6 +510,21 @@ var Timeline = class {
     this.changed();
     return true;
   }
+  /**
+   * Forgets the presses on a row the server has just re-rendered.
+   *
+   * 히스토리 응답의 행은 뷰어별 `myReactions`를 싣고 오므로 그 값이 서버의
+   * 값이다. 누름을 남겨 두면 그 뒤에 온 거절이 더 새로운 진실 위에 옛 값을
+   * 덮어쓴다. 행 전체 단위인 것은 페이지가 그 행의 이모지 전부를 다시 그려
+   * 주기 때문이다.
+   */
+  serverRendered(messageId) {
+    if (this.presses.size === 0) return;
+    const prefix = `${messageId}\0`;
+    for (const key of this.presses.keys()) {
+      if (key.startsWith(prefix)) this.presses.delete(key);
+    }
+  }
   /** Makes `items` safe to mutate: a copy, if the current one was handed out. */
   own() {
     if (!this.shared) return;
@@ -460,6 +539,9 @@ var Timeline = class {
 function emptied(message) {
   return { ...message, body: {}, deletedAt: message.deletedAt ?? Date.now() };
 }
+function pairKey(messageId, emoji) {
+  return `${messageId}\0${emoji}`;
+}
 function createTimeline(options) {
   return new Timeline(options);
 }
@@ -659,17 +741,49 @@ var Room = class extends Emitter {
   /**
    * Adds a reaction. Idempotent, like the frame.
    *
-   * The ack updates the row's `myReactions` (not its count -- see below),
-   * so the "I reacted" state is right even if the broadcast is missed.
+   * The row's `myReactions` moves **before the frame goes out** and rolls
+   * back if the server refuses; its count stays the server's. See
+   * `toggleReaction`.
    */
   async react(messageId, emoji) {
-    await this.chat.send("react", { roomId: await this.resolveId("reacting"), messageId, emoji, op: "add" });
-    this.timeline.reaction(messageId, emoji, void 0, true);
+    await this.toggleReaction(messageId, emoji, true);
   }
-  /** Removes a reaction. Idempotent; the ack clears it from `myReactions`. */
+  /** Removes a reaction. Idempotent, and optimistic the same way `react` is. */
   async unreact(messageId, emoji) {
-    await this.chat.send("react", { roomId: await this.resolveId("reacting"), messageId, emoji, op: "remove" });
-    this.timeline.reaction(messageId, emoji, void 0, false);
+    await this.toggleReaction(messageId, emoji, false);
+  }
+  /**
+   * Moves `myReactions` now, sends the frame after.
+   *
+   * 누른 값은 (사용자, 이모지)로 로컬에서 정해지고 엔진은 멱등이므로 ack를
+   * 기다릴 이유가 없다 — 기다리면 누른 느낌이 왕복 시간만큼 늦는다. 소비자가
+   * 자기 낙관 계층을 덧대면 이 필드의 주인이 둘이 되므로, SDK가 한다.
+   * **발행은 다르다**: `before_publish` 훅이 본문을 바꿀 수 있어 미리 그릴 값이
+   * 로컬에 없다. 그래서 `send()`는 낙관적이지 않다.
+   *
+   * 개수는 옮기지 않는다. ack가 오기 전에 남이 같은 이모지를 누르면 로컬
+   * +1/-1은 서버가 보낸 수와 다른 값이 되고, 그것을 고칠 이벤트는 이미
+   * 지나갔다. 또 ack와 방 프레임은 다른 길로 와 순서가 없으므로, 늦게 온 내
+   * ack(count 1)가 앞서 온 남의 이벤트(count 2)를 되돌린다.
+   *
+   * 거절·타임아웃·끊김이면 되돌리지만, 그 사이 더 새로운 값이 자리를 차지했다면
+   * 두고 나온다(`Timeline.settleReaction`).
+   */
+  async toggleReaction(messageId, emoji, mine) {
+    const press = this.timeline.pressReaction(messageId, emoji, mine);
+    try {
+      await this.chat.send("react", {
+        roomId: await this.resolveId("reacting"),
+        messageId,
+        emoji,
+        op: mine ? "add" : "remove"
+      });
+    } catch (err) {
+      if (press !== void 0) this.timeline.settleReaction(press, false);
+      throw err;
+    }
+    if (press !== void 0) this.timeline.settleReaction(press, true);
+    else this.timeline.reaction(messageId, emoji, void 0, mine);
   }
   /**
    * Moves this user's read cursor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kispi/chat",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Client SDK for the chat server: one WebSocket, many rooms, ordered history.",
   "license": "MIT",
   "type": "module",