threecode/engine

Search:
Group by:

Stateful terminal layout engine.

Controllers append transcript bytes and mutate fat-prompt state; this module owns the cursor geometry needed to clear/repaint the volatile footer around those appends. Scrollback bytes are append-only once emitted.

Types

TerminalEngine = object
Rows from the current cursor row to the top of the last painted volatile footer. Zero means no footer geometry is currently known.

Procs

proc appendTranscript(e: var TerminalEngine; transcriptBytes: string;
                      liveAnchored: bool; inputRunning: bool;
                      editor: ptr minline.LineEditor;
                      oldFooter, newFooter: FooterFrame;
                      compactRowsAboveFooter = 0; restoreEditor = true;
                      reserveFooter = true; transcriptOwnsSpacing = false) {.
    ...raises: [IOError, Exception],
    tags: [ReadEnvEffect, WriteIOEffect, RootEffect], forbids: [].}
Append transcript bytes as real scrollback while preserving or clearing the volatile footer. The engine computes cursor geometry from remembered footer state plus the current editor model; callers do not pass per-commit cursor movement values.
proc appendTranscript(transcriptBytes: string; liveAnchored: bool;
                      inputRunning: bool; editor: ptr minline.LineEditor;
                      oldFooter, newFooter: FooterFrame;
                      compactRowsAboveFooter = 0; restoreEditor = true;
                      reserveFooter = true; transcriptOwnsSpacing = false) {.
    ...raises: [IOError, Exception],
    tags: [ReadEnvEffect, WriteIOEffect, RootEffect], forbids: [].}
proc beginEditorRedraw(e: var TerminalEngine; ed: var minline.LineEditor;
                       ready: bool; frame: FooterFrame) {....raises: [IOError],
    tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
proc beginEditorRedraw(ed: var minline.LineEditor; ready: bool;
                       frame: FooterFrame) {....raises: [IOError],
    tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
proc clearToolViewport(e: var TerminalEngine; frame: FooterFrame;
                       inputRunning: bool; editor: ptr minline.LineEditor;
                       termW = 0) {....gcsafe, raises: [IOError, Exception], tags: [
    WriteIOEffect, ReadEnvEffect, RootEffect], forbids: [].}
proc clearToolViewport(frame: FooterFrame; inputRunning: bool;
                       editor: ptr minline.LineEditor; termW = 0) {....gcsafe,
    raises: [IOError, Exception],
    tags: [WriteIOEffect, ReadEnvEffect, RootEffect], forbids: [].}
proc endTurn(e: var TerminalEngine; inputRunning: bool;
             editor: ptr minline.LineEditor; oldFooter: FooterFrame;
             bytes: string) {....raises: [IOError],
                              tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
Render the transition from running turn to idle prompt. The visual transition bytes are still produced by the fat-prompt renderer; cursor geometry is owned by the engine.
proc endTurn(inputRunning: bool; editor: ptr minline.LineEditor;
             oldFooter: FooterFrame; bytes: string) {....raises: [IOError],
    tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
proc finishEditorRedraw(e: var TerminalEngine; ed: var minline.LineEditor;
                        showCaret = true) {....raises: [IOError],
    tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
proc finishEditorRedraw(ed: var minline.LineEditor; showCaret = true) {.
    ...raises: [IOError], tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
proc prepareAssistantContentStart(e: var TerminalEngine; inputRunning: bool;
                                  editor: ptr minline.LineEditor;
                                  oldFooter: FooterFrame;
                                  hadBufferedSubmit: bool; flush = true) {.
    ...raises: [IOError], tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
Clear volatile footer chrome so live assistant content can begin as ordinary transcript output. The clear geometry comes from the engine's remembered footer state, falling back to the supplied semantic footer.
proc prepareAssistantContentStart(inputRunning: bool;
                                  editor: ptr minline.LineEditor;
                                  oldFooter: FooterFrame;
                                  hadBufferedSubmit: bool; flush = true) {.
    ...raises: [IOError], tags: [ReadEnvEffect, WriteIOEffect], forbids: [].}
proc renderFooter(e: var TerminalEngine; frame: FooterFrame; inputRunning: bool;
                  editor: ptr minline.LineEditor; termW = 0) {....gcsafe,
    raises: [IOError, Exception],
    tags: [WriteIOEffect, ReadEnvEffect, RootEffect], forbids: [].}
Replace the volatile footer and repaint the editor in one synchronized frame. footerRowsAboveEditor is model geometry from the fat prompt, not a one-off cursor fix from a controller.
proc renderFooter(frame: FooterFrame; inputRunning: bool;
                  editor: ptr minline.LineEditor; termW = 0) {....gcsafe,
    raises: [IOError, Exception],
    tags: [WriteIOEffect, ReadEnvEffect, RootEffect], forbids: [].}
proc renderToolViewport(e: var TerminalEngine; rows: openArray[string];
                        frame: FooterFrame; inputRunning: bool;
                        editor: ptr minline.LineEditor; termW = 0) {....gcsafe,
    raises: [IOError, Exception],
    tags: [ReadEnvEffect, WriteIOEffect, RootEffect], forbids: [].}
Replace the volatile bash viewport and repaint footer/editor in one synchronized frame. The viewport is live chrome: it is not transcript scrollback, and the controller commits final output separately.
proc renderToolViewport(rows: openArray[string]; frame: FooterFrame;
                        inputRunning: bool; editor: ptr minline.LineEditor;
                        termW = 0) {....gcsafe, raises: [IOError, Exception], tags: [
    ReadEnvEffect, WriteIOEffect, RootEffect], forbids: [].}
proc syncWrite(bytes: string) {....gcsafe, raises: [IOError],
                                tags: [WriteIOEffect], forbids: [].}
proc syncWrite(e: var TerminalEngine; bytes: string) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}
Synchronized screen write for legacy frame helpers that have not yet been decomposed into footer model mutations.
proc updateToolViewportSymbol(symbol: string) {....gcsafe, raises: [], tags: [],
    forbids: [].}
Rewrite the leading glyph of the cached command banner row. The bar-tick thread calls this each tick to rotate the currency marker ($/€/£/¥); the next renderFooter repaint writes the updated row in one locked pass.
proc writeRaw(bytes: string) {....gcsafe, raises: [IOError], tags: [WriteIOEffect],
                               forbids: [].}
proc writeRaw(e: var TerminalEngine; bytes: string) {....raises: [IOError],
    tags: [WriteIOEffect], forbids: [].}
Raw screen write owned by the engine boundary.