1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
//! Present markdown slide decks as a TUI.
//!
//! deckhand turns a plain markdown file (or a JSON manifest) into a
//! full-screen terminal presentation with **live embedded terminals**, a
//! **two-dimensional slide grid**, an **overview with quick-jump codes**,
//! and **presenter notes** streamed to a second terminal. The same core
//! compiles to WebAssembly and powers an in-browser presenter at
//! <https://deckhand.sh>.
//!
//! Most people want the binary:
//!
//! ```text
//! deckhand talk.md # present
//! deckhand notes # presenter notes, in another terminal
//! deckhand compile deck.json # flatten a manifest to one file
//! ```
//!
//! # The deck format, in one slide
//!
//! ````text
//! ---
//! title: my talk
//! theme:
//! border_type: rounded
//! ---
//!
//! # hello ← column 1
//!
//! ---
//!
//! # demo ← column 2 (`---` = next column)
//!
//! ```terminal rows=10
//! python3 -q
//! ```
//!
//! ???
//! presenter notes live after the ??? line
//!
//! --
//!
//! ## the weeds ← deeper in column 2 (`--` = down)
//! ````
//!
//! Terminals are real PTYs when presenting natively; on the web they
//! replay captures baked in by `deckhand compile --snapshots`.
//!
//! # Architecture
//!
//! The crate is split so every presentation context shares one brain:
//!
//! - [`presenter::Presenter`] — the platform-independent core: 2-D
//! navigation, layout, theming, the overview, focus/selection, and all
//! drawing into a ratatui `Buffer`. It receives neutral
//! [`presenter::KeyPress`]/[`presenter::Mouse`] events.
//! - [`presenter::TerminalProvider`] — the extension point supplying the
//! live innards of terminal blocks. The native front end provides real
//! PTYs ([`present::PtyProvider`]); the wasm front end replays
//! snapshots; your embedding can provide ssh sessions, containers, or
//! recordings.
//! - Front ends: [`present`] (native TUI, crossterm) and `web`
//! (wasm-bindgen + xterm.js; compiled only for wasm32), each a thin
//! translation layer.
//!
//! # Module map
//!
//! | module | role |
//! |--------|------|
//! | [`deck`] | deck model + single-file markdown parsing |
//! | [`config`] | JSON manifest loading |
//! | [`markdown`] | markdown → styled ratatui text |
//! | [`highlight`] | lightweight code-block syntax highlighting |
//! | [`theme`] | theming: layout, borders, colors, precedence |
//! | [`qr`] | ```` ```qr ```` fences → scannable unicode QR codes |
//! | [`ascii_image`] | markdown images → colored ASCII art |
//! | [`banner`] | `h1_style: banner` → block-glyph headings |
//! | [`presenter`] | shared presentation core + provider trait |
//! | [`hints`] | overview quick-jump codes |
//! | [`compile`] | flatten any deck to single-file markdown |
//! | [`proto`] | presenter → notes-client wire format |
//! | native-only | [`present`], [`term`], [`server`], [`notes`], [`source`], [`snapshot`], [`cli`] |
//! | wasm-only | `web` |
//!
//! # Library quickstart
//!
//! Parse a deck and walk it with the shared presenter (a tiny provider
//! stands in for terminals):
//!
//! ```
//! use deckhand::deck;
//! use deckhand::presenter::{
//! Key, KeyPress, Presenter, TermState, TerminalProvider,
//! };
//! use ratatui::buffer::Buffer;
//! use ratatui::layout::Rect;
//!
//! struct NoTerms;
//! impl TerminalProvider for NoTerms {
//! fn prepare(&mut self, _: &deck::TermBlock, _: u16, _: u16) {}
//! fn state(&self, _: &deck::TermBlock) -> TermState {
//! TermState::Unavailable
//! }
//! fn draw(&mut self, _: &deck::TermBlock, _: Rect, _: &mut Buffer) {}
//! fn input(&mut self, _: usize, _: &[u8]) {}
//! fn scroll(&mut self, _: usize, _: isize) {}
//! fn restart(&mut self, _: &[usize]) {}
//! fn interactive(&self) -> bool {
//! false
//! }
//! }
//!
//! let deck = deck::parse("# hello\n---\n# world\n--\n## deeper\n", "demo")?;
//! let mut presenter = Presenter::new(deck, vec![], NoTerms)?;
//!
//! presenter.on_key(KeyPress::plain(Key::Char(' '))); // next slide
//! assert_eq!(presenter.position(), (1, 0));
//!
//! let area = Rect::new(0, 0, 80, 24);
//! let mut frame = Buffer::empty(area);
//! presenter.draw(area, &mut frame); // render anywhere a Buffer can go
//! # Ok::<(), anyhow::Error>(())
//! ```