Writer

For the past month or so I’ve been working on a bunch of tauri apps, each with a different front-end framework. The first one I want to talk about is Writer. It’s inspired by iaWriter in that it’s basically my attempt at remaking iaWriter with tools and libraries I know how to use. I also added some features that are a bit like Things, specifically the quick capture system.

It’s built with codemirror, React, and React-PDF on the front-end. One of the big things I tried to attempt with this project was to use Rust as much as possible to hold state, though you’ll see that there are more lines of code in TypeScript, likely due to markup. There’s a ton of markup and code splitting because I opted to use a lint rule that forced me to keep my JSX nesting under 3-4 levels, aptly called react/jsx-max-depth (I use this in the SolidJS project I’ll discuss later too).

Tauri holds document and file state and emits file-system events, and partial rendering of markdown. This is done via Tauri’s Emitter struct and the notify crate (it’s cross-platform, just like Tauri). Through JavaScript bindings, the listens for events and renders the current state of all files. An experiment I tried out with this was to build a system of ports, named after and inspired heavily by the Elm Architecture (TEA). Ports are bindings that Elm code uses to call JavaScript, and similarly, the ports in my project invoke Rust code. The basic flow is pretty simple:

Send a message (command identified by a string), receive an update from the “back-end,” and then update the UI accordingly.

One crazy thing I discovered about Tauri while working on this is that Tauri’s external drag being enabled completely breaks HTML5 drag and drop. I spent days trying to figure out how to properly compute drop zones before finding the github issue that explained this. I made a small website at writer.stormlightlabs.org and releases will be hosted on Github. I’m working on finalizing version 0.2.0 and am excited to share it.

Source code here: https://github.com/stormlightlabs/writer

Agent V

Agent V (v for visualizer) is a CLI and desktop GUI that ingests logs and session data from AI programming agents/assistants and displays them. Right now it supports Codex, Claude, OpenCode, and Crush. It’s been interesting to take a peek into how I use agents and the estimated token costs of what I ask them to do. It would be interesting to see how much it costs the companies hosting the models and the carbon footprint of my work.

As you can see from the screenshot that there are still some data quality kinks to work out. Those have been hard to keep up with. This is unconfirmed but it seems like OpenCode switched to a SQLite database to store session data while I was working on this (or I just didn’t notice it). As far as OpenCode goes, I had started with the export command from OpenCode’s CLI by having the system listen for updates to the log directory. When a log file was added it would call export and store the session. Like Writer, it uses notify as its filesystem watcher to look for new sessions in all sessions so that you can watch your sessions in real-time.

Source code here: https://github.com/stormlightlabs/agentv

Thunderus

Thunderus is an AI agent and harness I’m working on that is meant to provide me with a first-class experience using Kimi K2.5 and GLM5. I find that using Claude and OpenCode, though effective doesn’t work perfectly. GLM with OpenCode in particular will leave off a closing brace and enter a “death loop” trying to find and fix the problem. I don’t yet know if that’s a model problem or a harness problem but I know that side loading GLM keys into Claude doesn’t cause this. I want to leave Claude as-is with Anthropic models so I stick to OpenCode despite the occasional headache.

This is being built with Rust, specifically ratatui. I like Ratatui a lot but compared to libraries like Ink and Bubbletea which borrow patterns from frontend focused tools, it’s been a bit of a learning curve for me. Writing tools and streaming requests between the client and model hasn’t been too bad but getting the UI to match the designs I made has been difficult. One thing about designs: HTML and ASCII mockups are the way to go for TUIs.

They’ll look prettier than what comes out in your terminal but they do look cool.

It’s not open source…yet but once it’s usable I’ll post an update!

Video Editor X

Why it’s called X I don’t know. It’s basically untitled. This is the SolidJS + Tauri project I mentioned earlier. I quite like some of the constructs in Solid. It markets itself as a framework for fine grained reactivity but I really think it provides you with more transparency about the computations being done in your projects. The eslint plugin does a good job of telling you when you’re not properly leveraging signals too. Svelte obscures signals unless you try to type createRawSnippet where in order to use the props you pass into the snippet, you have to call a function. The big thing Solid provides as far as DX goes is no dependency array “footguns.” It automatically detects dependencies much like $derived an $effect in Svelte (which by the way, can be a footgun if you don’t use untrack appropriately) so the compiler reads calls to createEffect and createMemo to construct a list of dependencies. Pretty cool stuff.

The core problem this project this solves for me is wanting to take advantage of ffmpeg and its powerful set of features. I want a simple editing setup and a way to draw audio visualizations using it with a GUI. I also want to be able to take markdown slides and turn them into simple video with audio voiceover. It takes advantage of browser APIs exposed by WebViews for audio recording, editing and parsing libraries that JS can provide like codemirror, as well as htmltocanvas for markdown to html to png for the backend to put together in a video.

Source code here: https://github.com/stormlightlabs/video-editor

Closing Thoughts

I think I’m the poster child for what AI provides engineers, as well as what it exposes in us. My productively has skyrocketed and I’m building a lot of stuff that I’m proud of, but I’m awful at handling releases and promoting my own work. My workflow has changed around this where I don’t power through implementation at the same rate and instead work on a set of tasks with some level of TDD, then iterate on a feature until I feel ready to move forward. This feels like slowing down but my output is turning out better. I’m also leaning into desktop and terminal projects because I don’t need to setup and configure hosting for these projects. They very easily adhere to my local-first ethos.

I chose MiniSearch because it runs entirely in the browser, exposes well-documented ranking hooks, and maintains a reasonable bundle size even after adding conveniences such as fuzzy matching and prefix search.

Today, I’d like to walk through the different components of my implementation so that they can be reproduced or extended for your own use without requiring reverse-engineering of the repository. You can follow along with the source code here. As of writing, we’re in the refactor branch.

Why MiniSearch?

The choice of search engine for a static site involves trade-offs between implementation complexity, runtime performance, and user experience.

MiniSearch addresses the specific use case where full-text search features such as prefix search, fuzzy matching, and field boosting are required to achieve the experience I’m after. Still, the corpus fits comfortably in browser memory. By storing the index locally rather than querying a remote service, the system eliminates network latency. It enables true offline functionality, a characteristic particularly valuable for progressive web applications or documentation sites.

MiniSearch ends up at approximately 7 kB gzipped, with zero runtime dependencies, making it suitable for memory-constrained environments such as mobile browsers.

The library’s developer emphasizes a space-optimized index structure that balances retrieval speed against storage overhead, avoiding the memory explosion common in naïve inverted-index implementations, much like the one I wrote this past week.

Alternative client-side libraries such as Lunr.js or Elasticlunr offer similar capabilities. Still with different performance profiles: Lunr trades some query speed for a more compact index, while Elasticlunr removes stemming (reducing a word to its root form) to reduce build complexity. MiniSearch’s distinguishing feature is its tunable ranking system, which exposes BM25-inspired scoring with per-field boosts and configurable fuzzy-match tolerance.

Content Modeling & Invariants

The project leans on astro:content (Astro’s amazing content collection system) collections to guarantee that every document conforms to a known schema, with Zod for runtime validation. The content config file defines the fields for blog posts, bookmarks, projects, and pages, normalizing types such as date, tags, and categories before build time.

Because MiniSearch does not enforce schemas on the client, the quality of the index depends on the data discipline established by the user. Schema validation catches errors at build time rather than runtime, a property especially valuable when onboarding contributors or migrating legacy content. When a new post is created, it must match the schema; otherwise, Astro will throw an error, preventing malformed/invalid documents from entering the index.

Thanks to this front-loading of validation, the search system can assume structural integrity: every blog post will have a title, description, date, and tags array, eliminating defensive null checks in the indexing pipeline.

I explicitly mark draft fields on blog entries, capture URL metadata for bookmarks and projects, and expose optional Open Graph images on standalone pages. The search system later relies on these attributes to determine which documents are indexed and what metadata is shown in snippets. Establishing these invariants early simplifies downstream logic.

Index Construction Pipeline

The document index originates from search-index.json, an Astro API route that runs at build time and during development.

The handler invokes getCollection for each content type, filters out drafts, and converts markdown bodies into plaintext using a deterministic stripMarkdown helper. The helper removes headings, emphasis markers, inline code fences, and link syntax to ensure MiniSearch ingests only searchable prose. Every record in the resulting array is capped at 500 characters to keep the JSON payload compact.

The route exports prerender = true, instructing Astro to emit a static /search-index.json artifact during the production build. When running the dev server, the handler still executes dynamically, allowing me or any developer to create a new post, refresh the search panel, and immediately see the document without restarting the dev server. This dual-mode behavior ensures parity between development and production, eliminating the need for separate development & production pipelines.

To guard against regressions, the indexer tags each document with a stable id that combines the collection name and slug (for example, blog:mini-search-case-study). This identifier later drives result enrichment on the client, allowing the UI to pull auxiliary metadata, such as tags from the original document array, even if MiniSearch returns only a subset of fields for ranking purposes.

Field Boosting & Relevance Scoring

Boosts add another layer of control. The configuration doubles the weight of matches in title, sets a 1.5 multiplier on description, and leaves other fields at the default weight. These heuristics reflect user expectations: headlines should outrank incidental body matches and echo established search-engine practices.

The underlying mechanics draw from information retrieval research, specifically the BM25 ranking function that improves upon classical TF-IDF (Term Frequency-Inverse Document Frequency). Where TF-IDF naively multiplies term frequency by inverse document frequency, BM25 introduces term frequency saturation: once a document contains enough occurrences of a query term, additional mentions yield diminishing returns. This prevents keyword-stuffed documents from dominating results purely through repetition. The k₁ parameter controls the saturation curve; MiniSearch’s defaults align with standard search-engine tuning.

BM25 also normalizes for document length, addressing the bias toward longer texts in TF-IDF. A match in a short document often signals higher relevance than the same match buried in a 5000-word essay. By adjusting scores based on document length relative to the average corpus length, BM25 produces rankings that better match human judgment. Field boosting extends this framework by treating matches in high-value fields, such as titles, as if they appeared multiple times, effectively amplifying their contribution to the final score.

Fuzzy matching with a tolerance of 0.2 offers resilience to common typos without diluting precision, and prefix search ensures that partially typed terms still surface meaningful results. These features combine to create a forgiving search experience: users can type “progresive” instead of “progressive,” omit the final letters of a word mid-query, and still receive relevant hits.

UI

Two separate UI surfaces consume the same index.

The compact overlay is implemented in a SearchBar component and mounts as part of the global navigation. It fetches the index on first use, initializes MiniSearch once, and caches the resulting instance. Results appear immediately below the input, capped at ten entries to preserve readability inside the constrained panel. Each entry lists the title, an optional description snippet, the content type badge, and up to three tags. The dedicated search page reuses the same index but renders a paginated list with 12 results per page (I may make this configurable), explicit navigation controls, and richer snippets.

Because the page is route-level content, it also reads and stores state in the URL, with a query parameter to allow creation of shareable search links without additional server support. Both components guard against unnecessary hydration by running their initialization logic inside a document-level event listener.

Astro’s client-side router triggers this event whenever navigation occurs, so the search UI stays functional even during client-side transitions without re-downloading scripts. No component uses a client:* directive keeping the scripts inline, and the browser only executes them when the respective page is active.

Document Enrichment & Snippets

While MiniSearch returns ranking data, it does not know which field triggered the match or how to craft usable snippets. Both UI implementations solve this by searching the original documents array for a record with the matching id and calling helper functions defined within the class.

• findMatchedField tokenizes the query, checks the title, tags, description, and body in that order, and returns the first field containing a term.
  This information informs whether the UI should display a description or a body excerpt.

• extractMatchSnippet takes the plaintext body text, locates the earliest occurrence of any query token, and returns approximately 60–100 characters on either side (depending on the surface).
  If no term is found, the helper falls back to truncating the body to a fixed length.

• highlightMatch wraps each matched term in <mark> tags.
  Paired with custom CSS in both files, this produces consistent visual emphasis without re-processing the HTML on the server.

These helpers remain deterministic and pure. They also share identical logic between the overlay and the full page to avoid confusing users with mismatched results.

Data Prep & Error Handling

The construction pipeline follows indexing best practices by configuring searchable fields before adding documents. Defining which fields contribute to ranking and which weights to apply, ahead of time, allows MiniSearch to optimize its internal data structures during initialization. The alternative, reconfiguring fields after ingestion, would require rebuilding the index from scratch.

Document batching also matters, though less so for static builds than for real-time indexing. Because the search index route runs during build time, all documents are processed in a single operation. If the system ever migrates to incremental static regeneration, batching updates into larger payloads will outperform many small HTTP requests. A single large batch is processed more quickly than multiple smaller ones due to reduced overhead from request parsing and response serialization.

To minimize layout thrash, all DOM updates happen through string templates assembled before assignment. Highlighting occurs before the markup is rendered, preventing partial renders. The overlay also limits its vertical space with scroll overflow handling, so it does not push other layout elements around.

Because the endpoint produces deterministic JSON, there are few moving parts, but the surfacing of load failures still matters during deployments or CDN incidents.

In development, I often log the number of indexed documents after MiniSearch loads, which provides a quick sanity check that the expected collections were captured.

Performance

A static JSON index plus a WASM-free search engine results in low overhead.

The indexer truncates bodies, reducing payload size. This is a practice recommended by search optimization guides that emphasize trimming unnecessary data to accelerate processing. Cached responses mean repeat searches do not refetch data, and both components reuse the same MiniSearch instance across interactions. Because everything stays in the browser, latency hinges on client CPU rather than network round-trips, which keeps search responsive even for users on slow connections once the index is downloaded.

Pagination & Accessibility

The full search page integrates a small pagination module (paginate and setupPaginationNavigation). The first function slices the result array while returning metadata such as hasNext, hasPrev, and lastPage.

The second attaches click handlers to the “Previous” and “Next” buttons and keeps aria attributes in sync with the disabled state. When users navigate across pages, the class scrolls the viewport to the top for context continuity. These behaviors are implemented with minimal DOM mutations and no external dependencies.

Keyboard and screen-reader support come baked in. Inputs use descriptive placeholder text, results render as anchor elements for native focus management, and pagination controls expose aria-label attributes. The overlay includes logic to close itself when pressing Escape or clicking outside the panel, preventing inadvertent focus trapping.

Extensibility

Adding a new content collection requires two steps:

1. Extend your content schema

2. Replicate the indexing loop inside the search-index.json route.

It’s a good idea to keep naming conventions consistent to ensure the front-end helpers continue to work without modification.

If the new content introduces a different metadata taxonomy (for example, topics instead of tags), normalize it to the existing tags or categories arrays before serializing the document. MiniSearch configurations can evolve without rewriting the UI. For instance, adding field-specific fuzziness or custom tokenization can happen at instantiation time. However, any change that affects stored fields has to be mirrored in the result enrichment logic, or else the UI might request metadata that no longer exists in the index.

Conclusion

The search experience on this Astro site balances predictability and flexibility: it is deterministic at build time, lazy at runtime, and straightforward to extend. Adhering to Astro’s strict & built-in content schemas, normalizing documents before serialization, and instantiating MiniSearch exactly once per surface eliminates many of the pitfalls usually associated with client-side search.

I think the resulting implementation is fast, index-driven, and maintainable without external services. Let me know in the comments if you have any feedback or questions!

References

MiniSearch documentation - lucaong.github.io/minisearch
Luca Ongaro, “MiniSearch, a client-side full-text search engine” - lucaongaro.eu/blog
“Understanding TF-IDF and BM-25” - kmwllc.com
“BM25 Explained: A Better Ranking Algorithm than TF-IDF” - vishwasg.dev/blog
“BM25 relevance scoring” - Microsoft Learn
“Search indexing best practices for top performance” - algolia.com/blog
Stemming | Elastic Docs. https://www.elastic.co/docs/manage-data/data-store/text-analysis/stemming

Tarjan’s algorithm is an elegant linear-time method to identify strongly connected components (SCCs) in directed graphs. It underpins essential infrastructure in compilers, static analyzers, and dependency management systems. In software analysis, directed graphs arise naturally from imports, function calls, and data dependencies. Recognizing cycles within these graphs is critical for incremental computation, correctness, and maintainability.

Today I’d like to outline the algorithm’s structure and theoretical basis, then examine its application in the context of Beacon, a Rust-based Python language server that I’ve been building. Beacon’s workspace module treats source files and imports as a dependency graph. By integrating Tarjan’s algorithm into this architecture, the system achieves deterministic incremental analysis and reliable cycle detection without resorting to ad hoc heuristics. It offers us a simple yet powerful way to partition such graphs into strongly connected components using a single depth-first search (DFS).

Theory

Strongly Connected Components

Given a directed graph G = (V, E), a strongly connected component (SCC) is a maximal subset C ⊆ V such that for any two vertices u, v ∈ C, there are paths from u to v and from v to u. Collapsing each SCC into a single node produces a condensation graph, which is acyclic by definition. This transformation simplifies reasoning about dependency order and incremental updates.

A directed graph can be thought of as a set of points connected by one-way arrows. A strongly connected component (SCC) is a group of points where you can follow the arrows in some direction and always find your way from any point in the group back to any other point. If you shrink each of these groups down to a single point, you get a simpler version of the graph called a condensation graph. This new graph never has loops that let you return to your starting point. It always moves forward. That property makes it easier to understand how parts of a system depend on each other or how changes can be mutated in order. In software systems, SCCs represent groups of mutually dependent modules, so detecting and collapsing these cycles allows systems to analyze or rebuild only what is necessary.

The Algorithm

Tarjan’s algorithm identifies SCCs with linear time complexity (O(V + E) → O(N)), through a single depth-first traversal. It maintains the state as:

• index[v]: the order in which node (v) was discovered;

• lowlink[v]: the smallest discovery index reachable from (v), including back edges;

• A stack to record the current search path.

During traversal, each node is pushed onto the stack when it’s discovered. If we encounter an edge to a node already on the stack, it updates the lowlink value to the smaller index, recording a back edge. When index[v] and lowlink[v] are equal, the node is identified as the root of a strongly connected component; nodes are popped until that root is removed, forming a single SCC.

procedure strongconnect(v):
    v.index = index
    v.lowlink = index
    index += 1
    stack.push(v)
    v.onStack = true

for each (v, w) in E:
        if w.index is undefined:
            strongconnect(w)
            v.lowlink = min(v.lowlink, w.lowlink)
        else if w.onStack:
            v.lowlink = min(v.lowlink, w.index)
    if v.lowlink == v.index:
        pop vertices from stack until v is popped
        output these as one SCC

These SCCs can be generated in reverse topological order of the condensation graph. In other words, from components with no outgoing dependencies to those that depend on others.

This ordering is especially valuable in contexts such as dependency analysis and incremental scheduling, where processing components in dependency-resolved order ensures that each component’s prerequisites are handled before its own. In practice, this allows systems to update/recompute only the affected parts when changes occur, without reprocessing the entire graph. These features were paramount when traversing and analyzing Python projects with Beacon.

Python Workspaces as Graphs

A Python project can be interpreted as a directed graph where each module (file) is a node and each import statement forms a directed edge.

However, Python’s flexibility complicates this process. Imports can occur at runtime or conditionally within functions, and the distinction between source and stub files (.pyi) adds further complexity. A naive linear scan or heuristic ordering easily leads to inconsistent states or redundant reanalysis.

Beacon addresses this challenge by constructing a live dependency graph that represents the workspace as it evolves. Every edit, file addition, or configuration change updates this graph. Tarjan’s algorithm sits at the center of that process.

Beacon’s Implementation

Workspace Discovery and Graph Construction

Beacon begins by traversing the workspace using the ignore crate, to honor .gitignore and virtual environment patterns. Each discovered Python file becomes a node represented by a ModuleInfo record containing its URI, logical module name, source root, and dependency set.

The system parses each file’s abstract syntax tree (AST) and extracts both top-level and nested import statements to form directed edges. These edges are stored in an instance of DependencyGraph, which maintains both forward (“imports”) and reverse (“imported by”) links for constant-time queries.

Because Beacon’s document manager also tracks unsaved buffers, the graph always reflects the current editor state rather than the last file-system snapshot.

Running Tarjan’s Algorithm

When the dependency graph changes  after edits, additions, or deletions, the system invokes a routine based on Tarjan’s algorithm, implemented as the TarjanState struct. The algorithm iterates through all nodes, assigning indices and lowlink values while maintaining an explicit stack.

Each discovered SCC is a set of URIs representing modules that form a cycle. Single-element SCCs correspond to acyclic modules; multi-element SCCs reveal circular imports. Rather than treating cycles as errors, Beacon uses them as analysis units: type checking and inference occur on a per-SCC basis to ensure internal consistency among mutually dependent files.

Condensation and Topological Sorting

Once SCCs are identified, Beacon constructs a condensation graph where each SCC becomes a node. Edges are reversed  (if A imports B, then the condensed graph includes B → A) so that topological sorting can proceed in dependency order.

Kahn’s algorithm is then used to produce an analysis schedule: modules without incoming edges are processed first, followed by those whose dependencies are satisfied. The analyzer consumes this order directly to guarantee deterministic results across runs.

Incremental Re-analysis

When a developer edits a file, the document manager re-parses only the edited module. The graph updates its edges, and Tarjan’s algorithm re-runs to identify affected SCCs. Downstream dependencies are discovered through reverse edges, limiting invalidation to directly dependent modules.

Handling Stubs

Python’s dynamic typing makes stubs (.pyi files) essential for static analysis. Beacon indexes these stubs alongside source files and assigns them module identities in the graph. Tarjan’s traversal captures relationships between implementations and their type stubs.

This means that a cycle spanning a stub and its source file remains visible as a single SCC, such that the analyzer maintains a coherent understanding of symbol origins. A shared StubCache, guarded by RwLock (link), provides thread-safe access to these parsed artifacts during analysis.

Algorithmic and Architectural Interplay

Our integration of Tarjan’s algorithm demonstrates how a theoretically simple procedure can provide architectural clarity in a complex, concurrent system. Several examples of design patterns in practice emerge:

1. Separation of concerns
   The dependency graph handles edge management; Tarjan’s algorithm only classifies structure.

2. Predictable invalidation
   SCCs form natural recomputation boundaries.

3. Algorithmic composability.
   Tarjan’s results feed directly into Kahn’s algorithm for topological order, yielding a complete pipeline from discovery to analysis scheduling.

4. Concurrency awareness
   By keeping Tarjan’s DFS single-threaded but parallelizing parsing and indexing, Beacon maintains correctness without sacrificing performance.

Broader Implications

Tarjan’s algorithm continues to find new life in systems engineering because its structure aligns with the needs of dynamic environments:

• Incremental computation: SCCs define minimal recomputation units.

• Cycle detection: essential for dependency visualization and modularization.

• Deterministic ordering: condensation and topological sorting ensure reproducibility.

Beacon’s case illustrates that these properties are not confined to compilers or static analyzers; they apply equally to live, concurrent systems where files change continuously. By expressing workspace state as a graph and analysis as traversal, Beacon aligns with a lineage of systems that rely on mathematical invariants for predictability and performance.

Tarjan’s algorithm exemplifies the enduring relevance of algorithmic theory in modern software tooling. Its capacity to decompose complex graphs into minimal, interdependent components provides both computational efficiency and conceptual clarity. In the case of Beacon, this algorithm transforms a Python workspace from a collection of files into a structured dependency graph. Each edit, import, or configuration change becomes an update to that graph, and Tarjan’s logic ensures the system remains consistent. The lesson extends beyond any specific implementation: stable, deterministic software often emerges not from new algorithms but from the disciplined application of old ones. Tarjan’s algorithm, through its balance of simplicity and rigor, remains one of the best examples of that principle.

• “Tarjan’s Strongly Connected Components Algorithm.” Wikipedia, 31 Oct. 2025. Wikipedia, https://en.wikipedia.org/wiki/Tarjan%27s_strongly_connected_components_algorithm

• Tarjan, Robert E., and Uri Zwick. “Finding Strong Components Using Depth-First Search.” arXiv, 2022. DOI.org (Datacite), https://doi.org/10.48550/ARXIV.2201.07197.

Why Spend Time on TUI Tests?

Before we dive into mechanics, it is worth replaying the motivation. Don’t worry, I’m not going to evangelize TDD. There are better resources for that (🐐). TUIs are notoriously tricky to implement regression tests for. A single missed key event can strand users, and refactors that change layouts often break muscle memory. I needed to be confident that our task editor and data browsers survive quick refactors, and to be able to do so without launching a full terminal in every unit test. The answer was to focus on the Bubble Tea model layer. Bubble Tea already treats input, update logic, and rendering as pure(ish) functions. If we can drive those functions deterministically, we can catch regressions with unit-test speed.

The Test Harness

The heart of the setup lives in internal/ui/test_utilities.go. We created TUITestSuite, a struct that encapsulates state for tests that require direct interaction with any tea.Model. This means no real terminal, no threads unless we want them, and no dependence on the default renderer. The suite captures every model update and view string, exposes helpers for sending keyboard messages, and tracks context-based deadlines so tests do not hang when something goes wrong.

The struct definition and setup code look like this:

You will notice a deliberate omission in the SetupProgram helper: We never call tea.NewProgram. Instead, in tests, we’ll run Init, track the returned command, and call Update manually inside SendMessage (in class TEA fashion).

Bubble Tea models are pure enough that this keeps behavior faithful while giving tests the freedom to inject messages synchronously, suspend time, or inspect intermediate views without wrangling goroutines.

The harness also ships with a ControlledOutput writer and a dead-simple ControlledInput stub so we can capture renders when we need to assert on raw Lip Gloss strings.

Two small options make a big difference in practice.

1. WithInitialSize primes the model with a tea.WindowSizeMsg, which mirrors the behavior of real programs resizing themselves on startup.

2. WithTimeout wraps the underlying context so that every WaitFor call shares a deterministic deadline.

Both are defined alongside the suite in test_utilities.go, and they keep tests concise: we express the “terminal” dimensions we care about and let the harness enforce timeouts.

Driving the Model

Once the harness is in place, most tests read like transcripts of user flows. In internal/ui/task_edit_interactive_test.go, we rehearse how a human edits a task, flips between priority schemes, and navigates the status picker. The suite provides SendKey, SendKeyString, and SendMessage, making it easy to express those flows.

A representative sequence from that file looks like this:

This snippet highlights two philosophical decisions.

First, we keep model instances type-safe by casting inside the predicate rather than leaking internal state to the test harness.

Second, we wait for conditions instead of asserting immediately after a key press. Bubble Tea updates often fan out through commands, so giving the model a heartbeat to settle avoids race conditions without sleeping arbitrarily. The suite’s WaitFor helper polls the latest model snapshot every 10 milliseconds and respects the per-test context timeout. When conditionals remain false, the helper returns a wrapped error that is easy to debug. The same file uses SimulateKeySequence for longer workflows. By pairing key events with optional delays, we can mimic the rhythm of real navigation — for example, tabbing through fields and typing text before hitting Enter to persist a change. Because the harness records every intermediate model, assertions can target either the new view or the final state of the struct, whichever is more meaningful for the scenario under test.

Layered Assertions and Helpers

To keep assertions readable, we packaged a tiny helper set inside the same utility file. The Expect.AssertViewContains and Expect.AssertModelState helpers (see internal/ui/test_utilities.go) wrap the repetitive parts of checking the latest view or verifying an invariant on the current model.

These helpers lean on a shared string utility, shared.ContainsString, which normalizes text checks so we can write assertions without worrying about ANSI color sequences that Lip Gloss might add later.

We still write vanilla assertions when the outcome is obvious (for example, checking a boolean flag), but being able to say “assert that the view contains x” as a single line keeps the tests focused on behavior instead of mechanics. This also makes the intent obvious when reading failures in CI.

Pure Model Tests Still Matter

Not every test fires up the harness. For pure update logic, we lean on direct model instances, which keep the signal-to-noise ratio high and avoid unnecessary casts in the test body. The task editor tests in internal/ui/task_edit_test.go are a great example. In it, we build a fully initialized taskEditModel, feed it key messages by hand, and assert on struct fields immediately. Because Bubble Tea models implement the tea.Modelinterface, this style works in parallel with the harness-based tests. We tend to start with direct model tests to pin down deterministic rules (e.g., how priorityMode cycles when you press m). Then we add an integration-style harness test when we want to guarantee real key bindings stay wired up. This dual approach also pays off when Charmbracelet releases updates. Bubbles components like textinput or help occasionally change their internal focus behavior.

Our pure tests cover how we configure those components up front, while the harness-driven tests confirm the Bubble Tea glue code still reacts to real key events the way we expect.

Exercising Bubbles Components

Many of our models embed “bubbles.” The authentication form, for instance, uses two textinput fields with custom placeholders, echo modes, and focus rules. Our authentication form in internal/ui/auth_form_test.go shows how we verify those pieces without hitting the network. We initialize the model with or without a pre-filled handle, call Init to trigger the focus command Bubble Tea generates, and then lean on the harness to send keys:

Because the harness records the entire model, we can inspect component state without exposing setters just for tests. We can also assert that locked fields stay read-only, that validation messages appear inside the render output, and that submission flags flip when we trigger the shortcuts advertised in the help bubble. The tests run in milliseconds yet cover the interactions most likely to break when we tweak key maps or swap in a different Theme function from LipGloss.

Mocking Data Sources for Lists and Tables

Our data browser elements (DataList and DataTable) fetch records asynchronously and support filtering, searching, and pagination. Rather than connecting to an external service every time (though, because we use SQLite, there are examples of using a test repository in the codebase), we provide in-memory mocks that satisfy the same interfaces. You can see these in internal/ui/data_list_test.go and internal/ui/data_table_test.go. The mocks let us specify canned responses, inject errors, and verify that the models respond by showing toasts or falling back to static rendering. When paired with the harness, we can even step through search flows: focus the search field, type the query, send/type Enter, and wait for the view to update with filtered rows. One happy side effect is that these tests double as documentation for our model interfaces. When someone needs to add a new sortable column, they can read the table tests and see exactly which methods are required on the record type.

Handling Time, Commands, and Side Effects

Bubble Tea commands (tea.Cmd) are the trickiest part of testing TUIs because they hide asynchronous work behind function closures. In our current models, most commands either quit the program or kick off a repository operation. The harness’s executeCmd function is intentionally minimal. Right now, it ignores commands unless a test stubs in specific behavior. That gives us complete control over when asynchronous work happens.

When a new model needs to assert on command results, we wrap the command in a test implementation that captures messages and pushes those messages back into the suite with SendMessage.

The key is that we never have to start a separate Bubble Tea program or juggle channels ourselves; the harness keeps the execution single-threaded unless we want to test concurrency that we’ve added.

Time-sensitive logic is handled the same way. We either pass a deterministic clock to the model or use WaitFor with generous deadlines.

The WithTimeout option protects us from infinite waits when a predicate is wrong, while still letting tests use time.Sleep for small delays when trying to simulate the cadence of a real user. This is something you can observe in video scripting tools like VHS (also by charm!)

Bringing Charm Libraries Together

Charm publishes more than Bubble Tea, and our tests keep those pieces aligned. We use the help bubble extensively to advertise key bindings, so our harness tests assert on strings like “enter/ctrl+s: submit” to guarantee the instructions stay accurate.

LipGloss powers color and layout, but the harness captures raw strings without ANSI sequences. That means our tests verify semantic content  like  titles, selected markers, and validation hints, without flaking because of styling tweaks. When we migrate to a new color palette, we expect the snapshots to stay valid because we are intentionally leaving styling assertions to higher-level smoke tests. LipGloss changes are fun; they should not break sensible tests.

Tips for Extending the Suite

If you are adding a new Bubble Tea model to Noteleaf, try this playbook:

1. Start with pure model tests that drive Update directly.
   They run fast and force you to think about state transitions explicitly.

2. Pull in NewTUITestSuite when you bind real key maps or need to verify window-size handling. Reach for WaitFor and WaitForView instead of custom polling to keep timeouts consistent.

3. Mock repositories and data sources instead of reaching into production packages. The existing mocks for tasks, list items, and table records are flexible enough to reuse or crib from.

4. Assert on intent, not styling. Focus on flags, indices, and the view’s output.

Wrapping Up

Testing TUIs can feel daunting, but Bubble Tea’s functional core makes it possible to write expressive, reliable tests without firing up a terminal window. By centralizing the harness in TUITestSuite, leaning on Bubbles components’ predictable APIs, and mocking the data layer, we get rapid feedback that matches real user behavior. The patterns above have scaled from the original task editor to authentication, data browsing, and beyond, and we expect them to keep paying dividends as we explore more of Charm’s ecosystem.

If you are curious to see these ideas encoded in full, clone the repository and explore the linked files; there is plenty more to borrow, extend, or remix for your own Bubble Tea projects.

teatest

Charmbracelet quietly publishes a small experimental package called teatest, which aims to provide an official testing harness for Bubble Tea programs. It wrapstea.Program in a controlled environment that behaves like a headless terminal, similar in spirit to our internal TUITestSuite, but with a slightly different philosophy.

Where our approach isolates the model layer and drives it manually, teatest preserves the full Bubble Tea event loop. It spins up a TestModel process that runs a tea.Program under the hood, captures output frames, and exposes helpers for deterministic teardown and output comparison. This makes it a strong option to test rendering fidelity or program-level behavior rather than individual model transitions.

What teatest Provides

• Program-level execution: It executes a complete Bubble Tea program in a virtual terminal, preserving the message queue and renderer.

• Golden-file testing: Helpers like RequireEqualOutput make it possible to snapshot rendered output and compare it across commits.

• Timeouts and terminal sizing: Options such as WithFinalTimeout and WithInitialTermSize help reproduce stable terminal environments.

• Final model capture: Once the program exits, FinalModel returns the last model state for inspection without reflection hacks.

These features overlap with parts of our own harness but operate at a higher level, closer to how users experience the application.

When to choose teatest vs. other harnesses

• Use teatest when you care not just about internal model transitions but about full-program behavior: layout, rendered view, entire event loop.

• Be aware that because it runs the full event loop (via tea.Program), tests can be heavier, less fine-grained, and potentially slower. The article you referenced even explains why a custom harness (model-only) was chosen instead.

• If your need is “did the screen change as expected after a sequence of keys?” then teatest is a strong fit. If you need “Did the model change its internal flags correctly when I press these keys?”, a lighter harness may suffice.

To adopt teatest, take a look at this article on Charm’s blog.

Why We Chose to Roll Our Own (for Now)

teatest is elegant, but it carries trade-offs that didn’t fit Noteleaf’s priorities early on:

• Experimental status: It lives in the x/exp namespace, meaning API stability is not guaranteed.

• Full-program semantics: Because it runs the entire event loop, tests tend to be heavier and less deterministic when commands trigger asynchronous effects.

• Output focus: The golden-file strategy excels at catching layout regressions, but we needed fine-grained state inspection and control over command timing.

By contrast, our internal TUITestSuite treats models as pure state machines. There are no threads and no renderer letting us assert on intermediate states as often as we need. That design keeps the test cycle fast and predictable.

When teatest Might Be the Better Fit

If you are building a simpler TUI or care deeply about pixel-perfect layout regressions in menus, tables, or dashboards whose visual shape must not drift, teatest deserves a look. It will likely continue to grow as the de facto standard for verifying Bubble Tea applications as the Charm ecosystem converges around consistent (and more awesome) tooling.

Algebraic Data Types (ADTs) form a cornerstone of type theory and functional programming languages, offering a means to construct robust type systems by giving authors the ability to compose complex data types from simpler ones. When we say algebraic, we mean to define operations between type constructors and algebraic operations. In other words, product types correspond to multiplication (Cartesian products of sets of values), while sum types correspond to addition (disjoint unions of sets of values). By using sums and products to treat types algebraically, domains can be clearly and expressively represented, and handled exhaustively through pattern matching, a control flow construct common in functional languages, particularly those that share roots in the ML syntax and even in languages like Gleam and Rust. This exhaustiveness allows leveraging strong static type systems (such as those based on Hindley-Milner type inference) to catch errors at compile time and ensure correctness.

Foundations of ADTs: Sum and Product Types

Let’s dive deeper into the two fundamental constructs of ADTs:

1. Product Types

2. Sum Types

Product Types

Product types combine multiple values, called fields, into a single composite type. In many languages these are tuples and records (seen most commonly as key value pairs). Using set theory, we say that the set of values that make up a product type is the Cartesian product of those values. For example, a 2-tuple type of an integer and a boolean can represent any ordered pair of an integer and true, as well as an integer and false.

Sum Types

Sum types are represented by a group of related types, each of which is called a constructor. A constructor is a named variant that can carry any number of values of any valid type. In many programming languages these are called enums, or unions. The total number of values for a sum type is the sum of all possible values of its variants, i.e. the disjoint union of the sets of values of its variants (in set theory).

By combining sums and products, developers can model intricate data invariants directly in the type system. Consider a commonly implemented data structure: a binary tree. Usually a node, or leaf in a tree, is represented by its data, and pointers to its children. There are two possible cases for a binary tree that we can represent for a tree, either empty, or a root node with two subtrees. The node itself can be a product type which demonstrates the relationship between a type definition and the shape of its data.

Pattern Matching and Type Safety

Any variant of a sum type (a constructor) and its combinations are valid patterns. We check values against possible patterns using one of functional programming’s most compelling and powerful features, made possible by ADTs: Pattern Matching. This allows us to deconstruct values of constructors, and then bind inner fields to names (think destructuring assignment or tuple unpacking in JavaScript, and Python, respectively).

What makes this construct so powerful?

• Exhaustiveness checking: The compiler warns if not all variants are handled, preventing runtime “match failure” errors, ensuring correctness

• Clarity of intent: Each pattern branch explicitly names the data shape it handles, improving readability.

• Conciseness: Nested data can be deconstructed succinctly, reducing boilerplate.

Let’s return to our binary tree from the previous section. When we match against variants of our tree type in OCaml for example, the compiler ensures that any additional variant forces compile time updates to every expression. This is a safety guarantee provided by the compiler that reminds authors to cover every case in every match.

ADTs in OCaml

Let’s dive deeper into OCaml’s support for ADTs. These are provided by variant types (sum types) and records (product types). Here’s an example of how we might represent a tree in OCaml:

Here, 'a tree is what we call a parametric ADT, meaning it can hold values of any type 'a. The empty constructor carries no data, whereas Node carries a 3-tuple/triple: a value of type 'a and two subtrees of the same type. Using pattern matching, we can deconstruct the values to the following:

Records (called structs in languages like Rust and C++) provide named fields, improving self‐documentation:

This definition models geometric shapes with explicit field names. OCaml’s compiler enforces exhaustive matching on these variants, ensuring that any new shape variant must be accounted for in all uses of a match statement.

Parametric Polymorphism and Functoriality

OCaml’s ADTs support polymorphism, allowing definitions to be generic over types (e.g., the ‘a parameter in 'a tree). This parametricity allows for code reuse: the same tree‐processing functions work for trees containing any node type, like integer trees, string trees, or even complex user‐defined types (record or tuples!). Under the hood, the Hindley–Milner type system infers the most general types for functions operating on ADTs, sparing the programmer from repetitive annotations and preserving type safety.

ADTs in F#

F# mirrors OCaml’s ADT capabilities via discriminated unions, coupled with records for product types. In fact F# is often called Microsoft/.NET’s version of OCaml.

A binary tree in F# can be defined as:

This declaration is semantically identical to the OCaml variant. Pattern matching in F# uses the match…with construct:

For records and discriminated unions with named fields, F# allows:

Again we see that pattern matching can extract fields by name:

FSharp’s discriminated unions also support recursive definitions, union cases with multiple fields, and can model complex hierarchies without boilerplate classes or inheritance.

Enhancements: Active Patterns and Union Case Testing

Beyond basic ADTs, F# introduces active patterns, allowing custom deconstruction logic for values that may not be direct ADTs (e.g., strings or numbers). Active patterns further generalize pattern matching and maintain ADT‐like clarity across diverse data sources. Additionally, the :? operator enables union case testing in object‐oriented contexts, bridging ADTs with .NET interoperability. Note that F# is not a functional language, just a functional-first programming language.

Comparative Discussion

OCaml and F# share the ML-syntax lineage and nearly identical ADT semantics, whereby each language leverages ADTs to eliminate a wide class of runtime errors and to encode domain logic directly in type definitions. This encourages a design style where correctness emerges from the type checker rather than from comprehensive test suites alone. However, there are subtle differences:

• Syntax: OCaml uses type ... = … with constructors preceded by |, whereas F# uses a similar syntax but encourages naming union fields directly.

• Tooling: F# benefits from the .NET ecosystem, integrating seamlessly with C# libraries and Visual Studio tooling.

  • OCaml’s ecosystem is more language‐centric, with jbuilder/dune and opam managing builds and packages.

• Interoperability: F# ADTs compile to corresponding .NET types, which can be consumed by other CLR languages, sometimes requiring attribute annotations. In contrast OCaml ADTs compile to native code optimized for performance in different runtimes. Both languages have alternative compilers that allow compiling to JavaScript with Fable for F# and tools like Melange for OCaml (and js_of_ocaml).

Parametric ADTs and GADTs

Generalized Algebraic Data Types (abbreviated GADTs) extend ADTs by allowing constructors to specify more precise return types, enabling richer invariants and encoding of logical constraints in types. In OCaml, GADT syntax uses type ... = with explicit return type annotations, seen below:

Here, the type parameter of expr can vary with each constructor, allowing heterogeneous expression trees that preserve type correctness at compile time. Pattern matching on GADTs refines type information within branches, avoiding unsafe casts and facilitating advanced type‐driven programming.

F# also provides GADT‐like functionality via inline functions and the static resolution of type parameters. Researchers continue to explore seamless GADT integration in F# as part of language evolution efforts.

Applications and Benefits

ADTs shine in scenarios requiring:

• Domain modeling: Encoding business rules and workflows as sum‐of‐product types, such as HTTP response status codes, ASTs for compilers, or finite state machines.

• Error handling: Representing success/failure cases explicitly via Result<'T,'Error> or custom error unions, avoiding unchecked exceptions.

• Configuration and parsing: Defining precise schemas for configuration files or network protocols, with the compiler ensuring exhaustive parsing logic. If you’re familiar with the technique of using recursive descent for parsing syntax trees, you’ll find that matching against collections of tokens allows for a clean, non-regex based traversal.

• Data transformations: Building safe, type‐checked pipelines where each stage maps one ADT to another, guaranteeing all cases are addressed.

The algebraic nature of types also aligns with equational reasoning, enabling formal verification techniques and equational shortcuts in refactoring.

Conclusion

Algebraic Data Types represent a powerful abstraction in typed functional programming, seamlessly combining sum and product constructs to model complex domains. OCaml and F# both offer first‐class support for ADTs—via variants and discriminated unions respectively—paired with exhaustive pattern matching and robust type inference. Advanced extensions such as GADTs further blur the line between types and values, unlocking expressive design patterns and compile‐time guarantees. As software systems grow in complexity and correctness becomes paramount, ADTs stand out as an essential tool in the functional programmer’s toolkit, fostering concise, safe, and declarative code.

Summary

• ADTs blend product types (records, tuples) and sum types (variants, unions) to model complex data

• Pattern matching on ADTs enforces exhaustive handling and clear deconstruction of data 

• OCaml defines ADTs via type ... = | ... and supports parametric polymorphism and GADTs natively  

• F# uses discriminated unions and records, integrates with .NET, and offers advanced features like active patterns  

• GADTs extend ADTs by refining constructor return types, enabling richer invariants and type‐driven design 

• Benefits include safer domain modeling, exhaustive error handling, and support for formal reasoning and verification

References

• Clarkson, Michael R. . “3.9. Algebraic Data Types — OCaml Programming: Correct + Efficient + Beautiful.” Accessed May 1, 2025. https://cs3110.github.io/textbook/chapters/data/algebraic_data_types.html.

• Madhavapeddy, Anil, Yaron Minsky, and Yaron Minsky. Real World OCaml: Functional Programming for the Masses. Second edition. Cambridge, United Kingdom New York, NY: Cambridge University Press, 2022.

• W, Scott. “Algebraic Type Sizes and Domain Modelling | F# for Fun and Profit.” Accessed May 6, 2025. https://fsharpforfunandprofit.com/posts/type-size-and-design/.

• Chrichton, Will. “CS 242: Algebraic Data Types.” Accessed May 1, 2025. https://stanford-cs242.github.io/f19/lectures/03-2-algebraic-data-types.html.

• Dollard, Kathleen. “Pattern Matching - F#.” Accessed May 2, 2025. https://learn.microsoft.com/en-us/dotnet/fsharp/language-reference/pattern-matching.