ratatui_ruby-ui 0.1.0

data/README.md

@@ -0,0 +1,124 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# ratatui_ruby-ui
+
+[![
+builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby-ui.svg)](https://builds.sr.ht/~kerrick/ratatui_ruby-ui?) [![
+License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby-ui%2Fblob%2Fstable%2Fratatui_ruby-ui.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
+Gem Total Downloads](https://img.shields.io/gem/dt/ratatui_ruby-ui)](https://rubygems.org/gems/ratatui_ruby-ui) [![
+Gem Version](https://img.shields.io/gem/v/ratatui_ruby-ui)](https://rubygems.org/gems/ratatui_ruby-ui) [![
+Mailing List: Discussion](https://img.shields.io/badge/mailing_list-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) [![
+Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) [![
+Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-announce)
+
+
+## Introduction
+
+**ratatui_ruby-ui** is a gem in the [RatatuiRuby ecosystem](https://sr.ht/~kerrick/ratatui_ruby/).
+**ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
+
+> [!WARNING]
+> **ratatui_ruby-ui** is currently in **PRE-RELEASE**. The API will change rapidly, even between minor and patch versions.
+
+**[Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md)** — Native Rust performance, zero runtime overhead, and Ruby's expressiveness. [See how we compare](https://man.sr.ht/~kerrick/ratatui_ruby/why.md) to CharmRuby, raw Rust, and Go.
+
+Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the [`trunk` branch](https://git.sr.ht/~kerrick/ratatui_ruby-ui/tree/trunk) for pre-release updates.
+
+
+## Compatibility
+
+**ratatui_ruby-ui** is designed to run on [everything Ruby does](https://www.ruby-lang.org/en/documentation/installation/), including:
+
+- GNU/Linux, macOS, Windows, OpenBSD, and FreeBSD; and
+- x86_64 (AMD, Intel) and ARM (Apple Silicon, Raspberry Pi).
+
+We support the latest minor version of every
+[non-eol Ruby version](https://www.ruby-lang.org/en/downloads/branches/),
+including Ruby 4.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+gem "ratatui_ruby-ui"
+```
+<!-- SPDX-SnippetEnd -->
+
+And then execute:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+bundle install
+```
+<!-- SPDX-SnippetEnd -->
+
+Or install it yourself with:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+gem install ratatui_ruby-ui
+```
+<!-- SPDX-SnippetEnd -->
+
+
+## Usage
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+For a full tutorial, see [the Quickstart](./doc/getting_started/quickstart.md). For an explanation of the application architecture, see [Application Architecture](./doc/concepts/application_architecture.md).
+
+
+## Features
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [Quickstart](./doc/getting_started/quickstart.md) | Get running in 5 minutes |
+| [Application Architecture](./doc/concepts/application_architecture.md) | Patterns for scaling your app |
+| [Guides](./doc/index.md) | Tutorials, examples, and more |
+| API Reference | To generate full RDoc documentation, run `bundle exec rake rdoc` |
+| [Wiki](https://man.sr.ht/~kerrick/ratatui_ruby) | Learn more about the RatatuiRuby ecosystem |
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on [sourcehut](https://sourcehut.org) at https://sr.ht/~kerrick/ratatui_ruby/. This project is intended to be a safe, productive collaboration, and contributors are expected to adhere to the [Code of Conduct](https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md).
+
+
+Want to help develop **ratatui_ruby-ui**? Check out the [contribution guide on the wiki](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md).
+
+**Note**: Active development happens on the `trunk` branch. Use `trunk` if you are a contributor or want the latest cutting-edge features. `stable` is for stable releases only.
+
+
+## Copyright & License
+
+**ratatui_ruby-ui** is copyright 2026, Kerrick Long.
+
+The library is [AGPL-3.0-or-later](./LICENSES/AGPL-3.0-or-later.txt). Documentation snippets and widget examples are [MIT-0](./LICENSES/MIT-0.txt): copy and use them without attribution.
+
+Documentation is [CC-BY-SA-4.0](./LICENSES/CC-BY-SA-4.0.txt). Build tooling and full app examples are [AGPL-3.0-or-later](./LICENSES/AGPL-3.0-or-later.txt). See each file's SPDX comment for specifics.
+
+Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the [REUSE Specification – Version 3.3](https://reuse.software/spec-3.3/) for details.
+
+This program was created with significant assistance from multiple LLMs. The process was human-controlled through creative prompts, with human contributions to each commit. See commit footers for model attribution. [declare-ai.org](https://declare-ai.org/1.0.0/creative.html)

data/REUSE.toml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+version = 1
+
+[[annotations]]
+path = 'Gemfile.lock'
+SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
+[[annotations]]
+path = '**/snapshots/*.txt'
+SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+[[annotations]]
+path = '**/snapshots/*.ansi'
+SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "AGPL-3.0-or-later"
+
+[[annotations]]
+path = 'doc/images/*'
+SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require "bundler/gem_tasks"
+require "ratatui_ruby/devtools"
+
+RatatuiRuby::Devtools.install!
+
+# Import project-specific tasks
+Dir.glob("tasks/*.rake").each { |r| import r }
+
+task default: %w[lint:fix test lint reuse]

data/doc/concepts/application_architecture.md

@@ -0,0 +1,16 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Application Architecture
+
+Architect robust TUI applications using core library patterns and API best practices.
+
+## Core Concepts
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+
+## Thread and Ractor Safety
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files._

data/doc/concepts/application_testing.md

@@ -0,0 +1,49 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Application Testing Guide
+
+This guide explains how to test your RatatuiRuby applications using the provided `RatatuiRuby::TestHelper`.
+
+## Overview
+
+You need to verify that your application looks and behaves correctly. Manually checking every character on a terminal screen is tedious. Dealing with race conditions and complex state management in tests creates friction.
+
+The `TestHelper` module solves this. It provides a headless "test terminal" to capture output and a suite of robust assertions to verify state.
+
+Use it to write fast, deterministic tests for your TUI applications.
+
+## Setup
+
+First, require the test helper in your test file or `test_helper.rb`:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+require "ratatui_ruby/test_helper"
+require "minitest/autorun" # or your preferred test framework
+```
+<!-- SPDX-SnippetEnd -->
+
+Then, include the module in your test class:
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+class MyApplicationTest < Minitest::Test
+  include RatatuiRuby::TestHelper
+  # ...
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+## Writing Tests
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files and automated tests._

data/doc/custom.css

@@ -0,0 +1,22 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+.theme-toggle {
+  margin-left: 0 !important;
+}
+
+/* Terminal Previews (Native PNGs)
+ * The images already contain the window chrome and shadows.
+ * We just need to center them and ensure they scale down on mobile.
+ */
+img[src*="images/"] {
+  display: block;
+  margin: 2em auto;
+}

data/doc/getting_started/quickstart.md

@@ -0,0 +1,56 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Quickstart
+
+Welcome to **ratatui_ruby-ui**! This guide will help you get up and running with your first Terminal User Interface in Ruby.
+
+## Installation
+
+See [Installation in the README](../README.md#installation) for setup instructions.
+
+
+## Tutorials
+
+### Basic Application
+
+Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby-ui** app.
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+#### How it works
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+## Examples
+
+These examples showcase the full power of **ratatui_ruby-ui**. You can find their source code in the [examples directory](../examples).
+
+### Widget Demos
+
+Focused examples for individual concepts. Each demonstrates a single concept and ways to interact with it.
+
+| Widget | What it demonstrates |
+|--------|---------------------|
+| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+
+### Sample Applications
+
+These larger examples combine concepts into complete applications, demonstrating real-world TUI patterns and architectures.
+
+| Application | Architecture | What you'll learn |
+|-------------|--------------|-------------------|
+| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+
+
+## Next Steps
+
+Now that you've seen what **ratatui_ruby-ui** can do:
+
+- **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
+- **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
+- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](https://man.sr.ht/~kerrick/ratatui_ruby/troubleshooting/tui_output.md) to prevent screen corruption
+- **Explore the API**: Browse the [full documentation](../index.md)
+- **Learn the philosophy**: Read [Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md) for comparisons and design decisions
+- **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/index.md

@@ -0,0 +1,25 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Start Here
+
+
+## Documentation for Users
+
+- [README](../README.md): Project overview and installation
+
+### Getting Started
+
+- [Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md): Philosophy, comparisons, and what makes us different
+- [Quickstart](./getting_started/quickstart.md): Build your first TUI app
+
+### Concepts
+
+- [Application Architecture](./concepts/application_architecture.md): Lifecycle patterns and API choices
+- [Testing Your Application](./concepts/application_testing.md): Snapshot testing and style assertions
+
+
+## Documentation for Contributors
+
+- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features

data/lib/ratatui_ruby/ui/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
+  module Ui
+    # The version of this gem.
+    # See https://semver.org/spec/v2.0.0.html
+    VERSION = "0.1.0"
+  end
+end

data/lib/ratatui_ruby/ui.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "ui/version"
+
+# Entry point for the ratatui_ruby-ui gem.
+#
+# Ruby libraries benefit from a clear namespace. Gems need a central module.
+#
+# This module serves as the namespace root. All classes and utilities live here.
+#
+# Require this file to load the library.
+module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
+  # Namespace for library functionality.
+  module Ui
+  end
+end

data/mise.toml

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[tools]
+ruby = "4.0.0"
+python = "3.12"
+pre-commit = "latest"

data/tasks/example_viewer.html.erb

@@ -0,0 +1,172 @@
+<%#
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: AGPL-3.0-or-later
+%>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><%= page_title %> - Example Viewer</title>
+  
+  <script>
+  var rdoc_rel_prefix = "<%= doc_root_link.sub('index.html', '') %>";
+  var index_rel_prefix = "<%= '../' * (relative_path.split('/').size - 1) %>";
+  </script>
+
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_navigation.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_data.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_ranker.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_controller.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/aliki.js" defer></script>
+
+  <link href="<%= doc_root_link.sub('index.html', '') %>css/rdoc.css" rel="stylesheet">
+  <link href="<%= doc_root_link.sub('index.html', '') %>custom.css" rel="stylesheet">
+</head>
+<body class="file<%= ' has-toc' unless toc_items.empty? %>">
+<%= icons_svg %>
+  <header class="top-navbar">
+    <div class="navbar-brand">
+      Example Viewer
+    </div>
+    
+    <!-- Desktop search bar -->
+    <div class="navbar-search navbar-search-desktop" role="search">
+      <form action="#" method="get" accept-charset="utf-8">
+        <input id="search-field" role="combobox" aria-label="Search"
+               aria-autocomplete="list" aria-controls="search-results-desktop"
+               type="text" name="search" placeholder="Search (/) examples..."
+               spellcheck="false" autocomplete="off"
+               title="Type to search, Up and Down to navigate, Enter to load">
+        <ul id="search-results-desktop" aria-label="Search Results"
+            aria-busy="false" aria-expanded="false"
+            aria-atomic="false" class="initially-hidden search-results"></ul>
+      </form>
+    </div>
+
+    <!-- Mobile search icon button -->
+    <button id="search-toggle" class="navbar-search-mobile" aria-label="Open search" type="button">
+      <span aria-hidden="true">🔍</span>
+    </button>
+
+    <button id="theme-toggle" class="theme-toggle" aria-label="Switch to dark mode" type="button" onclick="cycleColorMode()">
+      <span class="theme-toggle-icon" aria-hidden="true">🌙</span>
+    </button>
+  </header>
+
+  <!-- Search Modal (Mobile) -->
+  <div id="search-modal" class="search-modal" hidden aria-modal="true" role="dialog" aria-label="Search">
+    <div class="search-modal-backdrop"></div>
+    <div class="search-modal-content">
+      <div class="search-modal-header">
+        <form class="search-modal-form" action="#" method="get" accept-charset="utf-8">
+          <span class="search-modal-icon" aria-hidden="true">🔍</span>
+          <input id="search-field-mobile" role="combobox" aria-label="Search"
+                 aria-autocomplete="list" aria-controls="search-results-mobile"
+                 type="text" name="search" placeholder="Search examples"
+                 spellcheck="false" autocomplete="off">
+          <button type="button" class="search-modal-close" aria-label="Close search" id="search-modal-close">
+            <span aria-hidden="true">esc</span>
+          </button>
+        </form>
+      </div>
+      <div class="search-modal-body">
+        <ul id="search-results-mobile" aria-label="Search Results"
+            aria-busy="false" aria-expanded="false"
+            aria-atomic="false" class="search-results search-modal-results initially-hidden"></ul>
+        <div class="search-modal-empty">
+          <p>No recent searches</p>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <nav id="navigation" role="navigation">
+    <div id="fileindex-section" class="nav-section">
+      <details class="nav-section-collapsible" open>
+        <summary class="nav-section-header">
+          <span class="nav-section-icon">
+             <svg><use href="#icon-file"></use></svg>
+          </span>
+          <span class="nav-section-title">Examples</span>
+          <span class="nav-section-chevron">
+            <svg><use href="#icon-chevron"></use></svg>
+          </span>
+        </summary>
+        <ul class="nav-list">
+          <li><a href="<%= doc_root_link %>">← Back to Docs</a></li>
+        </ul>
+      </details>
+    </div>
+    <div class="nav-section">
+      <details class="nav-section-collapsible" open>
+        <summary class="nav-section-header">
+          <span class="nav-section-icon">
+            <svg><use href="#icon-layers"></use></svg>
+          </span>
+          <span class="nav-section-title">Files</span>
+          <span class="nav-section-chevron">
+            <svg><use href="#icon-chevron"></use></svg>
+          </span>
+        </summary>
+        <ul class="link-list nav-list">
+          <%= render_tree(tree_data, relative_path, current_file_html) %>
+        </ul>
+      </details>
+    </div>
+  </nav>
+
+  <main role="main">
+    <div class="breadcrumb">
+      <%= breadcrumb_path %>
+    </div>
+    <%= file_header_html %>
+    <div class="content">
+      <%= file_content_html %>
+    </div>
+  </main>
+
+  <% unless toc_items.empty? %>
+  <aside class="table-of-contents" role="complementary" aria-label="Table of Contents">
+    <div class="toc-sticky">
+      <div class="toc-list">
+        <h3>On This Page</h3>
+        <%= render_toc(toc_items) %>
+      </div>
+    </div>
+  </aside>
+  <% end %>
+
+
+  <script>
+    const modes = ['auto', 'light', 'dark'];
+    const icons = { auto: '🌓', light: '☀️', dark: '🌙' };
+    
+    function setColorMode(mode) {
+      if (mode === 'auto') {
+        document.documentElement.removeAttribute('data-theme');
+        const systemTheme = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light';
+        document.documentElement.setAttribute('data-theme', systemTheme);
+      } else {
+        document.documentElement.setAttribute('data-theme', mode);
+      }
+      
+      const icon = icons[mode];
+      const toggle = document.getElementById('theme-toggle');
+      toggle.querySelector('.theme-toggle-icon').textContent = icon;
+      
+      localStorage.setItem('rdoc-theme', mode);
+    }
+    
+    function cycleColorMode() {
+      const current = localStorage.getItem('rdoc-theme') || 'auto';
+      const currentIndex = modes.indexOf(current);
+      const nextMode = modes[(currentIndex + 1) % modes.length];
+      setColorMode(nextMode);
+    }
+    
+    const savedMode = localStorage.getItem('rdoc-theme') || 'auto';
+    setColorMode(savedMode);
+  </script>
+</body>
+</html>

data/tasks/resources/build.yml.erb

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+<%- if has_rust -%>
+  - clang
+<%- end -%>
+  - git
+artifacts:
+  - <%= gem_name %>/pkg/<%= gem_filename %>
+sources:
+  - https://git.sr.ht/~kerrick/<%= gem_name %>
+tasks:
+  - setup: |
+      curl https://mise.jdx.dev/install.sh | sh
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+<%- if has_rust -%>
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
+<%- end -%>
+      . ~/.buildenv
+      export CI="true"
+      cd <%= gem_name %>
+      sed -i 's/ruby = .*/ruby = "<%= ruby_version %>"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:<%= bundler_version %>
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+<%- if has_rust -%>
+      mise x -- bundle exec rake compile
+<%- end -%>
+  - test: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      echo "Testing Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      echo "Linting Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      mise x -- bundle exec rake build

data/tasks/resources/index.html.erb

@@ -0,0 +1,44 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= project_name %> documentation</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    :root { color-scheme: light dark; }
+    body { font-family: system-ui, sans-serif; max-width: 800px; margin: 0 auto; padding: 2rem; line-height: 1.5; color: light-dark(#111, #eee); background: light-dark(#fff, #111); }
+    h1 { border-bottom: 2px solid light-dark(#eee, #333); padding-bottom: 0.5rem; }
+    ul { list-style: none; padding: 0; }
+    li { margin: 0.5rem 0; border: 1px solid light-dark(#ddd, #444); border-radius: 4px; }
+    a { display: block; padding: 1rem; text-decoration: none; color: light-dark(#0055aa, #44aaff); font-weight: bold; }
+    a:hover { background: light-dark(#f5f5f5, #222); }
+    .meta { font-weight: normal; color: light-dark(#666, #aaa); font-size: 0.9em; float: right; }
+  </style>
+</head>
+<body>
+  <h1><%= project_name %> documentation</h1>
+  <ul>
+    <% versions.each do |version| %>
+      <li>
+        <a href='<%= version.slug %>/index.html'>
+          <%= version.name %>
+          <span class='meta'>
+            <% if version.latest? %>
+              Latest
+            <% elsif version.edge? %>
+              Edge
+            <% else %>
+              Historical
+            <% end %>
+          </span>
+        </a>
+      </li>
+    <% end %>
+  </ul>
+</body>
+</html>