cargo-slide

A code-driven presentation engine combining Typst typesetting with a native Rust runtime
Native 60 FPS Software Rendering · Standalone Binary, .slide Archive & Pure Rust WASM Delivery · Interactive SQL Charts · Extensible Animation Traits

English | 简体中文

---

Overview

cargo-slide is an open-source command-line tool and presentation runtime designed for developers and researchers who prefer authoring slide decks in code. Developed as part of the backend infrastructure for the Apich workspace, it brings together two complementary technologies:

• Typst for typesetting: Sub-second compilation, clean markup syntax, first-class mathematical equation typesetting, and modular macros compiled directly to high-precision vector graphics (SVG).
• Rust for presentation playback: A standalone runtime built on tiny-skia that renders slides at a steady 60 FPS without web browser or Electron dependencies, offering presenter tools, audio DSP mixing, interactive charts, and three distinct distribution formats.

---

Three Delivery Paradigms

cargo-slide supports three delivery formats to accommodate different presentation environments:

Paradigm	Target Use Case	Format & Size	Runtime Dependencies
Standalone Binary	Production talks on trusted machines	Single executable (~14–15 MB)	None (fully self-contained)
Universal .slide Archive	Sharing via email, chat, or flash drive	Compressed archive (~1 MB, LZMA2)	Played via slide-viewer
WebAssembly CSR	Online presentations & web embedding	Static HTML/WASM bundle (Zero inline JavaScript)	Any modern Web browser

---

Key Features

• Typst-Centric Authoring: Slide decks are written in pure Typst markup (slides.typ). Rust is only required when implementing custom transition algorithms or shader-like effects via traits.
• Minimal Project Scaffolding: cargo slide init initializes a clean 5-file project structure without unnecessary boilerplate.
• Typora-Style WYSIWYG Desktop Editor (slide-editor):
  • Live visual preview canvas rendering vector slides directly in the document flow.
  • In-Place Slide Editing: Click directly inside the visual presentation flow to edit Typst markup inline with debounced live recompilation.
  • Categorized Insertion Bar: 1-click addition of content blocks (Paragraph, Headings, Lists, Code, Math Formulas), media & data (Table, SQL Chart, Video, Audio, Links), and presentation cues (Speaker Notes, Comments, Callouts, Grids).
  • Outline Sidebar & Navigation: Thumbnail preview cards and outline hierarchy for rapid slide navigation.
  • Speaker Notes & Pacing Engine: Clear visual distinction between speaker notes (SPEAKER NOTE) and block comments ([COMMENT]), word count tracking (Latin words + CJK characters), target presentation pacing, and slide density analysis.
  • Presentation Health Audit: Diagnostic inspection checking missing asset paths, excessive text density, and compiler errors.
  • Multi-Window Support & Unsaved Changes Guard: Open multiple concurrent editor windows (Ctrl+Shift+N or "+ Window" toolbar button) with isolated document states; closing any window (Ctrl+W or OS close button) with unsaved edits triggers a confirmation alert asking whether to force close, save and close, or cancel.
• Universal Viewer (slide-viewer):
  • Resizable modern GUI launcher with true fullscreen support (F / F11).
  • Automatic detection of local presentations and embedded 22-slide reference showcase.
  • Native file picker (O / Ctrl+O) supporting .slide, .typ, and deck.json.
  • One-click cross-platform installer (I key or slide-viewer install / cargo slide install-viewer) with file associations on Linux (.desktop, MIME), macOS (.app bundle), and Windows (Registry).
• Presenter Tools:
  • 4-Brush Whiteboard: Solid Pen (Pen), Translucent Highlighter (Highlighter, multiply blend), Neon Glow (Neon, dual-layer halo), and Directional Arrow (Arrow, auto-oriented arrowhead).
  • 14-Color Palette & Color Tuning: Quick swatches (1–0), stroke width adjustments ([ / ]), undo (U / Ctrl+Z), and per-slide clear (C / X).
  • Laser Pointer: Responsive red pointer with animated decay trail (L key).
  • Audio Engine: Background music playback, track looping, smooth crossfades, master volume slider, and self-dismissing on-screen toast notifications.
  • Video Playback: Video cards delegate playback to system media players (mpv, ffplay, or default player) in a detached non-blocking window.
• Interactive SQL Charts & HUD Data Inspector:
  • Read tabular data directly from .csv, .json, or .db (SQLite) files.
  • Execute in-memory SQL queries (SELECT ... WHERE ...) or pipeline DSL transformations.
  • In-presentation HUD Data Inspector: click any chart or table to switch visualization types (Bar, Line, Area, Scatter), apply transform presets (TOP 5, SORT ▼, SORT ▲, CUM, % SHARE, MA3), filter by condition (>50), sort columns, and export filtered data to CSV.
• Slide Overflow Protection: Compares compiled vector pages against declared #slide(...) counts. If content exceeds vertical canvas bounds, compilation reports the specific slide title and source line number.
• Universal Rendering & Vector Typography:
  • Native GUI components (slide-editor, slide-viewer) and CLI logs rely on universal Unicode/ASCII indicators ([OK], [WARN], [ERR], [INFO], + Note, etc.) to prevent missing-glyph boxes across minimal Linux environments, Wayland/X11 desktops, macOS, and Windows without requiring color emoji fonts.
  • Typst resolves slide content (Latin, CJK, math formulas, and symbols) into vector Bézier <path> outlines, ensuring consistent cross-platform presentation display.
• 13 Built-in Transitions & In-Slide Fragments: fade, cut, slide-left, slide-right, slide-up, slide-down, zoom, wipe-left, wipe-right, iris, glitch, cube, and particles. Control sequential item reveals with #step(order, effect: "...").
• Presentation Encryption & Integrity Protection:
  • Hardware PIV Token Mode (YubiKey / Smartcard): Binds presentation decryption to an on-card private key (9d Key Management slot) and verifies SHA3-512 integrity digests with an on-card signature (9c Digital Signature slot). Requires physical token presence and PIN authentication.
  • Software Dual-Key Keystore Mode (Passphrase / BIP-39 Recovery Mnemonic): Provides hardware-independent encryption by packaging asymmetric P-256 recipient and signing keys within an encrypted keystore protected by AES-256-GCM. Session keys are derived via PBKDF2-HMAC-SHA512 (600,000 iterations) and HKDF-SHA256 from a passphrase (with complexity validation) or a configurable 12/24-word BIP-39 recovery mnemonic (--mnemonic-words 12|24).
  • In-Memory Zero-Disk Unpacking & Process Hardening: Presentations are decrypted and decompressed strictly in RAM (MemoryAssetStore) and never written to physical disk. Decrypted buffers are locked in RAM via mlock to reduce swap file leakage, with automatic zeroization (zeroize) on termination. Process memory dumping is restricted via RLIMIT_CORE = 0, Linux dumpability suppression (PR_SET_DUMPABLE = 0), and macOS debugger attach denial (PT_DENY_ATTACH).
  • Masked Input & Authentication Retry Loops: Secret inputs (PIN, passphrase, mnemonic) are masked in terminal CLI prompts and native GUI dialogs. Verification failures prompt the user to re-enter (up to 3 attempts with remaining feedback) instead of aborting immediately. Constant-time comparisons protect against padding side-channel timing leaks.
  • Editor GUI Encryption Integration (slide-editor): Open, edit, and save encrypted .slide presentations directly in the native editor GUI with graphical credential prompts. The Export modal supports 1-click encrypted packaging with passphrase, 12/24-word BIP-39 mnemonic, or YubiKey PIV.
  • Web Protected Deployment & Session Tokens: In WebAssembly mode (cargo slide build/serve/export --format wasm --encrypt), presentation decks are compiled into an encrypted envelope. Visitors authenticate in-browser with their passphrase or mnemonic, which decrypts the presentation in pure Rust WebAssembly and caches a scoped session token in browser sessionStorage with configurable TTL (--token-ttl <seconds>, default 24h), preventing plaintext decks from sitting unprotected on static hosting.

---

Getting Started

Prerequisites

1. Rust Toolchain: Rust 1.80+ (recommended: latest stable). Install via rustup.rs.
2. Typst CLI: typst executable available in your PATH. Install via package manager (cargo install --locked typst-cli, brew install typst, or Linux packages).
3. (Optional) External Media Player: mpv or ffplay for video playback cards.

Step 1: Install cargo-slide and slide-viewer

Install from local source:

cargo install --path crates/cargo-slide
cargo install --path crates/slide-viewer

Or install the viewer to system associations:

slide-viewer install

Step 2: Initialize a New Presentation

cargo slide init my-talk
cd my-talk

The generated project contains 5 clean files:

my-talk/
├── slides.typ          # Main presentation content in Typst markup
├── theme.typ           # Theme styling, color palette, and canvas aspect ratio
├── slide.typ           # Built-in component macros (#slide, #step, #chart, etc.)
├── assets/
│   └── data.csv        # Sample dataset for interactive charts
└── .gitignore          # Excludes build caches and compiled binaries

(Note: If you plan to implement custom Rust animation traits, add --rust: cargo slide init my-talk --rust.)

Step 3: Author and Present

Edit slides.typ with your favorite text editor, then run:

# Launch Typora-style WYSIWYG desktop editor with live preview
cargo slide edit

# Launch native presentation player with 60 FPS rendering
cargo slide run

# Or launch development mode with live hot-reloading
cargo slide dev

# Run comprehensive presentation health audit (density, assets, pacing)
cargo slide check

Step 4: Build, Pack, or Serve

# 1. Build a self-contained single binary (~14 MB)
cargo slide build

# 2. Pack into a compressed .slide archive (~1 MB, LZMA2)
cargo slide pack -o presentation.slide

# 3. Export to Leptos WebAssembly CSR static website
cargo slide export --format wasm -o dist-web/

# 4. Host presentation locally with built-in static web server
cargo slide serve --open

# 5. Export to multi-page PDF or individual SVGs
cargo slide export --format pdf -o presentation.pdf
cargo slide export --format svg -o exported-svgs/

# 6. Package with encryption & integrity protection
# Hardware PIV token mode (YubiKey / Smartcard):
cargo slide pack slides.typ --encrypt
# Software passphrase mode (complexity enforced: >=10 chars, 3+ classes):
cargo slide pack slides.typ --encrypt --auth passphrase
# Software BIP-39 recovery mnemonic mode (12 or 24 words):
cargo slide pack slides.typ --encrypt --auth mnemonic --mnemonic-words 12
# Standalone encrypted executable:
cargo slide build slides.typ --format binary --encrypt --auth passphrase
# Protected Web deployment with TTL session tokens (client-side Wasm decryption):
cargo slide serve --encrypt --auth passphrase --token-ttl 86400
cargo slide export --format wasm --encrypt --auth mnemonic -o dist-web/

# 7. Cross-Platform Compilation (Natively built into cargo-slide, no scripts needed)
# Cross-compile for all 4 desktop targets (Linux x86_64, Linux ARM64, Windows x86_64, Windows ARM64):
cargo slide cross --target all

# Build specifically for Windows x86_64 (automatically uses lightweight Zig toolchain):
cargo slide cross --target windows-x86_64

# Build specifically for Linux ARM64:
cargo slide cross --target linux-aarch64

# Cross-compile standalone presentation runners (artifacts placed into ./dist/):
cargo slide cross slides.typ --target all

# Aliases and compatibility:
cargo slide dist --target all
cargo slide build slides.typ --all-targets

---

Presenter Controls & Keyboard Shortcuts

Key / Action	Function
Space / Enter / Right / Down / Left Click	Advance to next step (or next slide)
Backspace / Left / Up / Right Click	Step back to previous step (or previous slide)
PageDown / PageUp	Advance / reverse whole slide directly
Home / End	Jump to first / last slide
Digit(s) + Enter	Jump directly to specific slide number
F11 / F / Dock FULL	Toggle native fullscreen and windowed modes
L / Dock LSR	Toggle laser pointer with decay trail
P / Dock PEN	Toggle whiteboard annotation pen
T	Cycle whiteboard brush mode (Pen, Highlighter, Neon, Arrow)
[ / ]	Decrease / increase brush stroke width (2px, 4px, 8px, 14px)
Keys 1 .. 0	Quick palette colors (14 vibrant swatches)
U / Ctrl+Z	Undo last whiteboard ink stroke
C / X / Dock CLR	Clear annotations on current slide
Mouse Wheel / + / -	Adjust master audio volume (0% to 100%)
M / Dock VOL	Mute / unmute audio
H / ? / Dock HELP	Toggle shortcut help overlay
O / Ctrl+O	Open presentation file picker (.slide, .typ, .json)
I	Install viewer to system application launcher
Click on Chart / Table	Open interactive HUD Data Inspector modal
Click on Video Card	Launch external video player in detached window
Click on Hyperlink	Open external URL or preview local source text
Esc / Q	Close active modal / exit presentation

---

Interactive Charts & SQL Queries

1. Simple Chart from CSV

#chart(
  data: "assets/data.csv",
  type: "bar",
  title: "Runtime Memory Benchmarks",
  width: 100%,
  height: 6cm
)

2. In-Memory SQL Query

Query CSV, JSON, or SQLite datasets using standard SQL syntax:

#chart(
  data: "assets/telemetry.db",
  sql: "SELECT service, p99_latency FROM traces WHERE p99_latency > 50 ORDER BY p99_latency DESC",
  type: "bar",
  title: "High-Latency Microservices"
)

3. Pipeline DSL

For quick transformations without SQL:

#chart(
  data: "assets/metrics.json",
  dsl: "source -> filter(fps >= 30) -> select(Framework, FPS)",
  type: "line",
  title: "Frame Rate Comparison"
)

---

Technical Comparison

Feature	cargo-slide	Marp / Slidev	LaTeX Beamer
Primary Engine	Native Rust (tiny-skia) / Pure WASM	Web / Electron / Node.js	TeX / PDF reader
Primary Output	Single binary / .slide / WebAssembly	HTML bundle / PDF / App	Static PDF
Typography	Typst native vector paths	Browser CSS / Web fonts	LaTeX native fonts
Math Quality	Typst LaTeX-grade equations	KaTeX / MathJax	Native TeX math
Frame Rate	Steady 60 FPS	Variable (DOM/browser dependent)	Static (no transitions)
Presenter Tools	4-brush ink, laser trail, audio mixer, SQL inspector	Plugin dependent	PDF reader dependent
Dependencies	None for output binary or .slide	Browser or Node runtime	PDF viewer

---

Workspace Structure

cargo-slide/
├── Cargo.toml                      # Workspace configuration
├── crates/
│   ├── slide-core/                 # Typst compiler bridge, SVG parser, charts/SQL, package (LZMA2)
│   ├── slide-player/               # Native player: tiny-skia blitter, windowing, audio mixer, presenter tools, HUD
│   ├── slide-editor/               # Typora-style WYSIWYG live-preview desktop editor for Typst decks and documents
│   ├── slide-viewer/               # Standalone universal presentation player binary with GUI launcher for .slide files
│   ├── slide-web/                  # Pure Rust Leptos 0.7 CSR Web presentation player (strictly zero inline JS)
│   ├── slide-theme/                # Built-in themes, default templates, and Typst macros (#slide, #step, #chart)
│   └── cargo-slide/                # CLI tool implementing init, new, run, dev, edit, check, build, pack, serve, export
└── examples/
    ├── geek-presentation/          # 22-slide reference showcase demonstrating all engine capabilities
    ├── dist-web/                   # Exported Leptos CSR static web bundle
    └── slides.slide                # Pre-built reference .slide package (LZMA2)

---

Maintainers & Contact

cargo-slide is maintained as part of the backend infrastructure for the Apich workspace.

• Maintainer: Xinyu Yang (Xinyu.Yang@apich.org)
• Organization: Apich Organization (info@apich.org)
• Repository: https://github.com/Apich-Organization/cargo-slide

---

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).