twk_core 0.3.0
twk_core: ^0.3.0 copied to clipboard
A terminal rendering core for Dart, with no dependency but meta's annotations: a cell buffer, a damage-driven diff, Unicode segmentation, input and a render tree.
Changelog #
0.3.0 #
Breaking:
BoxConstraintstakes its bounds by name:BoxConstraints(maxWidth: n), a bound left out limiting nothing.minW,maxW,minH,maxH,constrainWandconstrainHareminWidth,maxWidth,minHeight,maxHeight,constrainWidthandconstrainHeight.Flex,Row,Column,Wrap,RenderFlexandRenderWrap:gapandrunGaparespacingandrunSpacing.log,LogLevel,LogRecordandLogSinkmoved fromtwk_core.darttopackage:twk_core/terminal.dart(andpackage:twk/log.dart).AppFrameandShellFramereplace the integer constants ofWire, which keepsprotocolandmaxPayload. The bytes on the wire are unchanged.- A process has one terminal:
Terminal.openon its own stdio throws aTerminalExceptionwhile another is open there and not suspended, andresumewhile another has it. Terminals over a link are independent. - An app in the background stops until it has the terminal:
app &untilfg.timeout ./appstops it too, and it ends at the timeout without opening; usetimeout --foreground ./app.
Added:
TwkApp(maxInputFps:), the cap on frames that input asks for: 120 by default,maxFpsin a remote session or wheremaxFpsis below 60.RenderParagraph.keepsPaint: the paragraph is a repaint boundary that repaints only the rows that differ. It must not be drawn over other objects' glyphs or be the tree's root.RenderParagraph(autoKeepsPaint:), whichTextsets, turns to it at eight rows or more, after layouts that held its size.TextPainter.prepareanddraw, whichpaintis both, andtracksDamagewithchangedRows.TerminalInfo.remote, fromTerminalDeclaration.remoteorSSH_TTYandSSH_CONNECTION.DeclaringLinkandTerminalDeclarationare exported.HeadlessTerminal(remote:)for tests.BoxConstraints.loose,expand,copyWith,loosen,enforce,tighten,deflate,widthConstraintsandheightConstraints,hasTightWidth,hasBoundedWidthandhasInfiniteWidth(and for the height),biggestandsmallest(a({int width, int height})).EdgeInsets.symmetricandEdgeInsets.fromLTRB.RenderList(padding:), anEdgeInsetsaround the items that scrolls with them.StyleTable.nearBlankandStyleTable.ownPen.
Changed:
- Frames keep to a grid of
maxFps; a frame late by a gap or more starts it again. - A frame of a type the receiver does not know is ignored and logged (
twk.wire) on both sides, once a type on a connection. - A welcome or a size frame of the wrong shape ends the link with a
TerminalException, whichSocketLink.connectthrows. - SIGHUP restores the terminal and exits with 129 on Linux and macOS. One the
process was started ignoring (
nohup) stays ignored. kill -TSTPdoes nothing while the app has the terminal on Linux and macOS. Ctrl+Z stops the app for the shell as before.StdioLinkwrites without blocking on Linux and macOS, through a descriptor of its own, and keeps what the terminal does not take.Terminal.closerestores the modes when its terminal took nothing for a second, or after five seconds on a link that can't say.- A repaint boundary's cells do not depend on what was painted in them before: it
fills with its pen.
Canvas.fillkeeps what is under a pen of no foreground. Canvas.mergeRunreturns the columns it advanced and keeps a wide glyph whole.RenderLog.addasks for a frame only when the line can show.- A jump in a
RenderListwith anitemExtenttakes one division. - The presenter writes fewer bytes over blanks and compares fewer cells once rows stop shifting.
Fixed:
- Images on Konsole, in an inline region and in a fixed viewport: pixels left behind, a region not printed again, the saved cursor overwritten, a moved placement keeping its old background.
- A
RenderEffectkeeps a two-column glyph across its edge whole. - A
TextPainterpaints spans given since the layout whether or not a query came first. - A box title with a line break stays whole when its pen changes.
- A
RenderWrapwith no children andspaceAroundno longer divides by zero. bidiMirrorfinds U+1DB03 to U+1DB09.
0.2.0 #
-
On Windows Ctrl+Space (and Ctrl+@) reaches the app as NUL again, as it did through dart:io's stdin: the console's VT input mode makes it the key 2 pressed with Ctrl and no character, which the terminal's own reader of the console left out.
-
On Windows the keys read from the console are encoded to UTF-8 in one pass, where they went through a
String,utf8.encodeand a copy: a read of 512 keys of ASCII, sent to the isolate that listens, takes 2.5 µs where it took 3.9. -
package:twk_core/libc.dart, new: the libc calls twk's packages share on Linux and macOS (pollandPollFd,read,write,pipe,close,ioctlwithfionread,tcgetattrandtcsetattr,callocandfree,errno), bound once with@Nativeand looked up on their first call. The core's reader of the terminal and its raw mode use it, as do twk_term'sPtyand twk's file watch, where each bound its own. The kernel32 calls ofWindowsConsoleandWindowsInputare now bound in one place too, inside the core. -
A
TextPainter(and aRenderParagraph) withmaxLines1 andTextOverflow.ellipsissplits and measures only the head of its text, the first columns its first line shows, and the rest only when asked (a wider layout,minIntrinsicWidth,maxIntrinsicWidth): a line of 20 000 characters cut at the screen's width costs what the screen shows, not the line. What is painted, the size and the answers ofcellAt,textRangeAtandcolumnsOfare as they were. A start or middle ellipsis, a clip and text in visual order with right-to-left characters are laid out from all of it.TextPainter.debugHeadOnlyanddebugForceFullare for tests. -
mayReorder(String)is public: whether a string has a character UAX #9 may draw out of logical order (a right-to-left letter, an Arabic number, a right-to-left embedding, override or isolate), skipping at once the code units below U+0590. The paragraph's layout and the editing fields shared two copies of it, now one. -
Canvas.textandCanvas.runsay in their documentation that they draw the string in stored order, for marks, digits and box glyphs, and that the text of a user goes through aTextPainter, which draws it as it reads in visual order. -
In visual order the
BoxTitles of aRenderDecoratedBoxread as aTextdoes: a right-to-left title was drawn in stored order, and is now drawn by aTextPainterthe box keeps for it, laid out when the room it is shown in or the text order changes, its ellipsis where the paragraph puts it. A title is cut and ellipsized in the same columns as before; the place it is shown in is unchanged. -
breakLines, the lines a text breaks into as a paragraph breaks it. -
An
Alignor aCenteron an axis of any length is as long as its child, as in Flutter: in a scroll view or a list's row it took 1 << 30 rows. -
With the kitty keyboard protocol a lone ESC waits
TerminalOptions.escapeTimeout, as without it, where it waited 500 ms.
Breaking:
- A cell's style id is a
StyleId, an extension type over int, apart from a pen id, which stays an int:styles.compose(pen, style)with the arguments swapped, a cell's style given toCanvas.textas the pen, or a pen toCanvas.runStyledno longer compile (they painted the wrong style, and only a debug assert caught some). Typed with it:StyleTable.style,compose,blankStyleOf,opaqueStyleOf(which answersStyleId.none, not -1, for a pen whose style depends on the cell underneath),fgOf,bgOf,underlineColorOf,attrsOf,linkIdOf,linkOf,erasable,sgrFromReset,transitionand themarkofsweep;Canvas.runStyled,runRangeStyled;Surface.clear,scrollRows,scrollRectand the style callback ofmarkCells(CellKeeper);LineEncoder.text;RenderEffect.effectCellandeffectStyle.Surface.stylesstays aUint32List:StyleId(surface.styles[i])reads one,.valuestores one.StyleId.baseis the style of all defaults, where 0 was. The type is erased: no cost at run time.
Added:
TextPainter, the layout engine ofRenderParagraphon its own, with no render tree:layout(constraints, segmenter:, order:)setswidthandheight,paint(canvas, x, y)draws at any place, and it answerstextRangeAt,cellAt,columnsOfand the intrinsic sizes. It reads no owner: the segmenter and the text order are given to it, and its setters record what they invalidated (takeInvalidation:TextInvalidation.none,paintorlayout).RenderParagraphowns one and draws and answers as before.RenderParagraph.columnsOf(start, end, y), the reverse oftextRangeAt: the columns of a row that draw a range of the text, as the last layout placed it (reordered in visual order, cut, justified), or null where none does.cellAtand it walk a row in one walk, so they read one model of it.
Fixed:
- The process's own terminal reads its input itself, in an isolate that
waits on it beside a wake object, rather than through dart:io's
stdin, which closed the input when the terminal let it go: fd 0 polled beside a pipe on Linux and macOS, the console's input buffer waited on beside an event on Windows (its key records, the console's VT sequences in its VT input mode, as UTF-8). A program started after an app or a session ended (ProcessStartMode.inheritStdio) reads what is typed again, where it got "Bad file descriptor", and a terminal opened again in the same process reads keys. Paused or closed, it reads nothing more from that moment, even while its isolate is still starting, and nothing of it keeps the process alive. A reading isolate that fails ends the input with aTerminalException. On Linux and macOS it reads what fd 0 has before it waits, as dart:io does: a paste goes through faster than through dart:io'sstdin(8 MB through a pseudo-terminal in 67 ms, against 77), a key as fast.
0.1.0 #
The first release.
TwkApp, the frame loop: input, layout and paint of what changed, one write per frame with backpressure; fullscreen, inline under the shell's history (commit,shrinkRegion) and in a fixedViewport; the last frame as plain text where the output is no terminal.Screen,SurfaceandCanvas: a packed cell buffer, interned glyphs (GlyphTable) and styles (StyleTable,Pen,Color,Attr), drawn through clips and translations; images in reserved cells (TerminalImage,ImagePlacement) with kitty graphics, sixel or iTerm2. A pen is the table's for good, a style until the table is swept:Screen.renderfrees the styles no cell has once twice as many are in use as after the last sweep (StyleTable.sweep,sweeps), so a screen of ever new colors keeps those it shows;Canvas.runStyleddraws in a style as it is, with no pen. The glyphs of several code points are swept the same way (GlyphTable.sweep,sweeps), and what keeps cells of a surface beyond it registers to be marked (Surface.keep,CellKeeper).Presenter: the damaged spans diffed against what the terminal shows and written with DEC 2026, scroll regions,ICH/DCH,REP,ECHandEL, asTerminalCapsallow.- The render tree:
RenderObject,PipelineOwner, boxes, text and paragraphs, padding and constraints, flex, stack, grid, wrap, lists, logs and viewports, effects, and diagnostics. Terminal: the process's terminal on Linux, macOS and Windows, or one over aTerminalLink; a capability probe, raw mode, resizes, the terminal restored on every exit path; titles, progress, notifications, the clipboard, links and pointer shapes.InputParserandInputEvents: keys (with the kitty keyboard protocol), the mouse, paste, focus, resize and color scheme reports; what it holds of a paste or an unterminated sequence bounded (pasteLimit,sequenceLimit), a longer paste in pieces (PasteEvent.more).- Unicode: grapheme segmentation, widths in two modes (
TextSegmenter,stringWidth,fitText,breakLines) and bidirectional text (BidiText). package:twk_core/terminal.dart: the terminal, styles, input and lines of text without the render tree.HeadlessTerminal,renderToStringandLineEncoder, for tests and one-off output.