@amritk/nish-aarch64-darwin 0.35.0 → 0.37.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 (128) hide show
  1. package/INSTALL.md +73 -59
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +50 -4
  4. package/package.json +1 -1
  5. package/runtime/async.d.mts +2 -0
  6. package/runtime/async.mjs +7 -0
  7. package/runtime/nish.d.ts +4849 -430
  8. package/runtime/nish.h +25 -0
  9. package/runtime/page.d.ts +53 -0
  10. package/runtime/page.mjs +146 -0
  11. package/runtime/runtime-async.c +557 -0
  12. package/runtime/runtime-wasm.c +63 -7
  13. package/runtime/vite.d.ts +30 -0
  14. package/runtime/vite.mjs +150 -0
  15. package/scripts/build.sh +252 -15
  16. package/std/README.md +107 -82
  17. package/std/base64.ts +34 -5
  18. package/std/bytes.ts +279 -59
  19. package/std/cli-args.ts +296 -70
  20. package/std/cli-flags.ts +184 -19
  21. package/std/cli.ts +475 -54
  22. package/std/collections.ts +121 -23
  23. package/std/compress/checksum.ts +44 -14
  24. package/std/compress/deflate.ts +224 -111
  25. package/std/compress/gzip.ts +217 -53
  26. package/std/compress/zlib.ts +63 -7
  27. package/std/crypto/aes.ts +128 -52
  28. package/std/crypto/base64url.ts +29 -5
  29. package/std/crypto/bcrypt-batch.ts +101 -34
  30. package/std/crypto/bcrypt.ts +93 -27
  31. package/std/crypto/chacha20poly1305.ts +69 -14
  32. package/std/crypto/ct.ts +32 -13
  33. package/std/crypto/ed25519.ts +66 -16
  34. package/std/crypto/hkdf.ts +198 -13
  35. package/std/crypto/hmac.ts +242 -37
  36. package/std/crypto/jwt.ts +204 -72
  37. package/std/crypto/p256.ts +222 -72
  38. package/std/crypto/p384.ts +51 -23
  39. package/std/crypto/pki-roots.ts +32 -2
  40. package/std/crypto/pki.ts +99 -30
  41. package/std/crypto/rsa.ts +56 -22
  42. package/std/crypto/sha1.ts +3 -0
  43. package/std/crypto/sha256.ts +24 -1
  44. package/std/crypto/sha512.ts +99 -14
  45. package/std/crypto/x25519.ts +163 -24
  46. package/std/crypto/x509-random.ts +10 -0
  47. package/std/crypto/x509.ts +133 -66
  48. package/std/host/ring.ts +124 -0
  49. package/std/json-equal.ts +31 -11
  50. package/std/json-format.ts +112 -13
  51. package/std/json-number.ts +76 -26
  52. package/std/json-pointer.ts +23 -1
  53. package/std/json-tokenizer.ts +126 -51
  54. package/std/json-typed.ts +757 -96
  55. package/std/json-value.ts +438 -157
  56. package/std/json.ts +170 -38
  57. package/std/map.ts +25 -7
  58. package/std/math.ts +36 -4
  59. package/std/net/buffer-pool.ts +42 -11
  60. package/std/net/dns-config.ts +109 -23
  61. package/std/net/dns-message.ts +62 -7
  62. package/std/net/dns-resolver.ts +247 -53
  63. package/std/net/dns.ts +203 -35
  64. package/std/net/fetch.ts +1267 -290
  65. package/std/net/handler.ts +296 -80
  66. package/std/net/hpack.ts +290 -77
  67. package/std/net/http-compress.ts +152 -36
  68. package/std/net/http-fields.ts +85 -9
  69. package/std/net/http1-client-codec.ts +129 -44
  70. package/std/net/http1-codec.ts +279 -114
  71. package/std/net/http1-server.ts +409 -139
  72. package/std/net/http2-frame.ts +289 -51
  73. package/std/net/http2-tls.ts +152 -49
  74. package/std/net/http2.ts +314 -160
  75. package/std/net/http3-frame.ts +165 -27
  76. package/std/net/http3-server.ts +282 -131
  77. package/std/net/http3.ts +377 -173
  78. package/std/net/outbound.ts +37 -3
  79. package/std/net/postgres-carrier.ts +144 -8
  80. package/std/net/postgres.ts +898 -260
  81. package/std/net/prefork.ts +202 -65
  82. package/std/net/qpack.ts +120 -32
  83. package/std/net/quic-conn-ack.ts +60 -12
  84. package/std/net/quic-conn-cid.ts +135 -27
  85. package/std/net/quic-conn-params.ts +109 -22
  86. package/std/net/quic-datagram.ts +50 -3
  87. package/std/net/quic-frame.ts +333 -23
  88. package/std/net/quic-listener.ts +161 -75
  89. package/std/net/quic-packet.ts +373 -73
  90. package/std/net/quic-recovery.ts +287 -65
  91. package/std/net/quic-stream.ts +436 -146
  92. package/std/net/quic.ts +693 -323
  93. package/std/net/router.ts +87 -40
  94. package/std/net/tls/client.ts +167 -51
  95. package/std/net/tls/codec.ts +494 -68
  96. package/std/net/tls/record-client.ts +140 -73
  97. package/std/net/tls/record-server.ts +233 -105
  98. package/std/net/tls/record.ts +142 -36
  99. package/std/net/tls/schedule.ts +235 -26
  100. package/std/net/tls/ticket.ts +161 -40
  101. package/std/net/tls/verify.ts +57 -10
  102. package/std/net/tls-tcp.ts +308 -95
  103. package/std/net/tls.ts +276 -102
  104. package/std/net/upstream.ts +81 -45
  105. package/std/net/url.ts +109 -22
  106. package/std/net/websocket.ts +140 -26
  107. package/std/net/webtransport.ts +243 -106
  108. package/std/pair.ts +10 -2
  109. package/std/random.ts +42 -15
  110. package/std/regex.ts +422 -257
  111. package/std/region.ts +70 -15
  112. package/std/secret.ts +52 -11
  113. package/std/sort.ts +17 -2
  114. package/std/sqlite.ts +256 -35
  115. package/std/sync/ring.ts +229 -56
  116. package/std/sync/shm.ts +203 -23
  117. package/std/term-io.ts +154 -78
  118. package/std/term-pixels.ts +144 -19
  119. package/std/term-probe.ts +77 -35
  120. package/std/term-rate.ts +199 -118
  121. package/std/term.ts +400 -175
  122. package/std/testing.ts +130 -32
  123. package/std/text.ts +84 -17
  124. package/std/threads.ts +248 -56
  125. package/std/yaml-json.ts +111 -97
  126. package/std/yaml-lines.ts +47 -15
  127. package/std/yaml-write.ts +45 -30
  128. package/std/yaml.ts +764 -384
package/std/term-rate.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * `std/term-rate` — how fast the link to the terminal is, measured from frames
2
+ * `nish/term-rate` — how fast the link to the terminal is, measured from frames
3
3
  * sent and acknowledged, and the frame rate and drawing detail a program keeps
4
4
  * to under it.
5
5
  *
@@ -10,15 +10,28 @@
10
10
  * (`RateDecision`). Every time is an `f64` count of milliseconds on the
11
11
  * caller's clock, as `FixedStep`'s is in `nish/term`.
12
12
  *
13
+ * import { RateController, RateOptions } from "nish/term-rate"
14
+ *
15
+ * const rate = new RateController(new RateOptions())
16
+ * // each turn of the loop, at nowMs:
17
+ * rate.tick(nowMs)
18
+ * if (rate.mayDraw(nowMs)) {
19
+ * // draw as rate.decision() says, then write the frame and `CSI 5 n`
20
+ * rate.frameSent(bytes, costNs, nowMs)
21
+ * }
22
+ * // for each `CSI 0 n` read back: rate.ackReceived(nowMs)
23
+ *
13
24
  * **The acknowledgement.** A frame is acknowledged when the terminal answers a
14
25
  * status query sent right after it: the terminal answers in order, so the
15
26
  * answer means every byte before it has been read and drawn. The query to send
16
- * is DSR 5, `CSI 5 n`, answered `CSI 0 n`. It is preferred over the cursor
17
- * position report (DSR 6, `CSI 6 n`, answered `CSI row ; col R`) because its
18
- * answer is one fixed string, and because a cursor report is the same bytes as
19
- * F3 with modifiers in the legacy key encoding (`CSI 1 ; mods R`), which a key
20
- * decoder would have to guess between. Two relays answer the query from their
21
- * own emulator, not from the terminal at the end of the link:
27
+ * is DSR 5, `CSI 5 n`, answered `CSI 0 n`.
28
+ *
29
+ * It is preferred over the cursor position report (DSR 6, `CSI 6 n`, answered
30
+ * `CSI row ; col R`) because its answer is one fixed string, and because a
31
+ * cursor report is the same bytes as F3 with modifiers in the legacy key
32
+ * encoding (`CSI 1 ; mods R`), which a key decoder would have to guess between.
33
+ * Two relays answer the query from their own emulator, not from the terminal at
34
+ * the end of the link:
22
35
  *
23
36
  * - tmux (commit 939e8e65) answers in `input.c` lines 1737–1747, the
24
37
  * `INPUT_CSI_DSR` case, which replies `\033[0n` to 5 and the position to 6
@@ -39,62 +52,70 @@
39
52
  * **What is measured.** Four running averages (exponentially weighted, so
40
53
  * recent frames count most and none is stored): the round trip from a frame's
41
54
  * send to its acknowledgement (weight 1/8, as TCP smooths its round trip, so
42
- * one late answer moves it little); the bytes a second the link delivered;
43
- * the cost to build a frame and the bytes in one (weight 1/4 each, so a
44
- * change of scene shows within a few frames).
45
- * The bandwidth and the latency are kept apart, so neither can take the
46
- * other's share of a round trip. A frame sent before the previous answer, and
47
- * answered more than the latency after it, kept the link busy from that answer
48
- * to its own: its bytes over that time measure the bandwidth. A frame sent
49
- * onto an idle link makes a trip, kept with the last 16 and the probe's:
50
- * against the quickest kept trip, one twice its bytes or half, 2 ms or more
51
- * apart, measures the bandwidth from the difference, which the latency is no
52
- * part of.
53
- * Both kinds smooth the bytes and the time apart (weight 1/4 each), so answers
54
- * arriving in a burst, each taking almost no time, do not read as unbounded
55
- * bandwidth; answers under 2 ms apart measure nothing this way. A sample
56
- * counts for the decisions for 5 seconds with no newer one, so a link that
57
- * narrows is not held to its old rate; the bandwidth reported keeps it until
58
- * a newer sample, which starts the average afresh, replaces it, or three
59
- * trips in a row take over twice what it and the quickest trip kept when
60
- * it was taken predict. The figure
61
- * is at least the most of the last 16 answers' bytes over their whole round
62
- * trips, since the bytes took no longer than that, so a link that widens shows on its first quick answer; but that
63
- * bound counts the latency as bytes' time, so alone it never makes the
64
- * bandwidth known to the decisions. The base latency is the least, over the
65
- * kept trips, of the round trip less the trip's bytes at the bandwidth: the
66
- * probe's round trip (`probeRttMs`: the status query alone is a few bytes, so
67
- * its round trip is the latency) counts from the start, the frames' once the
68
- * bandwidth is known. The kept trips roll over, so a changed route shows
69
- * within 16 trips. With frames of one size sent one at a time onto
70
- * an idle link and no probe the latency and the bytes cannot be told apart:
71
- * the bandwidth is then not known, its load counts as 0, and the trip load
72
- * governs on the frame's measured round trip: a cut is taken to shorten none
73
- * of it and a restore to lengthen all of it, so detail is neither cut for a
74
- * gain nor restored at a cost that may not be there.
75
- * Acknowledgements match sent frames oldest first. A frame due while the
76
- * unacknowledged limit is reached is dropped and counted; one not answered
77
- * within `rateAckTimeoutMs` plus four round trips is given up and counted as
78
- * lost, so a lost answer
79
- * stalls drawing for seconds, not for ever. Its answer may still come late, and
80
- * would otherwise be matched to the next frame, so after a give-up no frame is
81
- * drawn until as many answers have arrived, or one more timeout has passed
82
- * without them. A time, cost or size that is not a finite number, or is
83
- * negative, is not measured, and an empty frame says nothing about bandwidth.
55
+ * one late answer moves it little); the bytes a second the link delivered; the
56
+ * cost to build a frame and the bytes in one (weight 1/4 each, so a change of
57
+ * scene shows within a few frames). The bandwidth and the latency are kept
58
+ * apart, so neither can take the other's share of a round trip.
59
+ *
60
+ * A frame sent before the previous answer, and answered more than the latency
61
+ * after it, kept the link busy from that answer to its own: its bytes over that
62
+ * time measure the bandwidth. A frame sent onto an idle link makes a trip, kept
63
+ * with the last 16 and the probe's: against the quickest kept trip, one twice
64
+ * its bytes or half, 2 ms or more apart, measures the bandwidth from the
65
+ * difference, which the latency is no part of.
66
+ *
67
+ * Both kinds smooth the bytes and the time apart (weight 1/4 each), so answers
68
+ * arriving in a burst, each taking almost no time, do not read as unbounded
69
+ * bandwidth; answers under 2 ms apart measure nothing this way.
70
+ *
71
+ * A sample counts for the decisions for 5 seconds with no newer one, so a link
72
+ * that narrows is not held to its old rate; the bandwidth reported keeps it
73
+ * until a newer sample, which starts the average afresh, replaces it, or three
74
+ * trips in a row take over twice what it and the quickest trip kept when it was
75
+ * taken predict.
76
+ *
77
+ * The figure is at least the most of the last 16 answers' bytes over their
78
+ * whole round trips, since the bytes took no longer than that, so a link that
79
+ * widens shows on its first quick answer; but that bound counts the latency as
80
+ * bytes' time, so alone it never makes the bandwidth known to the decisions.
81
+ *
82
+ * The base latency is the least, over the kept trips, of the round trip less
83
+ * the trip's bytes at the bandwidth: the probe's round trip (`probeRttMs`: the
84
+ * status query alone is a few bytes, so its round trip is the latency) counts
85
+ * from the start, the frames' once the bandwidth is known. The kept trips roll
86
+ * over, so a changed route shows within 16 trips.
87
+ *
88
+ * With frames of one size sent one at a time onto an idle link and no probe the
89
+ * latency and the bytes cannot be told apart: the bandwidth is then not known,
90
+ * its load counts as 0, and the trip load governs on the frame's measured round
91
+ * trip: a cut is taken to shorten none of it and a restore to lengthen all of
92
+ * it, so detail is neither cut for a gain nor restored at a cost that may not
93
+ * be there. Acknowledgements match sent frames oldest first.
94
+ *
95
+ * A frame due while the unacknowledged limit is reached is dropped and counted;
96
+ * one not answered within `rateAckTimeoutMs` plus four round trips is given up
97
+ * and counted as lost, so a lost answer stalls drawing for seconds, not for
98
+ * ever. Its answer may still come late, and would otherwise be matched to the
99
+ * next frame, so after a give-up no frame is drawn until as many answers have
100
+ * arrived, or one more timeout has passed without them. A time, cost or size
101
+ * that is not a finite number, or is negative, is not measured, and an empty
102
+ * frame says nothing about bandwidth.
103
+ *
104
+ * **What is decided.**
84
105
  *
85
- * **What is decided.** The frame rate is a tier: 120 (only with `allow120` and
86
- * a `maxFps` of 120), 60, 30, 20, 15, 10 or 5. A tier fits when three loads
87
- * are all at most 1: the frame cost over 70% of the frame time, the bytes a
88
- * second the tier needs over 70% of the bytes a second the link delivers, and
89
- * the tier's frames times the round trip over 70% of the time the
90
- * unacknowledged limit allows (a link that answers in 100 ms carries at most
91
- * ten frames a second one at a time). The 30% left over absorbs a slow frame
92
- * without a dropped one. The rate falls to the best fitting tier after half a
93
- * second continuously over, and rises one tier after three seconds
94
- * continuously under the next tier's loads with a fifth to spare; after any
95
- * change it holds for a second, so the averages see the new rate before the
96
- * next decision. Falling fast and rising slowly keeps a flickering link from
97
- * flipping the rate.
106
+ * The frame rate is a tier: 120 (only with `allow120` and a `maxFps` of 120),
107
+ * 60, 30, 20, 15, 10 or 5. A tier fits when three loads are all at most 1: the
108
+ * frame cost over 70% of the frame time, the bytes a second the tier needs over
109
+ * 70% of the bytes a second the link delivers, and the tier's frames times the
110
+ * round trip over 70% of the time the unacknowledged limit allows (a link that
111
+ * answers in 100 ms carries at most ten frames a second one at a time).
112
+ *
113
+ * The 30% left over absorbs a slow frame without a dropped one. The rate falls
114
+ * to the best fitting tier after half a second continuously over, and rises one
115
+ * tier after three seconds continuously under the next tier's loads with a
116
+ * fifth to spare; after any change it holds for a second, so the averages see
117
+ * the new rate before the next decision. Falling fast and rising slowly keeps a
118
+ * flickering link from flipping the rate.
98
119
  *
99
120
  * It starts at the best tier on a local terminal: the probe answered under
100
121
  * 5 ms, or no `SSH_*` hint and no slow answer. Falling costs half a second and
@@ -325,84 +346,113 @@ export class TermStats {
325
346
  */
326
347
  export class RateController {
327
348
  /** The tiers allowed, fastest first, ending at 5. */
328
- tiers: i32[]
329
- /** Paces frames at `tier`. */
349
+ private tiers: i32[]
350
+ /**
351
+ * Paces frames at `tier`.
352
+ * @internal Used by `termIoWait` in term-io.ts.
353
+ */
330
354
  pacer: FixedStep
331
355
  /** When the tier or step last changed. */
332
- changedMs: f64
356
+ private changedMs: f64
333
357
  /** When the loads went over budget and stayed, or -1. */
334
- overSinceMs: f64
358
+ private overSinceMs: f64
335
359
  /** When the next step up came within its margin and stayed, or -1. */
336
- underSinceMs: f64
360
+ private underSinceMs: f64
337
361
  /** The send times of the unacknowledged frames, oldest at `head`. */
338
362
  sentMs: f64[]
339
363
  /** Their byte counts. */
340
- sentBytes: i32[]
364
+ private sentBytes: i32[]
341
365
  /** When the last acknowledgement arrived, or -1. */
342
- lastAckMs: f64
343
- /** The smoothed round trip, in milliseconds. */
366
+ private lastAckMs: f64
367
+ /**
368
+ * The smoothed round trip, in milliseconds.
369
+ * @internal Used by `Terminal` in term-io.ts.
370
+ */
344
371
  rttMs: f64
345
- /** The link's latency without bytes: the least, over the kept trips, of the round trip less the bytes' time. */
372
+ /**
373
+ * The link's latency without bytes: the least, over the kept trips, of the round trip less the bytes' time.
374
+ */
346
375
  baseRttMs: f64
347
376
  /** The latency as last worked out while the bandwidth was known, held once its samples age out. */
348
- heldLatencyMs: f64
349
- /** The round trips of the probe and of the latest frames sent onto an idle link, `rateTripCount` at most. */
377
+ private heldLatencyMs: f64
378
+ /**
379
+ * The round trips of the probe and of the latest frames sent onto an idle link, `rateTripCount` at most.
380
+ */
350
381
  tripMs: f64[]
351
382
  /** Their byte counts, 0 for the probe. */
352
- tripBytes: f64[]
383
+ private tripBytes: f64[]
353
384
  /** The bytes a second each of the latest answers proves at least, its bytes over its round trip. */
354
- floorPerSec: f64[]
385
+ private floorPerSec: f64[]
355
386
  /** The smoothed bytes of an answered frame, for the bandwidth. */
356
- ackBytes: f64
387
+ private ackBytes: f64
357
388
  /** The smoothed time the link spent on an answered frame, in milliseconds, for the bandwidth. */
358
- ackBusyMs: f64
389
+ private ackBusyMs: f64
359
390
  /**
360
391
  * The bytes a second delivered: `ackBytes` over `ackBusyMs`, at least the most of `floorPerSec`, which alone is a lower
361
392
  * bound. Samples older than `rateFreshMs` still count here while trips agree with them, but no decision uses them.
362
393
  */
363
394
  bytesPerSec: f64
364
395
  /** When the bandwidth was last sampled, by a frame that waited behind another or by two trips. */
365
- rateAtMs: f64
396
+ private rateAtMs: f64
366
397
  /** The quickest kept trip, or the round trip with none kept, when the bandwidth was last sampled: at least the latency then. */
367
- rateQuickMs: f64
398
+ private rateQuickMs: f64
368
399
  /** When frames were last given up on, while `stale` waits for their late answers. */
369
- staleSinceMs: f64
400
+ private staleSinceMs: f64
370
401
  /** The smoothed frame cost, in milliseconds. */
371
- costMs: f64
402
+ private costMs: f64
372
403
  /** The smoothed bytes per frame. */
373
- frameBytes: f64
374
- current: RateDecision
375
- measured: TermStats
376
- /** The least tier detail is cut to keep: the floor tier under `RATE_FIRST`, 5 under `DETAIL_FIRST`. */
404
+ private frameBytes: f64
405
+ private current: RateDecision
406
+ private measured: TermStats
407
+ /**
408
+ * The least tier detail is cut to keep: the floor tier under `RATE_FIRST`, 5 under `DETAIL_FIRST`.
409
+ */
377
410
  floorFps: i32
378
- /** The least tier above which `RATE_FIRST` keeps full detail. */
411
+ /**
412
+ * The least tier above which `RATE_FIRST` keeps full detail.
413
+ * @internal Nothing reads it.
414
+ */
379
415
  minTier: i32
416
+ /**
417
+ * What gives way first, `RATE_FIRST` or `DETAIL_FIRST`, from the options.
418
+ */
380
419
  prefer: i32
420
+ /**
421
+ * How many frames may await their acknowledgement at once: 1 or 2.
422
+ */
381
423
  maxUnacked: i32
382
- /** The fixed frame rate, or 0 when the controller chooses. */
424
+ /**
425
+ * The fixed frame rate, or 0 when the controller chooses.
426
+ * @internal Used by `Terminal` in term-io.ts.
427
+ */
383
428
  fixedFps: i32
384
429
  /** The frame rate in force. */
385
- tier: i32
430
+ private tier: i32
386
431
  /** The detail step in force, 0 (full detail) to `rateMaxLevel`. */
387
- level: i32
432
+ private level: i32
388
433
  /** The oldest unacknowledged frame's index in `sentMs`. */
389
- head: i32
390
- dropped: i32
391
- lost: i32
392
- /** Frames given up on whose answers may still come: the next answers are theirs, and no frame is drawn meanwhile. */
434
+ private head: i32
435
+ private dropped: i32
436
+ private lost: i32
437
+ /**
438
+ * Frames given up on whose answers may still come: the next answers are theirs, and no frame is drawn meanwhile.
439
+ * @internal Used by `Terminal` in term-io.ts.
440
+ */
393
441
  stale: i32
394
442
  /** Where the next trip goes in `tripMs` once it is full. */
395
- tripNext: i32
443
+ private tripNext: i32
396
444
  /** How many trips in a row have contradicted the aged bandwidth sample. */
397
- contradicted: i32
445
+ private contradicted: i32
398
446
  /** Where the next goes in `floorPerSec` once it is full. */
399
- floorNext: i32
447
+ private floorNext: i32
400
448
  /** Whether a frame has been asked for, so the pacer's clock runs. */
401
- paced: boolean
402
- /** Whether a round trip, from the probe or an answer, is known. */
449
+ private paced: boolean
450
+ /**
451
+ * Whether a round trip, from the probe or an answer, is known.
452
+ */
403
453
  haveRtt: boolean
404
454
  /** Whether a frame has been acknowledged, so decisions can start. */
405
- haveAck: boolean
455
+ private haveAck: boolean
406
456
  /**
407
457
  * Whether the bandwidth is known, so decisions may use it: sampled by a
408
458
  * frame that waited behind another or two trips of different sizes, within
@@ -411,9 +461,13 @@ export class RateController {
411
461
  */
412
462
  haveRate: boolean
413
463
  /** Whether a frame has been sent, so cost and size are known. */
414
- haveFrame: boolean
464
+ private haveFrame: boolean
415
465
 
416
- /** A controller for `options`, read once. */
466
+ /**
467
+ * A controller for `options`, read once.
468
+ *
469
+ * @param options The rate limits, preference and hints to run with; changing it later changes nothing.
470
+ */
417
471
  constructor(options: RateOptions) {
418
472
  this.prefer = options.prefer === DETAIL_FIRST ? DETAIL_FIRST : RATE_FIRST
419
473
  this.maxUnacked = options.maxUnacked >= 2 ? 2 : 1
@@ -497,7 +551,11 @@ export class RateController {
497
551
  this.publish()
498
552
  }
499
553
 
500
- /** Frames sent and not yet acknowledged. */
554
+ /**
555
+ * Frames sent and not yet acknowledged.
556
+ *
557
+ * @returns How many frames await their acknowledgement, from 0.
558
+ */
501
559
  unacked(): i32 {
502
560
  return toI32(this.sentMs.length) - this.head
503
561
  }
@@ -509,6 +567,9 @@ export class RateController {
509
567
  * limit, or while the answers to frames given up on may still come, is
510
568
  * counted as dropped, and the next waits for the next step. A time that is
511
569
  * not a finite number is refused.
570
+ *
571
+ * @param nowMs The time now, in milliseconds on the clock every call uses.
572
+ * @returns True when the program should draw and send a frame now.
512
573
  */
513
574
  mayDraw(nowMs: f64): boolean {
514
575
  if (!rateFinite(nowMs)) {
@@ -536,6 +597,10 @@ export class RateController {
536
597
  * sent at `nowMs`. A call whose time is not a finite number is ignored; a
537
598
  * cost that is not a finite number or is negative is not measured, and
538
599
  * negative bytes count as none.
600
+ *
601
+ * @param bytes The frame's size in bytes as written.
602
+ * @param costNs How long the frame took to build, in nanoseconds.
603
+ * @param nowMs When it was sent, in milliseconds on the clock every call uses.
539
604
  */
540
605
  frameSent(bytes: i32, costNs: f64, nowMs: f64): void {
541
606
  if (!rateFinite(nowMs)) {
@@ -571,6 +636,8 @@ export class RateController {
571
636
  * since the terminal answers in order. One with no frame waiting (a stray
572
637
  * answer) is ignored, and one whose time is not a finite number answers its
573
638
  * frame and measures nothing.
639
+ *
640
+ * @param nowMs When the acknowledgement was read, in milliseconds on the clock every call uses.
574
641
  */
575
642
  ackReceived(nowMs: f64): void {
576
643
  if (this.stale > 0) {
@@ -641,7 +708,7 @@ export class RateController {
641
708
  * one size measure nothing here, so small frames cannot drag the bandwidth
642
709
  * down to their round trip.
643
710
  */
644
- measureTrip(rtt: f64, bytes: f64): void {
711
+ private measureTrip(rtt: f64, bytes: f64): void {
645
712
  let quickest: i32 = -1
646
713
  for (let i: i32 = 0; i < toI32(this.tripMs.length); i++) {
647
714
  if (quickest < 0 || this.tripMs[i] < this.tripMs[quickest]) {
@@ -670,7 +737,7 @@ export class RateController {
670
737
  }
671
738
 
672
739
  /** The link spent `busyMs` on `bytes`: one sample of the bandwidth. */
673
- measureRate(bytes: f64, busyMs: f64): void {
740
+ private measureRate(bytes: f64, busyMs: f64): void {
674
741
  // A sample after the last aged out starts afresh, so a link that narrowed meanwhile is not averaged with its old rate.
675
742
  const first: boolean = this.ackBusyMs <= 0.0 || !this.haveRate
676
743
  this.rateAtMs = this.lastAckMs
@@ -694,7 +761,7 @@ export class RateController {
694
761
  * bytes over its whole round trip count the latency as bytes' time, and on
695
762
  * a far link that reads the bandwidth several times too low.
696
763
  */
697
- updateRate(): void {
764
+ private updateRate(): void {
698
765
  let rate: f64 = this.ackBusyMs > 0.0 ? (this.ackBytes * 1000.0) / this.ackBusyMs : 0.0
699
766
  this.haveRate = rate > 0.0 && this.lastAckMs - this.rateAtMs <= rateFreshMs
700
767
  for (let i: i32 = 0; i < toI32(this.floorPerSec.length); i++) {
@@ -709,7 +776,7 @@ export class RateController {
709
776
  * Stop deciding on the bandwidth once no sample is newer than `rateFreshMs`
710
777
  * at `nowMs`. The figure stays in `bytesPerSec` until a sample replaces it or a trip contradicts it.
711
778
  */
712
- ageRate(nowMs: f64): void {
779
+ private ageRate(nowMs: f64): void {
713
780
  if (this.haveRate && nowMs - this.rateAtMs > rateFreshMs) {
714
781
  this.heldLatencyMs = this.baseRttMs
715
782
  this.haveRate = false
@@ -727,7 +794,7 @@ export class RateController {
727
794
  * every frame sent before the answer ahead of it would look waited. The bandwidth never comes from the latency on an idle link, so
728
795
  * neither can drag the other down.
729
796
  */
730
- leastLatency(): f64 {
797
+ private leastLatency(): f64 {
731
798
  let least: f64 = -1.0
732
799
  for (let i: i32 = 0; i < toI32(this.tripMs.length); i++) {
733
800
  const bytes: f64 = this.tripBytes[i]
@@ -754,7 +821,7 @@ export class RateController {
754
821
  * there; more lengthens all of it, so detail is not restored on a link that
755
822
  * may not carry it.
756
823
  */
757
- fixedPart(rtt: f64, scale: f64): f64 {
824
+ private fixedPart(rtt: f64, scale: f64): f64 {
758
825
  if (!this.haveRate) {
759
826
  if (scale >= 1.0) {
760
827
  return 0.0
@@ -777,7 +844,7 @@ export class RateController {
777
844
  * `nowMs` lets a frame long unanswered count as a round trip at least that
778
845
  * long. A load not yet measured counts as 0.
779
846
  */
780
- load(fps: i32, level: i32, nowMs: f64): f64 {
847
+ private load(fps: i32, level: i32, nowMs: f64): f64 {
781
848
  const scale: f64 = rateLevelScale(this.level, level)
782
849
  const rate: f64 = toF64(fps)
783
850
  let worst: f64 = 0.0
@@ -802,7 +869,7 @@ export class RateController {
802
869
  }
803
870
 
804
871
  /** The fastest allowed tier slower than `fps` and no slower than `least`, or `least`. */
805
- slowerTier(fps: i32, least: i32): i32 {
872
+ private slowerTier(fps: i32, least: i32): i32 {
806
873
  for (const t of this.tiers) {
807
874
  if (t < fps && t >= least) {
808
875
  return t
@@ -812,7 +879,7 @@ export class RateController {
812
879
  }
813
880
 
814
881
  /** The slowest allowed tier faster than `fps`, or `fps` at the top. */
815
- fasterTier(fps: i32): i32 {
882
+ private fasterTier(fps: i32): i32 {
816
883
  let faster: i32 = fps
817
884
  for (const t of this.tiers) {
818
885
  if (t > fps) {
@@ -823,7 +890,7 @@ export class RateController {
823
890
  }
824
891
 
825
892
  /** Move to `fps` at detail step `level` at `nowMs`, rescaling the frame averages to the step. */
826
- moveTo(fps: i32, level: i32, nowMs: f64): void {
893
+ private moveTo(fps: i32, level: i32, nowMs: f64): void {
827
894
  if (level !== this.level) {
828
895
  const scale: f64 = rateLevelScale(this.level, level)
829
896
  this.costMs = this.costMs * scale
@@ -842,7 +909,7 @@ export class RateController {
842
909
  }
843
910
 
844
911
  /** One step down the path at `nowMs`, when over budget: fewer frames, or less detail. */
845
- stepDown(nowMs: f64): void {
912
+ private stepDown(nowMs: f64): void {
846
913
  const least: i32 = this.tiers[this.tiers.length - 1]
847
914
  if (this.tier > this.floorFps) {
848
915
  // Straight to the fastest tier down to the floor that fits.
@@ -872,7 +939,7 @@ export class RateController {
872
939
  * the descent backwards: tiers below the floor first, then detail, then
873
940
  * tiers above it.
874
941
  */
875
- stepUp(): i32 {
942
+ private stepUp(): i32 {
876
943
  if (this.tier < this.floorFps || (this.level === 0 && this.tier < this.tiers[0])) {
877
944
  return this.fasterTier(this.tier) * 8 + this.level
878
945
  }
@@ -887,6 +954,8 @@ export class RateController {
887
954
  * detail, restore it or rise, at most one change, with the hysteresis the
888
955
  * module header describes. Nothing is decided before the first
889
956
  * acknowledgement, nor at a fixed rate.
957
+ *
958
+ * @param nowMs The time now, in milliseconds on the clock every call uses.
890
959
  */
891
960
  tick(nowMs: f64): void {
892
961
  if (!rateFinite(nowMs)) {
@@ -912,7 +981,7 @@ export class RateController {
912
981
  }
913
982
 
914
983
  /** `tick`'s choosing, past its guards. */
915
- decide(nowMs: f64): void {
984
+ private decide(nowMs: f64): void {
916
985
  const settled: boolean = nowMs - this.changedMs >= rateSettleMs
917
986
  if (this.load(this.tier, this.level, nowMs) > 1.0) {
918
987
  this.underSinceMs = -1.0
@@ -939,7 +1008,7 @@ export class RateController {
939
1008
  }
940
1009
 
941
1010
  /** Copy the state into `current` and `measured`. */
942
- publish(): void {
1011
+ private publish(): void {
943
1012
  const d: RateDecision = this.current
944
1013
  d.fps = this.tier
945
1014
  d.resolutionDivisor = this.level >= 2 ? 4 : this.level + 1
@@ -956,12 +1025,20 @@ export class RateController {
956
1025
  s.lost = this.lost
957
1026
  }
958
1027
 
959
- /** How to draw the next frame, as of the last `tick`. */
1028
+ /**
1029
+ * How to draw the next frame, as of the last `tick`.
1030
+ *
1031
+ * @returns The frame rate, resolution divisor, richest backend and palette to draw with.
1032
+ */
960
1033
  decision(): RateDecision {
961
1034
  return this.current
962
1035
  }
963
1036
 
964
- /** What has been measured, as of the last `tick`. */
1037
+ /**
1038
+ * What has been measured, as of the last `tick`.
1039
+ *
1040
+ * @returns The rate, round trip, throughput, frame cost and frames dropped, unacknowledged and lost.
1041
+ */
965
1042
  stats(): TermStats {
966
1043
  return this.measured
967
1044
  }
@@ -991,6 +1068,10 @@ const rateBackendName = (cap: i32): string => {
991
1068
  * Write `stats` as two short lines, inverse, into `corner` (a `CORNER_*`) of
992
1069
  * `screen`: the rate, round trip and kilobytes a second, then the frame cost,
993
1070
  * the frames dropped and the backend cap. A screen too small clips them.
1071
+ *
1072
+ * @param screen The screen to draw on, before it is flushed.
1073
+ * @param stats What to show, such as `RateController.stats()`.
1074
+ * @param corner Which corner, one of the `CORNER_` constants.
994
1075
  */
995
1076
  export const drawStatsOverlay = (screen: Screen, stats: TermStats, corner: i32): void => {
996
1077
  const top: string = `${stats.tier}fps ${rateWhole(stats.rttMs)}ms ${rateWhole(stats.bytesPerSec / 1000.0)}kB/s`