@firstpick/pi-package-webui 0.9.5 → 0.9.6

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 (61) hide show
  1. package/README.md +5 -3
  2. package/bin/pi-webui.mjs +90 -5
  3. package/lib/optional-feature-catalog.mjs +1 -1
  4. package/lib/session-actions.mjs +20 -2
  5. package/package.json +1 -1
  6. package/public/app.js +1823 -262
  7. package/public/index.html +51 -31
  8. package/public/service-worker.js +4 -1
  9. package/public/stream-derived-output.mjs +799 -0
  10. package/public/stream-markdown-tail.mjs +204 -0
  11. package/public/stream-output-controller.mjs +193 -51
  12. package/public/stream-render-scheduler.mjs +85 -0
  13. package/public/styles.css +249 -18
  14. package/public/transcript-renderer.mjs +73 -24
  15. package/tests/boot-failure-diagnostics.test.mjs +3 -3
  16. package/tests/browser/composer-action-grid-reorder.spec.mjs +114 -31
  17. package/tests/browser/mobile-foundation.spec.mjs +28 -0
  18. package/tests/browser/stream-output-isolation.spec.mjs +308 -3
  19. package/tests/browser/user-noticeable-fixes.spec.mjs +204 -0
  20. package/tests/codex-fast-mode-static.test.mjs +2 -2
  21. package/tests/composer-action-grid-reorder-static.test.mjs +8 -7
  22. package/tests/control-visibility-static.test.mjs +3 -3
  23. package/tests/controls-layout-static.test.mjs +3 -3
  24. package/tests/cwd-footer-reliability-static.test.mjs +1 -1
  25. package/tests/fast-mode-client-static.test.mjs +1 -1
  26. package/tests/feature-decision-output-popup-static.test.mjs +2 -2
  27. package/tests/file-viewer-image-static.test.mjs +3 -3
  28. package/tests/fixtures/fake-pi.mjs +57 -10
  29. package/tests/fixtures/streaming-workloads.mjs +36 -0
  30. package/tests/footer-provider-usage-visual-static.test.mjs +15 -0
  31. package/tests/foreground-transcript-catch-up-static.test.mjs +7 -1
  32. package/tests/interaction-state-stability-static.test.mjs +3 -1
  33. package/tests/intercom-conversation-viewer-static.test.mjs +3 -3
  34. package/tests/intercom-conversations-http.test.mjs +16 -0
  35. package/tests/main-output-loading-static.test.mjs +3 -3
  36. package/tests/middle-button-drag-scroll-static.test.mjs +3 -3
  37. package/tests/mobile-continuity-tablet-static.test.mjs +3 -3
  38. package/tests/mobile-foundation-static.test.mjs +3 -3
  39. package/tests/mobile-phone-experience-static.test.mjs +1 -1
  40. package/tests/mobile-static.test.mjs +74 -63
  41. package/tests/open-issue-wizard-static.test.mjs +1 -1
  42. package/tests/persistent-ui-layout-static.test.mjs +4 -4
  43. package/tests/prompt-input-vertical-scroll-static.test.mjs +26 -0
  44. package/tests/questionnaire-dialog.test.mjs +3 -3
  45. package/tests/runtime-error-visibility.test.mjs +3 -3
  46. package/tests/session-auth-harness.test.mjs +26 -1
  47. package/tests/session-sampling-ui-static.test.mjs +3 -3
  48. package/tests/side-panel-section-height-removal-static.test.mjs +3 -3
  49. package/tests/stream-derived-output.test.mjs +121 -0
  50. package/tests/stream-markdown-tail.test.mjs +218 -0
  51. package/tests/stream-output-controller.test.mjs +119 -4
  52. package/tests/stream-output-isolation-static.test.mjs +27 -6
  53. package/tests/stream-output-workloads.test.mjs +40 -3
  54. package/tests/stream-render-scheduler.test.mjs +115 -0
  55. package/tests/streaming-ui-coupling.test.mjs +1 -1
  56. package/tests/subagent-observability-static.test.mjs +2 -2
  57. package/tests/syntax-highlighting-static.test.mjs +3 -3
  58. package/tests/theme-customizer-static.test.mjs +1 -1
  59. package/tests/thinking-format-parser.test.mjs +15 -0
  60. package/tests/todo-filter-static.test.mjs +148 -0
  61. package/tests/transcript-markdown-tail.test.mjs +137 -0
@@ -0,0 +1,204 @@
1
+ export const STREAMING_MARKDOWN_PLAIN_TAIL_LIMIT = 16 * 1024;
2
+
3
+ const LINE_LEADING = "leading";
4
+ const LINE_TICKS = "ticks";
5
+ const LINE_AFTER_TICKS = "after-ticks";
6
+ const LINE_LANGUAGE = "language";
7
+ const LINE_TRAILING = "trailing";
8
+ const LINE_INVALID = "invalid";
9
+
10
+ function initialLineState() {
11
+ return {
12
+ lineBlank: true,
13
+ lineStage: LINE_LEADING,
14
+ lineTicks: 0,
15
+ lineLanguage: "",
16
+ };
17
+ }
18
+
19
+ function initialState() {
20
+ return {
21
+ value: "",
22
+ scanOffset: 0,
23
+ boundary: 0,
24
+ inFence: false,
25
+ fenceContentOffset: -1,
26
+ fenceLanguage: "",
27
+ fenceTicks: 0,
28
+ scannedChars: 0,
29
+ fallback: false,
30
+ ...initialLineState(),
31
+ };
32
+ }
33
+
34
+ function isLineWhitespace(character) {
35
+ return character !== "\n" && /\s/.test(character);
36
+ }
37
+
38
+ function isFenceLanguageCharacter(character) {
39
+ return /[A-Za-z0-9_.+-]/.test(character);
40
+ }
41
+
42
+ function invalidateLineFence(state) {
43
+ state.lineStage = LINE_INVALID;
44
+ state.lineLanguage = "";
45
+ }
46
+
47
+ function advanceOpeningFenceCandidate(state, character) {
48
+ if (isLineWhitespace(character)) {
49
+ if (state.lineStage === LINE_LANGUAGE) state.lineStage = LINE_TRAILING;
50
+ else if (state.lineStage !== LINE_TRAILING) state.lineStage = LINE_AFTER_TICKS;
51
+ return;
52
+ }
53
+ if (isFenceLanguageCharacter(character) && state.lineStage !== LINE_TRAILING) {
54
+ state.lineStage = LINE_LANGUAGE;
55
+ state.lineLanguage += character;
56
+ return;
57
+ }
58
+ invalidateLineFence(state);
59
+ }
60
+
61
+ function advanceLineCharacter(state, character) {
62
+ // An invalid delimiter candidate necessarily already contains a non-space;
63
+ // later code/paragraph characters need only advance the outer scan cursor.
64
+ if (state.lineStage === LINE_INVALID) return;
65
+ const whitespace = isLineWhitespace(character);
66
+ if (!whitespace) state.lineBlank = false;
67
+
68
+ if (state.lineStage === LINE_LEADING) {
69
+ if (whitespace) return;
70
+ if (character === "`") {
71
+ state.lineStage = LINE_TICKS;
72
+ state.lineTicks = 1;
73
+ return;
74
+ }
75
+ invalidateLineFence(state);
76
+ return;
77
+ }
78
+
79
+ if (state.lineStage === LINE_TICKS) {
80
+ // CommonMark fences are three OR MORE backticks (```` ````md ```` wraps nested ``` blocks).
81
+ if (character === "`") {
82
+ state.lineTicks += 1;
83
+ return;
84
+ }
85
+ if (state.lineTicks < 3) {
86
+ invalidateLineFence(state);
87
+ return;
88
+ }
89
+ state.lineStage = LINE_AFTER_TICKS;
90
+ }
91
+
92
+ if (state.inFence) {
93
+ if (!whitespace) invalidateLineFence(state);
94
+ return;
95
+ }
96
+ advanceOpeningFenceCandidate(state, character);
97
+ }
98
+
99
+ function lineIsFenceDelimiter(state) {
100
+ if (state.lineTicks < 3 || state.lineStage === LINE_INVALID) return false;
101
+ // A closing fence needs at least as many backticks as the opening one.
102
+ if (state.inFence) return state.lineTicks >= (state.fenceTicks || 3) && (state.lineStage === LINE_TICKS || state.lineStage === LINE_AFTER_TICKS);
103
+ return [LINE_TICKS, LINE_AFTER_TICKS, LINE_LANGUAGE, LINE_TRAILING].includes(state.lineStage);
104
+ }
105
+
106
+ function finishLine(state, nextOffset) {
107
+ const fenceDelimiter = lineIsFenceDelimiter(state);
108
+ const blank = state.lineBlank;
109
+ if (state.inFence) {
110
+ if (fenceDelimiter) {
111
+ state.inFence = false;
112
+ state.fenceContentOffset = -1;
113
+ state.fenceLanguage = "";
114
+ state.fenceTicks = 0;
115
+ // A closed fence is an independently stable block. Committing it here
116
+ // prevents later prose from causing the completed code to tokenize again.
117
+ state.boundary = nextOffset;
118
+ }
119
+ } else if (fenceDelimiter) {
120
+ state.inFence = true;
121
+ state.fenceContentOffset = nextOffset;
122
+ state.fenceLanguage = state.lineLanguage;
123
+ state.fenceTicks = state.lineTicks;
124
+ }
125
+ if (!state.inFence && blank) state.boundary = nextOffset;
126
+ Object.assign(state, initialLineState());
127
+ }
128
+
129
+ function scanSuffix(state, value, start) {
130
+ for (let offset = start; offset < value.length; offset += 1) {
131
+ const character = value[offset];
132
+ state.scannedChars += 1;
133
+ if (character === "\n") finishLine(state, offset + 1);
134
+ else advanceLineCharacter(state, character);
135
+ }
136
+ state.scanOffset = value.length;
137
+ }
138
+
139
+ /**
140
+ * Advances streaming Markdown boundary state from only a caller-confirmed
141
+ * appended suffix. A non-append snapshot deliberately rebuilds from the full
142
+ * authoritative value and reports that fallback through `fallback`.
143
+ */
144
+ export function advanceStreamingMarkdownTail(previous, text, { complete = false, appendOnly = false, plainTailLimit = STREAMING_MARKDOWN_PLAIN_TAIL_LIMIT } = {}) {
145
+ const value = String(text || "");
146
+ const incremental = !!previous && appendOnly && value.length >= previous.value.length;
147
+ const state = incremental ? { ...previous } : initialState();
148
+ const start = incremental ? previous.value.length : 0;
149
+ state.scannedChars = 0;
150
+ state.fallback = !!previous && !incremental;
151
+ scanSuffix(state, value, start);
152
+ state.value = value;
153
+
154
+ if (complete) {
155
+ return {
156
+ boundary: value.length,
157
+ state,
158
+ scannedChars: state.scannedChars,
159
+ fallback: state.fallback,
160
+ tailKind: "complete",
161
+ liveMode: "authoritative",
162
+ fenceContentOffset: -1,
163
+ fenceLanguage: "",
164
+ };
165
+ }
166
+
167
+ const pendingFence = lineIsFenceDelimiter(state);
168
+ const pendingClose = state.inFence && pendingFence;
169
+ const pendingOpening = !state.inFence && pendingFence;
170
+ const tailLength = value.length - state.boundary;
171
+ let liveMode = "markdown";
172
+ let tailKind = "text";
173
+ let fenceContentOffset = state.fenceContentOffset;
174
+ let fenceLanguage = state.fenceLanguage;
175
+
176
+ if (pendingClose) {
177
+ // The existing parser already recognizes this delimiter as a close even
178
+ // before a trailing newline arrives, so render the tail authoritatively once.
179
+ liveMode = "authoritative";
180
+ tailKind = "closed-fence";
181
+ } else if (state.inFence) {
182
+ liveMode = "open-fence";
183
+ tailKind = "open-fence";
184
+ } else if (pendingOpening) {
185
+ liveMode = "open-fence";
186
+ tailKind = "open-fence";
187
+ fenceContentOffset = value.length;
188
+ fenceLanguage = state.lineLanguage;
189
+ } else if (tailLength > Math.max(0, Number(plainTailLimit) || 0)) {
190
+ liveMode = "plain";
191
+ tailKind = "long-text";
192
+ }
193
+
194
+ return {
195
+ boundary: state.boundary,
196
+ state,
197
+ scannedChars: state.scannedChars,
198
+ fallback: state.fallback,
199
+ tailKind,
200
+ liveMode,
201
+ fenceContentOffset,
202
+ fenceLanguage,
203
+ };
204
+ }
@@ -13,6 +13,7 @@ const MESSAGE_UPDATE_KINDS = Object.freeze({
13
13
 
14
14
  const COALESCIBLE_DELTA_TYPES = new Set(["thinking_delta", "text_delta", "toolcall_delta"]);
15
15
  const DIAGNOSTIC_INDEX_LIMIT = 4096;
16
+ const URGENT_PRESSURE_ENTRY_LIMIT = 1;
16
17
  export const DEFAULT_STREAM_PENDING_ENTRY_LIMIT = 128;
17
18
  export const DEFAULT_STREAM_PENDING_BYTE_LIMIT = 256 * 1024;
18
19
 
@@ -63,20 +64,107 @@ function defaultCancelFrame(handle) {
63
64
  else globalThis.clearTimeout(handle);
64
65
  }
65
66
 
67
+ function defaultSchedulePressureDrain(callback) {
68
+ return globalThis.setTimeout(callback, 0);
69
+ }
70
+
71
+ function defaultCancelPressureDrain(handle) {
72
+ globalThis.clearTimeout(handle);
73
+ }
74
+
66
75
  function positiveLimit(value, fallback, name) {
67
76
  if (value === undefined) return fallback;
68
77
  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`${name} must be a positive safe integer`);
69
78
  return value;
70
79
  }
71
80
 
72
- function eventByteSize(event) {
81
+ function jsonStringCodeUnits(value) {
82
+ let units = 2;
83
+ for (let index = 0; index < value.length; index += 1) {
84
+ const code = value.charCodeAt(index);
85
+ if (code === 0x22 || code === 0x5c || code === 0x08 || code === 0x09 || code === 0x0a || code === 0x0c || code === 0x0d) {
86
+ units += 2;
87
+ } else if (code < 0x20) {
88
+ units += 6;
89
+ } else if (code >= 0xd800 && code <= 0xdbff) {
90
+ const next = value.charCodeAt(index + 1);
91
+ if (next >= 0xdc00 && next <= 0xdfff) {
92
+ units += 2;
93
+ index += 1;
94
+ } else {
95
+ units += 6;
96
+ }
97
+ } else if (code >= 0xdc00 && code <= 0xdfff) {
98
+ units += 6;
99
+ } else {
100
+ units += 1;
101
+ }
102
+ }
103
+ return units;
104
+ }
105
+
106
+ function plainJsonCodeUnits(value, ancestors = new Set()) {
107
+ if (value === null) return 4;
108
+ if (typeof value === "string") return jsonStringCodeUnits(value);
109
+ if (typeof value === "boolean") return value ? 4 : 5;
110
+ if (typeof value === "number") return Number.isFinite(value) ? String(value).length : 4;
111
+ if (typeof value !== "object") return null;
112
+ if (ancestors.has(value)) return null;
113
+ const prototype = Object.getPrototypeOf(value);
114
+ if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value)) return null;
115
+ if (typeof value.toJSON === "function") return null;
116
+ ancestors.add(value);
117
+ let units = 2;
118
+ let count = 0;
119
+ if (Array.isArray(value)) {
120
+ for (const item of value) {
121
+ const itemUnits = plainJsonCodeUnits(item, ancestors);
122
+ units += (count > 0 ? 1 : 0) + (itemUnits === null ? 4 : itemUnits);
123
+ count += 1;
124
+ }
125
+ } else {
126
+ for (const key of Object.keys(value)) {
127
+ const item = value[key];
128
+ if (["undefined", "function", "symbol"].includes(typeof item)) continue;
129
+ const itemUnits = plainJsonCodeUnits(item, ancestors);
130
+ if (itemUnits === null) {
131
+ ancestors.delete(value);
132
+ return null;
133
+ }
134
+ units += (count > 0 ? 1 : 0) + jsonStringCodeUnits(key) + 1 + itemUnits;
135
+ count += 1;
136
+ }
137
+ }
138
+ ancestors.delete(value);
139
+ return units;
140
+ }
141
+
142
+ function conservativeEventBytes(event) {
143
+ const codeUnits = plainJsonCodeUnits(event);
144
+ if (codeUnits !== null) return Math.max(1, codeUnits * 2);
73
145
  try {
74
- return Math.max(1, JSON.stringify(event).length * 2);
146
+ const serialized = JSON.stringify(event);
147
+ return typeof serialized === "string" ? Math.max(1, serialized.length * 2) : DEFAULT_STREAM_PENDING_BYTE_LIMIT;
75
148
  } catch {
76
149
  return DEFAULT_STREAM_PENDING_BYTE_LIMIT;
77
150
  }
78
151
  }
79
152
 
153
+ function eventByteAccounting(event, classification) {
154
+ const bytes = conservativeEventBytes(event);
155
+ const delta = event?.assistantMessageEvent?.delta;
156
+ if (!COALESCIBLE_DELTA_TYPES.has(classification?.subtype) || typeof delta !== "string") {
157
+ return { bytes, envelopeBytes: bytes, payloadBytes: 0, incrementalDelta: false };
158
+ }
159
+ const payloadBytes = Math.max(0, (jsonStringCodeUnits(delta) - 2) * 2);
160
+ return {
161
+ bytes,
162
+ envelopeBytes: Math.max(0, bytes - payloadBytes),
163
+ payloadBytes,
164
+ incrementalDelta: true,
165
+ };
166
+ }
167
+
80
168
  function eventDebugIndex(event) {
81
169
  const value = Number(event?.isolationDeltaIndex ?? event?.streamIsolationIndex);
82
170
  return Number.isSafeInteger(value) && value >= 0 ? value : null;
@@ -106,12 +194,9 @@ function mergedAdjacentEntry(previous, incoming) {
106
194
  const previousKey = entryCoalesceKey(previous);
107
195
  if (!previousKey || previousKey !== entryCoalesceKey(incoming)) return null;
108
196
  if (incoming.classification.kind === "tool-execution") {
109
- const event = incoming.event;
110
197
  return {
111
198
  ...incoming,
112
- event,
113
199
  receivedAt: previous.receivedAt !== undefined ? previous.receivedAt : incoming.receivedAt,
114
- bytes: eventByteSize(event),
115
200
  sourceCount: previous.sourceCount + incoming.sourceCount,
116
201
  sourceIndexes: [...previous.sourceIndexes, ...incoming.sourceIndexes].slice(-DIAGNOSTIC_INDEX_LIMIT),
117
202
  };
@@ -125,11 +210,13 @@ function mergedAdjacentEntry(previous, incoming) {
125
210
  delta: `${typeof previousUpdate.delta === "string" ? previousUpdate.delta : ""}${typeof incomingUpdate.delta === "string" ? incomingUpdate.delta : ""}`,
126
211
  },
127
212
  };
213
+ const payloadBytes = previous.payloadBytes + incoming.payloadBytes;
128
214
  return {
129
215
  ...incoming,
130
216
  event,
131
217
  receivedAt: previous.receivedAt !== undefined ? previous.receivedAt : incoming.receivedAt,
132
- bytes: eventByteSize(event),
218
+ bytes: incoming.envelopeBytes + payloadBytes,
219
+ payloadBytes,
133
220
  sourceCount: previous.sourceCount + incoming.sourceCount,
134
221
  sourceIndexes: [...previous.sourceIndexes, ...incoming.sourceIndexes].slice(-DIAGNOSTIC_INDEX_LIMIT),
135
222
  };
@@ -138,14 +225,15 @@ function mergedAdjacentEntry(previous, incoming) {
138
225
  /**
139
226
  * Owns the bounded frame queue for high-frequency transcript stream events.
140
227
  * Adjacent compatible deltas are losslessly coalesced while event-kind and
141
- * semantic barriers retain server order. Overflow synchronously drains the
142
- * current batch; a single oversize event is applied directly, never dropped.
143
- * Every injected sink is transcript-specific and the optional diagnostic hook
144
- * is inert unless explicitly supplied by a test/debug caller.
228
+ * semantic barriers retain server order. First pressure uses one explicitly
229
+ * bounded urgent entry and a near-term task; repeated pressure, barriers, and
230
+ * oversize events retain synchronous lossless fallback behavior.
145
231
  */
146
232
  export function createStreamOutputController({
147
233
  scheduleFrame = defaultScheduleFrame,
148
234
  cancelFrame = defaultCancelFrame,
235
+ schedulePressureDrain = defaultSchedulePressureDrain,
236
+ cancelPressureDrain = defaultCancelPressureDrain,
149
237
  now = defaultNow,
150
238
  isOwnerCurrent = () => true,
151
239
  applyTextUpdate = () => {},
@@ -164,6 +252,9 @@ export function createStreamOutputController({
164
252
  if (typeof scheduleFrame !== "function" || typeof cancelFrame !== "function") {
165
253
  throw new TypeError("scheduleFrame and cancelFrame must be functions");
166
254
  }
255
+ if (typeof schedulePressureDrain !== "function" || typeof cancelPressureDrain !== "function") {
256
+ throw new TypeError("schedulePressureDrain and cancelPressureDrain must be functions");
257
+ }
167
258
  if (typeof now !== "function") throw new TypeError("now must be a function");
168
259
  const entryLimit = positiveLimit(maxPendingEntries, DEFAULT_STREAM_PENDING_ENTRY_LIMIT, "maxPendingEntries");
169
260
  const byteLimit = positiveLimit(maxPendingBytes, DEFAULT_STREAM_PENDING_BYTE_LIMIT, "maxPendingBytes");
@@ -179,9 +270,13 @@ export function createStreamOutputController({
179
270
  : () => {};
180
271
 
181
272
  let frameHandle = null;
273
+ let pressureHandle = null;
182
274
  let pending = [];
183
275
  let pendingBytes = 0;
276
+ let urgentEntry = null;
184
277
 
278
+ const totalCount = () => pending.length + (urgentEntry ? 1 : 0);
279
+ const totalBytes = () => pendingBytes + (urgentEntry?.bytes || 0);
185
280
  const ownerIsCurrent = (owner) => owner === undefined || isOwnerCurrent(owner) === true;
186
281
 
187
282
  const reportStale = (event, owner, classification, phase) => {
@@ -228,14 +323,20 @@ export function createStreamOutputController({
228
323
  return applied;
229
324
  };
230
325
 
231
- const drain = () => {
326
+ const cancelScheduledDrains = () => {
327
+ if (frameHandle !== null) cancelFrame(frameHandle);
328
+ if (pressureHandle !== null) cancelPressureDrain(pressureHandle);
232
329
  frameHandle = null;
233
- if (!pending.length) return 0;
234
- const entries = pending;
330
+ pressureHandle = null;
331
+ };
332
+
333
+ const drain = () => {
334
+ cancelScheduledDrains();
335
+ if (!pending.length && !urgentEntry) return 0;
336
+ const entries = urgentEntry ? [...pending, urgentEntry] : pending;
235
337
  pending = [];
236
338
  pendingBytes = 0;
237
- // Latency/duration measurement only runs when a diagnostic hook is
238
- // installed so the disabled hot path never pays for clock reads.
339
+ urgentEntry = null;
239
340
  const drainStart = diagnosticsEnabled ? now() : 0;
240
341
  let applied = 0;
241
342
  for (const entry of entries) {
@@ -260,18 +361,23 @@ export function createStreamOutputController({
260
361
  };
261
362
 
262
363
  const schedule = () => {
263
- if (frameHandle !== null) return;
264
- frameHandle = scheduleFrame(drain);
364
+ if (frameHandle !== null || pressureHandle !== null) return;
365
+ frameHandle = scheduleFrame(() => {
366
+ frameHandle = null;
367
+ drain();
368
+ });
265
369
  };
266
370
 
267
- const flush = () => {
268
- if (frameHandle !== null) {
269
- cancelFrame(frameHandle);
270
- frameHandle = null;
271
- }
272
- return drain();
371
+ const schedulePressure = () => {
372
+ if (pressureHandle !== null) return;
373
+ pressureHandle = schedulePressureDrain(() => {
374
+ pressureHandle = null;
375
+ drain();
376
+ });
273
377
  };
274
378
 
379
+ const flush = () => drain();
380
+
275
381
  const applyOversize = (entry) => {
276
382
  const applyStart = diagnosticsEnabled ? now() : 0;
277
383
  const applied = applyEntry(entry) ? 1 : 0;
@@ -283,33 +389,58 @@ export function createStreamOutputController({
283
389
  return applied;
284
390
  };
285
391
 
392
+ const reportOverflow = (reason, entry) => {
393
+ const record = { reason, pendingCount: totalCount(), pendingBytes: totalBytes(), incomingBytes: entry.bytes };
394
+ onOverflow(record);
395
+ emitDiagnostic({ type: "overflow", ...record });
396
+ };
397
+
286
398
  const enqueue = (entry) => {
287
- const last = pending[pending.length - 1];
399
+ const last = urgentEntry || pending[pending.length - 1];
288
400
  const merged = last ? mergedAdjacentEntry(last, entry) : null;
289
- if (merged && pendingBytes - last.bytes + merged.bytes <= byteLimit) {
290
- pending[pending.length - 1] = merged;
291
- pendingBytes = pendingBytes - last.bytes + merged.bytes;
292
- emitDiagnostic({ type: "queued", coalesced: true, pendingCount: pending.length, pendingBytes, sourceCount: merged.sourceCount });
401
+ const mergedFits = urgentEntry
402
+ ? merged?.bytes <= byteLimit
403
+ : merged && pendingBytes - last.bytes + merged.bytes <= byteLimit;
404
+ if (mergedFits) {
405
+ if (urgentEntry) urgentEntry = merged;
406
+ else {
407
+ pending[pending.length - 1] = merged;
408
+ pendingBytes = pendingBytes - last.bytes + merged.bytes;
409
+ }
410
+ emitDiagnostic({ type: "queued", coalesced: true, pendingCount: totalCount(), pendingBytes: totalBytes(), sourceCount: merged.sourceCount });
293
411
  return;
294
412
  }
295
413
 
296
- if (merged || pending.length >= entryLimit || pendingBytes + entry.bytes > byteLimit) {
297
- const reason = merged ? "coalesced-byte-limit" : pending.length >= entryLimit ? "entry-limit" : "byte-limit";
298
- onOverflow({ reason, pendingCount: pending.length, pendingBytes, incomingBytes: entry.bytes });
299
- emitDiagnostic({ type: "overflow", reason, pendingCount: pending.length, pendingBytes, incomingBytes: entry.bytes });
414
+ if (entry.bytes > byteLimit) {
415
+ if (totalCount()) {
416
+ emitDiagnostic({ type: "pressure", action: "synchronous-fallback", reason: "oversize-event", pendingCount: totalCount(), pendingBytes: totalBytes() });
417
+ flush();
418
+ }
419
+ reportOverflow("oversize-event", entry);
420
+ applyOversize(entry);
421
+ return;
422
+ }
423
+
424
+ if (urgentEntry) {
425
+ emitDiagnostic({ type: "pressure", action: "synchronous-fallback", reason: merged ? "urgent-merge-limit" : "urgent-slot-full", pendingCount: totalCount(), pendingBytes: totalBytes() });
300
426
  flush();
427
+ enqueue(entry);
428
+ return;
301
429
  }
302
430
 
303
- if (entry.bytes > byteLimit) {
304
- onOverflow({ reason: "oversize-event", pendingCount: 0, pendingBytes: 0, incomingBytes: entry.bytes });
305
- emitDiagnostic({ type: "overflow", reason: "oversize-event", pendingCount: 0, pendingBytes: 0, incomingBytes: entry.bytes });
306
- applyOversize(entry);
431
+ if (merged || pending.length >= entryLimit || pendingBytes + entry.bytes > byteLimit) {
432
+ const reason = merged ? "coalesced-byte-limit" : pending.length >= entryLimit ? "entry-limit" : "byte-limit";
433
+ reportOverflow(reason, entry);
434
+ urgentEntry = entry;
435
+ emitDiagnostic({ type: "pressure", action: "deferred", reason, pendingCount: totalCount(), pendingBytes: totalBytes() });
436
+ emitDiagnostic({ type: "queued", coalesced: false, urgent: true, pendingCount: totalCount(), pendingBytes: totalBytes(), sourceCount: entry.sourceCount });
437
+ schedulePressure();
307
438
  return;
308
439
  }
309
440
 
310
441
  pending.push(entry);
311
442
  pendingBytes += entry.bytes;
312
- emitDiagnostic({ type: "queued", coalesced: false, pendingCount: pending.length, pendingBytes, sourceCount: entry.sourceCount });
443
+ emitDiagnostic({ type: "queued", coalesced: false, pendingCount: totalCount(), pendingBytes: totalBytes(), sourceCount: entry.sourceCount });
313
444
  };
314
445
 
315
446
  return Object.freeze({
@@ -322,50 +453,61 @@ export function createStreamOutputController({
322
453
  reportStale(event, owner, classification, "dispatch");
323
454
  return true;
324
455
  }
456
+ const accounting = eventByteAccounting(event, classification);
325
457
  const entry = {
326
458
  event,
327
459
  classification,
328
460
  owner,
329
461
  receivedAt: diagnosticsEnabled ? now() : undefined,
330
- bytes: eventByteSize(event),
462
+ ...accounting,
331
463
  sourceCount: 1,
332
464
  sourceIndexes: diagnosticsEnabled && index !== null ? [index] : [],
333
465
  };
334
466
  enqueue(entry);
335
467
  if (classification.barrier) {
336
- emitDiagnostic({ type: "barrier", reason: classification.subtype, pendingCount: pending.length, pendingBytes });
468
+ emitDiagnostic({ type: "barrier", reason: classification.subtype, pendingCount: totalCount(), pendingBytes: totalBytes() });
337
469
  flush();
338
- } else if (pending.length) {
470
+ } else if (totalCount()) {
339
471
  schedule();
340
472
  }
341
473
  return true;
342
474
  },
343
475
  flush,
344
476
  barrier(reason = "semantic") {
345
- emitDiagnostic({ type: "barrier", reason: String(reason || "semantic"), pendingCount: pending.length, pendingBytes });
477
+ emitDiagnostic({ type: "barrier", reason: String(reason || "semantic"), pendingCount: totalCount(), pendingBytes: totalBytes() });
346
478
  return flush();
347
479
  },
348
480
  cancel(owner) {
349
- if (owner === undefined) pending = [];
350
- else pending = pending.filter((entry) => entry.owner !== owner);
351
- pendingBytes = pending.reduce((total, entry) => total + entry.bytes, 0);
352
- if (!pending.length && frameHandle !== null) {
353
- cancelFrame(frameHandle);
354
- frameHandle = null;
481
+ if (owner === undefined) {
482
+ pending = [];
483
+ urgentEntry = null;
484
+ } else {
485
+ pending = pending.filter((entry) => entry.owner !== owner);
486
+ if (urgentEntry?.owner === owner) urgentEntry = null;
355
487
  }
356
- emitDiagnostic({ type: "cancel", owner, pendingCount: pending.length, pendingBytes });
488
+ pendingBytes = pending.reduce((total, entry) => total + entry.bytes, 0);
489
+ if (!totalCount()) cancelScheduledDrains();
490
+ emitDiagnostic({ type: "cancel", owner, pendingCount: totalCount(), pendingBytes: totalBytes() });
357
491
  },
358
492
  pendingCount() {
359
- return pending.length;
493
+ return totalCount();
360
494
  },
361
495
  pendingBytes() {
362
- return pendingBytes;
496
+ return totalBytes();
363
497
  },
364
498
  limits() {
365
- return Object.freeze({ maxPendingEntries: entryLimit, maxPendingBytes: byteLimit });
499
+ return Object.freeze({
500
+ maxPendingEntries: entryLimit,
501
+ maxPendingBytes: byteLimit,
502
+ maxUrgentEntries: URGENT_PRESSURE_ENTRY_LIMIT,
503
+ maxUrgentBytes: byteLimit,
504
+ });
366
505
  },
367
506
  hasScheduledFrame() {
368
507
  return frameHandle !== null;
369
508
  },
509
+ hasScheduledPressureDrain() {
510
+ return pressureHandle !== null;
511
+ },
370
512
  });
371
513
  }
@@ -0,0 +1,85 @@
1
+ export const NORMAL_STREAM_RENDER_INTERVAL_MS = 40;
2
+
3
+ /**
4
+ * Latest-wins cadence for expensive normal-stream formatting. The first
5
+ * request renders synchronously; sustained requests publish at most once per
6
+ * interval. Semantic callers use flushNow(), while reset/cancellation uses
7
+ * cancel(). Clock and timer hooks keep cadence tests deterministic.
8
+ */
9
+ export function createLatestWinsRenderScheduler({
10
+ render,
11
+ now = () => (typeof globalThis.performance?.now === "function" ? globalThis.performance.now() : Date.now()),
12
+ schedule = (callback, delay) => globalThis.setTimeout(callback, delay),
13
+ cancelSchedule = (handle) => globalThis.clearTimeout(handle),
14
+ intervalMs = NORMAL_STREAM_RENDER_INTERVAL_MS,
15
+ onDiagnostic,
16
+ } = {}) {
17
+ if (typeof render !== "function") throw new TypeError("render is required");
18
+ if (typeof now !== "function" || typeof schedule !== "function" || typeof cancelSchedule !== "function") {
19
+ throw new TypeError("now, schedule, and cancelSchedule must be functions");
20
+ }
21
+ if (!Number.isFinite(intervalMs) || intervalMs < 1) throw new TypeError("intervalMs must be a positive number");
22
+ const diagnose = typeof onDiagnostic === "function"
23
+ ? (record) => {
24
+ try { onDiagnostic(Object.freeze(record)); } catch { /* Diagnostics cannot alter rendering. */ }
25
+ }
26
+ : () => {};
27
+
28
+ let handle = null;
29
+ let pendingValue;
30
+ let hasPending = false;
31
+ let lastFlushAt = null;
32
+
33
+ const clearHandle = () => {
34
+ if (handle !== null) cancelSchedule(handle);
35
+ handle = null;
36
+ };
37
+
38
+ const run = (reason = "scheduled") => {
39
+ clearHandle();
40
+ if (!hasPending) return false;
41
+ const value = pendingValue;
42
+ pendingValue = undefined;
43
+ hasPending = false;
44
+ lastFlushAt = now();
45
+ render(value, { reason });
46
+ diagnose({ type: "render-scheduler", action: "flush", reason });
47
+ return true;
48
+ };
49
+
50
+ const defer = () => {
51
+ if (handle !== null) return;
52
+ const elapsed = lastFlushAt === null ? intervalMs : Math.max(0, now() - lastFlushAt);
53
+ const delayMs = Math.max(0, intervalMs - elapsed);
54
+ handle = schedule(() => {
55
+ handle = null;
56
+ run("cadence");
57
+ }, delayMs);
58
+ diagnose({ type: "render-scheduler", action: "defer", delayMs });
59
+ };
60
+
61
+ return Object.freeze({
62
+ request(value) {
63
+ pendingValue = value;
64
+ hasPending = true;
65
+ if (lastFlushAt === null || now() - lastFlushAt >= intervalMs) return run("immediate");
66
+ defer();
67
+ return false;
68
+ },
69
+ flushNow(reason = "semantic") {
70
+ return run(String(reason || "semantic"));
71
+ },
72
+ cancel() {
73
+ clearHandle();
74
+ pendingValue = undefined;
75
+ hasPending = false;
76
+ lastFlushAt = null;
77
+ },
78
+ pending() {
79
+ return hasPending;
80
+ },
81
+ intervalMs() {
82
+ return intervalMs;
83
+ },
84
+ });
85
+ }