@kabmo-labs/kabmo 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (180) hide show
  1. package/README.md +45 -0
  2. package/dist/client/index.html +1 -1
  3. package/dist/client/index.js +333 -333
  4. package/dist/client/static/js/index-18xe7655.css +1 -0
  5. package/dist/client/static/js/{index-bpptfkz2.js → index-nxpe7835.js} +768 -763
  6. package/package.json +3 -1
  7. package/src/client/components/common/code-surface/bracket-guide.test.ts +249 -0
  8. package/src/client/components/common/code-surface/bracket-guide.ts +131 -0
  9. package/src/client/components/common/code-surface/documents.test.ts +5 -3
  10. package/src/client/components/common/code-surface/documents.ts +85 -0
  11. package/src/client/components/common/code-surface/extensions.test.ts +5 -0
  12. package/src/client/components/common/code-surface/extensions.ts +140 -7
  13. package/src/client/components/common/code-surface/fold-stack.test.ts +218 -0
  14. package/src/client/components/common/code-surface/fold.test.ts +148 -0
  15. package/src/client/components/common/code-surface/fold.ts +118 -0
  16. package/src/client/components/common/code-surface/indent-guide.ts +104 -0
  17. package/src/client/components/common/code-surface/indent.test.ts +239 -0
  18. package/src/client/components/common/code-surface/indent.ts +124 -0
  19. package/src/client/components/common/code-surface/index.tsx +76 -46
  20. package/src/client/components/common/code-surface/keymap.ts +12 -23
  21. package/src/client/components/common/code-surface/line-commands.test.ts +90 -0
  22. package/src/client/components/common/code-surface/line-commands.ts +103 -0
  23. package/src/client/components/common/code-surface/props.ts +87 -0
  24. package/src/client/components/common/code-surface/stream-language.test.ts +118 -0
  25. package/src/client/components/common/code-surface/stream-language.ts +123 -0
  26. package/src/client/components/common/code-surface/theme.test.ts +40 -5
  27. package/src/client/components/common/code-surface/theme.ts +113 -0
  28. package/src/client/components/common/code-surface/typing.test.ts +97 -0
  29. package/src/client/components/common/code-surface/typing.ts +111 -0
  30. package/src/client/components/common/toolbar-row/index.test.tsx +53 -4
  31. package/src/client/components/common/toolbar-row/index.tsx +101 -30
  32. package/src/client/components/layout/desktop-layout/WorkspacePanels.tsx +17 -0
  33. package/src/client/components/layout/desktop-layout/index.tsx +18 -0
  34. package/src/client/components/mobile/mobile-right-sidebar/FullEditor.tsx +35 -33
  35. package/src/client/components/mobile/mobile-right-sidebar/Header.tsx +20 -1
  36. package/src/client/components/mobile/mobile-right-sidebar/editor-props.ts +25 -0
  37. package/src/client/components/settings/categories/AppearanceSettings.tsx +6 -0
  38. package/src/client/components/settings/categories/appearance-settings/EditorIndentSection.tsx +87 -0
  39. package/src/client/components/settings/categories/appearance-settings/EditorTypingSection.tsx +99 -0
  40. package/src/client/components/workspace/chat-timeline/chat-input/expansion.ts +9 -4
  41. package/src/client/components/workspace/chat-timeline/chat-input/index.tsx +15 -11
  42. package/src/client/components/workspace/chat-timeline/chat-input/stretch-send.test.tsx +165 -0
  43. package/src/client/components/workspace/chat-timeline/tool-renderers/shared/DiffView.test.ts +17 -3
  44. package/src/client/components/workspace/chat-timeline/tool-renderers/shared/DiffView.tsx +10 -6
  45. package/src/client/components/workspace/editor/Body.tsx +24 -0
  46. package/src/client/components/workspace/editor/CommandPalette.tsx +4 -4
  47. package/src/client/components/workspace/editor/ConflictStrip.tsx +77 -0
  48. package/src/client/components/workspace/editor/Dialogs.tsx +53 -0
  49. package/src/client/components/workspace/editor/EmptyEditor.tsx +23 -0
  50. package/src/client/components/workspace/editor/ExternalChangeStrip.tsx +61 -0
  51. package/src/client/components/workspace/editor/FileDocument.tsx +89 -1
  52. package/src/client/components/workspace/editor/FilePane.tsx +43 -0
  53. package/src/client/components/workspace/editor/FindWidget.test.ts +9 -5
  54. package/src/client/components/workspace/editor/FindWidget.tsx +29 -0
  55. package/src/client/components/workspace/editor/GoToLineModal.tsx +123 -0
  56. package/src/client/components/workspace/editor/Notices.tsx +71 -0
  57. package/src/client/components/workspace/editor/Pane.tsx +118 -0
  58. package/src/client/components/workspace/editor/PluginColumn.tsx +32 -0
  59. package/src/client/components/workspace/editor/QuickOpenModal.tsx +146 -0
  60. package/src/client/components/workspace/editor/SaveAsModal.tsx +175 -0
  61. package/src/client/components/workspace/editor/SplitColumn.tsx +98 -0
  62. package/src/client/components/workspace/editor/SplitPane.tsx +57 -0
  63. package/src/client/components/workspace/editor/StatusBar.tsx +106 -0
  64. package/src/client/components/workspace/editor/TabContextMenu.tsx +75 -0
  65. package/src/client/components/workspace/editor/Tabs.tsx +195 -18
  66. package/src/client/components/workspace/editor/Toolbar.tsx +54 -181
  67. package/src/client/components/workspace/editor/index.tsx +199 -189
  68. package/src/client/components/workspace/editor/props.ts +64 -0
  69. package/src/client/components/workspace/editor/toolbar-clusters.tsx +300 -0
  70. package/src/client/components/workspace/file-explorer/Modals.tsx +14 -1
  71. package/src/client/components/workspace/file-explorer/TreeItem.tsx +2 -1
  72. package/src/client/components/workspace/file-explorer/clipboard.test.ts +3 -1
  73. package/src/client/components/workspace/file-explorer/index.test.ts +61 -0
  74. package/src/client/components/workspace/file-explorer/index.tsx +10 -48
  75. package/src/client/components/workspace/file-explorer/local-edit.test.ts +8 -3
  76. package/src/client/components/workspace/search-panel/Body.tsx +6 -1
  77. package/src/client/hooks/chat/composer/file-drop.ts +22 -37
  78. package/src/client/hooks/chat/composer/pipeline.test.ts +76 -0
  79. package/src/client/hooks/chat/composer/pipeline.ts +12 -1
  80. package/src/client/hooks/editor/caret-position.test.ts +58 -0
  81. package/src/client/hooks/editor/caret-position.ts +48 -0
  82. package/src/client/hooks/editor/file-editor-types.ts +200 -0
  83. package/src/client/hooks/editor/find-history.test.ts +132 -0
  84. package/src/client/hooks/editor/find-history.ts +46 -0
  85. package/src/client/hooks/editor/find-selection-range.test.ts +100 -0
  86. package/src/client/hooks/editor/find-selection-range.ts +49 -0
  87. package/src/client/hooks/editor/find-state.ts +13 -0
  88. package/src/client/hooks/editor/font.test.ts +0 -93
  89. package/src/client/hooks/editor/indent-settings.test.ts +104 -0
  90. package/src/client/hooks/editor/indent-settings.ts +88 -0
  91. package/src/client/hooks/editor/quick-open.test.ts +141 -0
  92. package/src/client/hooks/editor/quick-open.ts +127 -0
  93. package/src/client/hooks/editor/save-as.test.ts +156 -0
  94. package/src/client/hooks/editor/save-as.ts +122 -0
  95. package/src/client/hooks/editor/save-file.test.ts +179 -0
  96. package/src/client/hooks/editor/save-file.ts +73 -28
  97. package/src/client/hooks/editor/typing-settings.test.ts +73 -0
  98. package/src/client/hooks/editor/typing-settings.ts +65 -0
  99. package/src/client/hooks/editor/use-close-guard.ts +98 -0
  100. package/src/client/hooks/editor/use-editor-drop-overlay.test.ts +159 -0
  101. package/src/client/hooks/editor/use-editor-drop.shell.test.ts +224 -0
  102. package/src/client/hooks/editor/use-editor-drop.ts +58 -68
  103. package/src/client/hooks/editor/use-editor-find.test.ts +2 -2
  104. package/src/client/hooks/editor/use-editor-find.ts +38 -3
  105. package/src/client/hooks/editor/use-editor-panel-keys.ts +152 -0
  106. package/src/client/hooks/editor/use-editor-tab-state.ts +71 -0
  107. package/src/client/hooks/editor/use-external-change-notice.ts +71 -0
  108. package/src/client/hooks/editor/use-external-change.test.ts +88 -0
  109. package/src/client/hooks/editor/use-external-change.ts +146 -0
  110. package/src/client/hooks/editor/use-file-editor.ts +83 -116
  111. package/src/client/hooks/editor/use-file-read.ts +16 -8
  112. package/src/client/hooks/editor/use-file-writes.ts +28 -3
  113. package/src/client/hooks/editor/use-mobile-editor-find.ts +69 -0
  114. package/src/client/hooks/editor/use-mobile-reveal.ts +53 -0
  115. package/src/client/hooks/editor/use-search-reveal-jump.ts +57 -0
  116. package/src/client/hooks/editor/use-split-editor.test.tsx +169 -0
  117. package/src/client/hooks/editor/use-split-editor.ts +91 -0
  118. package/src/client/hooks/editor/use-unload-guard.tsx +117 -0
  119. package/src/client/hooks/editor/use-write-conflict.test.ts +164 -0
  120. package/src/client/hooks/editor/use-write-conflict.ts +152 -0
  121. package/src/client/hooks/editor/wheel-zoom.test.ts +141 -0
  122. package/src/client/hooks/editor/wheel-zoom.ts +96 -0
  123. package/src/client/hooks/ui/drag-presence.test.ts +193 -0
  124. package/src/client/hooks/ui/drag-presence.ts +108 -0
  125. package/src/client/hooks/ui/settings-modal.test.ts +115 -0
  126. package/src/client/hooks/workspace/file-listing.ts +36 -24
  127. package/src/client/hooks/workspace/file-tabs.test.ts +90 -0
  128. package/src/client/hooks/workspace/file-tabs.ts +46 -0
  129. package/src/client/hooks/workspace/file-tree-edits.ts +103 -0
  130. package/src/client/lib/desktop/dropped-paths.ts +83 -0
  131. package/src/client/lib/editor/tab-menu.test.ts +127 -0
  132. package/src/client/lib/editor/tab-menu.ts +127 -0
  133. package/src/client/lib/editor-dirty-tabs.test.ts +102 -0
  134. package/src/client/lib/editor-dirty-tabs.ts +103 -0
  135. package/src/client/lib/native/resume.test.ts +66 -0
  136. package/src/client/lib/native/resume.ts +42 -0
  137. package/src/client/main.tsx +8 -0
  138. package/src/client/tailwind.css +38 -0
  139. package/src/server/lib/bundler/css.test.ts +31 -0
  140. package/src/server/lib/fs/listing.test.ts +81 -16
  141. package/src/server/lib/fs/listing.ts +72 -5
  142. package/src/server/lib/fs/write-conflict.test.ts +68 -0
  143. package/src/server/lib/fs/write-conflict.ts +84 -0
  144. package/src/server/routes/fs/action-save-as.test.ts +82 -0
  145. package/src/server/routes/fs/action.test.ts +82 -0
  146. package/src/server/routes/fs/action.ts +54 -1
  147. package/src/server/routes/fs/exists.ts +11 -1
  148. package/src/server/routes/fs/read.ts +6 -1
  149. package/src/shared/lib/code/editor/find-replace.test.ts +1 -1
  150. package/src/shared/lib/code/editor/find-scan.test.ts +1 -1
  151. package/src/shared/lib/code/editor/find-scan.ts +22 -1
  152. package/src/shared/lib/code/editor/find-selection.test.ts +56 -0
  153. package/src/shared/lib/code/editor/indent-guide-rule.test.ts +65 -0
  154. package/src/shared/lib/code/editor/indent-guide-rule.ts +47 -0
  155. package/src/shared/lib/code/editor/indent-rules.test.ts +219 -0
  156. package/src/shared/lib/code/editor/indent-rules.ts +198 -0
  157. package/src/shared/lib/code/editor/keymap.test.ts +23 -0
  158. package/src/shared/lib/code/editor/keymap.ts +40 -3
  159. package/src/shared/lib/code/editor/palette.test.ts +25 -2
  160. package/src/shared/lib/code/editor/palette.ts +10 -0
  161. package/src/shared/lib/code/editor/stream-modes.ts +225 -0
  162. package/src/shared/lib/code/syntax-highlight.test.ts +1 -1
  163. package/src/shared/lib/fs/file-tree.test.ts +41 -0
  164. package/src/shared/lib/fs/file-tree.ts +126 -34
  165. package/src/shared/lib/fs/folder-chain.test.ts +87 -0
  166. package/src/shared/lib/fs/folder-chain.ts +91 -0
  167. package/src/shared/lib/fs/fs-helpers.test.ts +4 -50
  168. package/src/shared/lib/realtime/connection.test.ts +5 -1
  169. package/src/shared/lib/realtime/connection.ts +25 -119
  170. package/src/shared/lib/realtime/frozen-recovery.test.ts +93 -0
  171. package/src/shared/lib/realtime/resume.ts +223 -0
  172. package/src/shared/lib/realtime/state.ts +22 -0
  173. package/src/shared/lib/realtime/watchdog-wiring.test.ts +224 -0
  174. package/src/shared/lib/realtime/watchdog.test.ts +99 -0
  175. package/src/shared/lib/realtime/watchdog.ts +72 -0
  176. package/src/shared/lib/workspace/split-editor.test.ts +104 -0
  177. package/src/shared/lib/workspace/split-editor.ts +129 -0
  178. package/src/test-support/file-explorer-disk.test-util.ts +30 -3
  179. package/src/test-support/pristine-globals.ts +7 -0
  180. package/dist/client/static/js/index-k315p1e8.css +0 -1
@@ -39,9 +39,8 @@
39
39
  */
40
40
 
41
41
  import { realtimeSocketUrl } from '@/shared/lib/realtime/protocol';
42
+ import { createResumeWatch } from '@/shared/lib/realtime/resume';
42
43
  import {
43
- WS_CONNECTING,
44
- WS_OPEN,
45
44
  deliverFrame,
46
45
  liveTopics,
47
46
  notifyClosed,
@@ -63,12 +62,17 @@ const MAX_FAILED_DIALS = 4;
63
62
  const SLOW_RETRY_MS = 30_000;
64
63
  /** How long a dial may sit in CONNECTING before it is abandoned and retried. */
65
64
  const CONNECT_TIMEOUT_MS = 10_000;
65
+
66
66
  /**
67
- * How long a socket that LOOKS open has to answer a resume probe. A frozen tab
68
- * keeps `readyState === OPEN` for a connection the server already tore down, so
69
- * the only trustworthy answer is the server's own pong.
67
+ * Resume, watchdog and liveness probe live in `resume.ts`: they are the
68
+ * mechanism that repairs a connection the browser never reported dead, and they
69
+ * need `dial` — which this module owns — so the dependency is injected rather
70
+ * than imported back.
70
71
  */
71
- const WAKE_PROBE_MS = 2_000;
72
+ const resumeWatch = createResumeWatch(() => dial());
73
+
74
+ /** The tab (or the app, or the radio) is back. See `resume.ts`. */
75
+ export const wake = resumeWatch.wake;
72
76
 
73
77
  /**
74
78
  * The server answered a resume probe: the socket really is alive. Called from
@@ -81,6 +85,7 @@ export function notePong(id: number): void {
81
85
  host.probeId = undefined;
82
86
  clearTimeout(host.probeTimer);
83
87
  host.probeTimer = undefined;
88
+ host.lastInboundAt = Date.now();
84
89
  }
85
90
 
86
91
  function scheduleReconnect(): void {
@@ -97,111 +102,6 @@ function scheduleReconnect(): void {
97
102
  dial();
98
103
  }, delay);
99
104
  }
100
-
101
- /**
102
- * Ask a socket that LOOKS open whether it still is.
103
- *
104
- * A frozen tab keeps `readyState === OPEN` for a connection the server's
105
- * heartbeat already tore down, and no `close` is delivered until the browser
106
- * notices. Without this probe the resume path would trust a corpse and the
107
- * indicator would stay green over a stream that never resumes.
108
- */
109
- function probeLiveness(socket: WebSocket): void {
110
- const host = state();
111
- if (host.probeId !== undefined) return;
112
- const id = (host.probeSeq += 1);
113
- host.probeId = id;
114
- const abandon = (): void => {
115
- // A late answer from a socket that has since been replaced must not close
116
- // the live one: the deadline is only ever about THIS socket.
117
- if (host.probeId !== id) return;
118
- host.probeId = undefined;
119
- host.probeTimer = undefined;
120
- if (host.socket !== socket) return;
121
- try {
122
- socket.close();
123
- } catch {
124
- // Already gone.
125
- }
126
- };
127
- host.probeTimer = window.setTimeout(abandon, WAKE_PROBE_MS);
128
- if (!send({ t: 'ping', id })) abandon();
129
- }
130
-
131
- /**
132
- * The tab is back: a background freeze stopped our timers and the server's
133
- * heartbeat dropped the socket, so the failure count describes a window in
134
- * which nothing could run. Reset it and dial now if the socket is gone.
135
- *
136
- * Fires from `visibilitychange`, `pageshow` (bfcache) and `online` (the radio
137
- * can come back before the page is visible again). `online` also covers a
138
- * network that dropped without the tab ever hiding.
139
- */
140
- function wake(): void {
141
- const host = state();
142
- if (!host.wanted) return;
143
- host.failures = 0;
144
- const socket = host.socket;
145
- if (socket && socket.readyState === WS_CONNECTING) return;
146
- if (socket && socket.readyState === WS_OPEN) {
147
- probeLiveness(socket);
148
- return;
149
- }
150
- if (host.retryTimer !== undefined) {
151
- clearTimeout(host.retryTimer);
152
- host.retryTimer = undefined;
153
- }
154
- if (socket) {
155
- // Nulled FIRST: `close()` delivers `onclose` synchronously in some engines,
156
- // and that handler owns the retry decision for a socket it still believes
157
- // in. This socket is being abandoned on purpose, so its late close must
158
- // report nothing.
159
- host.socket = null;
160
- try {
161
- socket.close();
162
- } catch {
163
- // Already gone.
164
- }
165
- // The server tore this connection down while the tab was frozen, so every
166
- // value on screen is of unknown age even though no `close` arrived.
167
- notifyClosed();
168
- }
169
- dial();
170
- }
171
-
172
- /**
173
- * Install the resume listeners once. A no-op outside a document.
174
- *
175
- * The cleanup closes over the `document`/`window` it REGISTERED on rather than
176
- * reading the globals again when it runs. Those are not necessarily the same
177
- * objects: a test suite replaces them per case and deletes them when it is
178
- * done, and `resetConnection` (the teardown seam) would then dereference an
179
- * absent `document` and throw — measured on CI, where a suite that reset the
180
- * client after its own `restoreDomGlobals` failed the NEXT file with
181
- * `ReferenceError: document is not defined`. In a browser the two are always
182
- * the same object, so this changes nothing there.
183
- */
184
- function ensureWakeListeners(): void {
185
- const host = state();
186
- if (host.wakeCleanup) return;
187
- if (typeof window === 'undefined' || typeof document === 'undefined') return;
188
- const doc = document;
189
- const win = window;
190
- const onVisible = (): void => {
191
- if (!doc.hidden) wake();
192
- };
193
- const onOnline = (): void => wake();
194
- const onPageShow = (): void => wake();
195
- doc.addEventListener('visibilitychange', onVisible);
196
- win.addEventListener('online', onOnline);
197
- win.addEventListener('pageshow', onPageShow);
198
- host.wakeCleanup = () => {
199
- doc.removeEventListener('visibilitychange', onVisible);
200
- win.removeEventListener('online', onOnline);
201
- win.removeEventListener('pageshow', onPageShow);
202
- };
203
- }
204
-
205
105
  function dial(): void {
206
106
  const host = state();
207
107
  // A retry scheduled before the last subscriber left must not open a socket
@@ -239,6 +139,9 @@ function dial(): void {
239
139
  opened = true;
240
140
  clearTimeout(connectTimer);
241
141
  host.failures = 0;
142
+ // The socket just proved it is alive; the idle clock starts here so the
143
+ // watchdog does not probe a connection opened a moment ago.
144
+ host.lastInboundAt = Date.now();
242
145
  if (host.probeId !== undefined) {
243
146
  host.probeId = undefined;
244
147
  clearTimeout(host.probeTimer);
@@ -252,7 +155,11 @@ function dial(): void {
252
155
  };
253
156
 
254
157
  socket.onmessage = (event) => {
255
- if (typeof event.data === 'string') deliverFrame(event.data);
158
+ if (typeof event.data !== 'string') return;
159
+ // The idle clock the watchdog reads: every inbound frame — a delta, a
160
+ // snapshot, a pong — proves the socket is alive.
161
+ host.lastInboundAt = Date.now();
162
+ deliverFrame(event.data);
256
163
  };
257
164
 
258
165
  socket.onclose = () => {
@@ -286,7 +193,8 @@ export function connectIfNeeded(): void {
286
193
  const host = state();
287
194
  setWanted(liveTopics().length > 0);
288
195
  if (!host.wanted) return;
289
- ensureWakeListeners();
196
+ resumeWatch.ensureListeners();
197
+ resumeWatch.start();
290
198
  if (host.socket) return;
291
199
  if (host.retryTimer !== undefined) return;
292
200
  dial();
@@ -295,12 +203,10 @@ export function connectIfNeeded(): void {
295
203
  /** Test seam: close the socket and forget the connection state. */
296
204
  export function resetConnection(): void {
297
205
  const host = state();
298
- // Nulled BEFORE the call: a cleanup that throws (a listener target that is
299
- // already gone) must not leave the slot set, or the next reset retries the
300
- // same throw and the state below is never cleared.
301
- const cleanup = host.wakeCleanup;
302
- host.wakeCleanup = null;
303
- cleanup?.();
206
+ // Removes the resume listeners AND stops the watchdog. The watch nulls its own
207
+ // slots before running the cleanup, so a throwing listener target cannot leave
208
+ // them set and make the next reset retry the same throw.
209
+ resumeWatch.stop();
304
210
  clearTimeout(host.retryTimer);
305
211
  clearTimeout(host.probeTimer);
306
212
  const socket = host.socket;
@@ -0,0 +1,93 @@
1
+ /**
2
+ * @license
3
+ * SPDX-License-Identifier: Apache-2.0
4
+ */
5
+
6
+ /**
7
+ * The reported Android failure, end to end against a REAL server.
8
+ *
9
+ * A backgrounded phone freezes the page: the server's 30s protocol heartbeat
10
+ * reaps the socket because a frozen tab cannot answer a ping, and the browser
11
+ * never learns — `readyState` still says OPEN and no `close` is delivered. The
12
+ * channel used to sit on that corpse until the user reloaded the page.
13
+ *
14
+ * What this suite adds over the unit ones: the client is driven through its
15
+ * PUBLIC surface against a real `WebSocket` and the real route, so the wiring is
16
+ * production's; and the repair is triggered by nothing but time — no
17
+ * `visibilitychange`, no `pageshow`, no `online`, no native shell hook.
18
+ * `watchdog.test.ts` pins the decision table and `connection.test.ts` the
19
+ * interval that drives it; this pins that the decision reaches a live socket,
20
+ * abandons it, re-dials and RESUBSCRIBES.
21
+ *
22
+ * The real-time dependency is deliberate and named: the watchdog ticks on the
23
+ * platform clock, and faking that clock would fake the thing under test. Nothing
24
+ * here waits for a duration — the assertion is a topic value that can only
25
+ * arrive through the new socket's subscription.
26
+ */
27
+
28
+ import { afterEach, describe, expect, test } from 'bun:test';
29
+ import { Window } from 'happy-dom';
30
+
31
+ import { realtimeClient, resetRealtimeClient } from '@/shared/lib/realtime/client';
32
+ import { state } from '@/shared/lib/realtime/state';
33
+ import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
34
+ import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support/realtime-server';
35
+
36
+ let server: RealtimeTestServer | undefined;
37
+
38
+ afterEach(() => {
39
+ server?.stop();
40
+ server = undefined;
41
+ // The channel is PROCESS state, and this file is the one that dials a REAL
42
+ // socket. `restoreDomGlobals` only puts the runner's globals back; the live
43
+ // socket, its retry timer and the wanted flag survive into the next file,
44
+ // where `dial()` then early-returns on the socket it still holds and the next
45
+ // suite's constructor override never produces an instance. Measured on
46
+ // `Gates / Checks (Windows)`: `watchdog-wiring.test.ts` failed with
47
+ // `undefined is not an object (evaluating 'socket.open')` while passing when
48
+ // run alone.
49
+ resetRealtimeClient();
50
+ restoreDomGlobals();
51
+ });
52
+
53
+ describe('a frozen page with a socket the server already reaped', () => {
54
+ test('the watchdog re-dials and resubscribes with no event and no reload', async () => {
55
+ let value = 1;
56
+ server = await startRealtimeTestServer(new Map([['probe:topic', async () => value]]));
57
+ // The dial path builds its URL from `window.location` and uses its timers, so
58
+ // the window has to exist — and it has to name the listener's own port, or
59
+ // the socket dials a port nothing serves. `installDomGlobals` also swaps in
60
+ // the runner's own `WebSocket`, which is what makes the socket REAL.
61
+ installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
62
+
63
+ const unsubscribe = realtimeClient.subscribe('probe:topic', () => {});
64
+ try {
65
+ await server.waitForTopic<number>('probe:topic', (current) => current !== null, 5_000);
66
+ expect(realtimeClient.status()).toBe('open');
67
+ const reaped = state().socket!;
68
+
69
+ // The freeze, written as the state a frozen page leaves behind rather than
70
+ // by advancing a clock: an open-looking socket, silence older than the idle
71
+ // window, and a connection the server no longer answers on. `send` throwing
72
+ // is what a reaped socket does — the probe cannot be delivered, which is how
73
+ // the client discovers it is dead.
74
+ state().lastInboundAt = Date.now() - 60_000;
75
+ reaped.send = () => {
76
+ throw new Error('socket was reaped while the page was frozen');
77
+ };
78
+
79
+ // The NEW value can only reach this client through the replacement socket's
80
+ // subscription: the server answers every subscribe with a fresh snapshot,
81
+ // and nothing is buffered for a dead one. So this one assertion covers the
82
+ // whole chain — the probe failing, the socket being abandoned, the re-dial,
83
+ // and the live topic set being resubscribed.
84
+ value = 42;
85
+ const recovered = await server.waitForTopic<number>('probe:topic', (current) => current === 42, 25_000);
86
+ expect(recovered).toBe(42);
87
+ expect(realtimeClient.status()).toBe('open');
88
+ expect(state().socket).not.toBe(reaped);
89
+ } finally {
90
+ unsubscribe();
91
+ }
92
+ }, 40_000);
93
+ });
@@ -0,0 +1,223 @@
1
+ /**
2
+ * @license
3
+ * SPDX-License-Identifier: Apache-2.0
4
+ */
5
+
6
+ /**
7
+ * Resume: the half of the channel's lifecycle that repairs a connection the
8
+ * browser never told us was gone.
9
+ *
10
+ * Split from `connection.ts` (which owns dial, backoff and teardown) because a
11
+ * phone broke the event-based half, and the two are now genuinely different
12
+ * mechanisms. `connection.ts` reacts to events the PLATFORM delivers; this
13
+ * module reacts to ones it does not.
14
+ *
15
+ * ## Why events alone are not enough
16
+ *
17
+ * A backgrounded Android tab is frozen: timers stop, and the server's 30s
18
+ * protocol heartbeat tears the socket down because a frozen tab cannot answer a
19
+ * ping. The repair used to depend on `visibilitychange`, `pageshow` or `online`.
20
+ * Measured on the shipped Android shell, none of them reliably arrives: the
21
+ * WebView is never reported hidden when the app goes to the background, so
22
+ * returning to it fires no `visibilitychange`, and a socket the server reaped
23
+ * while the page was frozen produces no `close` — the browser still reports
24
+ * `readyState === OPEN`. The channel therefore sat on a corpse: status `open`,
25
+ * no frames, the stream frozen mid-answer, and only a page reload repaired it.
26
+ *
27
+ * ## The watchdog
28
+ *
29
+ * A running interval is the one signal a frozen page cannot fake, because a
30
+ * frozen page stops running it:
31
+ *
32
+ * - a tick that arrives much later than its deadline means the page was
33
+ * suspended, which is exactly the moment a resume has to be treated like one;
34
+ * - an OPEN socket with no inbound traffic for `IDLE_PROBE_AFTER_MS` is probed
35
+ * even when nothing woke the page, which catches a connection that died while
36
+ * the tab stayed visible (a Wi-Fi to cellular handoff).
37
+ *
38
+ * Both branches are idempotent: a probe already in flight is left alone, and
39
+ * `wake()` is a no-op on a healthy connection.
40
+ */
41
+
42
+ import {
43
+ WS_CONNECTING,
44
+ WS_OPEN,
45
+ notifyClosed,
46
+ send,
47
+ state,
48
+ } from '@/shared/lib/realtime/state';
49
+ import {
50
+ LIVENESS_TICK_MS,
51
+ watchdogAction,
52
+ } from '@/shared/lib/realtime/watchdog';
53
+
54
+ /**
55
+ * How long a socket that LOOKS open has to answer a resume probe. A frozen tab
56
+ * keeps `readyState === OPEN` for a connection the server already tore down, so
57
+ * the only trustworthy answer is the server's own pong.
58
+ */
59
+ const WAKE_PROBE_MS = 2_000;
60
+
61
+ /** Ask for a fresh socket. Injected by `connection.ts` so this module never
62
+ * imports the dial path back and the two stay acyclic. */
63
+ export type Dialer = () => void;
64
+
65
+ export interface ResumeWatch {
66
+ /** Install the tab-resume listeners once (a no-op outside a document). */
67
+ ensureListeners: () => void;
68
+ /** Start the watchdog. Idempotent. */
69
+ start: () => void;
70
+ /** Stop the watchdog and remove the listeners. */
71
+ stop: () => void;
72
+ /** Treat the page as back: reset the budget, probe or re-dial. */
73
+ wake: () => void;
74
+ }
75
+
76
+ /**
77
+ * Ask a socket that LOOKS open whether it still is.
78
+ *
79
+ * A frozen tab keeps `readyState === OPEN` for a connection the server's
80
+ * heartbeat already tore down, and no `close` is delivered until the browser
81
+ * notices. Without this probe the resume path would trust a corpse and the
82
+ * indicator would stay green over a stream that never resumes.
83
+ */
84
+ function probeLiveness(socket: WebSocket): void {
85
+ const host = state();
86
+ // A probe whose deadline passed while the page was frozen can never fire its
87
+ // own abandon: the timer was frozen with it. Discard it rather than letting it
88
+ // block every later probe — that is a socket that is never questioned and so
89
+ // never replaced.
90
+ if (host.probeId !== undefined && Date.now() - host.probeArmedAt > WAKE_PROBE_MS) {
91
+ host.probeId = undefined;
92
+ clearTimeout(host.probeTimer);
93
+ host.probeTimer = undefined;
94
+ }
95
+ if (host.probeId !== undefined) return;
96
+ const id = (host.probeSeq += 1);
97
+ host.probeId = id;
98
+ host.probeArmedAt = Date.now();
99
+ const abandon = (): void => {
100
+ // A late answer from a socket that has since been replaced must not close
101
+ // the live one: the deadline is only ever about THIS socket.
102
+ if (host.probeId !== id) return;
103
+ host.probeId = undefined;
104
+ host.probeTimer = undefined;
105
+ if (host.socket !== socket) return;
106
+ try {
107
+ socket.close();
108
+ } catch {
109
+ // Already gone.
110
+ }
111
+ };
112
+ host.probeTimer = window.setTimeout(abandon, WAKE_PROBE_MS);
113
+ if (!send({ t: 'ping', id })) abandon();
114
+ }
115
+
116
+ export function createResumeWatch(dial: Dialer): ResumeWatch {
117
+ /**
118
+ * The tab is back: a background freeze stopped our timers and the server's
119
+ * heartbeat dropped the socket, so the failure count describes a window in
120
+ * which nothing could run. Reset it and dial now if the socket is gone.
121
+ */
122
+ const wake = (): void => {
123
+ const host = state();
124
+ if (!host.wanted) return;
125
+ host.failures = 0;
126
+ const socket = host.socket;
127
+ if (socket && socket.readyState === WS_CONNECTING) return;
128
+ if (socket && socket.readyState === WS_OPEN) {
129
+ probeLiveness(socket);
130
+ return;
131
+ }
132
+ if (host.retryTimer !== undefined) {
133
+ clearTimeout(host.retryTimer);
134
+ host.retryTimer = undefined;
135
+ }
136
+ if (socket) {
137
+ // Nulled FIRST: `close()` delivers `onclose` synchronously in some
138
+ // engines, and that handler owns the retry decision for a socket it still
139
+ // believes in. This socket is being abandoned on purpose, so its late
140
+ // close must report nothing.
141
+ host.socket = null;
142
+ try {
143
+ socket.close();
144
+ } catch {
145
+ // Already gone.
146
+ }
147
+ // The server tore this connection down while the tab was frozen, so every
148
+ // value on screen is of unknown age even though no `close` arrived.
149
+ notifyClosed();
150
+ }
151
+ dial();
152
+ };
153
+
154
+ /**
155
+ * Install the resume listeners once. A no-op outside a document.
156
+ *
157
+ * The cleanup closes over the `document`/`window` it REGISTERED on rather than
158
+ * reading the globals again when it runs. Those are not necessarily the same
159
+ * objects: a test suite replaces them per case and deletes them when it is
160
+ * done, and the teardown would then dereference an absent `document` and throw
161
+ * — measured on CI, where a suite that reset the client after its own
162
+ * `restoreDomGlobals` failed the NEXT file with `ReferenceError: document is
163
+ * not defined`. In a browser the two are always the same object.
164
+ */
165
+ const ensureListeners = (): void => {
166
+ const host = state();
167
+ if (host.wakeCleanup) return;
168
+ if (typeof window === 'undefined' || typeof document === 'undefined') return;
169
+ const doc = document;
170
+ const win = window;
171
+ const onVisible = (): void => {
172
+ if (!doc.hidden) wake();
173
+ };
174
+ const onOnline = (): void => wake();
175
+ const onPageShow = (): void => wake();
176
+ doc.addEventListener('visibilitychange', onVisible);
177
+ win.addEventListener('online', onOnline);
178
+ win.addEventListener('pageshow', onPageShow);
179
+ host.wakeCleanup = () => {
180
+ doc.removeEventListener('visibilitychange', onVisible);
181
+ win.removeEventListener('online', onOnline);
182
+ win.removeEventListener('pageshow', onPageShow);
183
+ };
184
+ };
185
+
186
+ const start = (): void => {
187
+ const host = state();
188
+ if (host.livenessTimer !== undefined) return;
189
+ if (typeof window === 'undefined') return;
190
+ let lastTick = Date.now();
191
+ host.livenessTimer = window.setInterval(() => {
192
+ const now = Date.now();
193
+ const sinceTick = now - lastTick;
194
+ lastTick = now;
195
+ const socket = host.socket;
196
+ const action = watchdogAction({
197
+ sinceTick,
198
+ sinceInbound: now - host.lastInboundAt,
199
+ hidden: document.hidden,
200
+ open: socket?.readyState === WS_OPEN,
201
+ wanted: host.wanted,
202
+ });
203
+ if (action === 'wake') wake();
204
+ else if (action === 'probe' && socket) probeLiveness(socket);
205
+ }, LIVENESS_TICK_MS);
206
+ };
207
+
208
+ const stop = (): void => {
209
+ const host = state();
210
+ // Nulled BEFORE the call: a cleanup that throws (a listener target that is
211
+ // already gone) must not leave the slot set, or the next stop retries the
212
+ // same throw.
213
+ const cleanup = host.wakeCleanup;
214
+ host.wakeCleanup = null;
215
+ cleanup?.();
216
+ if (host.livenessTimer !== undefined) {
217
+ clearInterval(host.livenessTimer);
218
+ host.livenessTimer = undefined;
219
+ }
220
+ };
221
+
222
+ return { ensureListeners, start, stop, wake };
223
+ }
@@ -69,6 +69,25 @@ export interface ConnectionState {
69
69
  probeId: number | undefined;
70
70
  probeTimer: number | undefined;
71
71
  probeSeq: number;
72
+ /**
73
+ * When the armed probe was sent.
74
+ *
75
+ * A probe armed before the page was frozen keeps its deadline timer frozen
76
+ * with it, so `probeId` stays set forever and every later probe would return
77
+ * early — the socket is then never abandoned and nothing ever re-dials. The
78
+ * timestamp is what lets a probe that outlived its own deadline be discarded.
79
+ */
80
+ probeArmedAt: number;
81
+ /**
82
+ * When the last frame (or probe answer) arrived on the current socket.
83
+ *
84
+ * The watchdog compares this against `IDLE_PROBE_AFTER_MS` to decide whether
85
+ * an OPEN socket has gone quiet — which is the ONLY signal available when the
86
+ * browser never delivers a `close` (see `connection.ts`).
87
+ */
88
+ lastInboundAt: number;
89
+ /** The watchdog interval. `undefined` until the first subscription. */
90
+ livenessTimer: number | undefined;
72
91
  }
73
92
 
74
93
  /**
@@ -101,6 +120,9 @@ export function state(): ConnectionState {
101
120
  probeId: undefined,
102
121
  probeTimer: undefined,
103
122
  probeSeq: 0,
123
+ probeArmedAt: 0,
124
+ lastInboundAt: 0,
125
+ livenessTimer: undefined,
104
126
  });
105
127
  }
106
128