@kispi/chat 0.2.1 → 0.2.3

package/README.en.md

@@ -36,7 +36,7 @@ is in the browser, the whole app is open.
 | Property | |
 |---|---|
 | `state` | `'connecting' \| 'open' \| 'reconnecting' \| 'closed'` |
-| `user` | The connected user. `{id, name, avatar?}` |
+| `user` | The connected user. `{id, name, avatar?}` — **the identity the server accepted from the token** (what `hello` carried). Use this instead of parsing your token response. Set once `connect()`/`reconnect()` resolves |
 | `connectionId` | Identifier used for support requests and forced disconnects |
 | `hello` | Everything the server sent on connect (limits, total unread, warnings) |
 
@@ -44,6 +44,7 @@ is in the browser, the whole app is open.
 |---|---|
 | `connect()` | Connects. If already connected or connecting, it joins that attempt. Rejects on failure, but **retries continue in the background** (see below) |
 | `close()` | Disconnects. This one does not reconnect. Call `connect()` to come back |
+| `reconnect()` | **Re-authenticates**: calls `token()` again and replaces the socket. Room handles, subscriptions and `messages` are kept, and the state goes `open → reconnecting → open` (never `closed`). Use it after a nickname or avatar change (below) |
 | `room(roomId)` | Room handle. Same id, same object |
 | `roomByKey(key)` | Handle for a room opened by key. The server tells you the id when you subscribe. **Does not create the room** — for a key that doesn't exist, `subscribe()` rejects with `not_found` (see below) |
 | `rooms.list({cursor?, limit?})` | Rooms I'm a member of + unread + last message |
@@ -76,6 +77,7 @@ off()
 | `id` / `key` | Room identifiers. If opened by key, `id` is absent until you subscribe |
 | `lastSeq` | The room's last seq as reported by the server |
 | `presence` | `{count, users?, capped?}` |
+| `hasOlder` | Whether `loadOlder()` has more past to read. Lets you decide whether to draw "load earlier" before the first `loadOlder()`. The same test as `loadOlder()`'s `hasMore` (the first row is above the room's retention floor); `false` while the list is empty. Re-read it on `messages` |
 
 | Method | |
 |---|---|
@@ -85,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 |
+| `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 |
@@ -134,6 +136,33 @@ Wrapping it in `$state` (a deep proxy) or `ref` works, but does unnecessary work
 modified the same array in place and emitted it again, so on the reference-comparing side
 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 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
@@ -142,7 +171,14 @@ 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()
 ```
 
@@ -198,6 +234,20 @@ The last two leave `state` at `closed` and report why on `chat.on('error')` —
 or during a REST token refresh, where there is no caller to reject. Call `connect()` to come
 back.
 
+**After a nickname change, `reconnect()`.** The server reads the name and avatar from the
+token's claims once, when the socket authenticates. So after your backend changes the name,
+the next message on this connection still carries the old one. `reconnect()` calls `token()`
+again, re-authenticates with the new claims, and the rooms carry on from what they hold.
+`close()` + `connect()` works too, but passes through `closed` (your offline screen flashes)
+and removes the page listeners. Frames still awaiting an ack on the old socket reject with
+`closed`. When it resolves, `chat.user` is the new identity.
+
+```ts
+await api.updateNickname(name) // so your backend puts the new name in the next token()
+await chat.reconnect()
+chat.user?.name                // the new name
+```
+
 **The SDK handles token expiry.** The socket authenticates only once on connect, so it stays
 fine even when the token expires, but REST checks the token on every request. When REST gets a
 401, the SDK calls `token()` again and retries **once**. A second 401 (origin, revoked token,
@@ -340,12 +390,26 @@ spaces don't overlap.
 
 | Group | Methods |
 |---|---|
-| `rooms` | `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `members.list/add/remove` |
+| `rooms` | `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `presence(roomId, {full?})`, `members.list/add/remove` |
 | `messages` | `send(roomId, {sender, text?, kind?, attachments?, appMeta?, replyTo?, threadId?, clientMessageId?})`, `list`, `delete` |
-| `users` | `list({cursor?, limit?})`, `update`, `delete({purgeMessages?})`, `ban({until, reason?})`, `unban`, `revokeTokens`, `disconnect` |
+| `users` | `list({cursor?, limit?})`, `update`, `delete({purgeMessages?})`, `purgeMessages(userId)`, `ban({until, reason?})`, `unban`, `revokeTokens`, `disconnect` |
 | `events` | `list({after?, limit?})` — the outbox. Catches up on missed webhooks |
 | `webhooks` | `verify(headers, rawBody, {now?, tolerance?})` |
 
+`rooms.presence(roomId)` is `{count}`; with `{full: true}` it adds `users` (at most 1000,
+`capped: true` when cut). An empty room is `{count: 0}`, not a 404.
+
+**`users.purgeMessages(userId)` is moderation** — it deletes every message the user sent in the
+app (tombstones: seq is untouched, and watching clients get `message.deleted`) **without
+withdrawing them.** The name stays. For spam, **ban first**, then call it — a message posted
+while it runs is not in its listing. It does a bounded amount per call, so call again while
+`purgeCapped` is `true`. A withdrawn user is a 404 (use `delete(userId, {purgeMessages: true})`).
+
+```ts
+await chat.users.ban(userId, { until: Date.now() + 7 * 86_400_000, reason: 'spam' })
+while ((await chat.users.purgeMessages(userId)).purgeCapped) {}
+```
+
 `users.ban`'s `until` is **unix milliseconds and required.** For an indefinite ban, pick a
 far-future time yourself — it goes into the audit log as a decision, not an accident.
 

package/README.md

@@ -36,7 +36,7 @@ npm install @kispi/chat
 | 프로퍼티 | |
 |---|---|
 | `state` | `'connecting' \| 'open' \| 'reconnecting' \| 'closed'` |
-| `user` | 접속한 사람. `{id, name, avatar?}` |
+| `user` | 접속한 사람. `{id, name, avatar?}` — **서버가 토큰에서 받아들인 신원**(hello가 준 것)이다. 토큰 응답을 따로 파싱하지 말고 이것을 쓴다. `connect()`/`reconnect()`가 끝나면 채워져 있다 |
 | `connectionId` | 지원 문의와 강제 종료에 쓰는 식별자 |
 | `hello` | 서버가 접속 때 준 것 전부(한도, 총 unread, 경고) |
 
@@ -44,6 +44,7 @@ npm install @kispi/chat
 |---|---|
 | `connect()` | 붙는다. 이미 붙어 있거나 붙는 중이면 그 시도에 합류한다. 실패하면 거절하지만 **재시도는 백그라운드에서 계속된다**(아래) |
 | `close()` | 끊는다. 이건 재접속하지 않는다. 다시 붙으려면 `connect()` |
+| `reconnect()` | **다시 인증한다**: `token()`을 다시 불러 소켓을 바꾼다. 방 핸들과 구독, `messages`는 그대로이고 상태는 `open → reconnecting → open`이다(`closed`를 거치지 않는다). 닉네임·아바타를 바꾼 뒤에 쓴다(아래) |
 | `room(roomId)` | 방 핸들. 같은 id면 같은 객체 |
 | `roomByKey(key)` | 키로 여는 방 핸들. 구독할 때 서버가 id를 알려 준다. **방을 만들지 않는다** — 없는 키면 `subscribe()`가 `not_found`로 거절한다(아래) |
 | `rooms.list({cursor?, limit?})` | 내가 멤버인 방 + unread + 마지막 메시지 |
@@ -76,6 +77,7 @@ off()
 | `id` / `key` | 방 식별자. 키로 열었으면 구독 전까지 `id`가 없다 |
 | `lastSeq` | 서버가 알려 준 방의 마지막 seq |
 | `presence` | `{count, users?, capped?}` |
+| `hasOlder` | `loadOlder()`로 더 읽을 과거가 있는지. 첫 `loadOlder()` 전에 "이전 메시지" 버튼을 그릴지 정할 때 쓴다. `loadOlder()`의 `hasMore`와 같은 판정(맨 위 행이 방의 보존 하한 위에 있는지)이고, 목록이 비었으면 `false`. `messages` 이벤트 때 다시 읽는다 |
 
 | 메서드 | |
 |---|---|
@@ -85,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(...)` | 리액션. 멱등 |
+| `react(messageId, emoji)` / `unreact(...)` | 리액션. 멱등. **프레임보다 먼저** 그 행의 `myReactions`를 고치고, 서버가 거절하면 되돌린다. 개수는 건드리지 않는다 |
 | `reactionsOf(messageId, {emoji?, cursor?, limit?})` | 누가 눌렀는지. **한 행은 (유저, 이모지) 쌍**이라 한 사람이 여러 줄일 수 있다. `limit` 기본 50 최대 100, 마지막 페이지의 `cursor`는 빈 문자열 |
 | `markRead(seq, {threadId?})` | 읽음 커서 |
 | `typing()` | 입력 중. 던지지 않는다 |
@@ -132,6 +134,30 @@ room.on('messages', m => (messages.value = m))
 `$state`(깊은 프록시)나 `ref`로 감싸도 동작하지만 필요 없는 일을 한다. 0.1.x는 같은
 배열을 제자리에서 고쳐 다시 내보내서, 참조로 비교하는 쪽에서는 화면이 멈췄다.
 
+**리액션: `reactions`는 모두의 개수, `myReactions`는 내가 누른 이모지다.** 둘 다
+SDK가 라이브로 맞춘다 — 개수는 `reaction.*` 이벤트의 `count`로, `myReactions`는 그
+이벤트의 `userId`가 `chat.user.id`일 때(다른 탭·기기에서 누른 것 포함)와 내
+`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`에 넣으므로
@@ -139,7 +165,15 @@ room.on('messages', m => (messages.value = m))
 불러도 요청은 하나이고, `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()
 ```
 
@@ -191,6 +225,19 @@ token: async () => {
 뒤의 둘은 `state`를 `closed`로 두고 `chat.on('error')`로 이유를 낸다. 재접속 중이나
 REST의 토큰 갱신 중이라 거절을 받을 호출자가 없어도 그렇다. 다시 붙으려면 `connect()`.
 
+**닉네임을 바꾸면 `reconnect()`.** 서버는 이름·아바타를 접속할 때 토큰 claim에서
+한 번 읽는다. 그래서 백엔드에서 이름을 바꿔도 이 접속의 다음 메시지는 옛 이름이다.
+`reconnect()`는 `token()`을 다시 불러 새 claim으로 다시 인증하고, 방은 가진 것에서
+이어서 따라잡는다. `close()` + `connect()`도 되지만 `closed`를 거쳐(오프라인 화면이
+깜빡인다) 페이지 리스너까지 떼어 낸다. 옛 소켓에서 ack를 기다리던 프레임은 `closed`로
+거절된다. 끝나면 `chat.user`가 새 신원이다.
+
+```ts
+await api.updateNickname(name) // 백엔드가 다음 token()에 새 이름을 싣게 한다
+await chat.reconnect()
+chat.user?.name                // 새 이름
+```
+
 **토큰 만료는 SDK가 처리한다.** 소켓은 접속할 때 한 번만 인증하므로 토큰이 만료돼도
 멀쩡하지만, REST는 요청마다 토큰을 본다. REST가 401을 받으면 SDK가 `token()`을 다시
 불러 **한 번** 재시도한다. 두 번째 401(오리진, 폐기된 토큰, 밴)은 그대로 던진다.
@@ -331,12 +378,26 @@ app.post('/api/chat-token', (req, res) => {
 
 | 그룹 | 메서드 |
 |---|---|
-| `rooms` | `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `members.list/add/remove` |
+| `rooms` | `ensure({key?, type, name?, meta?, members?})`, `ensureDM([a, b])`, `get`, `update`, `delete`, `custom(roomId, payload)`, `presence(roomId, {full?})`, `members.list/add/remove` |
 | `messages` | `send(roomId, {sender, text?, kind?, attachments?, appMeta?, replyTo?, threadId?, clientMessageId?})`, `list`, `delete` |
-| `users` | `list({cursor?, limit?})`, `update`, `delete({purgeMessages?})`, `ban({until, reason?})`, `unban`, `revokeTokens`, `disconnect` |
+| `users` | `list({cursor?, limit?})`, `update`, `delete({purgeMessages?})`, `purgeMessages(userId)`, `ban({until, reason?})`, `unban`, `revokeTokens`, `disconnect` |
 | `events` | `list({after?, limit?})` — outbox. 놓친 웹훅을 따라잡는다 |
 | `webhooks` | `verify(headers, rawBody, {now?, tolerance?})` |
 
+`rooms.presence(roomId)`는 `{count}`이고, `{full: true}`면 `users`(최대 1000명, 잘리면
+`capped: true`)가 붙는다. 빈 방은 404가 아니라 `{count: 0}`이다.
+
+**`users.purgeMessages(userId)`는 모더레이션이다** — 그 유저가 앱에서 보낸 메시지를
+전부 지우되(tombstone: seq는 그대로, 보고 있는 클라이언트에는 `message.deleted`가
+간다) **탈퇴시키지 않는다.** 이름도 남는다. 스팸이면 **밴을 먼저** 하고 부른다 — 도는
+사이에 올라온 메시지는 목록에 없다. 한 번에 상한만큼만 하므로 `purgeCapped`가
+`true`인 동안 다시 부른다. 탈퇴한 유저는 404다(그때는 `delete(userId, {purgeMessages: true})`).
+
+```ts
+await chat.users.ban(userId, { until: Date.now() + 7 * 86_400_000, reason: 'spam' })
+while ((await chat.users.purgeMessages(userId)).purgeCapped) {}
+```
+
 `users.ban`의 `until`은 **unix 밀리초이고 필수다.** 무기한 밴은 먼 미래 시각을
 직접 고른다 — 감사 로그에 사고가 아니라 결정으로 남는다.
 

package/dist/index.cjs

@@ -204,6 +204,25 @@ var Timeline = class {
   shared = false;
   /** The `loadOlder` in flight, so a scroll handler firing twice asks once. */
   older;
+  /**
+   * The lowest seq the room still keeps (`minSeq` from the subscribe ack;
+   * 1 until told). Below it there is nothing to read, whatever seq says.
+   */
+  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;
   }
@@ -212,6 +231,22 @@ var Timeline = class {
     this.shared = true;
     return this.items;
   }
+  /**
+   * Whether `loadOlder()` would find anything, answered without asking.
+   *
+   * `loadOlder()`의 `hasMore`와 같은 판정이다: 맨 위 행이 방의 보존 하한
+   * (`minSeq`, seq는 1부터 구멍 없이 붙는다)보다 위에 있고, 앞선 `loadOlder`가
+   * 덜 찬 페이지로 끝을 알린 적이 없으면 더 있다. 첫 `loadOlder()` 전에 "이전
+   * 메시지 더 보기"를 그릴지 정할 수 있게 한다. 목록이 비었으면 false다.
+   */
+  get hasOlder() {
+    const first = this.items[0];
+    return !this.exhausted && first !== void 0 && first.seq > this.floor;
+  }
+  /** Records the room's retention floor (`minSeq`). */
+  setFloor(minSeq) {
+    this.floor = Math.max(1, minSeq);
+  }
   /** The highest seq this timeline holds, hole or no hole. */
   get highestSeq() {
     return this.items.at(-1)?.seq ?? 0;
@@ -255,7 +290,9 @@ var Timeline = class {
     this.epoch++;
     this.fills.clear();
     this.pendingDeletes.clear();
+    this.presses.clear();
     this.items = [];
+    this.exhausted = false;
     this.shared = false;
     this.changed();
   }
@@ -281,8 +318,10 @@ 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;
     this.shared = false;
     for (const m of this.items) {
       if (this.pendingDeletes.has(m.id)) this.applyDelete(m.id);
@@ -333,20 +372,84 @@ var Timeline = class {
    *
    * The server sends the new `count` with the event, so this is a
    * replacement rather than an increment: two clients reacting at once
-   * cannot drift the way `+1`/`-1` would.
+   * 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.
    */
-  reaction(messageId, emoji, count) {
+  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];
-    const existing = current.reactions ?? [];
-    const slot = existing.findIndex((r) => r.emoji === emoji);
-    let next;
-    if (count <= 0) next = existing.filter((r) => r.emoji !== emoji);
-    else if (slot === -1) next = [...existing, { emoji, count }];
-    else next = existing.map((r, i) => i === slot ? { emoji, count } : r);
+    let reactions = current.reactions;
+    if (count !== void 0) {
+      const existing = current.reactions ?? [];
+      const slot = existing.findIndex((r) => r.emoji === emoji);
+      if (count <= 0) reactions = existing.filter((r) => r.emoji !== emoji);
+      else if (slot === -1) reactions = [...existing, { emoji, count }];
+      else reactions = existing.map((r, i) => i === slot ? { emoji, count } : r);
+    }
+    let myReactions = current.myReactions;
+    if (mine !== void 0) {
+      const held = current.myReactions ?? [];
+      const has = held.includes(emoji);
+      if (mine && !has) myReactions = [...held, emoji];
+      else if (!mine && has) myReactions = held.filter((e) => e !== emoji);
+    }
+    if (reactions === current.reactions && myReactions === current.myReactions) return;
+    const next = { ...current };
+    if (reactions !== void 0) next.reactions = reactions;
+    if (myReactions !== void 0) next.myReactions = myReactions;
     this.own();
-    this.items[at] = { ...current, reactions: next };
+    this.items[at] = next;
     this.changed();
   }
   /** Applies a `thread.updated` to the root message's aggregate. */
@@ -383,14 +486,16 @@ var Timeline = class {
   }
   async readOlder(limit) {
     const first = this.items[0];
-    if (first === void 0 || first.seq <= 1) return { messages: [], hasMore: false };
+    if (first === void 0 || first.seq <= this.floor) return { messages: [], hasMore: false };
     const epoch = this.epoch;
     const page = await this.options.fetchRange({ after: 0, before: first.seq, limit });
     if (this.epoch !== epoch) return { messages: [], hasMore: true };
     for (const m of page) this.insert(m, false);
     if (page.length > 0) this.changed();
     const top = page[0];
-    return { messages: page, hasMore: page.length >= limit && top !== void 0 && top.seq > 1 };
+    const hasMore = page.length >= limit && top !== void 0 && top.seq > this.floor;
+    this.exhausted = !hasMore;
+    return { messages: page, hasMore };
   }
   /**
    * Fetches everything between what we have and `upTo`.
@@ -437,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;
@@ -461,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;
@@ -475,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);
 }
@@ -538,6 +662,17 @@ var Room = class extends Emitter {
       onChange: (messages) => this.emit("messages", messages)
     });
   }
+  /**
+   * Whether older history exists above the first message held -- what
+   * `loadOlder()` would report as `hasMore`, known before calling it.
+   *
+   * Derived from the first row's seq against the room's retention floor
+   * (the subscribe ack's `minSeq`), and false once a `loadOlder()` came
+   * back short. False while nothing is loaded. Re-read it on `messages`.
+   */
+  get hasOlder() {
+    return this.timeline.hasOlder;
+  }
   /** Everything this client knows about the room, in seq order. A new array whenever it changes. */
   get messages() {
     return this.timeline.messages;
@@ -616,6 +751,7 @@ var Room = class extends Emitter {
     this.id = ack.roomId;
     this.chat.registerRoomId(ack.roomId, this);
     this.lastSeq = ack.lastSeq;
+    if (typeof ack.minSeq === "number") this.timeline.setFloor(ack.minSeq);
     if (ack.presence !== void 0) this.presence = ack.presence;
     if (attempt.wasReset) {
       await this.loadRecent(current);
@@ -659,12 +795,52 @@ var Room = class extends Emitter {
     });
     return page.messages;
   }
-  /** Adds a reaction. Idempotent, like the frame. */
+  /**
+   * Adds a reaction. Idempotent, like the frame.
+   *
+   * 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" });
+    await this.toggleReaction(messageId, emoji, true);
   }
+  /** 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" });
+    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.
@@ -859,7 +1035,9 @@ var Room = class extends Emitter {
       case "reaction.added":
       case "reaction.removed": {
         const r = data;
-        this.timeline.reaction(r.messageId, r.emoji, r.count);
+        const me = this.chat.user?.id;
+        const mine = me !== void 0 && r.userId === me ? type === "reaction.added" : void 0;
+        this.timeline.reaction(r.messageId, r.emoji, r.count, mine);
         break;
       }
       case "thread.updated": {
@@ -1108,6 +1286,48 @@ var ChatClient = class extends Emitter {
     });
     return this.opening;
   }
+  /**
+   * Re-authenticates: calls `token()` again and replaces the socket, keeping
+   * every room handle and every subscription.
+   *
+   * For when the identity the server holds has to change mid-session --
+   * a nickname change, a new avatar, fresh claims. The server reads the
+   * token once, at `auth`, so `sender.name` on the next message is the old
+   * one until the connection is re-authenticated. `close()` + `connect()`
+   * does that too, but passes through `closed` (a consumer's "you are
+   * offline" screen) and tears down the page listeners.
+   *
+   * States: `open` → `reconnecting` → `open`, never `closed`. Rooms
+   * resubscribe from what they hold and catch up the gap, as after any
+   * drop; `messages` is kept. Frames awaiting an ack on the old socket are
+   * rejected with `closed`. `chat.user` is the new identity once this
+   * resolves. If `token()` fails the client keeps retrying in the
+   * background like any reconnect (and this rejects); a `ChatError` from
+   * `token()` stops it at `closed`, as on connect.
+   *
+   * On a client that is not connected (never connected, or `close()`d) it
+   * is `connect()`.
+   */
+  async reconnect() {
+    if (this.opening !== void 0) await this.opening.catch(() => {
+    });
+    const socket = this.socket;
+    if (socket === void 0 || this.state !== "open") return this.connect();
+    this.clearTimers();
+    this.retired.add(socket);
+    this.socket = void 0;
+    this.failPending(new ChatError("closed", "the connection was replaced by reconnect()"));
+    try {
+      socket.close(1e3, "client reconnecting");
+    } catch {
+    }
+    this.opening = this.openOnce("reconnecting").finally(() => {
+      this.opening = void 0;
+    });
+    return this.opening;
+  }
+  /** Sockets `reconnect()` replaced: their late events are not this client's any more. */
+  retired = /* @__PURE__ */ new WeakSet();
   /**
    * Closes for good.
    *
@@ -1221,8 +1441,8 @@ var ChatClient = class extends Emitter {
     this.state = next;
     this.emit("state", next);
   }
-  async openOnce() {
-    this.setState(this.attempt === 0 ? "connecting" : "reconnecting");
+  async openOnce(state = this.attempt === 0 ? "connecting" : "reconnecting") {
+    this.setState(state);
     let authData;
     try {
       authData = await this.authData();
@@ -1248,6 +1468,7 @@ var ChatClient = class extends Emitter {
         else reject(err);
       };
       socket.addEventListener("message", (ev) => {
+        if (this.retired.has(socket)) return;
         const frame = JSON.parse(String(ev.data));
         if (frame.type === "hello") {
           this.onHello(frame.data);
@@ -1268,6 +1489,7 @@ var ChatClient = class extends Emitter {
         this.onFrame(frame);
       });
       socket.addEventListener("close", () => {
+        if (this.retired.has(socket)) return;
         if (this.socket !== void 0 && this.socket !== socket) return;
         this.clearTimers();
         this.socket = void 0;