Files
Bundle OKF 0.1 · 8 conceitos · acg-box/rsnap
Open source Repository Open in the app JSON README (API)
About
# Files
- [Documentation Policy](policy.md) - Repository documentation authority, placement, and maintenance policy for Documentation Policy.
- [Rsnap OpenWiki Quickstart](quickstart.md) - Canonical entry point for Rsnap repository knowledge, routing readers by authority class to specifications, runbooks, references, decisions, research provenance, and drift evidence.
# Directories
- [decisions](decisions/)
- [evidence](evidence/)
- [reference](reference/)
- [research](research/)
- [runbook](runbook/)
- [spec](spec/)
Details
- Kind
- OKF bundles
- Topic
- Files & documents
- Publisher
- acg-box
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 6
- Open pull requests
- 6
- Last push
- 2026-09-09T00:05:19Z
- Repository state
- ativo
- Language
- Swift
- License
- GPL-3.0
- Added
- 2026-09-08 09:01:12
- Updated
- 2026-09-08 09:01:12
- Origin id
acg-box/rsnap:openwiki/index.md
README
<div align="center">
# Rsnap
macOS-first screenshot app built with a native host and Rust core.
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://github.com/acg-box/rsnap/actions/workflows/language.yml)
[](https://github.com/acg-box/rsnap/actions/workflows/release.yml)
[](https://github.com/acg-box/rsnap/tags)
[](https://github.com/acg-box/rsnap)
[](https://github.com/acg-box/rsnap)
https://github.com/user-attachments/assets/ff2fe84f-f551-40e8-919c-66ae8a61f8e7
<img src="assets/readme/rsnap-settings-output.jpg" alt="Rsnap Settings Output view" width="860">
</div>
## Feature Highlights
- Menubar-only app (no Dock icon) on macOS.
- Global hotkey: `Alt+X` (macOS: Option-X).
- Quick screenshot hotkey: `Alt+Shift+X` (macOS: Option-Shift-X) for transient UI
such as context menus and submenu stacks.
- Transparent capture-session overlay that blocks desktop interaction.
- HUD near the cursor showing global `x,y` and `rgb(r,g,b)`.
- Left click + drag freezes a selected region; a single left click freezes the hovered window or falls back to the active monitor fullscreen.
- On macOS, entering Frozen mode restores the pre-capture target after selection completes instead of leaving Rsnap focused; exiting capture restores the original frontmost app.
- In Frozen mode, a dragged-region capture can be dragged from inside the bright selection area to reposition it without resizing.
- In Frozen mode, `Space` copies the current frozen PNG to the clipboard and exits.
- In Frozen mode, Cmd+S (macOS) / Ctrl+S saves the current PNG to disk and exits.
- On macOS, Frozen mode can recognize text from the current capture and copy the result to the clipboard from the toolbar.
- Frozen toolbar tools include pointer, pen, arrow, text, mosaic, spotlight, undo, redo,
auto-center, OCR, Scroll Capture for dragged-region freezes, copy, and save.
- `Esc` cancels capture.
- Glass HUD with Classic Glass fallback and Liquid Glass in release builds on supported macOS.
- Tab-triggered loupe sample and frozen-mode toolbar for quick action access.
## Status
Prototype / in active development.
## App identity
- Product display name: **Rsnap**.
- macOS app bundle name: **Rsnap.app**.
- Lower-case `rsnap` remains only for stable technical identifiers such as the repository slug,
Cargo package names, crate paths, environment variables, bundle identifiers, telemetry schemas,
and C ABI symbols. See `openwiki/spec/app-identity.md`.
## Reset posture
- Shipping behavior on macOS now enters through the native host lane:
- `native/macos-host/` is the SwiftPM AppKit host shell and the default local Run path.
- `apps/rsnap/` is now a thin launcher/bootstrap crate that stages or opens the native host
bundle and records startup logging.
- `packages/rsnap-overlay/` is now a narrowed Rust transition crate for macOS live-sampling
adapters that have not yet moved into the native host.
- The active reset target is no longer a pure-Rust UI stack. New boundary crates now live in:
- `packages/rsnap-capture-core/` for platform-neutral session semantics and host/core protocol
models, plus Rust-owned export, frozen-overlay edit/export, capture-frame rendering, wallpaper
thumbnail, minimap, scroll stitching, selection-transform, and image-analysis algorithms
- `packages/rsnap-host-ffi/` for the thin C ABI that the native macOS host calls
through `packages/rsnap-host-ffi/include/rsnap_host_ffi.h`
- Current version support remains **macOS only**. Windows and Linux stay out of scope for this
version beyond protocol and abstraction design.
## Capture platform support
- Live sampling path: **macOS 12.3+** via ScreenCaptureKit. Live loupe/window
sampling uses `SCStream`.
- Live mode is stream-first and does not capture full display on cursor movement.
- Frozen capture imagery on macOS uses the native capture stack;
`openwiki/spec/capture-session.md` is the current contract source of truth.
- Menubar and Dock are not included in live window-outline targeting.
- Windows support is planned (minimum Windows 10), but not implemented yet.
- As of v0.2.5, the native-host release exposes Scroll Capture for dragged-region Frozen captures
on macOS. It uses ordered ScreenCaptureKit region frames, overlay-local wheel forwarding, and
Rust-owned fail-closed stitching. Release readiness for broader target apps is governed by
`openwiki/runbook/scroll-capture-recovery-plan.md`.
## Usage
### Installation
#### Download macOS Build
Download the latest macOS zip:
<https://github.com/acg-box/rsnap/releases/latest/download/rsnap-aarch64-apple-darwin.zip>
Unzip it and move `Rsnap.app` to `/Applications`.
Release builds include Sparkle-based updates. Use `Settings...` -> `About` -> `Check` for the
standard macOS update flow; the About Auto Update mode defaults to `Install` for signed release builds
with the Sparkle appcast configured.
#### Build from Source
```sh
git clone https://github.com/acg-box/rsnap
cd rsnap
cargo build --workspace
cargo run -p rsnap
```
#### macOS Gatekeeper approval for signed but unnotarized builds
Current preview release builds are signed, but are not notarized by Apple. If macOS blocks
`Rsnap.app` after you unzip a downloaded build, first try to open it. Then open `System Settings`
-> `Privacy & Security`, find the message about Rsnap, and select `Open Anyway`. Authenticate and
confirm `Open` when macOS asks. Do this only for a bundle that you built or downloaded from this
repository's GitHub Releases page.
The release uses an Apple Development certificate whose authority label ends with `RD3D4LH465`.
Signed code reports the code-signing `TeamIdentifier` `T54QFA7W2S` and uses Hardened Runtime.
If `Open Anyway` is not available, move the trusted app to `/Applications`, then use this terminal
fallback:
```sh
xattr -rd com.apple.quarantine /Applications/Rsnap.app
```
If Terminal reports a permission error, grant Terminal Full Disk Access in `System Settings` ->
`Privacy & Security` -> `Full Disk Access`, then rerun the command. If you keep the app in a
different location, replace `/Applications/Rsnap.app` with that bundle path.
After Gatekeeper allows the app to open, continue with Screen Recording permission below.
### macOS permissions
Rsnap requires **Screen Recording** permission to capture other apps/windows.
- ScreenCaptureKit live sampling on macOS requires macOS 12.3+ and Screen Recording permission.
- Normal region/window/monitor capture does not require Accessibility or Input Monitoring.
- The retained scroll-capture path uses Screen Recording-backed screenshots plus overlay-local
wheel forwarding; it does not require Accessibility, Input Monitoring, Accessibility target
acquisition, app scripting, or browser/DOM access. The v0.2.5 native-host release exposes Scroll
Capture from dragged-region Frozen captures only.
- Quick Screenshot uses a temporary macOS event tap to keep transient target UI focused while Rsnap
captures the selected region. If macOS refuses the event tap, Quick Screenshot fails closed and
records native-host telemetry; Screen Recording remains the required permission for captured
pixels.
- macOS may describe Screen Recording as `Screen & System Audio Recording` or as direct screen/audio access when Rsnap bypasses the system picker.
- Settings -> Permissions shows Screen Recording as the required capture permission.
- Normal native capture depends on Screen Recording; if access is missing, Rsnap opens the Screen Recording page in System Settings and shows a floating drag-to-grant guide.
- You can reopen the Permissions section from `Settings…` in the tray or menubar menu at any time.
- Base capture path: `System Settings` -> `Privacy & Security` -> `Screen Recording`.
- Enable `Rsnap.app`, then retry capture. If macOS still keeps capture blocked after changing a permission, relaunch the app.
### Screenshot shortcuts
- New Screenshot: `Alt+X` (macOS: Option-X). Use this for the normal live capture overlay.
- Quick Screenshot: `Alt+Shift+X` (macOS: Option-Shift-X). Use this for transient UI that
would disappear when another app activates, such as context menus and submenu stacks.
- In live capture, `Tab` toggles the loupe sample.
- In Frozen mode, `Space` copies the current frozen PNG to the clipboard and exits.
- In Frozen mode, Cmd+S (macOS) / Ctrl+S saves the current PNG to disk and exits.
- `Esc` cancels capture.
### HUD settings behavior
- The native `Settings…` window currently owns:
- New Screenshot shortcut
- Quick Screenshot shortcut
- HUD glass enable/disable
- HUD glass style (`Classic Glass` / `Liquid Glass`)
- Liquid Glass style (`Regular` / `Clear`) when supported by macOS and the current build
- shared HUD tint / color, plus Classic Glass opacity / blur
- HUD `Tab` hint visibility
- loupe sample size (`small` / `medium` / `large`)
- output directory
- filename prefix
- output naming (`timestamp` / `sequence`)
- frozen toolbar placement (`bottom` / `top`)
### Output (save-to-disk)
- In Frozen mode, use Cmd+S (macOS) / Ctrl+S to save a PNG to disk and exit.
- On macOS, use the frozen toolbar `Recognize Text` action to copy recognized text from the current frozen capture and exit.
- Output is configured in the native `Settings…` window:
- `Save Location` (default: Desktop)
- `Filename Prefix` (default: `Rsnap`, sanitized to `[A-Za-z0-9_-]`)
- `Naming` (`Timestamp` or `Sequence`)
- `Frame Preset` (`Off`, wallpaper, or gradient backgrounds)
- `Apply To` for drag-region and window captures; scroll capture follows drag-region, and
fullscreen captures are excluded
### Current scroll-capture status
As of v0.2.5, Scroll Capture is exposed for dragged-region Frozen captures on macOS. It remains
absent for window-click and fullscreen freezes. The retained Rust scroll-capture session,
deterministic tests, and benchmark surfaces remain the validation authority for stitching behavior.
The implementation commits downward growth only after ordered-frame pairwise registration plus
overlap proof, fails closed on weak registration or rewind, and forwards wheel input to target apps
through one universal path. Follow `openwiki/runbook/scroll-capture-recovery-plan.md` for
release-scope validation beyond the deterministic and native smoke surfaces.
## Development
```sh
npm ci --ignore-scripts
npm run check
cargo make checks
cargo make test-host-reset
cargo make test-macos-native-host-stage
./scripts/build_and_run.sh --verify
```
Native-host local loop:
- `scripts/build_and_run.sh` builds `rsnap-host-ffi`, builds `native/macos-host/`, stages
`target/rsnap-native-host/Rsnap.app`, and launches it as a real `.app` bundle.
- On macOS, `cargo run -p rsnap` now delegates to that staged native host bundle instead of
starting a legacy Rust-owned capture runtime.
- `.codex/environments/environment.toml` points the Codex app Run button at that script.
- `cargo make test-host-reset` now includes the native-host bridge probe in addition to the Rust
core and header checks.
- `scripts/build_and_run.sh stage` stages the native host bundle without launching it; this is the
macOS packaging entrypoint used by release automation.
- The live native-host path is now driven by `primary interaction -> scene.liveSelectionPreview ->
requestFreezeSnapshot`, so the host no longer keeps its own pending freeze-selection shadow
state.
- The native host keeps OS-facing ownership. It captures or discovers platform resources, passes
source pixels and resource paths through `RsnapHostBridge`, displays returned images, and performs
clipboard, save-panel, OCR, and update side effects. Rust owns the final-byte and image-planning
algorithms exposed through `rsnap-host-ffi`.
Smoke/perf entrypoints:
```sh
scripts/smoke/native-hud-follow-macos.sh
scripts/smoke/native-visual-contract-macos.sh
scripts/smoke/native-scroll-capture-macos.sh
scripts/smoke/self-check-macos.sh
scripts/smoke/macos.sh
scripts/smoke/native-prepared-export-macos.sh
scripts/smoke/sparkle-update-local.sh
scripts/perf/local.sh
scripts/perf/self-check-macos.sh
scripts/perf/macos.sh
```
`scripts/smoke/macos.sh` runs the native visual contract and HUD-follow smoke. `scripts/perf/macos.sh`
runs the deterministic Rust perf sweep plus the native-host HUD-follow and visual-contract smokes.
For durable command selection, verification order, baseline workflow, and asset ownership:
- `openwiki/runbook/performance-validation.md`
- `openwiki/reference/smoke-perf-validation-surface.md`
- `openwiki/runbook/release.md`
The capture-session contract lives at `openwiki/spec/capture-session.md`.
## Workspace Layout
The tracked workspace currently keeps:
- `native/macos-host/` as the new AppKit-first macOS host shell and local run target
- `apps/rsnap/` as the thin launcher/bootstrap crate for the native host bundle
- `packages/rsnap-overlay/` as the narrowed Rust transition crate for retained helper surfaces
- `packages/rsnap-capture-core/` as the durable product-semantics and image-algorithm layer
- `packages/rsnap-host-ffi/` as the thin C ABI bridge used by the native macOS host
Generated or local-only directories such as `target/`, `.worktrees/`, and `.workspaces/` are not
part of the tracked repository structure. For the authoritative layout and ownership map, read
`openwiki/reference/workspace-layout.md`.
## Documentation
- Product and development overview: this `README.md`
- Canonical OpenWiki router: `openwiki/quickstart.md`
- Open Knowledge Format v0.1 bundle index: `openwiki/index.md`
- Normative specs: `openwiki/spec/index.md`
- Procedural runbooks: `openwiki/runbook/index.md`
- Current implementation references: `openwiki/reference/index.md`
- Durable design rationale: `openwiki/decisions/index.md`
- Research provenance and drift evidence: `openwiki/research/index.md` and
`openwiki/evidence/index.md`
- OpenWiki policy and placement rules: `openwiki/policy.md`
- Repository-specific OpenWiki brief: `openwiki/INSTRUCTIONS.md`
## Support Me
If you find this project helpful and would like to support its development, you can buy me a coffee!
Your support is greatly appreciated and motivates me to keep improving this project.
- **Fiat**
- [Ko-fi](https://ko-fi.com/hack_ink)
- [Afdian](https://afdian.com/a/hack_ink)
- **Crypto**
- **Bitcoin**
- `bc1pedlrf67ss52md29qqkzr2avma6ghyrt4jx9ecp9457qsl75x247sqcp43c`
- **Ethereum**
- `0x3e25247CfF03F99a7D83b28F207112234feE73a6`
- **Polkadot**
- `156HGo9setPcU2qhFMVWLkcmtCEGySLwNqa3DaEiYSWtte4Y`
Thank you for your support!
## Appreciation
We would like to extend our heartfelt gratitude to the following projects and contributors:
- The Rust community for their continuous support and development of the Rust ecosystem.
## Additional Acknowledgements
- TODO
<div align="right">
### License
<sup>Licensed under [GPL-3.0](LICENSE).</sup>
</div>