bionicreader

README

Bionic Reader

Read text with emphasis on the beginnings of words.

Bionic Reader works with text streams, Markdown documents, and interactive shell sessions. It runs locally and keeps your words intact. Try different emphasis settings to find what feels comfortable; no reading-speed improvement is promised.

Bionic Reader emphasizes word beginnings.

Installation

Install with your package manager using the commands below. Homebrew installs prebuilt binaries; Cargo installs from crates.io. See installation details for channel availability, direct-download alternatives, and platform requirements.

Homebrew

brew tap arturoaviles/tap
brew trust arturoaviles/tap
brew install bionic-reader

Homebrew selects the matching prebuilt binary. See the Homebrew guide for updates, removal, and platform requirements.

Linux

# Debian / Ubuntu
curl -fL "https://github.com/arturoaviles/bionic-reader/releases/latest/download/bionic-reader-linux-$(dpkg --print-architecture).deb" -o bionic-reader.deb
sudo apt install ./bionic-reader.deb

# Fedora
curl -fL "https://github.com/arturoaviles/bionic-reader/releases/latest/download/bionic-reader-linux-$(rpm --eval '%{_arch}').rpm" -o bionic-reader.rpm
sudo dnf install --nogpgcheck ./bionic-reader.rpm

# Arch Linux
curl -fL "https://github.com/arturoaviles/bionic-reader/releases/latest/download/bionic-reader-linux-$(uname -m).pkg.tar.zst" -o bionic-reader.pkg.tar.zst
sudo pacman -U ./bionic-reader.pkg.tar.zst

Python and Node.js

# pip (in a virtual environment) or uv
pip install bionic-reader
uv tool install bionic-reader

# npm, Yarn, or pnpm
npm install --global @arturoaviles/bionic-reader
yarn add @arturoaviles/bionic-reader
pnpm add --global @arturoaviles/bionic-reader

Cargo

cargo install bionic-reader --locked

Yarn installs into the current project; run it with yarn bionic-reader. Package managers select the CPU architecture automatically. Linux release filenames use the native architecture query shown above. You can also download native binaries from GitHub Releases.

Application libraries

Install packages from PyPI, npm, or crates.io, or the Go module proxy. The library APIs below share the CLI's local transformation engine. See the library guide for complete options, errors, and platform requirements.

Earlier CLI-only releases do not include the callable APIs shown below. The registry installation commands select the latest available release.

Python

The library API requires Python 3.11+. Install into your application's virtual environment:

python -m pip install bionic-reader

See the Python examples for formats, profiles, Markdown, custom rendering, configuration, and file conversion.

from bionic_reader import Reader

reader = Reader()
print(reader.render("Hello world", format="html", profile="balanced"))
print(reader.segments("Hello world"))

JavaScript

The library API requires Node 22+. Install into your application:

npm install @arturoaviles/bionic-reader

See the JavaScript examples for Node.js, browser, TypeScript, and React usage.

Initialize the bundled WebAssembly engine once:

import { createReader } from '@arturoaviles/bionic-reader';

const reader = await createReader();
console.log(reader.render('Hello world', { format: 'html', profile: 'balanced' }));
console.log(reader.segments('Hello world'));

CommonJS uses const { createReader } = require('@arturoaviles/bionic-reader') and awaits initialization in an async function. Browser bundlers select the browser loader. React applications can use BionicReaderProvider and BionicText from @arturoaviles/bionic-reader/react; see the React example for initialization and hydration.

Rust

Requires Rust 1.85.1+. Add the crate to your application:

cargo add bionic-reader

See the Rust examples for document transformation, text segments, configuration, streaming, and custom segmentation.

use bionic_reader::reading::{Options, Reader};
use bionic_reader::settings::OutputFormat;

fn main() -> Result<(), bionic_reader::Error> {
    let reader = Reader::new();
    let options = Options::default();
    println!("{}", reader.render("Hello world", OutputFormat::Html, &options)?);
    println!("{:?}", reader.segments("Hello world", &options)?);
    Ok(())
}

Formatted output requires an explicit ansi, plain, markdown, or html format. Text segments contain literal text and an emphasized flag for custom presentation. Calls use explicit settings and deterministic defaults; they do not implicitly read CLI configuration or terminal state.

Go

Requires Go 1.25+. Install into your application:

go get github.com/arturoaviles/bionic-reader

See the Go examples for formats, profiles, Markdown, concurrent use, configuration, and file conversion.

package main

import (
    "context"
    "fmt"
    bionicreader "github.com/arturoaviles/bionic-reader"
)

func main() {
    ctx := context.Background()
    reader, err := bionicreader.NewReader(ctx)
    if err != nil { panic(err) }
    defer reader.Close()
    html, err := reader.Render(ctx, "Hello world", bionicreader.HTML, bionicreader.Options{})
    if err != nil { panic(err) }
    fmt.Println(html)
}

The Rust engine is embedded as WebAssembly and runs locally through wazero. Consumers need no CGO, Rust installation, separate CLI, or runtime downloads. Reuse and close the reader; calls are safe concurrently and accept contexts for cancellation. Go support starts with the 0.3.0 release.

The reader

bionic-reader read article.txt
cat article.txt | bionic-reader read

Scroll with the arrow keys or j/k, search with /, and press q to leave. Use ? for all shortcuts. Adjust emphasis while you read with +/-, or try settings interactively with bionic-reader preview.

The CLI

bionic-reader -t 'Make long passages easier to follow.'
cat article.txt | bionic-reader
bionic-reader --input-format markdown --style always < article.md

# Change the reading style.
bionic-reader --profile subtle -t 'A lighter touch.'
bionic-reader --fraction 0.6 --every 2 -t 'Choose your own emphasis.'

# Export HTML or Markdown.
bionic-reader --format html < article.txt > article.html
bionic-reader --format markdown < article.txt > emphasized.md

See bionic-reader --help and the usage guide for formats, profiles, safe terminal controls, and reader shortcuts.

Shell integration

Start a reading session with bionic-reader session. Known editors, pagers, and full-screen applications use passthrough. Inside a session, use bionic-reader off, on, or toggle to control emphasis, and exit to leave.

For automatic sessions, add one initializer to your shell configuration:

# ~/.bashrc
eval "$(bionic-reader init bash)"
# ~/.zshrc
eval "$(bionic-reader init zsh)"

Bash, Zsh, fish, shell completions, and seven framework adapters are covered in the shell guide.

Configuration

Save preferences in ~/.config/bionic-reader/config.toml, or beneath an absolute XDG_CONFIG_HOME:

profile = "balanced"
fraction = 0.5
emphasis = "bold"

Command-line settings override the file. See the configuration guide for all options and precedence.

Contributing

See CONTRIBUTING.md for development checks, BUILD.md for source builds, and RELEASE.md for release and package publication.

License

MIT.

Documentation

Overview

Code generated by scripts/build-go-engine.sh; DO NOT EDIT.

Package bionicreader transforms text and Markdown with bionic reading emphasis. It embeds the shared Rust engine and runs locally without CGO, Rust, a CLI, or a network service. Reuse a Reader and close it when finished.

Index

• Constants
• Variables
• func Pointer[T any](value T) *T
• type Error
  • func (e *Error) Error() string
• type Format
• type LengthRule
• type Options
• type Reader
  • func NewReader(ctx context.Context) (*Reader, error)
  • func (r *Reader) Close() error
  • func (r *Reader) ParseConfig(ctx context.Context, contents string) (Options, error)
  • func (r *Reader) Render(ctx context.Context, text string, format Format, options Options) (string, error)
  • func (r *Reader) Segments(ctx context.Context, text string, options Options) ([]TextSegment, error)
• type TextSegment

Examples

• Reader.Render

Constants

const Version = "0.3.0"

Version is the Cargo-owned package and embedded-engine version.

Variables

var ErrClosed = &Error{Code: "closed_reader", Message: "bionic reader is closed or uninitialized"}

ErrClosed is returned when using a closed or uninitialized Reader.

Functions

func Pointer

func Pointer[T any](value T) *T

Pointer returns a pointer to a setting, including a zero or false value.

Types

type Error

type Error struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

Error is a transformation or engine failure with a stable machine-readable code. Codes are invalid_input, initialization_failed, engine_failed, and closed_reader. Context cancellation and deadline errors are returned directly.

func (*Error) Error

func (e *Error) Error() string

type Format

type Format string

Format is the explicitly selected document output representation.

const (
	ANSI     Format = "ansi"
	Plain    Format = "plain"
	Markdown Format = "markdown"
	HTML     Format = "html"
)

type LengthRule

type LengthRule struct {
	MaxLength uint32  `json:"max_length"`
	Fraction  float64 `json:"fraction"`
}

LengthRule sets an emphasis fraction through an inclusive word-length limit.

type Options

type Options struct {
	Enabled       *bool        `json:"enabled,omitempty"`
	Profile       string       `json:"profile,omitempty"`
	Fraction      *float64     `json:"fraction,omitempty"`
	Every         *uint32      `json:"every,omitempty"`
	MinWordLength *uint32      `json:"min_word_length,omitempty"`
	LengthRules   []LengthRule `json:"length_rules,omitempty"`
	Emphasis      string       `json:"emphasis,omitempty"`
	InputFormat   string       `json:"input_format,omitempty"`
	Controls      string       `json:"controls,omitempty"`
	SkipCode      *bool        `json:"skip_code,omitempty"`
}

Options overrides balanced defaults. Nil pointers leave defaults unchanged; Pointer(false) and Pointer(0.0) explicitly disable emphasis or prefix selection. Word counts must be positive and rules must have increasing thresholds.

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader owns a reusable compiled engine. Calls are safe concurrently and use isolated instances without filesystem or network access. It must not be copied. Close waits for active calls; cancel their contexts to interrupt them.

func NewReader

func NewReader(ctx context.Context) (*Reader, error)

NewReader loads and validates the embedded engine. No files are discovered or downloaded. The context bounds initialization, not the lifetime of the reader.

func (*Reader) Close

func (r *Reader) Close() error

Close releases engine resources and is idempotent. It waits for active calls.

func (*Reader) ParseConfig

func (r *Reader) ParseConfig(ctx context.Context, contents string) (Options, error)

ParseConfig parses explicitly supplied TOML contents, performing no file I/O. A style of never disables emphasis; auto is deterministically enabled. The caller still chooses Render's format explicitly. Session-only fields are ignored.

func (*Reader) Render

func (r *Reader) Render(ctx context.Context, text string, format Format, options Options) (string, error)

Render transforms a whole Unicode string in the explicitly selected format. Markdown input is limited to 8 MiB of UTF-8. Other inputs are bounded by available memory and the WebAssembly linear-memory limit. No configuration files, terminal state, NO_COLOR, or TERM are inspected.

Example

package main

import (
	"context"
	"fmt"

	bionicreader "github.com/arturoaviles/bionic-reader"
)

func main() {
	ctx := context.Background()
	reader, err := bionicreader.NewReader(ctx)
	if err != nil {
		panic(err)
	}
	defer reader.Close()
	html, err := reader.Render(ctx, "Hello world", bionicreader.HTML, bionicreader.Options{})
	if err != nil {
		panic(err)
	}
	fmt.Println(html)
}

Output:
<strong>Hel</strong>lo <strong>wor</strong>ld

func (*Reader) Segments

func (r *Reader) Segments(ctx context.Context, text string, options Options) ([]TextSegment, error)

Segments returns ordered literal text segments without terminal controls or byte offsets. Markdown input retains source syntax and protects code by default.

type TextSegment

type TextSegment struct {
	Text       string `json:"text"`
	Emphasized bool   `json:"emphasized"`
}

TextSegment is literal visible text with its bionic reading emphasis state.