Ensub is a local-first English immersion and spaced-repetition application suite. It turns words encountered in documents or pasted text into vocabulary cards with an offline definition, pronunciation, source context, and deterministic SM-2 review schedule.
Ensub Core v0.1.0 is delivered and stable; v0.1.0-rc1 is the verified
repository baseline from which the v0.2.0 interactive Player was built. The
PWA/Web Player is now feature complete and frozen as a reference prototype,
and native Android is the active client track.
The same Rust domain and language engines power a command-line interface, a
terminal reader, a native COSMIC desktop application and panel applet, and the
installable Ensub Player for synchronized podcast transcripts, offline lookup,
capture, and review. Native data stays in SQLite. The separate Ensub Core
sandbox is an offline browser reference harness backed by localStorage. The
optional Ensub Context companion uses an anonymous Supabase session and an
OpenAI-compatible model without exposing provider credentials to the browser.
The repository includes these implemented surfaces:
| Surface | Entry point | Current capability |
|---|---|---|
| CLI | esb |
Add and parse vocabulary, review due cards, inspect due counts and statistics |
| TUI | esb tui [FILE] |
Read Markdown or plain text, inspect and capture words, run quick reviews |
| COSMIC GUI | ensub-gui |
Dashboard, vocabulary library, document reader, text capture, and review sessions |
| COSMIC applet | ensub-applet |
Due-count badge, one-card review popover, and clipboard capture HUD |
| Ensub Player | crates/web_player |
Frozen v0.2.0 reference PWA with synchronized, locally cached podcast transcripts; maintenance and regression only |
| Ensub Core sandbox | crates/web_sandbox |
Offline real-lexicon parsing, capture, SRS review, snapshots, and multi-tab coordination |
| Ensub Context | crates/web_site |
Optional online contextual analysis and private cloud-backed capture history |
| Android Spike 1 | android |
Active Kotlin/Compose client proving UniFFI-backed transcript synchronization with in-activity Media3 playback |
The native desktop packaging targets Linux with COSMIC Desktop.
Ensub requires Rust 1.93 or newer. From a source checkout, install the CLI and
its TUI reader with:
cargo install --path crates/cli --lockedCapture a word and its source sentence:
esb add immersion \
--context "Immersion turns ordinary reading into deliberate practice." \
--source "reading-notes"Extract and capture every dictionary-backed candidate from standard input:
printf '%s\n' "Reading authentic material builds durable vocabulary." \
| esb parse --yes --source "terminal-example"The first captured card is immediately due:
esb due
esb review
esb statsOpen the terminal reader with a Markdown or plain-text document:
esb tui article.mdEnsub embeds its native lexicon, creates the SQLite schema automatically, and uses the platform-standard local data and cache directories. No dictionary download or database setup is required.
Build the COSMIC application and applet:
cargo build --release -p ensub-cli -p ensub-gui -p ensub-appletFor a user-local installation of esb, desktop binaries, entries, applet entry,
metadata, and icons:
PREFIX="$HOME/.local" sh packaging/install.shEnsure $HOME/.local/bin is on PATH. The applet entry can then be added from
COSMIC panel settings. Distribution-specific COSMIC and graphics development
packages may be required to compile libcosmic.
Create the two deterministic local v0.2.0 archives and SHA256SUMS with:
sh packaging/build-release.shThis command writes only under target/release-artifacts; it does not publish
or upload artifacts.
See Getting Started for development launch commands and the contextual web assistant setup.
| Guide | Contents |
|---|---|
| Getting Started | Prerequisites, installation, first capture, and surface launch commands |
| User Guide | CLI options, TUI keys, GUI navigation, applet, and web workflows |
| Architecture | Crate boundaries, data flow, storage adapters, and concurrency model |
| Development | Workspace layout, validation commands, tests, web builds, and release builds |
| Platform Status | Frozen PWA/WASM scope, regression policy, and active native Android track |
| Android Spike 1 Design | UniFFI facade, DTO contract, Android ownership, build flow, and deferred scope |
| Android Spike 1 | Android prerequisites, native generation, Gradle build, tests, and APK locations |
| Data and Privacy | Native and browser storage, path overrides, concurrency, backup, and reset behavior |
| v0.2.0 Release Audit | PRD acceptance criteria, release-gate evidence, and tag preconditions |
| Offline Lexicon | Corpus provenance, generated artifacts, extraction, and regeneration |
| Ensub Player | PWA build, local cache, direct browser fetching, and preview |
| Ensub Core Sandbox | Offline WASM build, verification, and local preview |
| Ensub Context | Supabase setup, LLM secrets, build, preview, and privacy |
API documentation can be generated locally with:
cargo doc --workspace --no-deps --openPortable policy is separated from platform I/O:
core_engine domain records, SM-2 scheduling, storage contracts
language_engine tokenization, morphology, documents, lexicon contracts
ensub-theme portable semantic RGB themes and CSS export
ensub-sqlite native SQLite storage and bundled offline lexicon
ensub-cli command dispatch and terminal prompts
ensub-tui terminal reader and quick-review state machine
ensub-gui native COSMIC desktop application and capture HUD
ensub-applet native COSMIC panel applet
ensub-wasm browser bindings and local snapshot storage
web_player installable podcast and synchronized-transcript workspace
web_sandbox offline Ensub Core reference harness
web_site optional online Ensub Context companion
core_engine has no UI, database, platform, async-runtime, or WASM dependency.
Native and browser adapters depend inward on its StorageAdapter contract.
Visual frontends adapt the shared ensub-theme semantic colors to their own
toolkits; Catppuccin Mocha Mauve is the default preset.
Run the repository's primary checks from the workspace root:
cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspaceWASM and static-site development has additional target and browser checks; they are listed in Development.
The v0.2.0 release-hardening checks include production panic and placeholder enforcement plus generated Player artifact scanning:
sh scripts/verify.sh hardeningDefinitions and parts of speech are derived from Open English WordNet 2025. Pronunciations are derived from CMUdict 0.7b and converted from ARPAbet to broad General American IPA. The generated lexicon contains 32,463 lexemes, 49,207 surface forms, and 78,463 ranked senses.
Pinned source versions, checksums, transformation notes, and third-party
license notices are under
crates/sqlite_storage/assets.
Ensub source code is available under either the MIT License or the Apache License 2.0. Bundled lexical data retains its source licenses and attribution requirements as documented in the lexicon provenance files.