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.Button Method
julia
Button(label; focused=false, tick=nothing, ...)

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

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.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.Paragraph Method
julia
Paragraph(text; wrap=no_wrap, alignment=align_left, block=nothing, ...)

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.

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.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.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.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._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_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 stdin. 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._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_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. Kitty unlinks the segment after reading (t=s protocol).

Each call uses a unique name derived from a monotonic counter, so multiple images rendered in the same frame never collide.

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._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.anchor Method

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

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. Press Ctrl+C to quit. 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.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.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.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 black.

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.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.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.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, or :search).

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_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{ColorRGB};
             decay::DecayParams=DecayParams(), tick::Int=0,
             cols::Int=0, rows::Int=0) → Vector{UInt8}

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

Uses a=T (transmit + display), f=24 (raw RGB), q=2 (suppress OK). Passes s=width,v=height for pixel dimensions and c=cols,r=rows for cell placement when provided.

Returns UInt8[] for all-black images (matches encode_sixel behavior).

Tachikoma.encode_sixel Method
julia
encode_sixel(pixels::Matrix{ColorRGB}; decay::DecayParams=DecayParams(), tick::Int=0) → Vector{UInt8}

Full pipeline: optionally copy pixels (only when decay is active), apply decay, build palette via flat LUT, encode sixel escape sequence. Returns the complete DCS ... ST byte sequence.

Pixel matrix is indexed [row, col] with row 1 at top.

Each sixel band writes an explicit background layer (color 0 = black) before data colors, ensuring old sixel data is properly overwritten between frames.

Performance: reuses module-level buffers across frames to minimize allocations.

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::ColorRGB)

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.focusable Method
julia
focusable(widget) → Bool

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

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_mouse! Method

Convenience overload using cached content area from last render.

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.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{ColorRGB})

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_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.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.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.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_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.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.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_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::ColorRGB)

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.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.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.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.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.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.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.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.

Index ​