@amritk/nish-aarch64-darwin 0.35.0 → 0.36.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 (119) hide show
  1. package/INSTALL.md +6 -1
  2. package/bin/nish +0 -0
  3. package/docs/AI.md +9 -2
  4. package/package.json +1 -1
  5. package/runtime/nish.d.ts +4612 -430
  6. package/runtime/vite.d.ts +30 -0
  7. package/runtime/vite.mjs +150 -0
  8. package/scripts/build.sh +108 -13
  9. package/std/base64.ts +34 -5
  10. package/std/bytes.ts +256 -40
  11. package/std/cli-args.ts +296 -70
  12. package/std/cli-flags.ts +184 -19
  13. package/std/cli.ts +475 -54
  14. package/std/collections.ts +121 -23
  15. package/std/compress/checksum.ts +44 -14
  16. package/std/compress/deflate.ts +224 -111
  17. package/std/compress/gzip.ts +217 -53
  18. package/std/compress/zlib.ts +63 -7
  19. package/std/crypto/aes.ts +80 -9
  20. package/std/crypto/base64url.ts +22 -0
  21. package/std/crypto/bcrypt-batch.ts +88 -21
  22. package/std/crypto/bcrypt.ts +60 -0
  23. package/std/crypto/chacha20poly1305.ts +53 -0
  24. package/std/crypto/ct.ts +32 -13
  25. package/std/crypto/ed25519.ts +47 -0
  26. package/std/crypto/hkdf.ts +198 -13
  27. package/std/crypto/hmac.ts +235 -31
  28. package/std/crypto/jwt.ts +192 -63
  29. package/std/crypto/p256.ts +159 -16
  30. package/std/crypto/p384.ts +28 -3
  31. package/std/crypto/pki-roots.ts +32 -2
  32. package/std/crypto/pki.ts +81 -15
  33. package/std/crypto/rsa.ts +33 -3
  34. package/std/crypto/sha1.ts +3 -0
  35. package/std/crypto/sha256.ts +24 -1
  36. package/std/crypto/sha512.ts +99 -14
  37. package/std/crypto/x25519.ts +152 -14
  38. package/std/crypto/x509-random.ts +10 -0
  39. package/std/crypto/x509.ts +67 -7
  40. package/std/json-equal.ts +19 -0
  41. package/std/json-format.ts +112 -13
  42. package/std/json-number.ts +64 -14
  43. package/std/json-pointer.ts +23 -1
  44. package/std/json-tokenizer.ts +100 -29
  45. package/std/json-typed.ts +713 -66
  46. package/std/json-value.ts +400 -124
  47. package/std/json.ts +138 -10
  48. package/std/map.ts +25 -7
  49. package/std/math.ts +36 -4
  50. package/std/net/buffer-pool.ts +42 -11
  51. package/std/net/dns-config.ts +109 -23
  52. package/std/net/dns-message.ts +62 -7
  53. package/std/net/dns-resolver.ts +247 -53
  54. package/std/net/dns.ts +203 -35
  55. package/std/net/fetch.ts +151 -61
  56. package/std/net/handler.ts +278 -80
  57. package/std/net/hpack.ts +262 -52
  58. package/std/net/http-compress.ts +125 -15
  59. package/std/net/http-fields.ts +85 -9
  60. package/std/net/http1-client-codec.ts +100 -19
  61. package/std/net/http1-codec.ts +235 -27
  62. package/std/net/http1-server.ts +343 -85
  63. package/std/net/http2-frame.ts +272 -35
  64. package/std/net/http2-tls.ts +135 -34
  65. package/std/net/http2.ts +247 -106
  66. package/std/net/http3-frame.ts +154 -17
  67. package/std/net/http3-server.ts +246 -96
  68. package/std/net/http3.ts +307 -115
  69. package/std/net/outbound.ts +37 -3
  70. package/std/net/postgres-carrier.ts +144 -8
  71. package/std/net/postgres.ts +723 -103
  72. package/std/net/prefork.ts +164 -31
  73. package/std/net/qpack.ts +105 -18
  74. package/std/net/quic-conn-ack.ts +59 -12
  75. package/std/net/quic-conn-cid.ts +124 -27
  76. package/std/net/quic-conn-params.ts +70 -10
  77. package/std/net/quic-datagram.ts +43 -3
  78. package/std/net/quic-frame.ts +286 -12
  79. package/std/net/quic-listener.ts +101 -32
  80. package/std/net/quic-packet.ts +302 -21
  81. package/std/net/quic-recovery.ts +228 -44
  82. package/std/net/quic-stream.ts +353 -91
  83. package/std/net/quic.ts +489 -171
  84. package/std/net/router.ts +87 -40
  85. package/std/net/tls/client.ts +166 -51
  86. package/std/net/tls/codec.ts +413 -56
  87. package/std/net/tls/record-client.ts +110 -55
  88. package/std/net/tls/record-server.ts +159 -59
  89. package/std/net/tls/record.ts +109 -12
  90. package/std/net/tls/schedule.ts +235 -26
  91. package/std/net/tls/ticket.ts +159 -40
  92. package/std/net/tls/verify.ts +49 -3
  93. package/std/net/tls-tcp.ts +250 -45
  94. package/std/net/tls.ts +221 -59
  95. package/std/net/upstream.ts +81 -45
  96. package/std/net/url.ts +97 -13
  97. package/std/net/websocket.ts +122 -12
  98. package/std/net/webtransport.ts +220 -89
  99. package/std/pair.ts +10 -2
  100. package/std/random.ts +34 -9
  101. package/std/regex.ts +352 -198
  102. package/std/region.ts +70 -15
  103. package/std/secret.ts +52 -11
  104. package/std/sort.ts +17 -2
  105. package/std/sqlite.ts +256 -35
  106. package/std/sync/ring.ts +205 -35
  107. package/std/sync/shm.ts +194 -16
  108. package/std/term-io.ts +137 -64
  109. package/std/term-pixels.ts +144 -19
  110. package/std/term-probe.ts +66 -25
  111. package/std/term-rate.ts +128 -57
  112. package/std/term.ts +332 -121
  113. package/std/testing.ts +130 -32
  114. package/std/text.ts +73 -7
  115. package/std/threads.ts +229 -41
  116. package/std/yaml-json.ts +94 -82
  117. package/std/yaml-lines.ts +47 -15
  118. package/std/yaml-write.ts +24 -16
  119. package/std/yaml.ts +764 -384
package/std/term.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * `std/term` — a terminal drawn as a grid of coloured cells, and the keys a
2
+ * `nish/term` — a terminal drawn as a grid of coloured cells, and the keys a
3
3
  * terminal sends turned into events.
4
4
  *
5
5
  * import { Screen, Canvas, rgb, COLOR_DEFAULT, enterAltScreen, hideCursor } from "nish/term";
@@ -412,7 +412,14 @@ const termLeadBits = (c: i32, width: i32): i32 => {
412
412
  return width === 3 ? c & 15 : c & 7
413
413
  }
414
414
 
415
- /** The colour with red, green and blue each in 0–255, as `0xRRGGBB`; a component outside is clamped. */
415
+ /**
416
+ * A colour from its red, green and blue.
417
+ *
418
+ * @param r Red, 0–255; a value outside is clamped.
419
+ * @param g Green, 0–255; a value outside is clamped.
420
+ * @param b Blue, 0–255; a value outside is clamped.
421
+ * @returns The colour as `0xRRGGBB`, for any `fg`, `bg` or pixel.
422
+ */
416
423
  export const rgb = (r: i32, g: i32, b: i32): i32 =>
417
424
  (termClamp(r, 0, 255) << 16) | (termClamp(g, 0, 255) << 8) | termClamp(b, 0, 255)
418
425
 
@@ -431,9 +438,11 @@ const termCubeLevel = (v: i32): i32 => {
431
438
  const termCubeValue = (q: i32): i32 => (q === 0 ? 0 : q * 40 + 55)
432
439
 
433
440
  /**
434
- * The 256-colour palette index nearest `colour`: one of the 6×6×6 cube
435
- * (16–231) or of the 24 greys (232–255), whichever is closer in RGB.
436
- * `COLOR_DEFAULT` stays itself.
441
+ * The 256-colour palette entry nearest a colour: one of the 6×6×6 cube (16–231)
442
+ * or of the 24 greys (232–255), whichever is closer in RGB.
443
+ *
444
+ * @param colour An `0xRRGGBB` colour, or `COLOR_DEFAULT`.
445
+ * @returns The palette index; `COLOR_DEFAULT` stays itself.
437
446
  */
438
447
  export const paletteIndex = (colour: i32): i32 => {
439
448
  if (colour < 0) {
@@ -460,35 +469,73 @@ export const paletteIndex = (colour: i32): i32 => {
460
469
  return greyDistance < cubeDistance ? step + 232 : cube
461
470
  }
462
471
 
463
- /** Switch to the alternate screen, which the terminal restores the old contents from on leaving. */
472
+ /**
473
+ * Switch to the alternate screen, which the terminal restores the old contents
474
+ * from on leaving.
475
+ *
476
+ * @returns The escape sequence, to `write`.
477
+ */
464
478
  export const enterAltScreen = (): string => "\x1b[?1049h"
465
479
 
466
- /** Leave the alternate screen and show what was there before `enterAltScreen`. */
480
+ /**
481
+ * Leave the alternate screen and show what was there before `enterAltScreen`.
482
+ *
483
+ * @returns The escape sequence, to `write`.
484
+ */
467
485
  export const leaveAltScreen = (): string => "\x1b[?1049l"
468
486
 
469
- /** Hide the cursor, so a redraw does not flicker it across the screen. */
487
+ /**
488
+ * Hide the cursor, so a redraw does not flicker it across the screen.
489
+ *
490
+ * @returns The escape sequence, to `write`.
491
+ */
470
492
  export const hideCursor = (): string => "\x1b[?25l"
471
493
 
472
- /** Show the cursor again. */
494
+ /**
495
+ * Show the cursor again.
496
+ *
497
+ * @returns The escape sequence, to `write`.
498
+ */
473
499
  export const showCursor = (): string => "\x1b[?25h"
474
500
 
475
- /** Move the cursor home and erase the whole screen; a `Screen` that was drawn on wants `invalidate` after it. */
501
+ /**
502
+ * Move the cursor home and erase the whole screen; a `Screen` that was drawn on
503
+ * wants `invalidate` after it.
504
+ *
505
+ * @returns The escape sequences, to `write`.
506
+ */
476
507
  export const clearScreen = (): string => "\x1b[H\x1b[2J"
477
508
 
478
- /** Reset colour and attributes to the terminal's defaults: SGR 0. */
509
+ /**
510
+ * Reset colour and attributes to the terminal's defaults: SGR 0.
511
+ *
512
+ * @returns The escape sequence, to `write`.
513
+ */
479
514
  export const resetStyle = (): string => "\x1b[0m"
480
515
 
481
- /** Move the cursor to column `x`, row `y`, both from 0. */
516
+ /**
517
+ * Move the cursor to a cell.
518
+ *
519
+ * @param x The column, from 0 at the left.
520
+ * @param y The row, from 0 at the top.
521
+ * @returns The escape sequence, to `write`.
522
+ */
482
523
  export const moveCursor = (x: i32, y: i32): string => `\x1b[${y + 1};${x + 1}H`
483
524
 
484
525
  /**
485
526
  * Begin a synchronized update (DEC mode 2026): a terminal that knows the mode
486
527
  * holds what follows until `endSync`, then paints it in one go, so a frame is
487
528
  * never seen half drawn. One that does not ignores it.
529
+ *
530
+ * @returns The escape sequence, to `write`.
488
531
  */
489
532
  export const beginSync = (): string => "\x1b[?2026h"
490
533
 
491
- /** End a synchronized update, so the terminal paints what `beginSync` held. */
534
+ /**
535
+ * End a synchronized update, so the terminal paints what `beginSync` held.
536
+ *
537
+ * @returns The escape sequence, to `write`.
538
+ */
492
539
  export const endSync = (): string => "\x1b[?2026l"
493
540
 
494
541
  /**
@@ -598,30 +645,34 @@ export class Screen {
598
645
  /** The frame's attributes, laid out as `glyphs`: `ATTR_BOLD` and `ATTR_INVERSE`, or'd. */
599
646
  attrs: i32[]
600
647
  /** The code points the terminal was last sent; -1 is a cell not yet sent. */
601
- sentGlyphs: i32[]
648
+ private sentGlyphs: i32[]
602
649
  /** The foregrounds the terminal was last sent. */
603
- sentFgs: i32[]
650
+ private sentFgs: i32[]
604
651
  /** The backgrounds the terminal was last sent. */
605
- sentBgs: i32[]
652
+ private sentBgs: i32[]
606
653
  /** The attributes the terminal was last sent. */
607
- sentAttrs: i32[]
654
+ private sentAttrs: i32[]
608
655
  /** The bytes `flush` builds, sized by `resize` and reused from frame to frame. */
609
- out: u8[]
656
+ private out: u8[]
610
657
  /** Columns. */
611
658
  width: i32
612
659
  /** Rows. */
613
660
  height: i32
614
661
  /** How many of `out` the flush in progress has written. */
615
- outLen: i32
662
+ private outLen: i32
616
663
  /** Whether colours go out as 256-colour palette indices rather than 24-bit RGB. */
617
664
  palette256: boolean
618
665
  /** Whether a `flush` that changes anything is wrapped in `beginSync` and `endSync`; off until set. */
619
666
  sync: boolean
620
667
 
621
668
  /**
622
- * A `width × height` screen of blank cells in the terminal's colours, none
623
- * of them sent yet, so the first `flush` draws them all. With `palette256`
624
- * set, every colour is sent as its nearest 256-colour index (`paletteIndex`).
669
+ * A screen of blank cells in the terminal's colours, none of them sent yet,
670
+ * so the first `flush` draws them all.
671
+ *
672
+ * @param width Columns, as the terminal reports them.
673
+ * @param height Rows, as the terminal reports them.
674
+ * @param palette256 Whether to send every colour as its nearest 256-colour index
675
+ * (`paletteIndex`), for a terminal without 24-bit colour.
625
676
  */
626
677
  constructor(width: i32, height: i32, palette256: boolean) {
627
678
  this.width = width < 0 ? 0 : width
@@ -642,10 +693,13 @@ export class Screen {
642
693
  }
643
694
 
644
695
  /**
645
- * Make the screen `width × height`, blank and unsent: a terminal that changed
646
- * size is redrawn in full. Each side is at most 4,096 cells and the screen at
647
- * most 1,048,576, rows dropped to fit, so no size a terminal reports makes it
696
+ * Make the screen a new size, blank and unsent: a terminal that changed size
697
+ * is redrawn in full. Each side is at most 4,096 cells and the screen at most
698
+ * 1,048,576, rows dropped to fit, so no size a terminal reports makes it
648
699
  * overflow or run out of memory.
700
+ *
701
+ * @param width The new columns.
702
+ * @param height The new rows.
649
703
  */
650
704
  resize(width: i32, height: i32): void {
651
705
  this.width = termClamp(width, 0, TERM_MAX_SIDE)
@@ -669,7 +723,11 @@ export class Screen {
669
723
  this.invalidate()
670
724
  }
671
725
 
672
- /** Blank every cell of the frame being drawn: a space on `background`, default foreground, no attributes. */
726
+ /**
727
+ * Blank every cell of the frame being drawn.
728
+ *
729
+ * @param background The colour each cell's space is drawn on; the foreground is the default and no attribute is set.
730
+ */
673
731
  clear(background: i32): void {
674
732
  this.glyphs.fill(TERM_SPACE)
675
733
  this.fgs.fill(COLOR_DEFAULT)
@@ -686,9 +744,17 @@ export class Screen {
686
744
  }
687
745
 
688
746
  /**
689
- * Draw code point `glyph` at column `x`, row `y`; a cell off the screen is
690
- * not drawn. Bits of `attrs` other than `ATTR_BOLD` and `ATTR_INVERSE` are
691
- * dropped, so `flush` never has an attribute it cannot write.
747
+ * Draw one character in a cell; a cell off the screen is not drawn.
748
+ *
749
+ * @param x The column, from 0.
750
+ * @param y The row, from 0.
751
+ * @param glyph The character's code point, taken to be one column wide. A C0 or C1 control, DEL,
752
+ * a surrogate or a value that is no code point is sent as U+FFFD, so a cell cannot move the
753
+ * cursor or open an escape.
754
+ * @param fg The character's colour, `0xRRGGBB` or `COLOR_DEFAULT`.
755
+ * @param bg The cell's colour behind it, `0xRRGGBB` or `COLOR_DEFAULT`.
756
+ * @param attrs `ATTR_BOLD` and `ATTR_INVERSE` bits; any other bit is dropped, so `flush` never
757
+ * has an attribute it cannot write.
692
758
  */
693
759
  set(x: i32, y: i32, glyph: i32, fg: i32, bg: i32, attrs: i32): void {
694
760
  if (x < 0 || y < 0 || x >= this.width || y >= this.height) {
@@ -705,8 +771,15 @@ export class Screen {
705
771
  }
706
772
 
707
773
  /**
708
- * Draw `s` from column `x` of row `y`, one cell per character, clipped at
709
- * the edges, and answer the column after its last character.
774
+ * Draw a string along a row, one cell per character, clipped at the edges.
775
+ *
776
+ * @param x The column of the first character, from 0; it may be off the screen.
777
+ * @param y The row, from 0.
778
+ * @param s The text. A control character in it, a line break included, takes a cell and is sent as U+FFFD.
779
+ * @param fg The characters' colour.
780
+ * @param bg The colour behind them.
781
+ * @param attrs `ATTR_BOLD` and `ATTR_INVERSE` bits, as `set` takes them.
782
+ * @returns The column after the last character, `x` plus the characters in `s`, whether or not they were clipped.
710
783
  */
711
784
  text(x: i32, y: i32, s: string, fg: i32, bg: i32, attrs: i32): i32 {
712
785
  const n: i32 = toI32(s.length)
@@ -720,7 +793,13 @@ export class Screen {
720
793
  return column
721
794
  }
722
795
 
723
- /** The code point drawn at column `x`, row `y` of the frame being drawn, or -1 off the screen. */
796
+ /**
797
+ * What the frame being drawn holds in a cell.
798
+ *
799
+ * @param x The column, from 0.
800
+ * @param y The row, from 0.
801
+ * @returns The code point drawn there, or -1 off the screen.
802
+ */
724
803
  glyphAt(x: i32, y: i32): i32 {
725
804
  if (x < 0 || y < 0 || x >= this.width || y >= this.height) {
726
805
  return -1
@@ -729,13 +808,13 @@ export class Screen {
729
808
  }
730
809
 
731
810
  /** Append one byte to the flush in progress; `flush` has reserved the room. */
732
- put(b: i32): void {
811
+ private put(b: i32): void {
733
812
  this.out[this.outLen] = toU8(b)
734
813
  this.outLen = this.outLen + 1
735
814
  }
736
815
 
737
816
  /** Append `v`, at least 0, in decimal: the three digits a colour channel has without recursing. */
738
- putDecimal(v: i32): void {
817
+ private putDecimal(v: i32): void {
739
818
  if (v >= 100) {
740
819
  if (v >= 1000) {
741
820
  this.putDecimal((v / 1000) | 0)
@@ -749,7 +828,7 @@ export class Screen {
749
828
  }
750
829
 
751
830
  /** Append `ESC [ ? 2026` and `final`, which sets or resets synchronized output. */
752
- putSyncMode(final: i32): void {
831
+ private putSyncMode(final: i32): void {
753
832
  this.put(TERM_ESC)
754
833
  this.put(TERM_BRACKET)
755
834
  this.put(TERM_PRIVATE)
@@ -763,7 +842,7 @@ export class Screen {
763
842
  * negative number — goes as U+FFFD, so a cell cannot move the cursor, open
764
843
  * an escape or send bytes that are not UTF-8.
765
844
  */
766
- putGlyph(cp: i32): void {
845
+ private putGlyph(cp: i32): void {
767
846
  if (cp >= TERM_SPACE && cp < TERM_DELETE) {
768
847
  this.put(cp)
769
848
  } else if (cp >= 160 && cp < 2048) {
@@ -783,7 +862,7 @@ export class Screen {
783
862
  }
784
863
 
785
864
  /** Append the SGR parameters for colour `key` (an RGB or a palette index) on base 30 (foreground) or 40. */
786
- putColour(base: i32, key: i32): void {
865
+ private putColour(base: i32, key: i32): void {
787
866
  if (key < 0) {
788
867
  this.putDecimal(base + 9)
789
868
  return
@@ -807,7 +886,7 @@ export class Screen {
807
886
  }
808
887
 
809
888
  /** The value a colour is sent as and compared by: itself, or its palette index under `palette256`. */
810
- colourKey(colour: i32): i32 {
889
+ private colourKey(colour: i32): i32 {
811
890
  if (colour < 0) {
812
891
  return COLOR_DEFAULT
813
892
  }
@@ -815,20 +894,21 @@ export class Screen {
815
894
  }
816
895
 
817
896
  /**
818
- * The escapes and glyphs that turn the frame last sent into the frame drawn,
819
- * and the drawn frame becomes the sent one. Write the answer with `write`;
820
- * an empty string means nothing changed.
897
+ * Turn the frame last sent into the frame drawn, and make the drawn frame the
898
+ * sent one.
821
899
  *
822
900
  * Changed cells are visited row by row. The cursor is moved only when it is
823
901
  * not already at the cell — `ESC [ n C` along the row, `ESC [ row ; col H`
824
902
  * otherwise — and a gap of up to three unchanged ASCII cells in the current
825
- * style is rewritten instead, which is shorter than the move. A style is
826
- * sent only when it differs from the previous cell's, and only the parts
827
- * that differ, from a reset when an attribute has to be turned off. A flush
828
- * that leaves the terminal in a style other than the default ends with
829
- * `ESC [ 0 m`, so what the caller writes next starts plain. With `sync` set,
830
- * a flush that changes anything is wrapped in `beginSync` and `endSync`, in
831
- * the same string, so the terminal paints the frame whole.
903
+ * style is rewritten instead, which is shorter than the move. A style is sent
904
+ * only when it differs from the previous cell's, and only the parts that
905
+ * differ, from a reset when an attribute has to be turned off. A flush that
906
+ * leaves the terminal in a style other than the default ends with `ESC [ 0
907
+ * m`, so what the caller writes next starts plain. With `sync` set, a flush
908
+ * that changes anything is wrapped in `beginSync` and `endSync`, in the same
909
+ * string, so the terminal paints the frame whole.
910
+ *
911
+ * @returns The escapes and glyphs, to `write`; `""` when nothing changed.
832
912
  */
833
913
  flush(): string {
834
914
  const w: i32 = this.width
@@ -1021,7 +1101,12 @@ export class Canvas {
1021
1101
  /** One colour per pixel, row by row. */
1022
1102
  pixels: i32[]
1023
1103
 
1024
- /** A canvas of `screen`'s size, every pixel `COLOR_DEFAULT`. Make a new one after the screen is resized. */
1104
+ /**
1105
+ * A canvas of `screen`'s size, every pixel `COLOR_DEFAULT`. Make a new one
1106
+ * after the screen is resized.
1107
+ *
1108
+ * @param screen The screen it draws on, two pixels to a cell, one above the other.
1109
+ */
1025
1110
  constructor(screen: Screen) {
1026
1111
  this.screen = screen
1027
1112
  this.width = screen.width
@@ -1030,7 +1115,11 @@ export class Canvas {
1030
1115
  this.pixels.fill(COLOR_DEFAULT)
1031
1116
  }
1032
1117
 
1033
- /** Set every pixel to `colour`. */
1118
+ /**
1119
+ * Set every pixel to one colour.
1120
+ *
1121
+ * @param colour The colour, `0xRRGGBB` or `COLOR_DEFAULT` for none.
1122
+ */
1034
1123
  clear(colour: i32): void {
1035
1124
  this.pixels.fill(colour)
1036
1125
  const rows: i32 = this.height >> 1
@@ -1041,7 +1130,13 @@ export class Canvas {
1041
1130
  }
1042
1131
  }
1043
1132
 
1044
- /** The colour of the pixel at `x`, `y`, or `COLOR_DEFAULT` off the canvas. */
1133
+ /**
1134
+ * What colour a pixel is.
1135
+ *
1136
+ * @param x The pixel column, from 0.
1137
+ * @param y The pixel row, from 0; two to a screen row.
1138
+ * @returns The colour, or `COLOR_DEFAULT` off the canvas.
1139
+ */
1045
1140
  pixel(x: i32, y: i32): i32 {
1046
1141
  if (x < 0 || y < 0 || x >= this.width || y >= this.height) {
1047
1142
  return COLOR_DEFAULT
@@ -1049,7 +1144,13 @@ export class Canvas {
1049
1144
  return this.pixels[y * this.width + x]
1050
1145
  }
1051
1146
 
1052
- /** Set the pixel at `x`, `y` to `colour`; a pixel off the canvas is not drawn. */
1147
+ /**
1148
+ * Set one pixel; a pixel off the canvas is not drawn.
1149
+ *
1150
+ * @param x The pixel column, from 0.
1151
+ * @param y The pixel row, from 0; two to a screen row.
1152
+ * @param colour The colour, `0xRRGGBB` or `COLOR_DEFAULT` for none.
1153
+ */
1053
1154
  setPixel(x: i32, y: i32, colour: i32): void {
1054
1155
  if (x < 0 || y < 0 || x >= this.width || y >= this.height) {
1055
1156
  return
@@ -1058,7 +1159,15 @@ export class Canvas {
1058
1159
  this.paintCell(x, y >> 1)
1059
1160
  }
1060
1161
 
1061
- /** Fill the `w × h` rectangle whose top-left pixel is `x`, `y`, clipped to the canvas. */
1162
+ /**
1163
+ * Fill a rectangle, clipped to the canvas.
1164
+ *
1165
+ * @param x The top-left pixel's column.
1166
+ * @param y The top-left pixel's row.
1167
+ * @param w The width in pixels; 0 or less fills nothing.
1168
+ * @param h The height in pixels; 0 or less fills nothing.
1169
+ * @param colour The colour, `0xRRGGBB` or `COLOR_DEFAULT` for none.
1170
+ */
1062
1171
  fillRect(x: i32, y: i32, w: i32, h: i32, colour: i32): void {
1063
1172
  const left: i32 = x < 0 ? 0 : x
1064
1173
  const top: i32 = y < 0 ? 0 : y
@@ -1077,9 +1186,15 @@ export class Canvas {
1077
1186
  }
1078
1187
 
1079
1188
  /**
1080
- * Draw a line from `x0`, `y0` to `x1`, `y1`, both ends included (Bresenham's).
1081
- * Any `i32` ends will do: the walk stops once it leaves the canvas for good,
1082
- * though one that starts far outside steps all the way in.
1189
+ * Draw a line, both ends included (Bresenham's). Any `i32` ends will do: the
1190
+ * walk stops once it leaves the canvas for good, though one that starts far
1191
+ * outside steps all the way in.
1192
+ *
1193
+ * @param x0 The first end's pixel column.
1194
+ * @param y0 The first end's pixel row.
1195
+ * @param x1 The other end's pixel column.
1196
+ * @param y1 The other end's pixel row.
1197
+ * @param colour The colour, `0xRRGGBB` or `COLOR_DEFAULT` for none.
1083
1198
  */
1084
1199
  line(x0: i32, y0: i32, x1: i32, y1: i32, colour: i32): void {
1085
1200
  // The error terms are f64, exact here, because a span past 2^30 overflows `2 * err` in i32.
@@ -1117,9 +1232,15 @@ export class Canvas {
1117
1232
  }
1118
1233
 
1119
1234
  /**
1120
- * Draw `s` in cells from column `col` of cell row `row` in `fg`, each
1121
- * character on the colour of the pixels behind it (the top one, or the
1122
- * bottom one where the top is unset), and answer the column after it.
1235
+ * Draw a string in screen cells over the pixels, each character on the colour
1236
+ * of the pixels behind it (the top one, or the bottom one where the top is
1237
+ * unset).
1238
+ *
1239
+ * @param col The cell column of the first character, from 0.
1240
+ * @param row The cell row, from 0: pixel rows `2 * row` and `2 * row + 1`.
1241
+ * @param s The text.
1242
+ * @param fg The characters' colour.
1243
+ * @returns The column after the last character, whether or not it was clipped.
1123
1244
  */
1124
1245
  text(col: i32, row: i32, s: string, fg: i32): i32 {
1125
1246
  const n: i32 = toI32(s.length)
@@ -1135,7 +1256,10 @@ export class Canvas {
1135
1256
  return column
1136
1257
  }
1137
1258
 
1138
- /** Redraw the screen cell at `col`, `row` from its two pixels. */
1259
+ /**
1260
+ * Redraw the screen cell at `col`, `row` from its two pixels.
1261
+ * @internal Called by `drawHalfBlocks` in term-pixels.ts.
1262
+ */
1139
1263
  paintCell(col: i32, row: i32): void {
1140
1264
  const top: i32 = this.pixel(col, row * 2)
1141
1265
  const bottom: i32 = this.pixel(col, row * 2 + 1)
@@ -1156,7 +1280,12 @@ export class KeyEvent {
1156
1280
  /** The character's code point, the control byte, or the escape sequence's final byte. */
1157
1281
  code: i32
1158
1282
 
1159
- /** The event of kind `kind` with code `code`. */
1283
+ /**
1284
+ * A key event.
1285
+ *
1286
+ * @param kind One of the `KEY_` constants.
1287
+ * @param code The code point for `KEY_CHAR`, otherwise the byte that named the key.
1288
+ */
1160
1289
  constructor(kind: i32, code: i32) {
1161
1290
  this.kind = kind
1162
1291
  this.code = code
@@ -1205,7 +1334,11 @@ export class TermEvent {
1205
1334
  /** For `EVENT_FOCUS`, whether the terminal gained focus. */
1206
1335
  gained: boolean
1207
1336
 
1208
- /** An event of type `type` with every other field at its default. */
1337
+ /**
1338
+ * An event with every field but its type at its default.
1339
+ *
1340
+ * @param type One of the `EVENT_` constants.
1341
+ */
1209
1342
  constructor(type: i32) {
1210
1343
  this.type = type
1211
1344
  this.key = 0
@@ -1249,10 +1382,13 @@ export class KeyDecoder {
1249
1382
  /** How long a held ESC waits for the rest of a sequence, in milliseconds. */
1250
1383
  escapeTimeoutMs: f64
1251
1384
  /** The bytes of an unfinished sequence, carried to the next call. */
1252
- pending: u8[]
1385
+ private pending: u8[]
1253
1386
  /** When the first held byte arrived (`feed`), or the last (`feedEvents`). */
1254
- pendingSince: f64
1255
- /** The bytes of the paste so far. */
1387
+ private pendingSince: f64
1388
+ /**
1389
+ * The bytes of the paste so far.
1390
+ * @internal Used by `termDecodePaste` and `termCsiEvent`.
1391
+ */
1256
1392
  pasteBytes: u8[]
1257
1393
  /**
1258
1394
  * How many cursor position reports (`ESC [ 6 n`) are awaited. `ESC [ r ; c R`
@@ -1266,10 +1402,18 @@ export class KeyDecoder {
1266
1402
  cellHeightPx: i32
1267
1403
  /** Whether SGR mouse reports are in pixels (mode 1016), so `px` and `py` are set and `x`, `y` derived. */
1268
1404
  pixelMouse: boolean
1269
- /** Whether a bracketed paste has begun and not ended. */
1405
+ /**
1406
+ * Whether a bracketed paste has begun and not ended.
1407
+ * @internal Used by `termDecodePaste`, `termCsiEvent` and `termDecodeEvents`.
1408
+ */
1270
1409
  pasting: boolean
1271
1410
 
1272
- /** A decoder that gives up on an unfinished sequence after `escapeTimeoutMs` (25–50 is usual). */
1411
+ /**
1412
+ * A decoder with nothing held.
1413
+ *
1414
+ * @param escapeTimeoutMs How long an unfinished sequence is held before it is given up, in
1415
+ * milliseconds; 25–50 is usual.
1416
+ */
1273
1417
  constructor(escapeTimeoutMs: f64) {
1274
1418
  this.escapeTimeoutMs = escapeTimeoutMs
1275
1419
  this.pending = []
@@ -1282,15 +1426,25 @@ export class KeyDecoder {
1282
1426
  this.pasteBytes = []
1283
1427
  }
1284
1428
 
1285
- /** Whether bytes are held, so the caller should `poll` once the timeout has passed. */
1429
+ /**
1430
+ * Whether bytes are held, so the caller should `poll` once the timeout has
1431
+ * passed.
1432
+ *
1433
+ * @returns True while the bytes of an unfinished sequence are held.
1434
+ */
1286
1435
  waiting(): boolean {
1287
1436
  return toI32(this.pending.length) > 0
1288
1437
  }
1289
1438
 
1290
1439
  /**
1291
- * The keys in `bytes[0, count)`, read at time `nowMs`, after whatever was
1292
- * held: held bytes older than the timeout are given up first, as keys of
1293
- * their own, and the rest continue into these.
1440
+ * Decode what was read, after whatever was held: held bytes older than the
1441
+ * timeout are given up first, as keys of their own, and the rest continue
1442
+ * into these.
1443
+ *
1444
+ * @param bytes The buffer the read filled.
1445
+ * @param count How many of its bytes the read filled, from the start.
1446
+ * @param nowMs When the bytes were read, on the clock `poll` is given.
1447
+ * @returns The keys, in the order they were typed; an unfinished sequence at the end is held.
1294
1448
  */
1295
1449
  feed(bytes: u8[], count: i32, nowMs: f64): KeyEvent[] {
1296
1450
  const events: KeyEvent[] = this.poll(nowMs)
@@ -1305,7 +1459,12 @@ export class KeyDecoder {
1305
1459
  return events
1306
1460
  }
1307
1461
 
1308
- /** The keys held bytes become once `escapeTimeoutMs` has passed since they arrived: none before then. */
1462
+ /**
1463
+ * Give up held bytes once the timeout has passed since they arrived.
1464
+ *
1465
+ * @param nowMs The time now, on the clock `feed` was given.
1466
+ * @returns The keys the held bytes become, or none before the timeout.
1467
+ */
1309
1468
  poll(nowMs: f64): KeyEvent[] {
1310
1469
  const events: KeyEvent[] = []
1311
1470
  const held: i32 = toI32(this.pending.length)
@@ -1318,9 +1477,14 @@ export class KeyDecoder {
1318
1477
  }
1319
1478
 
1320
1479
  /**
1321
- * The events in `bytes[0, count)`, read at time `nowMs`, after whatever was
1322
- * held, as `feed` takes them. The timeout counts from the last byte that
1323
- * arrived, so a reply split across reads is not given up halfway.
1480
+ * Decode what was read into events of every kind, after whatever was held, as
1481
+ * `feed` takes them. The timeout counts from the last byte that arrived, so a
1482
+ * reply split across reads is not given up halfway.
1483
+ *
1484
+ * @param bytes The buffer the read filled.
1485
+ * @param count How many of its bytes the read filled, from the start.
1486
+ * @param nowMs When the bytes were read, on the clock `pollEvents` is given.
1487
+ * @returns The events, in the order they were sent; an unfinished sequence or paste at the end is held.
1324
1488
  */
1325
1489
  feedEvents(bytes: u8[], count: i32, nowMs: f64): TermEvent[] {
1326
1490
  const events: TermEvent[] = this.pollEvents(nowMs)
@@ -1335,9 +1499,12 @@ export class KeyDecoder {
1335
1499
  }
1336
1500
 
1337
1501
  /**
1338
- * The events held bytes become once `escapeTimeoutMs` has passed: an ESC as
1339
- * `KEY_ESCAPE`, an unterminated DCS, APC or OSC as nothing. A paste waits
1340
- * for its end however long it takes.
1502
+ * Give up held bytes once the timeout has passed: an ESC as `KEY_ESCAPE`, an
1503
+ * unterminated DCS, APC or OSC as nothing. A paste waits for its end however
1504
+ * long it takes.
1505
+ *
1506
+ * @param nowMs The time now, on the clock `feedEvents` was given.
1507
+ * @returns The events the held bytes become, or none before the timeout.
1341
1508
  */
1342
1509
  pollEvents(nowMs: f64): TermEvent[] {
1343
1510
  const events: TermEvent[] = []
@@ -1351,7 +1518,7 @@ export class KeyDecoder {
1351
1518
  }
1352
1519
 
1353
1520
  /** The held bytes followed by `bytes[0, count)`. */
1354
- merged(bytes: u8[], count: i32): u8[] {
1521
+ private merged(bytes: u8[], count: i32): u8[] {
1355
1522
  const held: i32 = toI32(this.pending.length)
1356
1523
  const n: i32 = termClamp(count, 0, toI32(bytes.length))
1357
1524
  const work: u8[] = new Array<u8>(held + n)
@@ -1366,7 +1533,7 @@ export class KeyDecoder {
1366
1533
  }
1367
1534
 
1368
1535
  /** Hold `work` from `used` on; when `restart` is set, the held bytes count as arriving at `nowMs`. */
1369
- keep(work: u8[], used: i32, restart: boolean, nowMs: f64): void {
1536
+ private keep(work: u8[], used: i32, restart: boolean, nowMs: f64): void {
1370
1537
  const rest: u8[] = []
1371
1538
  for (let k: i32 = used; k < toI32(work.length); k++) {
1372
1539
  if (!(k >= 0)) {
@@ -1407,17 +1574,22 @@ export class KeyState {
1407
1574
  firstRepeatMs: f64
1408
1575
  /** The latest send time of an answered query that `delivered` was given: everything the terminal generated before it has arrived. */
1409
1576
  watermarkMs: f64
1410
- /** The keys down, each as `termKeyId` names it. */
1577
+ /**
1578
+ * The keys down, each as `termKeyId` names it.
1579
+ * @internal Used by `Terminal` in term-io.ts.
1580
+ */
1411
1581
  downKeys: i32[]
1412
1582
  /** When each key down last pressed or repeated. */
1413
- downSince: f64[]
1583
+ private downSince: f64[]
1414
1584
  /** Whether each key down has repeated. */
1415
- downRepeated: boolean[]
1585
+ private downRepeated: boolean[]
1416
1586
  /** The code each key down last came with, which its synthesized release carries. */
1417
- downCodes: i32[]
1587
+ private downCodes: i32[]
1418
1588
  /** The `MOD_` bits each key down last came with, which its synthesized release carries. */
1419
- downMods: i32[]
1420
- /** Whether releases are made up from silence; false from the first real release, or when the caller knows kitty flag 2 is on. */
1589
+ private downMods: i32[]
1590
+ /**
1591
+ * Whether releases are made up from silence; false from the first real release, or when the caller knows kitty flag 2 is on.
1592
+ */
1421
1593
  releasesAreSynthetic: boolean
1422
1594
  /** Whether silence is measured against `watermarkMs` rather than the clock; set by `delivered`, which the caller may clear when answers stop. */
1423
1595
  watermarked: boolean
@@ -1440,27 +1612,33 @@ export class KeyState {
1440
1612
  }
1441
1613
 
1442
1614
  /**
1443
- * Whether the key of kind `key` is down. `code` tells a `KEY_CHAR`,
1444
- * `KEY_CONTROL` or `KEY_UNKNOWN` apart and is ignored for the rest; a
1445
- * letter is the same key in either case, since Shift changes the code a
1446
- * terminal sends.
1615
+ * Whether a key is down. A letter is the same key in either case, since Shift
1616
+ * changes the code a terminal sends.
1617
+ *
1618
+ * @param key The key's `KEY_` kind.
1619
+ * @param code Tells a `KEY_CHAR`, `KEY_CONTROL` or `KEY_UNKNOWN` apart, as `TermEvent.code` does;
1620
+ * ignored for the other kinds.
1621
+ * @returns True from the key's press until its release, real or synthetic, or a loss of focus.
1447
1622
  */
1448
1623
  isDown(key: i32, code: i32): boolean {
1449
1624
  return this.find(termKeyId(key, code)) >= 0
1450
1625
  }
1451
1626
 
1452
1627
  /**
1453
- * Take `events`, which arrived at `nowMs`, and answer what the program
1454
- * should see: first the releases `tick` makes for the keys `events` does
1455
- * not mention (a held key's repeats can wait in a read longer than the
1456
- * gap), then each event, with
1457
- * Ctrl-C as `EVENT_QUIT` (its repeats and release dropped) and a press of a
1458
- * key already down marked `ACTION_REPEAT` while releases are synthetic.
1459
- * A real release of a key not down is dropped: it was let go already, made
1460
- * up from silence or by losing focus. Losing focus lets every key go, since
1461
- * its release goes elsewhere. A non-finite `nowMs` releases nothing; a key
1462
- * it presses keeps its last time, and a new one is timed from the watermark
1463
- * (0 without one).
1628
+ * Take the events of one read and answer what the program should see: first
1629
+ * the releases `tick` makes for the keys the events do not mention (a held
1630
+ * key's repeats can wait in a read longer than the gap), then each event,
1631
+ * with Ctrl-C as `EVENT_QUIT` (its repeats and release dropped) and a press
1632
+ * of a key already down marked `ACTION_REPEAT` while releases are synthetic.
1633
+ *
1634
+ * A real release of a key not down is dropped: it was let go already, made up
1635
+ * from silence or by losing focus. Losing focus lets every key go, since its
1636
+ * release goes elsewhere.
1637
+ *
1638
+ * @param events The events, as `KeyDecoder.feedEvents` or `pollEvents` gave them.
1639
+ * @param nowMs When they arrived. A non-finite time releases nothing; a key it presses keeps its
1640
+ * last time, and a new one is timed from the watermark (0 without one).
1641
+ * @returns The events to act on, in order.
1464
1642
  */
1465
1643
  apply(events: TermEvent[], nowMs: f64): TermEvent[] {
1466
1644
  const out: TermEvent[] = this.releaseDue(nowMs, events)
@@ -1485,10 +1663,11 @@ export class KeyState {
1485
1663
  }
1486
1664
 
1487
1665
  /**
1488
- * Everything the terminal generated before `sentAtMs`, on the caller's
1489
- * clock, has arrived: the answer to an in-order query sent then has come
1490
- * back. From now on silence is measured against the latest such time. A
1491
- * non-finite `sentAtMs` is ignored.
1666
+ * Note that everything the terminal generated before a time has arrived: the
1667
+ * answer to an in-order query sent then has come back. From now on silence is
1668
+ * measured against the latest such time.
1669
+ *
1670
+ * @param sentAtMs When the query was sent, on the caller's clock; a non-finite time is ignored.
1492
1671
  */
1493
1672
  delivered(sentAtMs: f64): void {
1494
1673
  if (!termFinite(sentAtMs)) {
@@ -1501,21 +1680,30 @@ export class KeyState {
1501
1680
  }
1502
1681
 
1503
1682
  /**
1504
- * How long before `nowMs` the latest answered query was sent, or -1 with no
1505
- * watermark: the caller clears `watermarked` once this passes its bound.
1683
+ * How long ago the latest answered query was sent; the caller clears
1684
+ * `watermarked` once this passes its bound.
1685
+ *
1686
+ * @param nowMs The time now, on the clock `delivered` was given.
1687
+ * @returns The milliseconds since that query was sent, or -1 with no watermark.
1506
1688
  */
1507
1689
  deliveredAgoMs(nowMs: f64): f64 {
1508
1690
  return this.watermarked ? nowMs - this.watermarkMs : toF64(-1)
1509
1691
  }
1510
1692
 
1511
- /** The releases due by `nowMs` while releases are synthetic: each key whose gap has passed, let go. */
1693
+ /**
1694
+ * The releases due while releases are synthetic: each key whose gap has
1695
+ * passed, let go.
1696
+ *
1697
+ * @param nowMs The time now, on the clock `apply` was given.
1698
+ * @returns The synthetic releases, one per key let go; none while releases are real.
1699
+ */
1512
1700
  tick(nowMs: f64): TermEvent[] {
1513
1701
  const none: TermEvent[] = []
1514
1702
  return this.releaseDue(nowMs, none)
1515
1703
  }
1516
1704
 
1517
1705
  /** The releases due by `nowMs`, as `tick` makes them, for the keys no key event in `batch` names. */
1518
- releaseDue(nowMs: f64, batch: TermEvent[]): TermEvent[] {
1706
+ private releaseDue(nowMs: f64, batch: TermEvent[]): TermEvent[] {
1519
1707
  const out: TermEvent[] = []
1520
1708
  if (!this.releasesAreSynthetic || !termFinite(nowMs)) {
1521
1709
  return out
@@ -1534,7 +1722,7 @@ export class KeyState {
1534
1722
  }
1535
1723
 
1536
1724
  /** Record key event `e` at `nowMs`; false for a release of a key not down, which `apply` drops. */
1537
- press(e: TermEvent, nowMs: f64): boolean {
1725
+ private press(e: TermEvent, nowMs: f64): boolean {
1538
1726
  const at: i32 = this.find(termKeyId(e.key, e.code))
1539
1727
  if (e.action === ACTION_RELEASE) {
1540
1728
  this.releasesAreSynthetic = false
@@ -1570,7 +1758,7 @@ export class KeyState {
1570
1758
  }
1571
1759
 
1572
1760
  /** Let key `at` go, appending its release to `out`. */
1573
- release(at: i32, out: TermEvent[]): void {
1761
+ private release(at: i32, out: TermEvent[]): void {
1574
1762
  const id: i32 = this.downKeys[at]
1575
1763
  const e: TermEvent = new TermEvent(EVENT_KEY)
1576
1764
  e.key = id >> 21
@@ -1582,7 +1770,7 @@ export class KeyState {
1582
1770
  }
1583
1771
 
1584
1772
  /** Where key `id` is in `downKeys`, or -1. */
1585
- find(id: i32): i32 {
1773
+ private find(id: i32): i32 {
1586
1774
  for (let k: i32 = 0; k < toI32(this.downKeys.length); k++) {
1587
1775
  if (this.downKeys[k] === id) {
1588
1776
  return k
@@ -1592,7 +1780,7 @@ export class KeyState {
1592
1780
  }
1593
1781
 
1594
1782
  /** Drop key `at`, keeping the others in order. */
1595
- remove(at: i32): void {
1783
+ private remove(at: i32): void {
1596
1784
  const last: i32 = toI32(this.downKeys.length) - 1
1597
1785
  for (let k: i32 = at; k < last; k++) {
1598
1786
  this.downKeys[k] = this.downKeys[k + 1]
@@ -1623,16 +1811,32 @@ export class KeyState {
1623
1811
  export class FixedStep {
1624
1812
  /** The length of one step, in milliseconds. */
1625
1813
  stepMs: f64
1626
- /** The time since the last step, in milliseconds, under one step after each `advance`. */
1814
+ /**
1815
+ * The time since the last step, in milliseconds, under one step after each `advance`.
1816
+ * @internal Used by `termIoDue` in term-io.ts.
1817
+ */
1627
1818
  carry: f64
1628
- /** The time the last `advance` was given. */
1819
+ /**
1820
+ * The time the last `advance` was given.
1821
+ * @internal Used by `termIoDue` in term-io.ts.
1822
+ */
1629
1823
  lastMs: f64
1630
1824
  /** The most steps one `advance` answers. */
1631
1825
  maxSteps: i32
1632
- /** Whether `advance` has been called, so `lastMs` is a time. */
1826
+ /**
1827
+ * Whether `advance` has been called, so `lastMs` is a time.
1828
+ * @internal Used by `termIoWait` in term-io.ts.
1829
+ */
1633
1830
  started: boolean
1634
1831
 
1635
- /** A clock of `stepsPerSecond` steps a second (1 at least), running at most `maxSteps` (1 at least) per `advance`. */
1832
+ /**
1833
+ * A clock for a simulation that steps at a fixed rate whatever the frame
1834
+ * rate.
1835
+ *
1836
+ * @param stepsPerSecond The rate; 1 at least.
1837
+ * @param maxSteps The most steps one `advance` answers, 1 at least; time past them is dropped, so
1838
+ * a stall does not have to be caught up.
1839
+ */
1636
1840
  constructor(stepsPerSecond: i32, maxSteps: i32) {
1637
1841
  const rate: i32 = stepsPerSecond < 1 ? 1 : stepsPerSecond
1638
1842
  this.stepMs = 1000.0 / toF64(rate)
@@ -1643,9 +1847,12 @@ export class FixedStep {
1643
1847
  }
1644
1848
 
1645
1849
  /**
1646
- * The steps to run for the time between the last call and `nowMs`. The first
1647
- * call only starts the clock and answers 0, as does a time earlier than the
1648
- * last one.
1850
+ * The steps to run for the time between the last call and now. The first call
1851
+ * only starts the clock and answers 0, as does a time earlier than the last
1852
+ * one.
1853
+ *
1854
+ * @param nowMs The time now, in milliseconds.
1855
+ * @returns How many steps to run, 0 to `maxSteps`.
1649
1856
  */
1650
1857
  advance(nowMs: f64): i32 {
1651
1858
  if (!this.started || !(nowMs >= this.lastMs)) {
@@ -1670,7 +1877,11 @@ export class FixedStep {
1670
1877
  return steps
1671
1878
  }
1672
1879
 
1673
- /** How far into the next step the clock is, from 0 up to but not including 1. */
1880
+ /**
1881
+ * How far into the next step the clock is, for drawing between two steps.
1882
+ *
1883
+ * @returns A fraction from 0 up to but not including 1.
1884
+ */
1674
1885
  alpha(): f64 {
1675
1886
  return this.carry / this.stepMs
1676
1887
  }