Tachikoma.jl

Appearance

API Reference ​

Auto-generated API documentation for all documented symbols in Tachikoma.jl.

Functions and types that have docstrings are listed below. As docstring coverage increases, this page will grow automatically.

All Documented Symbols ​

Tachikoma.ALL_THEMES Constant

All themes for iteration (mode-dependent).

Tachikoma.WINDOW_OPACITY Constant

Global default opacity for new FloatingWindows (0.0–1.0).

Tachikoma.BorderedButton Type
julia
BorderedButton(; box=BOX_ROUNDED)

Full box-bordered button (3 rows):

julia
╭──────────╮
│  Label   │
╰──────────╯
Tachikoma.BoxTabs Type
julia
BoxTabs(; box=BOX_PLAIN)

Box-drawn borders around each tab. Requires 3 rows of height (top border, label, bottom border). The active tab's bottom border is removed to create a connected appearance.

Tachikoma.BracketButton Type
julia
BracketButton()

Default button style: [ Label ] with brackets. Single-line rendering.

Tachikoma.BracketTabs Type
julia
BracketTabs()

Default tab style: active tab wrapped in [brackets], inactive tabs with spaces. Single-line rendering.

Tachikoma.Button Method
julia
Button(label; focused=false, button_style=ButtonStyle(), flash_frames::Int=8, flash_style::Function=_default_button_flash_style, ...)

Clickable button with optional pulse animation. Enter/Space or mouse click to activate. The caller handles the action (Elm architecture pattern).

Tachikoma.ButtonDecoration Type
julia
ButtonDecoration

Abstract type for button rendering styles. Subtype this and implement _render_button! to create custom button appearances.

Built-in decorations:

  • BracketButton() — [ Label ] (default, 1 row)

  • BorderedButton() — full box border (3 rows)

  • PlainButton() — just the label text, no decoration

Tachikoma.ButtonStyle Type
julia
ButtonStyle{D<:ButtonDecoration}

Visual configuration for a Button.

Examples

julia
ButtonStyle()                                        # default brackets
ButtonStyle(decoration=BorderedButton())             # rounded border
ButtonStyle(decoration=BorderedButton(box=BOX_HEAVY)) # heavy border
ButtonStyle(decoration=PlainButton())                # just text
Tachikoma.Checkbox Method
julia
Checkbox(label; checked=false, focused=false, ...)

Togglable checkbox. Press Enter or Space to toggle.

Tachikoma.CladoBranch Type

A drawable segment of a radial cladogram.

  • Arc (radius1 ≈ radius2): sweep from angle1 to angle2 at constant radius.

  • Radial (angle1 ≈ angle2): extend from radius1 to radius2 at constant angle.

trait is a 0–1 value that evolves along branches for coloring.

Tachikoma.CodeEditor Method
julia
CodeEditor(; text="", mode=:insert, focused=true, tick=nothing, ...)

Syntax-highlighted code editor with Vim-style modal editing (mode=:normal/:insert), line numbers, undo/redo, and Julia tokenization.

Tachikoma.DataColumn Method
julia
DataColumn(name, values; width=0, align=col_left, format=nothing)

A column in a DataTable. Set width=0 for auto-sizing, format for custom display.

Tachikoma.DropDown Method
julia
DropDown(items; selected=1, max_visible=8, ...)

Collapsed select picker. Enter/Space to open, Up/Down to navigate, Enter to select.

Tachikoma.EventScript Type
julia
EventScript(items...) <: Function

Builds a scripted input sequence for headless app recordings.

Each item is either a (delay, event) tuple or a vector of such tuples (returned by seq, rep, and chars). The delay is always relative to the previous entry, so the declaration order is the firing order.

Call an EventScript with fps to get a Vector{Tuple{Int,Any}} of (frame_number, event) pairs suitable for passing to record_app.

See also: seq, rep, chars, pause, key

Tachikoma.EventScript Method
julia
(es::EventScript)(fps) → Vector{Tuple{Int,Any}}

Convert the EventScript to frame-indexed events at the given fps.

Tachikoma.Fill Type

Fills remaining space. weight controls relative proportion when multiple Fills exist.

Tachikoma.Fixed Type

Fixed-size constraint in cells.

Tachikoma.FloatingWindow Type
julia
FloatingWindow(; title, x, y, width, height, content=nothing, ...)

A positioned, bordered panel that can be rendered at arbitrary coordinates. Supports animated borders, semi-transparency, and custom content via either a content widget or an on_render callback.

  • content: any widget with render(widget, rect, buf)

  • on_render: (inner::Rect, buf::Buffer, focused::Bool, frame) -> nothing

  • opacity: 0.0 (fully transparent) to 1.0 (fully opaque); defaults to WINDOW_OPACITY[] (0.95)

  • border_color: override border color (ColorRGB); nothing uses theme

  • bg_color: override background color; nothing uses theme

Tachikoma.FocusRing Type
julia
FocusRing(items::Vector)

Circular focus manager for navigating between focusable widgets. Use next!/prev! to cycle focus and current to get the active widget.

Tachikoma.Form Method
julia
Form(fields; submit_label="Submit", block=nothing, tick=nothing, ...)

Container for labeled input fields with Tab/Shift-Tab navigation and a submit button. Use value(form) to get a Dict of field values and valid(form) to check validation.

Tachikoma.MarkdownPane Method
julia
MarkdownPane(source; width=80, block=nothing, show_scrollbar=true, ...)

Scrollable markdown viewer. Parses source via CommonMark.jl (requires the markdown extension — call enable_markdown() first) and displays styled output in a ScrollPane. Automatically reflows text when the render width changes.

Style keyword arguments

h1_style, h2_style, h3_style, bold_style, emph_style, code_style, link_style, quote_style, text_style, hr_style.

Tachikoma.Max Type

Maximum-size constraint — expands up to size cells.

Tachikoma.Min Type

Minimum-size constraint — takes at least size cells, expands if space remains.

Tachikoma.Model Type
julia
Model

Abstract type for application state. Subtype this and implement:

  • view(model, frame) — render the UI (required)

  • update!(model, event) — handle events (required)

  • should_quit(model) — return true to exit (default: false)

  • init!(model, terminal) — one-time setup (optional)

  • cleanup!(model) — teardown (optional)

Tachikoma.PTY Type
julia
PTY

Manages a pseudo-terminal pair: a master fd (parent reads/writes) connected to a child process running in its own terminal session.

Read subprocess output from pty.output (a Channel{Vector{UInt8}}). Write input via pty_write(pty, data).

Tachikoma.Paragraph Method
julia
Paragraph(text; wrap=no_wrap, alignment=align_left, block=nothing, ansi=true, raw=false, ...)

Styled text block with configurable wrapping (no_wrap, word_wrap, char_wrap) and alignment (align_left, align_center, align_right). Also accepts Vector{Span} for mixed-style text.

When ansi=true (the default), strings containing ANSI escape sequences are automatically parsed into styled spans — colors (standard, 256, RGB), bold, dim, italic, underline, and strikethrough are all supported.

When ansi=false, escape sequences are stripped and text is shown unstyled. When raw=true, escape sequences are shown as visible literals (e.g. ␛[31m) for debugging — this overrides ansi.

Tachikoma.Percent Type

Percentage of total space.

Tachikoma.PixelImage Method
julia
PixelImage(cells_w, cells_h; block=nothing, style=tstyle(:primary),
           decay=DecayParams())

Create a PixelImage widget sized for cells_w × cells_h terminal cells. Pixel dimensions are computed from terminal cell metrics.

Tachikoma.PlainButton Type
julia
PlainButton()

Plain text button with no bracket or border decoration. Styled text only.

Tachikoma.PlainTabs Type
julia
PlainTabs()

Plain text tabs with no bracket or border decoration. Active tab uses active style, inactive uses inactive style.

Tachikoma.REPLWidget Type
julia
REPLWidget(; rows=24, cols=80, ...)

An embedded Julia REPL that runs in the current process. The REPL shares the host's module space — any loaded packages and variables are accessible.

Renders identically to the standard Julia REPL: colored prompts, tab completion, help mode (?), pkg mode (]), shell mode (;), history, and multi-line editing all work.

Example

julia
rw = REPLWidget(; rows=20, cols=80)

# In your view:
render(rw, area, buf)

# In your update!:
handle_key!(rw, evt)

# Cleanup:
close!(rw)
Tachikoma.RadioGroup Method
julia
RadioGroup(labels; selected=1, focused=false, cursor=1, ...)

Mutually exclusive selection from a list. Up/Down to navigate, Enter/Space to select.

Tachikoma.Ratio Type

Ratio of total space — num/den of the effective total.

Tachikoma.ScrollbarState Type
julia
ScrollbarState()

Tracks scrollbar geometry and drag state for mouse interaction. Embed in any scrollable widget and call handle_scrollbar_mouse! from your handle_mouse! method.

Update state.rect during rendering to the scrollbar's bounding Rect.

Tachikoma.SelectableList Method
julia
SelectableList(items; selected=1, focused=false, tick=nothing, show_scrollbar=true, ...)

Scrollable list with keyboard navigation and mouse support. Keyboard: Up/Down to move, Home/End for first/last, PageUp/PageDown for jumps. Mouse: click to select, scroll wheel to scroll.

Tachikoma.Spring Method
julia
Spring(target; value=target, stiffness=180.0, damping=:critical)

Create a spring animation. damping can be a number or a symbol:

  • :critical — no overshoot, fastest settling (2√stiffness)

  • :over — sluggish, no overshoot (2.5√stiffness)

  • :under — slight bounce (1.2√stiffness)

Tachikoma.TabBarStyle Type
julia
TabBarStyle{D<:TabDecoration}

Visual configuration for a TabBar. Controls decoration style, colors, separator, and overflow appearance.

Examples

julia
# Default bracket style
TabBarStyle()

# Box-drawn tabs
TabBarStyle(decoration=BoxTabs())

# Heavy box tabs with custom colors
TabBarStyle(decoration=BoxTabs(box=BOX_HEAVY),
            active=tstyle(:primary, bold=true))

# Plain text, no decoration
TabBarStyle(decoration=PlainTabs(), separator=" · ")
Tachikoma.TabDecoration Type
julia
TabDecoration

Abstract type for tab rendering styles. Subtype this and implement _render_tabs! to create custom tab appearances.

Built-in decorations:

  • BracketTabs() — [Active] Inactive (default)

  • BoxTabs() — box-drawn borders around each tab (3 rows)

  • PlainTabs() — plain text, no decoration

Tachikoma.TerminalWidget Type
julia
TerminalWidget(cmd; rows=24, cols=80, scrollback_limit=1000)

Embedded terminal emulator widget. Spawns cmd in a PTY and renders its output. Use as standalone or as content inside a FloatingWindow.

julia
TerminalWidget()                           # Julia REPL
TerminalWidget(["/bin/bash"])              # bash shell
TerminalWidget(["julia", "--banner=no"])   # Julia without banner

Forward events in your update!:

julia
handle_key!(tw, evt)    # keyboard → PTY
handle_mouse!(tw, evt)  # scroll wheel → scrollback

Render in your view:

julia
render(tw, area, buf)   # drains PTY output + renders screen
Tachikoma.TerminalWidget Method
julia
TerminalWidget(pty::PTY; ...)

Create a TerminalWidget from a pre-existing PTY (e.g., from pty_pair). Used by REPLWidget for in-process REPL rendering.

Tachikoma.TextArea Method
julia
TextArea(; text="", focused=false, tick=nothing, ...)

Multi-line text editor with line-based cursor movement and scrolling.

Tachikoma.TextInput Method
julia
TextInput(; text="", focused=false, tick=nothing, validator=nothing, ...)

Single-line text input with cursor movement, clipboard, and optional validation. The validator is a function String → Union{String, Nothing} — return an error message or nothing if valid.

Tachikoma.TreeView Method
julia
TreeView(root; selected=0, focused=false, tick=nothing, ...)

Hierarchical tree with keyboard navigation. Up/Down to move, Left to collapse/go to parent, Right to expand/enter child, Enter/Space to toggle.

Tachikoma.Wait Type
julia
Wait

Sentinel event type used by pause() to advance the EventScript timeline cursor without firing an event.

Tachikoma.WindowManager Type
julia
WindowManager(; windows=FloatingWindow[], focus_shortcuts=true)

Manages a stack of FloatingWindows with z-order (last = topmost), focus cycling, and mouse-based title-bar dragging.

julia
By default, focus shortcuts are enabled so the manager consumes
Ctrl+J / Ctrl+K for next/previous focus. Set `focus_shortcuts=false`
to keep all focus keys in content widgets.
Base.deleteat! Method

Remove a window by index.

Base.length Method

Number of windows.

Base.push! Method

Add a window to the top of the stack.

Tachikoma._apply_window_opacity! Method
julia
_apply_window_opacity!(buf, rect, window_bg, opacity)

Apply semi-transparent window compositing to a buffer region.

Blends each cell's existing colors with the window's background color according to opacity (0.0 = fully transparent, 1.0 = fully opaque):

  • Background: lerps from existing bg toward window_bg by opacity. At 0.95, the result is 95% window bg + 5% existing (barely see-through).

  • Foreground: lerps from existing fg toward the blended bg by opacity, fading underlying text proportionally so it doesn't float at full brightness against the composited background.

Only called when opacity < 1.0; at full opacity the caller does a solid fill.

Tachikoma._cfmakeraw! Method
julia
_cfmakeraw!(fd::Cint)

Set a file descriptor to raw mode via cfmakeraw + tcsetattr. Used to pre-configure the PTY slave before wrapping it in Base.TTY, so that LineEdit's later raw!() call is a no-op (preventing any possible blocking on tcsetattr).

Tachikoma._char_wrap_spans! Method

Char-wrap a Span vector into visual lines.

Tachikoma._char_wrap_string! Method

Char-wrap a plain string into visual lines.

Tachikoma._detect_cell_pixels_escape! Method
julia
_detect_cell_pixels_escape!()

Query terminal via escape sequences. Tries:

  • \e[16t → cell size (ESC [ 6 ; h ; w t) — most direct

  • \e[14t → text area pixels (ESC [ 4 ; h ; w t) — fallback

Temporarily enters raw mode to read responses.

Tachikoma._detect_cell_pixels_ioctl! Method
julia
_detect_cell_pixels_ioctl!() → Bool

Use TIOCGWINSZ ioctl to get pixel dimensions from the kernel. Tries stdin, stdout, and /dev/tty.

Tachikoma._detect_cell_pixels_prefs! Method
julia
_detect_cell_pixels_prefs!() → Bool

Check LocalPreferences.toml for manual cell pixel dimensions. Set via: cell_pixel_w and cell_pixel_h keys.

Tachikoma._detect_graphics_from_env Method
julia
_detect_graphics_from_env() -> GraphicsProtocol

Infer graphics protocol from terminal environment variables, without sending any escape sequences. Used as:

  • Primary detection for remote TTY sessions (where probing is unsafe).

  • Fast-path before probing for known terminals in local sessions.

Detection priority (kitty > sixel):

  • Kitty: TERM=xterm-kitty, KITTY_WINDOW_ID set, TERM_PROGRAM=kitty

  • Ghostty: TERM=xterm-ghostty, GHOSTTY_RESOURCES_DIR set

  • WezTerm: TERM_PROGRAM=WezTerm → sixel (kitty support incomplete)

  • iTerm2: TERM_PROGRAM=iTerm.app → sixel

  • foot: TERM=foot or TERM=foot-extra → sixel

  • mlterm: TERM=mlterm → sixel

Tachikoma._detect_kitty_graphics! Method
julia
_detect_kitty_graphics!(io::IO) -> Bool

Query terminal for Kitty graphics protocol support by sending a minimal 1×1 query image (a=q,t=d,f=24) with a unique id (i=31). Returns true if the terminal responds with _G and i=31. Must be called after raw mode and start_input!().

Tachikoma._detect_kitty_keyboard! Method
julia
_detect_kitty_keyboard!(io::IO) -> Bool

Query terminal for Kitty keyboard protocol support via CSI ? u. Writes query to io (should be the terminal output, e.g. /dev/tty), reads response from the input stream. Returns true if terminal responds with CSI ? flags u. Must be called after raw mode and start_input!().

Tachikoma._detect_sixel_geometry! Method
julia
_detect_sixel_geometry!()

Query the actual sixel rendering pixel dimensions via XTSMGRAPHICS (\e[?2;1;0S). This is the definitive way to determine sixel pixel geometry — it returns the real rendering dimensions regardless of DPI scaling, font size, or terminal coordinate system quirks.

Supported by WezTerm, xterm, foot, mlterm, and other sixel-capable terminals. Falls back gracefully (SIXEL_AREA_PX stays at (0,0)) on terminals that don't respond.

Updates SIXEL_AREA_PX[].

Tachikoma._dirty_stale_gfx! Method
julia
_dirty_stale_gfx!(prev, cur, old_bounds, new_regions)

Force cells that were sixel-covered last frame but not this frame to appear changed in the diff, so flush! re-emits them. Writing any character to a cell clears the terminal's sixel layer at that position.

Tachikoma._dt_find_border Method

Find column index whose right border is near x (±1 cell tolerance). Returns 0 if none.

Tachikoma._dt_visible_cols Method

Count how many columns are fully visible starting from col_offset, using last rendered widths.

Tachikoma._extract_action_from_params Method
julia
_extract_action_from_params(params) -> KeyAction

Extract event type from CSI params that may contain colon-separated modifiers:event_type format (Kitty protocol extension on legacy sequences). Returns key_press when no event type is present (legacy terminals).

Tachikoma._fb_blend! Method

Blend RGBA image into the framebuffer at the given cell position.

Tachikoma._fb_flush! Method

Encode dirty framebuffer region as sixel and emit as graphics.

Tachikoma._fb_init! Method

Clear/resize framebuffer, filling with cell background colors from the buffer.

Tachikoma._filter_visible_gfx Method
julia
_filter_visible_gfx(regions, buf) → Vector{GraphicsRegion}

Return only graphics regions whose reserved cell area has not been overwritten by later widget rendering. A region is occluded if any cell in its area differs from the blank (' ', RESET) that render_graphics! placed there.

Tachikoma._is_ssh_session Method
julia
_is_ssh_session() → Bool

Detect if running inside an SSH session. Shared memory requires the Julia process and Kitty terminal to be on the same machine.

Tachikoma._kitty_shm_cleanup! Method
julia
_kitty_shm_cleanup!()

Promote the current generation and unlink the previous one. Called at the start of each frame: unlinks segments from two frames ago (the terminal has had a full frame to read them), then moves the last frame's segments into the "previous" slot.

Tachikoma._kitty_shm_cleanup_all! Method
julia
_kitty_shm_cleanup_all!()

Unlink every tracked segment (both generations). Called on TUI exit, process replacement, and atexit.

Tachikoma._kitty_shm_probe! Method
julia
_kitty_shm_probe!() → Bool

Test whether POSIX shared memory transmission is available. Requires local (non-SSH) POSIX session with working shm_open.

Tachikoma._kitty_shm_write Method
julia
_kitty_shm_write(rgb::Vector{UInt8}) → Union{String, Nothing}

Write raw RGB bytes to a POSIX shared memory segment for Kitty to read. Returns the shm name on success, nothing on failure.

Each call gets a unique name via a monotonic counter. The name is tracked in _KITTY_SHM_CURRENT for deferred cleanup (see _kitty_shm_cleanup!).

Uses ccall(:memcpy, ...) for the copy — this is opaque to Julia's compiler and prevents dead store elimination of writes to mmap'd memory.

Tachikoma._load_sixel_scale! Method
julia
_load_sixel_scale!()

Load sixel pixel scale factors from LocalPreferences.toml. Set via: sixel_scale_w and sixel_scale_h keys (Float64, default 1.0).

Compensates for terminals that report logical pixel dimensions via escape sequences / ioctl but render sixel graphics at device-pixel resolution (common on macOS Retina displays).

Tachikoma._pixelimage_pixel_dims Method
julia
_pixelimage_pixel_dims(cells_w, cells_h)

Compute pixel dimensions that exactly tile with cell boundaries.

Prefers SIXEL_AREA_PX (from XTSMGRAPHICS query) which gives the actual sixel rendering pixel dimensions. Falls back to TEXT_AREA_PX with SIXEL_SCALE multiplier, then CELL_PX.

Tachikoma._render_dotwave_terrain! Method
julia
_render_dotwave_terrain!(buf, area, tick, preset, amplitude, cam_height, speed;
                         color_transform=identity)

Parallax mountain silhouette renderer. Draws n_ridges layered mountain profiles in braille using painter's algorithm (far → near). Each layer is a wave-modulated band whose top contour creates the ridgeline. Near ridges are tall, bright, and near the bottom of the screen; far ridges are thin, dim, and near the horizon.

color_transform(::ColorRGB) → ColorRGB is applied to each cell's final color (used by the background system to dim/desaturate).

Tachikoma._render_visual_lines! Method

Render pre-wrapped visual String lines.

Tachikoma._render_visual_lines! Method

Render pre-wrapped visual Span lines.

Tachikoma._start_pty_reader Method
julia
_start_pty_reader(pty::PTY) → Task

Spawn an @async task that uses FileWatching.poll_fd to efficiently wait for data on the PTY master fd, then reads it and pushes chunks to pty.output. This integrates with Julia's event loop via libuv so it never blocks the main thread.

Tachikoma._tab_rendered_width Method

Rendered width of a single tab including decoration.

Tachikoma._tab_style Method

Get the style for tab i, using per-tab color if available, otherwise active/inactive.

Tachikoma._track_key_state! Method
julia
_track_key_state!(evt::KeyEvent) -> KeyEvent

Update key-down tracking and reclassify press→repeat when appropriate. If a key_press arrives for a key already in _KEYS_DOWN (no release seen), it's a repeat from a terminal sending raw bytes for held keys.

Tachikoma._try_put! Method
julia
_try_put!(ch::Channel{Nothing})

Non-blocking signal to the wake channel. If the channel already has a pending signal, skip — the main loop will wake anyway. This prevents deadlock: put! on a full channel blocks, which can freeze a PTY reader inside its on_data callback while the main thread waits for that reader in pty_close!.

Tachikoma._update_follow_total! Method

Like _update_follow! but takes an explicit total (for wrapped line count).

Tachikoma._wire_push_data! Method
julia
_wire_push_data!(tw::TerminalWidget)

Set up the PTY on_data callback to immediately drain the output channel into the VT parser. This eliminates the pull-based delay where data sat in the channel until the next render() → drain!() cycle.

Tachikoma._wrap_content Method

Wrap String content into visual lines.

Tachikoma._wrap_content Method

Wrap Span content into visual lines.

Tachikoma.active_themes Method

Return the active theme pack based on light/dark mode.

Tachikoma.advance_layout! Method

Advance layout animation tweens, applying current values to windows.

Tachikoma.anchor Method

Anchor a widget within a parent rect using the widget's intrinsic_size.

Tachikoma.ansi_enabled Method
julia
ansi_enabled() → Bool

Return whether ANSI escape sequence parsing is enabled globally. Widgets like Paragraph and ScrollPane use this as their default.

Tachikoma.app Method
julia
app(model::Model; fps=60, default_bindings=true, on_stdout=nothing, on_stderr=nothing)

Run a TUI application with the Elm architecture loop: poll events → update! → view. Enters the alternate screen, enables raw mode and mouse, then renders at fps frames/sec. Ctrl+C is dispatched as a KeyEvent(:ctrl_c) — handle it in update! to quit or confirm. Set default_bindings=false to disable built-in shortcuts (theme picker, help overlay, etc.).

Stdout and stderr are automatically redirected during TUI mode to prevent background println() from corrupting the display. Pass on_stdout / on_stderr callbacks to receive captured lines (e.g., for an activity log). See with_terminal.

Tachikoma.apply_decay! Method
julia
apply_decay!(pixels, params::DecayParams, tick::Int)

In-place bit-rot effects on pixel buffer. All effects are scaled by the master params.decay intensity. Skips black (background) pixels.

Tachikoma.apply_decay_subsampled! Method
julia
apply_decay_subsampled!(pixels, params::DecayParams, tick::Int, step::Int)

Subsampled decay: compute effects every step pixels and fill blocks. Gives step² speedup for decay-heavy frames at the cost of block artifacts (acceptable since decay is itself a distortion effect).

Tachikoma.border_shimmer! Method
julia
border_shimmer!(buf, rect, base_color, tick; box=BOX_ROUNDED, intensity=0.15)

Draw a block border where each border character has subtly varying brightness driven by noise. Creates an organic, living border effect. Falls back to uniform base_color when animations disabled.

Tachikoma.breathe Method
julia
breathe(tick; period=90) → Float64 ∈ [0, 1]

Asymmetric breathing curve — slow inhale, quick exhale. More organic than a pure sine. Returns 1.0 when animations disabled.

Tachikoma.brighten Method
julia
brighten(c::ColorRGB, amount::Float64) → ColorRGB

Brighten a color by amount ∈ [0, 1]. 0 = unchanged, 1 = white.

Tachikoma.bring_to_front! Method

Bring window at idx to the front (top of z-order) and focus it.

Tachikoma.buffer_to_text Method
julia
buffer_to_text(buf::Buffer, rect::Rect) → String

Extract the visible text from a rectangular region of the buffer. Trailing spaces on each line are stripped; trailing blank lines removed.

Tachikoma.button_height Method

How many rows this decoration needs.

Tachikoma.canvas_bg Method

Background color for pixel canvases — black in dark mode, white in light mode.

Tachikoma.canvas_dot_size Method
julia
canvas_dot_size(c) → (w, h)

Return the dot-space dimensions for a canvas (backend-agnostic).

Tachikoma.capture_frame! Method
julia
capture_frame!(rec::CastRecorder, buf::Buffer, width::Int, height::Int;
               gfx_regions, pixel_snapshots)

Snapshot the current buffer as cell-level data and pixel snapshots. Called from draw!. No ANSI encoding is done during recording — the .tach format stores cell snapshots directly, and export formats (.gif, .svg, .apng) are generated on demand from the snapshots.

During the countdown period, frames are skipped so UI notifications (like the countdown itself) don't appear in the recording.

Tachikoma.cascade! Method
julia
cascade!(wm, area; animate=true, duration=15)

Arrange windows in a cascading stack. Animates smoothly when animate=true.

Tachikoma.cell_pixels Method
julia
cell_pixels() → (w, h)

Return the pixel dimensions of a single terminal cell.

Tachikoma.center Method

Center a widget within a parent rect using the widget's intrinsic_size.

Tachikoma.chars Method
julia
chars(text; pace=0.08) → Vector{Tuple{Float64,Any}}

Expand text into a sequence of KeyEvents, pace seconds apart.

julia
EventScript((1.0, key(:tab)), chars("Alice"; pace=0.1))
Tachikoma.clear! Method
julia
clear!(c::PixelCanvas)

Clear all pixels.

Tachikoma.clear! Method
julia
clear!(img::PixelImage)

Clear all pixels to the current background color.

Tachikoma.clear_recording! Method
julia
clear_recording!(rec::CastRecorder)

Free all recording data (timestamps, cell snapshots, pixel snapshots). Call after export is complete or when dismissing the export modal.

Tachikoma.clipboard_copy! Method
julia
clipboard_copy!(text::String)

Copy text to the system clipboard. Uses pbcopy on macOS, xclip on Linux.

Tachikoma.close! Method
julia
close!(rw::REPLWidget)

Shut down the in-process REPL and clean up the PTY.

Tachikoma.close! Method
julia
close!(tw::TerminalWidget)

Close the PTY and terminate the child process. Call this in your model's cleanup.

Tachikoma.color_wave Method
julia
color_wave(tick, x, colors; speed=0.04, spread=0.08) → ColorRGB

Smooth multi-stop color gradient wave sweeping across x positions. colors should be a tuple/vector of Color256 or ColorRGB. Returns colors[1] (as RGB) when animations disabled.

Tachikoma.compress_dead_space Method
julia
compress_dead_space(cell_snapshots, timestamps, pixel_snapshots;
                    compress=1.0)

Process recorded frame data to compress "dead space" — periods where the screen content is unchanging across consecutive frames.

Identical consecutive frames are collapsed to a single frame. The duration of each dead run is then compressed using a logarithmic curve controlled by compress:

  • compress = 1.0: no timing change (identity — only deduplicates frames)

  • compress = 2.0: mild compression

  • compress = 3-4: moderate compression

  • compress = 10.0: aggressive compression compressed_gap = gap / (1 + (compress - 1) * log(1 + gap))

Short gaps are barely affected; long gaps are compressed logarithmically.

Original gapcompress=2compress=5compress=10
0.1s0.09s0.07s0.05s
1.0s0.59s0.27s0.14s
5.0s1.79s0.61s0.31s
10.0s2.94s0.94s0.47s
30.0s6.77s2.04s1.02s

Returns (cell_snapshots, timestamps, pixel_snapshots) with the same types as the input, ready for write_tach or export_gif_from_snapshots.

Tachikoma.copy_rect Method
julia
copy_rect(model::Model) → Union{Rect, Nothing}

Override to return the Rect of the focused pane for Ctrl+Y copy. Return nothing to copy the full screen (default).

Tachikoma.create_canvas Method
julia
create_canvas(width, height; style=tstyle(:primary))

Backend-agnostic canvas factory. Returns BlockCanvas or Canvas depending on the active render backend preference.

Tachikoma.datatable_detail Method

Default detail function: shows all column values for a row.

Tachikoma.detect_cell_pixels! Method
julia
detect_cell_pixels!()

Detect terminal cell pixel dimensions. Tries in order:

  1. LocalPreferences.toml override (cell_pixel_w, cell_pixel_h)

  2. TIOCGWINSZ ioctl (no terminal I/O needed)

  3. \e[16t escape sequence (cell size report)

  4. \e[14t escape sequence (text area report)

Then queries XTSMGRAPHICS (\e[?2;1;0S) for the actual sixel rendering pixel dimensions. This is critical because many terminals report logical pixels via ioctl/escape sequences but render sixel at device pixel resolution (e.g. macOS Retina).

Updates CELL_PX[], TEXT_AREA_PX[], TEXT_AREA_CELLS[], and SIXEL_AREA_PX[]. Falls back to defaults (w=8, h=16) if all methods fail.

Tachikoma.dim_color Method
julia
dim_color(c::ColorRGB, amount::Float64) → ColorRGB

Dim a color by amount ∈ [0, 1]. 0 = unchanged, 1 = black.

Tachikoma.discover_mono_fonts Method
julia
discover_mono_fonts() → Vector{NamedTuple{(:name,:path), Tuple{String,String}}}

Scan system font directories for monospace fonts. Results are cached for the session. The first entry is always (name="(none — text hidden)", path="") for users who only want SVG export.

Tachikoma.drain! Method
julia
drain!(tw::TerminalWidget) → Bool

Drain any remaining buffered output from the PTY channel and feed it through the VT parser. Most data is already processed eagerly by the on_data callback; this handles stragglers and process exit detection. Called automatically by render.

Tachikoma.drift Function
julia
drift(tick, seed; speed=0.02) → Float64 ∈ [0, 1]

Slow noise drift for organic color/value wandering. Each seed produces a different drift path. Returns 0.5 when animations disabled.

Tachikoma.editor_mode Method

Return the current editor mode (:insert, :normal, :search, or :command).

Tachikoma.enable_gif Method
julia
enable_gif()

Ensure the GIF export extension is loaded. If FreeTypeAbstraction and ColorTypes are installed but not yet imported, this triggers their loading so TachikomaGifExt activates. Errors with an install hint if the packages are missing.

Tachikoma.enable_markdown Method
julia
enable_markdown()

Ensure the CommonMark.jl extension is loaded. If CommonMark is installed but not yet imported, this triggers its loading so TachikomaMarkdownExt activates. Errors with an install hint if the package is missing.

Tachikoma.enable_sqlite Method
julia
enable_sqlite()

Ensure the SQLite extension is loaded. If SQLite and DBInterface are installed but not yet imported, this triggers their loading so TachikomaSQLiteExt activates.

Tachikoma.enable_tables Method
julia
enable_tables()

Ensure the Tables.jl extension is loaded. If Tables is installed but not yet imported, this triggers its loading so TachikomaTablesExt activates. Errors with an install hint if the package is missing.

Tachikoma.encode_kitty Method
julia
encode_kitty(pixels::Matrix{ColorRGBA};
             decay=DecayParams(), tick=0, cols=0, rows=0) → Vector{UInt8}

Encode a pixel matrix as a Kitty graphics protocol APC sequence.

Uses a=T (transmit + display), q=2 (suppress OK). Pixels with a==0x00 are transparent (f=32 RGBA); if all pixels are opaque, uses f=24 (RGB). Passes s=width,v=height for pixel dimensions and c=cols,r=rows for cell placement when provided.

Returns UInt8[] for all-transparent images.

Tachikoma.encode_kitty_rgba Method
julia
encode_kitty_rgba(rgba::Vector{UInt8}, w::Int, h::Int; cols=0, rows=0) -> Vector{UInt8}

Encode pre-built RGBA pixel data for kitty graphics protocol. rgba must be w * h * 4 bytes in row-major order (top-to-bottom, left-to-right). Alpha channel is preserved for transparency compositing.

Tachikoma.export_svg Method
julia
export_svg(filename, width, height, cell_snapshots, timestamps;
           font_family=_SVG_DEFAULT_FONTS, font_path="",
           bg_color=_SVG_DEFAULT_BG, fg_color=_SVG_DEFAULT_FG,
           cell_w=8, cell_h=16) → String

Export an animated SVG from cell snapshots. Each frame becomes a <g> group with SMIL visibility animation timed to the recording timestamps.

When font_path points to a .ttf/.otf file, the font is embedded via base64 @font-face so the SVG renders identically on any machine. Returns the filename written.

Tachikoma.fbm Method
julia
fbm(x, [y]; octaves=3, lacunarity=2.0, gain=0.5) → Float64 ∈ [0, 1]

Fractal Brownian Motion — layered noise for natural-looking texture. Higher octaves = more detail. Good for subtle organic variation.

Tachikoma.fill_gradient! Method
julia
fill_gradient!(buf, rect, c1, c2; direction=:horizontal)

Fill a rect with a smooth color gradient between two colors. direction can be :horizontal, :vertical, or :diagonal. Characters are filled with spaces; only the foreground color varies.

Tachikoma.fill_noise! Method
julia
fill_noise!(buf, rect, c1, c2, tick; scale=0.2, speed=0.03)

Fill a rect with animated 2D noise texture blending between two colors. Creates an organic, slowly shifting background pattern. Falls back to solid c1 fill when animations disabled.

Tachikoma.fill_pixel_rect! Method
julia
fill_pixel_rect!(c::PixelCanvas, x0::Int, y0::Int, x1::Int, y1::Int, color::ColorRGBA)

Fill a rectangle of pixels with a single color. Coordinates are 1-based and clamped to canvas bounds. Use this instead of looping set_pixel! for block fills — avoids per-pixel bounds checking overhead.

Tachikoma.fill_rect! Method
julia
fill_rect!(img::PixelImage, x0, y0, x1, y1, color)

Fill a rectangle of pixels. Coordinates are 1-based and clamped.

Tachikoma.find_font_variant Method
julia
find_font_variant(font_path, variant) → String

Find a style variant of a font file (e.g. "Bold", "Italic", "BoldItalic"). Returns the path to the variant file, or "" if not found. Results are cached to avoid repeated filesystem lookups during export.

Tachikoma.flicker Function
julia
flicker(tick, seed; intensity=0.1, speed=0.15) → Float64 ∈ [1-intensity, 1]

Stochastic brightness flicker for CRT/phosphor aesthetics. Higher intensity = more pronounced flicker. Each seed gets its own flicker pattern. Returns 1.0 when animations disabled.

Tachikoma.focus_next! Method

Cycle focus to the next window and bring it to front.

Tachikoma.focus_prev! Method

Cycle focus to the previous window and bring it to front.

Tachikoma.focusable Method
julia
focusable(widget) → Bool

Return whether a widget can receive keyboard focus. Defaults to false.

Tachikoma.focused_window Method

Get the focused window, or nothing.

Tachikoma.glow Method
julia
glow(x, y, cx, cy; radius=5.0, falloff=2.0) → Float64 ∈ [0, 1]

Radial glow intensity centered at (cx, cy). Returns 1.0 at center, fades to 0.0 beyond radius. falloff controls curve sharpness. Not gated by animations_enabled — purely geometric.

Tachikoma.handle_all_key_actions Method
julia
handle_all_key_actions(model::Model) → Bool

Override to return true if the app should receive key_release events in addition to key_press and key_repeat. By default, press and repeat events are forwarded to update! but release events are dropped. Apps that need release events (e.g. games) can override this to return true.

Tachikoma.handle_event! Method
julia
handle_event!(wm::WindowManager, evt::Event) → Bool

Dispatch keyboard and mouse events to WindowManager-owned handlers.
Tachikoma.handle_key! Method
julia
handle_key!(modal, evt) → Symbol

Handle key events for the modal. Returns:

  • :confirm — user confirmed (Enter on confirm, or right-hand shortcut)

  • :cancel — user cancelled (Escape, Enter on cancel)

  • :none — key was handled but no decision yet (navigation)

  • false — key was not handled

Tachikoma.handle_key! Method
julia
handle_key!(wm::WindowManager, evt::KeyEvent) → Bool

Ctrl+J cycles focus to the next window, Ctrl+K to the previous.
Works on all terminals — no Kitty protocol required.
Only consumed when `focus_shortcuts=true`; otherwise passes through.
Tachikoma.handle_mouse! Method

Convenience overload using cached content area from last render.

Tachikoma.handle_mouse! Method
julia
handle_mouse!(modal, evt) → Symbol

Handle mouse events. Returns :confirm, :cancel, :none, or false. Click on a button to select+confirm. Hover to highlight.

Tachikoma.handle_mouse! Method
julia
handle_mouse!(lst::SelectableList, evt::MouseEvent) → Bool

Handle mouse events: left-click to select, scroll wheel to scroll. Uses last_area cached during the most recent render call.

Tachikoma.handle_scrollbar_mouse! Method
julia
handle_scrollbar_mouse!(state, evt) → Union{Float64, Nothing}

Handle scrollbar click/drag events. Returns a scroll fraction (0.0–1.0) when the scrollbar was interacted with, or nothing if the event was not a scrollbar interaction. The caller maps the fraction to its own offset model.

Returns nothing (not a fraction) on drag release — the caller should still return true to consume the event.

Usage

julia
frac = handle_scrollbar_mouse!(state, evt)
if frac !== nothing
    my_offset = round(Int, frac * max_offset)
    return true
elseif state.dragging  # release event
    return false       # already consumed above
end
Tachikoma.has_pending_output Method
julia
has_pending_output(model::Model) → Bool

Override to return true when the model has asynchronous data ready to process — for example, pending PTY output in terminal widgets.

The app loop checks this after each frame. When true, the inter-frame sleep is skipped and the next frame is processed immediately. This dramatically reduces latency for data flowing through nested terminal widgets (from ~16ms per nesting layer down to ~1-2ms).

Default: false (always sleep between frames).

Tachikoma.hue_shift Method
julia
hue_shift(c::ColorRGB, degrees::Float64) → ColorRGB

Rotate the hue of a color by degrees. Preserves saturation and lightness.

Tachikoma.intrinsic_size Method
julia
intrinsic_size(widget) → (width, height) or nothing

Return the natural size of a widget in terminal cells, or nothing if the widget fills whatever space it is given.

Tachikoma.intrinsic_size Method

Return (width, height) in terminal cells for this BigText widget.

Tachikoma.jitter Method
julia
jitter(tick, seed; amount=0.5, speed=0.1) → Float64 ∈ [-amount, amount]

Noise-based jitter for organic wobble. Deterministic per seed. Returns 0.0 when animations disabled.

Tachikoma.key Method
julia
key(k::Symbol) → KeyEvent
key(c::Char)   → KeyEvent

Shorthand KeyEvent constructor for use in event scripts.

Tachikoma.line! Method
julia
line!(c::PixelCanvas, x0, y0, x1, y1)

Bresenham line drawing in dot-space (same as Canvas).

Tachikoma.list_hit Method
julia
list_hit(evt::MouseEvent, content_area::Rect, offset::Int, n_items::Int) → Int

Returns 1-based item index clicked, or 0 if outside list area or not a left press.

Tachikoma.list_scroll Method
julia
list_scroll(evt::MouseEvent, offset::Int, n_items::Int, visible_h::Int) → Int

Returns new offset for scroll wheel events, or current offset if not a scroll.

Tachikoma.load_pixels! Method
julia
load_pixels!(img::PixelImage, src::Matrix{ColorRGBA})

Nearest-neighbor scale source matrix to fill widget pixel buffer. Source is indexed [row, col].

Tachikoma.load_tach Method
julia
load_tach(filename) → (width, height, cell_snapshots, timestamps, pixel_snapshots)

Load a .tach recording file. Returns the grid dimensions, cell snapshots, timestamps, and pixel snapshot data — ready for any export function.

Tachikoma.markdown_extension_loaded Method
julia
markdown_extension_loaded() → Bool

Return true if the CommonMark.jl extension has been loaded.

Tachikoma.markdown_to_spans Function
julia
markdown_to_spans(md::AbstractString, width::Int; kwargs...) → Vector{Vector{Span}}

Parse Markdown text and return styled Span lines suitable for ScrollPane. Requires the CommonMark.jl extension — call enable_markdown() first.

Tachikoma.noise Method
julia
noise(x::Float64, y::Float64) → Float64 ∈ [0, 1]

2D value noise. Smooth, deterministic.

Tachikoma.noise Method
julia
noise(x::Float64) → Float64 ∈ [0, 1]

1D value noise. Smooth, deterministic, tileable.

Tachikoma.parse_ansi Method
julia
parse_ansi(str::AbstractString) → Vector{Span}

Parse a string containing ANSI escape sequences (SGR codes) and return a vector of Spans with the corresponding Style attributes applied.

Supports:

  • Standard colors (30–37 fg, 40–47 bg)

  • Bright colors (90–97 fg, 100–107 bg)

  • 256-color mode (38;5;n / 48;5;n)

  • 24-bit RGB (38;2;r;g;b / 48;2;r;g;b)

  • Bold, dim, italic, underline, strikethrough, reverse video

  • Reset (0 / \e[m)

  • Non-SGR escape sequences are silently stripped.

Example

julia
spans = parse_ansi("\e[1;31mError:\e[0m something broke")
Paragraph(spans)
Tachikoma.parse_kitty_key Method
julia
parse_kitty_key(params::Vector{UInt8}) -> KeyEvent

Parse a CSI u sequence from the Kitty keyboard protocol. Format: keycode[;[modifiers][:event_type]]u

Tachikoma.pause Method
julia
pause(seconds) → (delay, Wait())

Advance the EventScript timeline cursor by seconds without firing an event.

Tachikoma.pending_command! Method

Consume and return the last completed :command (e.g. "wq", "w", "q"). Returns "" if no command is pending. Call after handle_key! to dispatch commands.

Tachikoma.pixel_line! Method
julia
pixel_line!(c::PixelCanvas, x0::Int, y0::Int, x1::Int, y1::Int)

Bresenham line drawing at native pixel resolution (1-based).

Tachikoma.pixel_line! Method
julia
pixel_line!(img::PixelImage, x0, y0, x1, y1, color)

Bresenham line drawing at pixel resolution (1-based).

Tachikoma.pixel_line! Method
julia
pixel_line!(img::PixelImage, x0, y0, x1, y1)

Bresenham line using img.color.

Tachikoma.pixel_size Method
julia
pixel_size(area::Rect) → (w, h)

Estimate pixel dimensions for a character Rect.

Tachikoma.prepare_for_exec! Method
julia
prepare_for_exec!()

Prepare the terminal for process replacement via execvp. Restores stdin/stdout/stderr to /dev/tty, writes terminal restore sequences, and exits raw mode. Works without access to the Terminal struct or CaptureState — operates entirely at the OS fd level.

Call this immediately before ccall(:execvp, ...) or similar process replacement from any context (async tasks, bridge code, etc.).

Tachikoma.pty_alive Method
julia
pty_alive(pty::PTY) → Bool

Check if the child process is still running (non-blocking waitpid).

Tachikoma.pty_close! Method
julia
pty_close!(pty::PTY)

Close the PTY master fd, stop the reader task, send SIGHUP to the child (if any), and reap it.

Tachikoma.pty_pair Method
julia
pty_pair(; rows=24, cols=80) → (pty::PTY, slave_fd::Cint)

Create a PTY pair without spawning a subprocess. Returns the PTY (master side with reader task) and the raw slave fd. The caller is responsible for the slave fd (e.g., wrapping it in Julia IO for an in-process REPL). The PTY has child_pid = 0.

Tachikoma.pty_read Method
julia
pty_read(pty::PTY, buf::Vector{UInt8}, max_bytes::Int) → Int

Non-blocking read from the PTY master fd. Returns the number of bytes read into buf, or 0 if no data is available. Returns -1 on error (other than EAGAIN).

Note: Prefer reading from pty.output (Channel) instead of calling this directly. The background reader task handles reading automatically.

Tachikoma.pty_resize! Method
julia
pty_resize!(pty::PTY, rows::Int, cols::Int)

Update the PTY's terminal size. Sends TIOCSWINSZ ioctl and SIGWINCH to the child process group so it can reflow its output.

Tachikoma.pty_spawn Method
julia
pty_spawn(cmd::Vector{String}; rows=24, cols=80) → PTY

Create a PTY pair and spawn a child process running cmd. Uses openpty() for PTY creation and posix_spawnp() for process spawning (avoids fork() deadlocks in multithreaded Julia). POSIX_SPAWN_SETSID gives the child its own session, and opening the slave PTY by path makes it the controlling terminal.

A background reader task is started automatically. Read output from pty.output (a Channel).

Tachikoma.pty_write Method
julia
pty_write(pty::PTY, data::Vector{UInt8})

Write raw bytes to the PTY master fd (sends input to the subprocess).

Tachikoma.pulse Method
julia
pulse(tick; period=60, lo=0.3, hi=1.0) → Float64

Smooth sinusoidal pulse between lo and hi. Returns hi when animations are disabled.

Tachikoma.record_app Method
julia
record_app(model::Model, filename::String;
           width=80, height=24, frames=120, fps=30,
           events=Event[])

Record a Model headlessly into a .tach file. Runs for frames frames at the given fps, optionally injecting events from the events list.

The events argument is a vector of (frame_number, event) pairs. Events are dispatched to update! when their frame number is reached.

Example

julia
record_app(DashboardModel(), "dashboard.tach";
           width=80, height=24, frames=180, fps=15)
Tachikoma.record_gif Function
julia
record_widget(filename::String, width::Int, height::Int,
              num_frames::Int; fps::Int=10) do buf, area, frame_idx
    # render widgets here
end

Record arbitrary widget rendering into a .tach file. The callback receives (Buffer, Rect, frame_index) and should render into the buffer. Pixel content is supported: use render_graphics!(frame, data, rect) by accepting a Frame from the 4-argument callback form.

For single-frame static screenshots, use num_frames=1.

Example

julia
record_widget("gauge.tach", 60, 3, 1) do buf, area, frame
    render(Gauge(0.75, block=Block(title="CPU")), area, buf)
end
Tachikoma.recording_enabled Method
julia
recording_enabled(model::Model) → Bool

Override to return false to disable the Ctrl+R recording shortcut. Useful for apps with embedded terminals or REPLs where Ctrl+R should be forwarded to the content instead.

Tachikoma.render Function
julia
render(widget, area::Rect, buf::Buffer)

Render a widget into the given buffer region. This is the core widget protocol — implement this method via multiple dispatch to create new widgets.

Tachikoma.render Method
julia
render(c::PixelCanvas, rect::Rect, buf::Buffer)

Fallback render path: samples pixel buffer to braille characters, same visual as Canvas but at pixel resolution.

Tachikoma.render Method
julia
render(c::PixelCanvas, rect::Rect, f::Frame; tick::Int=0, decay::DecayParams=DecayParams())

Primary render path: encodes pixels via the detected graphics protocol and places them into the frame's region list. Decay defaults to off (clean rendering); pass decay=decay_params() for bit-rot effects.

Tachikoma.render Method
julia
render(si::PixelImage, rect::Rect, buf::Buffer)

Render PixelImage to a Buffer by sampling pixels to braille characters.

Tachikoma.render Method
julia
render(si::PixelImage, rect::Rect, f::Frame; tick::Int=0)

Render PixelImage to a Frame via the detected graphics protocol.

Tachikoma.render Method
julia
render(wm::WindowManager, area::Rect, buf::Buffer; tick=nothing)

Render all windows back-to-front within the given area. If omitted, tick defaults to the manager's internal tick counter.

Tachikoma.render_background! Method
julia
render_background!(bg, buf, area, tick; brightness=0.3, saturation=0.5, speed=0.5)

Render an animated background texture into area of buf.

Call this at the start of your view() function, before rendering foreground widgets. Foreground writes will naturally overwrite the background in cells they touch.

  • brightness (0–1): master brightness of background colors

  • saturation (0–1): color saturation (0 = grayscale)

  • speed (>0): animation speed multiplier applied to tick

Tachikoma.render_canvas Method
julia
render_canvas(c, rect, f::Frame; tick=0)

Backend-agnostic render helper. Dispatches to the correct render method for Canvas, BlockCanvas, or PixelCanvas.

Tachikoma.render_graphics! Method
julia
render_graphics!(f::Frame, data::Vector{UInt8}, area::Rect;
                 pixels::Union{Matrix{ColorRGB}, Nothing}=nothing,
                 format::GraphicsFormat=gfx_fmt_sixel)

Place pre-encoded raster data (sixel or Kitty) into the frame, reserving the character buffer area with blanks. When pixels is provided, the pixel matrix is stored for raster export (GIF/APNG).

Tachikoma.render_rgba! Method
julia
render_rgba!(f::Frame, rgba::Vector{UInt8}, w::Int, h::Int, area::Rect;
             cols::Int=area.width, rows::Int=area.height, z::Int=-1,
             scale_to_cells::Bool=true)

Render RGBA pixel data into a Frame. On kitty, uses native RGBA with z-index for layered compositing. On sixel, blends into a virtual framebuffer that gets composited and encoded at frame end. Pixels with (0,0,0,0) are transparent and will not be rendered.

rgba must be w * h * 4 bytes in row-major order (top-to-bottom, left-to-right).

Tachikoma.rep Method
julia
rep(event, n; gap=1.0) → Vector{Tuple{Float64,Any}}

Repeat event n times, each gap seconds after the previous.

julia
EventScript(rep(key('r'), 4))   # fire 'r' at t=1, 2, 3, 4
Tachikoma.reset_background! Method
julia
reset_background!(img::PixelImage)

Re-enable canvas-bg tracking so img.bg follows canvas_bg() on subsequent syncs (clears, resizes, theme changes).

Tachikoma.route_output! Method
julia
route_output!(rw::REPLWidget, text::String)

Inject text into the REPL widget's display. Used by the on_stdout/on_stderr callbacks to route captured process output (e.g., from shell mode or Pkg operations) into the widget.

Writes directly to the PTY output channel rather than through the slave TTY handle. This avoids libuv threading issues when the REPL frontend is concurrently using the same underlying PTY (e.g., during Pkg operations triggered by using SomePackage).

Tachikoma.seq Method
julia
seq(events...; gap=1.0) → Vector{Tuple{Float64,Any}}

Return a sequence where each event fires gap seconds after the previous one. The first event fires gap seconds after the preceding entry in the EventScript.

julia
EventScript(
    (2.0, key(:down)),                    # t=2
    seq(key(:down), key(:up); gap=0.5),  # t=2.5, t=3
)
Tachikoma.set_ansi_enabled! Method
julia
set_ansi_enabled!(enabled::Bool)

Enable or disable global ANSI escape sequence parsing. Individual widgets can still override via their ansi keyword argument.

Tachikoma.set_background! Method
julia
set_background!(img::PixelImage, bg::ColorRGBA)

Set the background color for img and rewrite any pixels currently holding the old background. Disables canvas-bg tracking so the color is preserved across theme changes, resizes, and clears. Pass a color equal to canvas_bg() via reset_background! to re-enable tracking.

Tachikoma.set_markdown! Method
julia
set_markdown!(mp::MarkdownPane, source; width=mp.last_width)

Update the markdown content and re-parse. Optionally specify a new width.

Tachikoma.set_pixel! Method
julia
set_pixel!(c::PixelCanvas, px::Int, py::Int, color::ColorRGBA)

Set a single pixel with an explicit color.

Tachikoma.set_pixel! Method
julia
set_pixel!(c::PixelCanvas, px::Int, py::Int)

Set a single pixel at native resolution. 1-based coordinates: px ∈ [1, c.pixel_w], py ∈ [1, c.pixel_h]. Uses c.color for the pixel color.

Tachikoma.set_pixel! Method
julia
set_pixel!(img::PixelImage, x, y, color)

Set a single pixel at 1-based coordinates. Bounds-checked.

Tachikoma.set_pixel! Method
julia
set_pixel!(img::PixelImage, x, y)

Set a single pixel using img.color.

Tachikoma.set_point! Method
julia
set_point!(c::PixelCanvas, dx::Int, dy::Int)

Set a point in dot-space coordinates (same coord system as Canvas). Each dot maps to a proportional slice of the pixel buffer, ensuring full coverage with no gaps at the edges.

Tachikoma.set_theme! Method
julia
set_theme!(t::Theme)
set_theme!(name::Symbol)

Set the active theme by value or by name (e.g., :kokaku, :motoko).

Tachikoma.set_value! Function
julia
set_value!(widget, v)

Programmatically set a widget's value.

Tachikoma.set_wake! Method
julia
set_wake!(model::Model, notify::Function)

Called by the app loop with a zero-arg notification function. Models that own async data sources (TerminalWidgets, REPLWidgets) should store this function and pass it to set_wake!(tw::TerminalWidget, notify) on existing and newly created widgets.

Tachikoma.set_wake! Method
julia
set_wake!(tw::TerminalWidget, notify::Function)

Store the app-loop wake function. Called by model-level set_wake!.

Tachikoma.set_window_opacity! Method
julia
set_window_opacity!(v::Float64)

Set and persist the global window opacity.

Tachikoma.shimmer Method
julia
shimmer(tick, x; speed=0.08, scale=0.15) → Float64 ∈ [0, 1]

Noise-driven shimmer along a horizontal axis. Good for subtly varying brightness across a row of characters. Returns 0.5 when animations disabled.

Tachikoma.sixel_area_pixels Method
julia
sixel_area_pixels() → (w, h)

Return the actual sixel rendering pixel dimensions (from XTSMGRAPHICS). Returns (w=0, h=0) if not available.

Tachikoma.sixel_scale Method
julia
sixel_scale() → (w, h)

Return the sixel pixel scale factors (from LocalPreferences.toml).

Tachikoma.split_layout Method
julia
split_layout(layout::Layout, rect::Rect) → Vector{Rect}

Divide a Rect into sub-regions according to the layout's direction and constraints.

Tachikoma.split_with_spacers Method
julia
split_with_spacers(layout::Layout, rect::Rect) → (Vector{Rect}, Vector{Rect})

Like split_layout, but also returns N+1 spacer rects: a leading edge spacer, one between each item pair, and a trailing edge spacer. Edge spacers have zero width/height when items fill the entire space.

Tachikoma.sqlite_extension_loaded Method
julia
sqlite_extension_loaded() → Bool

Return true if the SQLite extension has been loaded (i.e. SQLitePagedProvider is available).

Tachikoma.start_recording! Method
julia
start_recording!(rec::CastRecorder, width::Int, height::Int;
                 filename::String="")

Begin a live recording session. A 5-second countdown runs first so the "Recording in N..." notification disappears before frames are captured.

Tachikoma.step! Function
julia
step!(wm::WindowManager, area::Union{Rect, Nothing}=nothing;
      layout_interval::Int=0, layout_tile_at::Int=1, layout_cascade_at::Int=23,
      layout_animate::Bool=true, layout_duration::Int=12) -> Int

Advance the WM tick by one and optionally run automatic layout changes.

If layout_interval > 0, every frame advances an internal phase from 1:layout_interval and:

  • at layout_tile_at, tile!(wm, area)

  • at layout_cascade_at, cascade!(wm, area)

Return the updated tick count.

Tachikoma.stop_recording! Method
julia
stop_recording!(rec::CastRecorder) → String

Stop recording and write the .tach file. Returns the filename written. Cell snapshots are preserved for the export modal; call clear_recording! after export is complete to free memory.

Tachikoma.tab_height Method

How many rows this decoration needs.

Tachikoma.tables_extension_loaded Method
julia
tables_extension_loaded() → Bool

Return true if the Tables.jl extension has been loaded (i.e. DataTable accepts a Tables.jl-compatible source).

Tachikoma.task_queue Method
julia
task_queue(model::Model) → Union{TaskQueue, Nothing}

Override to return a TaskQueue for background task integration. When non-nothing, completed tasks are drained each frame and dispatched to update!(model, event) as TaskEvents. Default: nothing (no queue).

Tachikoma.text_area_cells Method
julia
text_area_cells() → (w, h)

Return the cell grid dimensions detected at TUI startup.

Tachikoma.text_area_pixels Method
julia
text_area_pixels() → (w, h)

Return the total text area pixel dimensions detected at TUI startup.

Tachikoma.theme Method
julia
theme() → Theme

Return the currently active theme.

Tachikoma.tick Method

Current internal tick counter for per-frame/window-manager updates.

Tachikoma.tile! Method
julia
tile!(wm, area; animate=true, duration=15)

Arrange windows in a tiled grid layout. Animates smoothly when animate=true.

Tachikoma.to_colortype Function

Convert Tachikoma color to ColorTypes.jl equivalent. Requires ColorTypes loaded.

Tachikoma.token_style Method
julia
token_style(kind::TokenKind) → Style

Return the theme-derived style for a given token kind. Uses the current theme's color slots: keywords → primary, strings → success, comments → text_dim, etc.

Tachikoma.tokenize_code Method
julia
tokenize_code(lang::AbstractString, chars::Vector{Char}) → Union{Vector{Token}, Nothing}

Tokenize a line of code in the given language. Returns nothing if the language is not supported. Supported languages: julia, python, bash/sh, typescript/javascript.

Tachikoma.tstyle Method
julia
tstyle(field::Symbol; bold=false, dim=false, italic=false, underline=false)

Create a Style using a color from the current theme. field is a theme color name like :primary, :accent, :text, :error, etc.

Example

julia
tstyle(:primary, bold=true)  # bold text in the theme's primary color
Tachikoma.tty_path Method
julia
tty_path() → Union{String, Nothing}

Return the device path of the current terminal (e.g. "/dev/ttys042"). Tries /dev/tty first, then falls back to ttyname(0) (stdin's device). Returns nothing if no terminal is available (e.g. piped stdin).

Useful for passing as tty_out when launching a Tachikoma app inside a PTY-spawned subprocess where /dev/tty may not be configured.

Tachikoma.unset_point! Method
julia
unset_point!(c::PixelCanvas, dx::Int, dy::Int)

Clear a point in dot-space coordinates.

Tachikoma.valid Method
julia
valid(widget) → Bool

Return whether a widget's current value passes validation. Defaults to true for widgets without validators.

Tachikoma.value Function
julia
value(widget)

Return the current user-facing value of a widget.

Returns: String (TextInput/TextArea/CodeEditor), Bool (Checkbox), Int (RadioGroup/SelectableList/DataTable), String (DropDown), Dict{String,Any} (Form).

Tachikoma.window_opacity Method
julia
window_opacity() → Float64

Current global window opacity (0.0–1.0). New FloatingWindows use this as their default.

Tachikoma.window_rect Method

Return the bounding Rect for this window.

Tachikoma.with_terminal Method
julia
with_terminal(f; tty_out=nothing, on_stdout=nothing, on_stderr=nothing)

Run f(terminal) inside the TUI lifecycle (alt screen, raw mode, mouse).

Stdout and stderr are always redirected to pipes during TUI mode to prevent background println() calls from corrupting the display. Rendering goes to /dev/tty directly, bypassing the redirected file descriptors.

Pass on_stdout / on_stderr callbacks to receive captured lines (e.g., for an activity log). When no callbacks are provided, captured output is silently discarded.

Pass tty_out with a path like "/dev/ttys042" to render into a different terminal window than the one running the Julia process. Run cat > /dev/null in the target terminal before handing off its path — this parks the shell and absorbs any buffered input without displaying it. Input (keyboard/mouse) continues to come from the current terminal or via synthetic events. Terminal resize is supported via periodic size polling (once per second).

Tachikoma.write_tach Method
julia
write_tach(filename, width, height, cell_snapshots, timestamps, pixel_snapshots)

Write a .tach recording file. The header is written uncompressed, then all frame data is Zstd-compressed.

Tachikoma.@tachikoma_app Macro
julia
@tachikoma_app

Import the Tachikoma callback functions so you can extend them with your own methods. Place this after using Tachikoma in your module:

julia
module MyApp
using Tachikoma
@tachikoma_app

struct App <: Model ... end
view(m::App, f::Frame) = ...
update!(m::App, e::KeyEvent) = ...
should_quit(m::App) = ...
end

Equivalent to:

julia
import Tachikoma: view, update!, should_quit, init!, cleanup!,
                  handle_all_key_actions, copy_rect, task_queue
Tachikoma.Paged.InMemoryPagedProvider Type
julia
InMemoryPagedProvider(columns, data)

Built-in provider that wraps column-major Vector{Vector{Any}} data and implements sorting, substring search, and per-column filtering in-process. This is the paged equivalent of passing vectors directly to DataTable.

Arguments

  • columns::Vector{PagedColumn}: column definitions

  • data::Vector{Vector{Any}}: column-major data (each inner vector is one column)

Tachikoma.Paged._pdt_build_request Method

Build a PageRequest from current widget state.

Tachikoma.Paged._pdt_clamp_state! Method

Clamp page/selection after data changes.

Tachikoma.Paged._pdt_default_detail Method

Default detail view: shows each column name paired with its value.

Tachikoma.Paged._pdt_detail_fn Method

Return the effective detail function (custom or built-in default).

Tachikoma.Paged.column_defs Function
julia
column_defs(provider::PagedDataProvider) -> Vector{PagedColumn}

Return column definitions. Providers must implement this method.

Tachikoma.Paged.create_sqlite_provider Method
julia
create_sqlite_provider(db, table_name; kwargs...) -> PagedDataProvider

Create a SQLite-backed paged data provider. Requires the SQLite extension to be loaded (via using SQLite or enable_sqlite()).

Tachikoma.Paged.fetch_page Function
julia
fetch_page(provider::PagedDataProvider, request::PageRequest) -> PageResult

Fetch a page of data. Providers must implement this method.

Tachikoma.Paged.filter_capabilities Method

Return filter capabilities (supported operators per column type).

Tachikoma.Paged.pdt_fetch! Method

Synchronous fetch — blocks until data is available. Used by constructor and tests.

Tachikoma.Paged.pdt_fetch_async! Method
julia
pdt_fetch_async!(pdt, queue; task_id=:pdt_fetch)

Non-blocking fetch — spawns the provider call on a background thread. The result arrives as a TaskEvent{PageResult} or TaskEvent{Exception}. Call pdt_receive! from your update!(model, ::TaskEvent) handler.

Tachikoma.Paged.pdt_receive! Method

Apply a successful PageResult to the widget.

Tachikoma.Paged.pdt_receive_error! Method

Apply a fetch error to the widget.

Tachikoma.Paged.pdt_refresh! Method

Trigger a data refresh — uses async hook if set, otherwise sync fetch.

Tachikoma.Paged.pdt_set_provider! Method
julia
pdt_set_provider!(pdt::PagedDataTable, provider::PagedDataProvider)

Switch the data provider with automatic state reset. Resets page, filters, search, column widths, and re-fetches data from the new provider.

Tachikoma.Paged.supports_filter Method

Return whether the provider supports per-column filtering.

Tachikoma.Paged.supports_search Method

Return whether the provider supports global text search.

Index ​