diff --git a/.audit/omacy-impl.tsv b/.audit/omacy-impl.tsv
new file mode 100644
index 0000000..5b76523
--- /dev/null
+++ b/.audit/omacy-impl.tsv
@@ -0,0 +1,15 @@
+ts phase decision why evidence result
+2026-08-27T14:54:03Z frame lock done-predicate: engine FFI+parity tests green on Linux; Swift host+appex sources match architecture.md; canary idle/System Settings remains a Mac gate Linux VM cannot compile Swift or run ScreenSaverEngine; prove the engine here and ship complete macOS sources docs/architecture.md:298 docs/ffi.md docs/parity.md framed
+2026-08-27T15:09:47Z harness vendor ttfx at v0.3.2 pin and copy Omarchy wordmark scaffold before features; pin is the recorded SHA not floating master vendor/ttfx/PIN assets/branding/screensaver.txt copied
+2026-08-27T16:22:38Z impl snapshot fill_grid at frame() emit unstable rumble restores coords after ANSI; live pack desynced Metal from oracle vendor/ttfx/src/engine/terminal.rs store_snapshot; tests/parity.rs 37x2x2x180 green pass
+2026-08-27T16:22:38Z impl ascii goldens + Fairfax HD + host/appex sources parity.md conversion matrix and architecture host+appex assets/fixtures/conversion apps/Omacy docs/macos-gates.md engine-proven; Mac idle unverified
+2026-08-27T16:50:00Z impl close remaining architecture gaps atomic store, lifecycle, occupancy/atlas, dead recover, copy, panic+budget tests cargo test -p omacy-engine; cargo test --manifest-path vendor/ttfx/Cargo.toml; cargo test -p omacy-engine --release --test budget engine pass; Mac idle unverified
+2026-08-27T16:46:50Z impl close remaining architecture gaps atomic store, lifecycle, occupancy/atlas, dead recover, copy, panic+budget tests docs/architecture.md testing table + host/appex sources in-progress
+2026-08-27T17:01:46Z impl canary thumbnails, SVG href reject, session contract tests architecture thumbnail + FFI wait/pending/re-entrant + no file SVG cargo test -p omacy-engine pass
+2026-08-27T17:06:12Z impl appex per-display loadView + duplicate pluginkit warning Settings preview 30Hz and multi-display need the real frame; PlugInKit sticky if two locations apps/Omacy/OmacyScreensaver/OmacySaverViewController.swift PluginManager.swift in-progress
+2026-08-27T17:15:04Z ci add macos-15 xcodebuild of host+appex Linux cannot compile Swift; a GitHub Mac runner can prove the Aerial-path targets link .github/workflows/macos.yml in-progress
+2026-08-27T17:37:02Z ci macos-26 xcodebuild + renderer NSObject + cargo PATH PaperSaver 0.2.0 needs Swift 6.2; macos-15 was 6.1; Xcode scripts drop ~/.cargo/bin; displayLink needs NSObject .github/workflows/macos.yml apps/Omacy/scripts/build-engine.sh OmacyRenderer.swift in-progress
+2026-08-27T17:49:00Z ci one rust build phase (appex) macos-26 failed: both targets wrote libomacy_engine.a; host already depends on appex apps/Omacy/Omacy.xcodeproj/project.pbxproj in-progress
+2026-08-27T18:11:00Z ci fix displayLink non-optional + omacy_status log macos-26 Swift: guard let on CADisplayLink; Int() on C enum apps/Omacy/Shared/OmacyRenderer.swift in-progress
+2026-08-27T18:47:00Z ci host+appex BUILD SUCCEEDED on Xcode 26.6 deinit no longer calls MainActor stop; PreviewView is a typealias; one -lomacy_engine link local xcodebuild Release arm64; Omacy.app/Contents/PlugIns/OmacyScreensaver.appex pass
+2026-08-27T20:10:30Z impl stop Metal drawable invalidation on layout CAMetalLayer was view.layer; layout rewrote drawableSize + rebuilt atlas every pass; busy ring presented cleared frames preview video 45% black frames; Peter confirmed host preview continuous pass
diff --git a/.github/workflows/engine.yml b/.github/workflows/engine.yml
new file mode 100644
index 0000000..f813fc7
--- /dev/null
+++ b/.github/workflows/engine.yml
@@ -0,0 +1,21 @@
+name: engine
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ submodules: recursive
+ - uses: dtolnay/rust-toolchain@master
+ with:
+ toolchain: 1.88.0
+ - name: Engine tests
+ run: cargo test -p omacy-engine
+ - name: Vendored ttfx tests
+ run: cargo test --manifest-path vendor/ttfx/Cargo.toml
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
new file mode 100644
index 0000000..107ed37
--- /dev/null
+++ b/.github/workflows/macos.yml
@@ -0,0 +1,46 @@
+name: macos
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+
+jobs:
+ host:
+ # PaperSaver 0.2.0 is swift-tools-version 6.2. macos-15 ships Xcode 16 / Swift 6.1.
+ # Deployment target stays 15.0; this runner is only the compile host (Peter develops on Tahoe).
+ runs-on: macos-26
+ steps:
+ - uses: actions/checkout@v4
+ - uses: dtolnay/rust-toolchain@master
+ with:
+ toolchain: 1.88.0
+ targets: aarch64-apple-darwin
+ - name: Show compilers
+ run: |
+ xcodebuild -version
+ swift --version
+ rustc --version
+ cargo --version
+ - name: Build host app and screensaver appex
+ working-directory: apps/Omacy
+ run: |
+ export PATH="${CARGO_HOME:-$HOME/.cargo}/bin:$PATH"
+ xcodebuild \
+ -project Omacy.xcodeproj \
+ -scheme Omacy \
+ -configuration Release \
+ -destination 'generic/platform=macOS' \
+ -skipMacroValidation \
+ -skipPackagePluginValidation \
+ ARCHS=arm64 \
+ ONLY_ACTIVE_ARCH=YES \
+ EXCLUDED_ARCHS=x86_64 \
+ CODE_SIGN_IDENTITY="-" \
+ CODE_SIGNING_ALLOWED=NO \
+ CODE_SIGNING_REQUIRED=NO \
+ AD_HOC_CODE_SIGNING_ALLOWED=YES \
+ CODE_SIGN_STYLE=Manual \
+ DEVELOPMENT_TEAM="" \
+ ENABLE_HARDENED_RUNTIME=NO \
+ build
diff --git a/.gitignore b/.gitignore
index cf8de4a..6e37a84 100644
--- a/.gitignore
+++ b/.gitignore
@@ -57,9 +57,13 @@ Carthage/Build/
# https://docs.fastlane.tools/best-practices/source-control/#source-control
fastlane/report.xml
+fastlane/README.md
fastlane/Preview.html
fastlane/screenshots/**/*.png
fastlane/test_output
+fastlane/.env
+*.p8
+build/
# Rust
target/
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..226922e
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,858 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "adler2"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys",
+]
+
+[[package]]
+name = "arrayref"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb"
+
+[[package]]
+name = "arrayvec"
+version = "0.7.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+
+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "clap"
+version = "4.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_complete"
+version = "4.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3be2ad0423bdbbb0e25bc89add796f3559706d4a95e1bc98e4d9662a957b6a19"
+dependencies = [
+ "clap",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "color_quant"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "core_maths"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77745e017f5edba1a9c1d854f6f3a52dac8a12dd5af5d2f54aecf61e43d80d30"
+dependencies = [
+ "libm",
+]
+
+[[package]]
+name = "crc32fast"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8498c871161e1742aaa9d52551b2d6ebdd4c3d45a3be423e3728f33b955be550"
+dependencies = [
+ "cfg-if",
+]
+
+[[package]]
+name = "data-url"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be1e0bca6c3637f992fc1cc7cbc52a78c1ef6db076dbf1059c4323d6a2048376"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "euclid"
+version = "0.22.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1a05365e3b1c6d1650318537c7460c6923f1abdd272ad6842baa2b509957a06"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
+[[package]]
+name = "flate2"
+version = "1.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
+dependencies = [
+ "crc32fast",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "float-cmp"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"
+
+[[package]]
+name = "fontconfig-parser"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbc773e24e02d4ddd8395fd30dc147524273a83e54e0f312d986ea30de5f5646"
+dependencies = [
+ "roxmltree",
+]
+
+[[package]]
+name = "fontdb"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "457e789b3d1202543297a350643cf459f836cade38934e7a4cf6a39e7cde2905"
+dependencies = [
+ "fontconfig-parser",
+ "log",
+ "memmap2",
+ "slotmap",
+ "tinyvec",
+ "ttf-parser",
+]
+
+[[package]]
+name = "gif"
+version = "0.13.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4ae047235e33e2829703574b54fdec96bfbad892062d97fed2f76022287de61b"
+dependencies = [
+ "color_quant",
+ "weezl",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "moxcms",
+ "num-traits",
+ "png 0.18.1",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
+[[package]]
+name = "imagesize"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edcd27d72f2f071c64249075f42e205ff93c9a4c5f6c6da53e79ed9f9832c285"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "kurbo"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c62026ae44756f8a599ba21140f350303d4f08dcdcc71b5ad9c9bb8128c13c62"
+dependencies = [
+ "arrayvec",
+ "euclid",
+ "smallvec",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "log"
+version = "0.4.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "memmap2"
+version = "0.9.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1219ed1b7f229ee7104d281dd01d6802fe28bb6e95d292942c4daacdeb798c0"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
+dependencies = [
+ "adler2",
+ "simd-adler32",
+]
+
+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "omacy-engine"
+version = "0.1.0"
+dependencies = [
+ "image",
+ "libc",
+ "resvg",
+ "serde",
+ "serde_json",
+ "tiny-skia",
+ "ttfx",
+]
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "pico-args"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5be167a7af36ee22fe3115051bc51f6e6c7054c9348e28deb4f49bd6f705a315"
+
+[[package]]
+name = "png"
+version = "0.17.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"
+dependencies = [
+ "bitflags 1.3.2",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags 2.13.1",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pxfm"
+version = "0.1.30"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d55d956fa96f5ec02be2e13af0e20391a5aa83d6a074e3ad368959d0fab299ea"
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "resvg"
+version = "0.45.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a8928798c0a55e03c9ca6c4c6846f76377427d2c1e1f7e6de3c06ae57942df43"
+dependencies = [
+ "gif",
+ "image-webp",
+ "log",
+ "pico-args",
+ "rgb",
+ "svgtypes",
+ "tiny-skia",
+ "usvg",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "rgb"
+version = "0.8.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47b34b781b31e5d73e9fbc8689c70551fd1ade9a19e3e28cfec8580a79290cc4"
+dependencies = [
+ "bytemuck",
+]
+
+[[package]]
+name = "roxmltree"
+version = "0.20.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c20b6793b5c2fa6553b250154b78d6d0db37e72700ae35fad9387a46f487c97"
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags 2.13.1",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
+[[package]]
+name = "rustybuzz"
+version = "0.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd3c7c96f8a08ee34eff8857b11b49b07d71d1c3f4e88f8a88d4c9e9f90b1702"
+dependencies = [
+ "bitflags 2.13.1",
+ "bytemuck",
+ "core_maths",
+ "log",
+ "smallvec",
+ "ttf-parser",
+ "unicode-bidi-mirroring",
+ "unicode-ccc",
+ "unicode-properties",
+ "unicode-script",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.151"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "simd-adler32"
+version = "0.3.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
+
+[[package]]
+name = "simplecss"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a9c6883ca9c3c7c90e888de77b7a5c849c779d25d74a1269b0218b14e8b136c"
+dependencies = [
+ "log",
+]
+
+[[package]]
+name = "siphasher"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ee5873ec9cce0195efcb7a4e9507a04cd49aec9c83d0389df45b1ef7ba2e649"
+
+[[package]]
+name = "slotmap"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bdd58c3c93c3d278ca835519292445cb4b0d4dc59ccfdf7ceadaab3f8aeb4038"
+dependencies = [
+ "version_check",
+]
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "strict-num"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6637bab7722d379c8b41ba849228d680cc12d0a45ba1fa2b48f2a30577a06731"
+dependencies = [
+ "float-cmp",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "svgtypes"
+version = "0.15.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68c7541fff44b35860c1a7a47a7cadf3e4a304c457b58f9870d9706ece028afc"
+dependencies = [
+ "kurbo",
+ "siphasher",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6275cddf4610d1775e6d1fe9469b2e77d0f39fd98fb7450901b821e0c53649f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "terminal_size"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "230a1b821ccbd75b185820a1f1ff7b14d21da1e442e22c0863ea5f08771a8874"
+dependencies = [
+ "rustix",
+ "windows-sys",
+]
+
+[[package]]
+name = "tiny-skia"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83d13394d44dae3207b52a326c0c85a8bf87f1541f23b0d143811088497b09ab"
+dependencies = [
+ "arrayref",
+ "arrayvec",
+ "bytemuck",
+ "cfg-if",
+ "log",
+ "png 0.17.16",
+ "tiny-skia-path",
+]
+
+[[package]]
+name = "tiny-skia-path"
+version = "0.11.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c9e7fc0c2e86a30b117d0462aa261b72b7a99b7ebd7deb3a14ceda95c5bdc93"
+dependencies = [
+ "arrayref",
+ "bytemuck",
+ "strict-num",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
+[[package]]
+name = "ttf-parser"
+version = "0.25.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31"
+dependencies = [
+ "core_maths",
+]
+
+[[package]]
+name = "ttfx"
+version = "0.3.2"
+dependencies = [
+ "clap",
+ "clap_complete",
+ "terminal_size",
+]
+
+[[package]]
+name = "unicode-bidi"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"
+
+[[package]]
+name = "unicode-bidi-mirroring"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5dfa6e8c60bb66d49db113e0125ee8711b7647b5579dc7f5f19c42357ed039fe"
+
+[[package]]
+name = "unicode-ccc"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce61d488bcdc9bc8b5d1772c404828b17fc481c0a582b5581e95fb233aef503e"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "unicode-properties"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7df058c713841ad818f1dc5d3fd88063241cc61f49f5fbea4b951e8cf5a8d71d"
+
+[[package]]
+name = "unicode-script"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "383ad40bb927465ec0ce7720e033cb4ca06912855fc35db31b5755d0de75b1ee"
+
+[[package]]
+name = "unicode-vo"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b1d386ff53b415b7fe27b50bb44679e2cc4660272694b7b6f3326d8480823a94"
+
+[[package]]
+name = "usvg"
+version = "0.45.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "80be9b06fbae3b8b303400ab20778c80bbaf338f563afe567cf3c9eea17b47ef"
+dependencies = [
+ "base64",
+ "data-url",
+ "flate2",
+ "fontdb",
+ "imagesize",
+ "kurbo",
+ "log",
+ "pico-args",
+ "roxmltree",
+ "rustybuzz",
+ "simplecss",
+ "siphasher",
+ "strict-num",
+ "svgtypes",
+ "tiny-skia-path",
+ "unicode-bidi",
+ "unicode-script",
+ "unicode-vo",
+ "xmlwriter",
+]
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "weezl"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "xmlwriter"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec7a2a501ed189703dba8b08142f057e887dfc4b2cc4db2d343ac6376ba3e0b9"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
+
+[[package]]
+name = "zune-core"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f423a2c17029964870cfaabb1f13dfab7d092a62a29a89264f4d36990ca414a"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.4.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29ce2c8a9384ad323cf564b67da86e21d3cfdff87908bc1223ed5c99bc792713"
+dependencies = [
+ "zune-core",
+]
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..6fdfb24
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,16 @@
+[workspace]
+members = ["crates/omacy-engine"]
+resolver = "2"
+
+[workspace.package]
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/dedene/omacy-screensaver"
+
+[profile.dev]
+panic = "unwind"
+
+[profile.release]
+panic = "unwind"
+lto = true
+codegen-units = 1
diff --git a/Gemfile b/Gemfile
new file mode 100644
index 0000000..7a118b4
--- /dev/null
+++ b/Gemfile
@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem "fastlane"
diff --git a/Gemfile.lock b/Gemfile.lock
new file mode 100644
index 0000000..ed2be90
--- /dev/null
+++ b/Gemfile.lock
@@ -0,0 +1,364 @@
+GEM
+ remote: https://rubygems.org/
+ specs:
+ CFPropertyList (3.0.8)
+ abbrev (0.1.2)
+ addressable (2.9.0)
+ public_suffix (>= 2.0.2, < 8.0)
+ artifactory (3.0.17)
+ atomos (0.1.3)
+ aws-eventstream (1.4.0)
+ aws-partitions (1.1282.0)
+ aws-sdk-core (3.254.1)
+ aws-eventstream (~> 1, >= 1.3.0)
+ aws-partitions (~> 1, >= 1.992.0)
+ aws-sigv4 (~> 1.9)
+ base64
+ bigdecimal
+ jmespath (~> 1, >= 1.6.1)
+ logger
+ aws-sdk-kms (1.130.0)
+ aws-sdk-core (~> 3, >= 3.254.0)
+ aws-sigv4 (~> 1.5)
+ aws-sdk-s3 (1.229.0)
+ aws-sdk-core (~> 3, >= 3.254.1)
+ aws-sdk-kms (~> 1)
+ aws-sigv4 (~> 1.5)
+ aws-sigv4 (1.12.1)
+ aws-eventstream (~> 1, >= 1.0.2)
+ babosa (1.0.4)
+ base64 (0.3.0)
+ benchmark (0.5.0)
+ bigdecimal (4.1.2)
+ claide (1.1.0)
+ colored (1.2)
+ colored2 (3.1.2)
+ commander (4.6.0)
+ highline (~> 2.0.0)
+ csv (3.3.6)
+ declarative (0.0.20)
+ digest-crc (0.7.0)
+ rake (>= 12.0.0, < 14.0.0)
+ domain_name (0.6.20240107)
+ dotenv (2.8.1)
+ emoji_regex (3.2.3)
+ erb (6.0.7)
+ excon (1.7.0)
+ logger
+ faraday (2.14.3)
+ faraday-net_http (>= 2.0, < 3.5)
+ json
+ logger
+ faraday-cookie_jar (0.0.8)
+ faraday (>= 0.8.0)
+ http-cookie (>= 1.0.0)
+ faraday-follow_redirects (0.5.0)
+ faraday (>= 1, < 3)
+ faraday-multipart (1.2.0)
+ multipart-post (~> 2.0)
+ faraday-net_http (3.4.4)
+ net-http (~> 0.5)
+ faraday-retry (2.4.0)
+ faraday (~> 2.0)
+ fastimage (2.4.1)
+ fastlane (2.238.0)
+ CFPropertyList (>= 2.3, < 5.0.0)
+ abbrev (~> 0.1)
+ addressable (>= 2.9.0, < 3.0.0)
+ artifactory (~> 3.0)
+ aws-sdk-s3 (~> 1.197)
+ babosa (>= 1.0.3, < 2.0.0)
+ base64 (~> 0.2)
+ benchmark (>= 0.1.0)
+ bundler (>= 2.4.0, < 5.0.0)
+ colored (~> 1.2)
+ commander (~> 4.6)
+ csv (~> 3.3)
+ dotenv (>= 2.1.1, < 3.0.0)
+ emoji_regex (>= 0.1, < 4.0)
+ excon (>= 0.71.0, < 2.0.0)
+ faraday (~> 2.7)
+ faraday-cookie_jar (~> 0.0.8)
+ faraday-follow_redirects (~> 0.3)
+ faraday-multipart (~> 1.0)
+ faraday-retry (~> 2.0)
+ fastimage (>= 2.1.0, < 3.0.0)
+ fastlane-sirp (>= 1.1.0)
+ gh_inspector (>= 1.1.2, < 2.0.0)
+ google-apis-androidpublisher_v3 (~> 0.3)
+ google-apis-playcustomapp_v1 (~> 0.1)
+ google-cloud-env (>= 1.6.0, < 2.3.0)
+ google-cloud-storage (~> 1.31)
+ highline (~> 2.0)
+ http-cookie (~> 1.0.5)
+ irb (>= 1.8)
+ json (< 3.0.0)
+ jwt (>= 2.10.3, < 4)
+ logger (>= 1.6, < 2.0)
+ mini_magick (>= 4.9.4, < 5.0.0)
+ multi_json (~> 1.12)
+ multipart-post (>= 2.0.0, < 3.0.0)
+ mutex_m (~> 0.3)
+ naturally (~> 2.2)
+ nkf (~> 0.2)
+ optparse (>= 0.1.1, < 1.0.0)
+ ostruct (>= 0.1.0)
+ plist (>= 3.1.0, < 4.0.0)
+ rubyzip (>= 2.0.0, < 3.0.0)
+ security (= 0.1.5)
+ simctl (~> 1.6.3)
+ terminal-notifier (>= 2.0.0, < 3.0.0)
+ terminal-table (~> 4)
+ tty-screen (>= 0.6.3, < 1.0.0)
+ tty-spinner (>= 0.8.0, < 1.0.0)
+ word_wrap (~> 1.0.0)
+ xcodeproj (>= 1.13.0, < 2.0.0)
+ xcpretty (~> 0.4.1)
+ xcpretty-travis-formatter (>= 0.0.3, < 2.0.0)
+ fastlane-sirp (1.1.0)
+ gh_inspector (1.1.3)
+ google-apis-androidpublisher_v3 (0.107.0)
+ google-apis-core (>= 0.15.0, < 2.a)
+ google-apis-core (1.2.5)
+ addressable (~> 2.9)
+ faraday (~> 2.13)
+ faraday-follow_redirects (~> 0.3)
+ googleauth (~> 1.14)
+ mini_mime (~> 1.1)
+ multi_json (~> 1.11)
+ representable (~> 3.0)
+ retriable (>= 3.1, < 5.0)
+ google-apis-iamcredentials_v1 (0.28.0)
+ google-apis-core (>= 0.15.0, < 2.a)
+ google-apis-playcustomapp_v1 (0.18.0)
+ google-apis-core (>= 0.15.0, < 2.a)
+ google-apis-storage_v1 (0.66.0)
+ google-apis-core (>= 0.15.0, < 2.a)
+ google-cloud-core (1.9.0)
+ google-cloud-env (>= 1.0, < 3.a)
+ google-cloud-errors (~> 1.0)
+ google-cloud-env (2.2.2)
+ base64 (~> 0.2)
+ faraday (>= 1.0, < 3.a)
+ google-cloud-errors (1.7.0)
+ google-cloud-storage (1.62.0)
+ addressable (~> 2.8)
+ digest-crc (~> 0.4)
+ google-apis-core (>= 0.18, < 2)
+ google-apis-iamcredentials_v1 (~> 0.18)
+ google-apis-storage_v1 (>= 0.42)
+ google-cloud-core (~> 1.6)
+ googleauth (~> 1.9)
+ mini_mime (~> 1.0)
+ google-logging-utils (0.2.0)
+ googleauth (1.17.4)
+ faraday (>= 1.0, < 3.a)
+ google-cloud-env (~> 2.2)
+ google-logging-utils (~> 0.1)
+ jwt (>= 1.4, < 4.0)
+ os (>= 0.9, < 2.0)
+ pstore (~> 0.1)
+ signet (>= 0.16, < 2.a)
+ highline (2.0.3)
+ http-cookie (1.0.8)
+ domain_name (~> 0.5)
+ io-console (0.9.2)
+ irb (1.18.0)
+ pp (>= 0.6.0)
+ prism (>= 1.3.0)
+ rdoc (>= 4.0.0)
+ reline (>= 0.4.2)
+ jmespath (1.6.2)
+ json (2.21.2)
+ jwt (3.2.0)
+ base64
+ logger (1.7.0)
+ mini_magick (4.13.2)
+ mini_mime (1.1.5)
+ multi_json (1.21.1)
+ multipart-post (2.4.1)
+ mutex_m (0.3.0)
+ nanaimo (0.4.0)
+ naturally (2.3.0)
+ net-http (0.9.1)
+ uri (>= 0.11.1)
+ nkf (0.3.0)
+ optparse (0.8.1)
+ os (1.1.4)
+ ostruct (0.6.3)
+ plist (3.7.2)
+ pp (0.6.4)
+ prettyprint
+ prettyprint (0.2.0)
+ prism (1.9.0)
+ pstore (0.2.1)
+ public_suffix (7.0.5)
+ rake (13.4.2)
+ rbs (4.2.0)
+ logger
+ prism (>= 1.6.0)
+ tsort
+ rdoc (8.0.0)
+ erb
+ prism (>= 1.6.0)
+ rbs (>= 4.0.0)
+ tsort
+ reline (0.7.0)
+ io-console (~> 0.5)
+ representable (3.2.0)
+ declarative (< 0.1.0)
+ trailblazer-option (>= 0.1.1, < 0.2.0)
+ uber (< 0.2.0)
+ retriable (4.2.0)
+ rexml (3.4.4)
+ rouge (3.28.0)
+ rubyzip (2.4.1)
+ security (0.1.5)
+ signet (0.22.0)
+ addressable (~> 2.8)
+ faraday (>= 0.17.5, < 3.a)
+ jwt (>= 1.5, < 4.0)
+ simctl (1.6.10)
+ CFPropertyList
+ naturally
+ terminal-notifier (2.0.0)
+ terminal-table (4.0.0)
+ unicode-display_width (>= 1.1.1, < 4)
+ trailblazer-option (0.1.2)
+ tsort (0.2.0)
+ tty-cursor (0.7.1)
+ tty-screen (0.8.2)
+ tty-spinner (0.9.3)
+ tty-cursor (~> 0.7)
+ uber (0.1.0)
+ unicode-display_width (3.2.0)
+ unicode-emoji (~> 4.1)
+ unicode-emoji (4.2.0)
+ uri (1.1.1)
+ word_wrap (1.0.0)
+ xcodeproj (1.28.1)
+ CFPropertyList (>= 2.3.3, < 4.0)
+ atomos (~> 0.1.3)
+ base64
+ claide (>= 1.0.2, < 2.0)
+ colored2 (~> 3.1)
+ nanaimo (~> 0.4.0)
+ nkf
+ rexml (>= 3.3.6, < 4.0)
+ xcpretty (0.4.1)
+ rouge (~> 3.28.0)
+ xcpretty-travis-formatter (1.0.1)
+ xcpretty (~> 0.2, >= 0.0.7)
+
+PLATFORMS
+ arm64-darwin-25
+ ruby
+
+DEPENDENCIES
+ fastlane
+
+CHECKSUMS
+ CFPropertyList (3.0.8) sha256=2c99d0d980536d3d7ab252f7bd59ac8be50fbdd1ff487c98c949bb66bb114261
+ abbrev (0.1.2) sha256=ad1b4eaaaed4cb722d5684d63949e4bde1d34f2a95e20db93aecfe7cbac74242
+ addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+ artifactory (3.0.17) sha256=3023d5c964c31674090d655a516f38ca75665c15084140c08b7f2841131af263
+ atomos (0.1.3) sha256=7d43b22f2454a36bace5532d30785b06de3711399cb1c6bf932573eda536789f
+ aws-eventstream (1.4.0) sha256=116bf85c436200d1060811e6f5d2d40c88f65448f2125bc77ffce5121e6e183b
+ aws-partitions (1.1282.0) sha256=d6c7c4ad2e4f8cd4ca56445bfbb3958fec0deecd959c1e2bcd3a83c9aa308c18
+ aws-sdk-core (3.254.1) sha256=518089e32134c3478cd4ec63d07fb966546a45e9e4cbf5f80d2cf16d5699d29b
+ aws-sdk-kms (1.130.0) sha256=a2e83662ca31b77a2a19c9aa2f40a98165a67270c18c718fe1c70d0cbd7cd749
+ aws-sdk-s3 (1.229.0) sha256=7dd11a111875b3505d2ec0a0a383a6aab6c1badb3d4e94e7fbb958a24451f596
+ aws-sigv4 (1.12.1) sha256=6973ff95cb0fd0dc58ba26e90e9510a2219525d07620c8babeb70ef831826c00
+ babosa (1.0.4) sha256=18dea450f595462ed7cb80595abd76b2e535db8c91b350f6c4b3d73986c5bc99
+ base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+ benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
+ bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+ claide (1.1.0) sha256=6d3c5c089dde904d96aa30e73306d0d4bd444b1accb9b3125ce14a3c0183f82e
+ colored (1.2) sha256=9d82b47ac589ce7f6cab64b1f194a2009e9fd00c326a5357321f44afab2c1d2c
+ colored2 (3.1.2) sha256=b13c2bd7eeae2cf7356a62501d398e72fde78780bd26aec6a979578293c28b4a
+ commander (4.6.0) sha256=7d1ddc3fccae60cc906b4131b916107e2ef0108858f485fdda30610c0f2913d9
+ csv (3.3.6) sha256=aba61e7e507a66f03d45cb1f3c4b6359861c3504038b422962875dce099e4456
+ declarative (0.0.20) sha256=8021dd6cb17ab2b61233c56903d3f5a259c5cf43c80ff332d447d395b17d9ff9
+ digest-crc (0.7.0) sha256=64adc23a26a241044cbe6732477ca1b3c281d79e2240bcff275a37a5a0d78c07
+ domain_name (0.6.20240107) sha256=5f693b2215708476517479bf2b3802e49068ad82167bcd2286f899536a17d933
+ dotenv (2.8.1) sha256=c5944793349ae03c432e1780a2ca929d60b88c7d14d52d630db0508c3a8a17d8
+ emoji_regex (3.2.3) sha256=ecd8be856b7691406c6bf3bb3a5e55d6ed683ffab98b4aa531bb90e1ddcc564b
+ erb (6.0.7) sha256=c5ca6dc25b0ef974a44dc8f59fe847577122483b1968a38dec305c60bf91ee92
+ excon (1.7.0) sha256=b8deec2bf978123b7e4b13a103ffec61557c6feaba34706dbc1ce4a94dec33e0
+ faraday (2.14.3) sha256=1882247e6766615c8220b4392bf1d27f6ebb63d8e28267587cef1fb0bf37f278
+ faraday-cookie_jar (0.0.8) sha256=0140605823f8cc63c7028fccee486aaed8e54835c360cffc1f7c8c07c4299dbb
+ faraday-follow_redirects (0.5.0) sha256=5cde93c894b30943a5d2b93c2fe9284216a6b756f7af406a1e55f211d97d10ad
+ faraday-multipart (1.2.0) sha256=7d89a949693714176f612323ca13746a2ded204031a6ba528adee788694ef757
+ faraday-net_http (3.4.4) sha256=0e78af151747ed1b00f33e25973b4bc220d7f16c00c39676817c8b12331eb588
+ faraday-retry (2.4.0) sha256=7b79c48fb7e56526faf247b12d94a680071ff40c9fda7cf1ec1549439ad11ebe
+ fastimage (2.4.1) sha256=c64bebd46b6fd8943ab70c1e6e85ff728f970f2e48f92ecd249b6bc3a540ad20
+ fastlane (2.238.0) sha256=78e9252df2224c7e427012638e41051edfa29b133a40fda883fd2f1c13a77b98
+ fastlane-sirp (1.1.0) sha256=10bc94f9682efd8e1badfb31452a76dd8981f1f3a33717c765fde6d75b54d847
+ gh_inspector (1.1.3) sha256=04cca7171b87164e053aa43147971d3b7f500fcb58177698886b48a9fc4a1939
+ google-apis-androidpublisher_v3 (0.107.0) sha256=b8207eecc89e6a9f7ea11aa88a07bccdcae5ca90121330079db4ef4696a2f3ff
+ google-apis-core (1.2.5) sha256=e21562b5627a0fc6a0c3165e429c3afed0f6a628eaa514e83f7204dda1adff69
+ google-apis-iamcredentials_v1 (0.28.0) sha256=0a92ffe6cc39c569554af2a77a25dfc61519ed8bbb64ab04cffdd352dc5ef106
+ google-apis-playcustomapp_v1 (0.18.0) sha256=44b277b9dee4a59ac5e9d98be1485edc5e382d2f9d73c79ae8908a455786a254
+ google-apis-storage_v1 (0.66.0) sha256=fdf6d65d3fc77e7046b3494333a818ece9e2afd763bb161e1a7a9e70cf198351
+ google-cloud-core (1.9.0) sha256=ab55409f51488e8deefb6edcc1ce4771dfb5da2fe7b3bc075709a030c2b682a4
+ google-cloud-env (2.2.2) sha256=94bed40e05a67e9468ce1cb38389fba9a90aa8fc62fc9e173204c1dca59e21e7
+ google-cloud-errors (1.7.0) sha256=6e682f42d89aae08689f36f28495de629d756da076bafff0003bac7f8042ebb3
+ google-cloud-storage (1.62.0) sha256=e2c3c08bf8fd40d50be92304084942203314d4fc0ee52028e99f9359c3ad1330
+ google-logging-utils (0.2.0) sha256=675462b4ea5affa825a3442694ca2d75d0069455a1d0956127207498fca3df7b
+ googleauth (1.17.4) sha256=acc2cac2a6011048f149c922cbc6c9675719e165aa5000c7fa3876c480fe9ae3
+ highline (2.0.3) sha256=2ddd5c127d4692721486f91737307236fe005352d12a4202e26c48614f719479
+ http-cookie (1.0.8) sha256=b14fe0445cf24bf9ae098633e9b8d42e4c07c3c1f700672b09fbfe32ffd41aa6
+ io-console (0.9.2) sha256=efa74f891dd03c0939a931dfc6e74c2813d904763d456ea9762b0525e748db08
+ irb (1.18.0) sha256=de9454a0703a54704b9811a5ef31a60c86949fbf4013fcf244fabc7c775248e3
+ jmespath (1.6.2) sha256=238d774a58723d6c090494c8879b5e9918c19485f7e840f2c1c7532cf84ebcb1
+ json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+ jwt (3.2.0) sha256=5419b1fe37b1da0982bd07051f573a8b8789ab724c2aa7e785e4784a3ed217d7
+ logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+ mini_magick (4.13.2) sha256=71d6258e0e8a3d04a9a0a09784d5d857b403a198a51dd4f882510435eb95ddd9
+ mini_mime (1.1.5) sha256=8681b7e2e4215f2a159f9400b5816d85e9d8c6c6b491e96a12797e798f8bccef
+ multi_json (1.21.1) sha256=e6126a31808e3b4d19f483c775ceac34df190dffa62adfb63a165ee14ba68080
+ multipart-post (2.4.1) sha256=9872d03a8e552020ca096adadbf5e3cb1cd1cdd6acd3c161136b8a5737cdb4a8
+ mutex_m (0.3.0) sha256=cfcb04ac16b69c4813777022fdceda24e9f798e48092a2b817eb4c0a782b0751
+ nanaimo (0.4.0) sha256=faf069551bab17f15169c1f74a1c73c220657e71b6e900919897a10d991d0723
+ naturally (2.3.0) sha256=459923cf76c2e6613048301742363200c3c7e4904c324097d54a67401e179e01
+ net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
+ nkf (0.3.0) sha256=357a8dbeba38b727b75930f665146546076a394a1c243faf634ff176e3588895
+ optparse (0.8.1) sha256=42bea10d53907ccff4f080a69991441d611fbf8733b60ed1ce9ee365ce03bd1a
+ os (1.1.4) sha256=57816d6a334e7bd6aed048f4b0308226c5fb027433b67d90a9ab435f35108d3f
+ ostruct (0.6.3) sha256=95a2ed4a4bd1d190784e666b47b2d3f078e4a9efda2fccf18f84ddc6538ed912
+ plist (3.7.2) sha256=d37a4527cc1116064393df4b40e1dbbc94c65fa9ca2eec52edf9a13616718a42
+ pp (0.6.4) sha256=dfcb0fce700c41456265922884f9fe195d7fbb0674a3578e6c0f69588e82b570
+ prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+ prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+ pstore (0.2.1) sha256=03904d0f2c66579e96d1e6704cdabc0c88df7ea8ed8782d9f3569f6f6c702c1a
+ public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+ rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+ rbs (4.2.0) sha256=51f7b886dcc05bc09e10b901daa6a81829f6adc03101d6ca9ea4aac6103e0674
+ rdoc (8.0.0) sha256=03bf8c08a9639658855a0cfd77c0abca8325c227693f7f33f82957811348c469
+ reline (0.7.0) sha256=5b012d8e55dbf9d450f12bde2cf7d15ff546ae80b3f8f3b30e570d431815583d
+ representable (3.2.0) sha256=cc29bf7eebc31653586849371a43ffe36c60b54b0a6365b5f7d95ec34d1ebace
+ retriable (4.2.0) sha256=90c3b257472a1c02f2a3dfa64dd35a420f7a624cef1a5981e20fdac5730f8cdc
+ rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+ rouge (3.28.0) sha256=0d6de482c7624000d92697772ab14e48dca35629f8ddf3f4b21c99183fd70e20
+ rubyzip (2.4.1) sha256=8577c88edc1fde8935eb91064c5cb1aef9ad5494b940cf19c775ee833e075615
+ security (0.1.5) sha256=3a977a0eca7706e804c96db0dd9619e0a94969fe3aac9680fcfc2bf9b8a833b7
+ signet (0.22.0) sha256=b76d495ccb07ad35dbc89f3e920665a9d8ed717141955034005d7843dcfe4780
+ simctl (1.6.10) sha256=b99077f4d13ad81eace9f86bf5ba4df1b0b893a4d1b368bd3ed59b5b27f9236b
+ terminal-notifier (2.0.0) sha256=7a0d2b2212ab9835c07f4b2e22a94cff64149dba1eed203c04835f7991078cea
+ terminal-table (4.0.0) sha256=f504793203f8251b2ea7c7068333053f0beeea26093ec9962e62ea79f94301d2
+ trailblazer-option (0.1.2) sha256=20e4f12ea4e1f718c8007e7944ca21a329eee4eed9e0fa5dde6e8ad8ac4344a3
+ tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+ tty-cursor (0.7.1) sha256=79534185e6a777888d88628b14b6a1fdf5154a603f285f80b1753e1908e0bf48
+ tty-screen (0.8.2) sha256=c090652115beae764336c28802d633f204fb84da93c6a968aa5d8e319e819b50
+ tty-spinner (0.9.3) sha256=0e036f047b4ffb61f2aa45f5a770ec00b4d04130531558a94bfc5b192b570542
+ uber (0.1.0) sha256=5beeb407ff807b5db994f82fa9ee07cfceaa561dad8af20be880bc67eba935dc
+ unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+ unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+ uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
+ word_wrap (1.0.0) sha256=f556d4224c812e371000f12a6ee8102e0daa724a314c3f246afaad76d82accc7
+ xcodeproj (1.28.1) sha256=6f12670f00739d9817ca27ac89d6ef01cc86050e22a0bc08a3131487e5b5cddc
+ xcpretty (0.4.1) sha256=b14c50e721f6589ee3d6f5353e2c2cfcd8541fa1ea16d6c602807dd7327f3892
+ xcpretty-travis-formatter (1.0.1) sha256=aacc332f17cb7b2cba222994e2adc74223db88724fe76341483ad3098e232f93
+
+BUNDLED WITH
+ 4.0.14
diff --git a/NOTICE b/NOTICE
index f8e71c4..bffcf0d 100644
--- a/NOTICE
+++ b/NOTICE
@@ -13,3 +13,6 @@ LICENSE and NOTICE; those notices must be kept when vendoring ttfx.
Omarchy’s default screensaver wordmark and the image-to-Braille conversion
rules come from https://github.com/basecamp/omarchy, Copyright (c) 37signals /
Omarchy contributors, MIT License.
+
+The bundled screensaver font is Fairfax HD, Copyright (c) 2017–2020 Kreative
+Software, licensed under the SIL Open Font License 1.1. See assets/fonts/OFL.txt.
diff --git a/README.md b/README.md
index 00ca118..0084d17 100644
--- a/README.md
+++ b/README.md
@@ -4,12 +4,48 @@ A macOS screensaver that plays Omarchy’s ASCII text-effects loop: your logo (o
Rust `ttfx` engine, Swift/Metal view, Aerial-style host app + screensaver extension.
-**Status:** architecture only (revision 7). Spec: [docs/architecture.md](docs/architecture.md), [docs/ffi.md](docs/ffi.md), [docs/parity.md](docs/parity.md).
+**Status:** engine tested (`cargo test -p omacy-engine`). Host `.app` + `com.apple.screensaver` `.appex` compile on Xcode 26.6. Idle / System Settings listing remains a Mac gate: [docs/macos-gates.md](docs/macos-gates.md).
+
+Spec: [docs/architecture.md](docs/architecture.md), [docs/ffi.md](docs/ffi.md), [docs/parity.md](docs/parity.md).
+
+## Engine
+
+```
+cargo test -p omacy-engine
+```
+
+Pins: `vendor/ttfx/PIN` is ttfx v0.3.2 (`7203e354498462064b7c0a89375051f65cf2ce99`). Default art is `assets/branding/screensaver.txt`.
+
+## Mac host
+
+Open `apps/Omacy/Omacy.xcodeproj` on macOS 15+. The Xcode build phase runs `apps/Omacy/scripts/build-engine.sh`, which builds `libomacy_engine.a` for `aarch64-apple-darwin` and links it into the app and the appex.
+
+CI compiles that same scheme on `macos-26` (unsigned; deployment target 15.0). Idle / System Settings listing remains a machine gate: [docs/macos-gates.md](docs/macos-gates.md).
+
+Put `Omacy.app` in `/Applications`, then use the host to register the extension (`pluginkit`) and enable it (PaperSaver). The host will not register from a random path.
+
+Configuration (paste art, PNG/SVG conversion, effect, restore default) lives in the host and writes App Group `group.be.zenjoy.omacy`.
+
+## Signing
+
+Developer ID uses Zenjoy team `25TVW8MSGJ` and the same match repo as Zentty (`zentty-certificates`). Profiles:
+
+- `match Direct be.zenjoy.omacy macos`
+- `match Direct be.zenjoy.omacy.screensaver macos`
+
+```
+bundle exec fastlane mac generate_signing # once, or to renew
+bundle exec fastlane mac sync_signing # readonly install
+bundle exec fastlane mac archive # Developer ID export
+bundle exec fastlane mac notarize_app
+```
+
+Env: copy `fastlane/.env.example` or reuse Zentty’s 1Password item (`Zentty Release Environment`).
## Credits
-The motion is [Terminal Text Effects](https://github.com/ChrisBuilds/terminaltexteffects) by ChrisBuilds, running on [ttfx](https://github.com/omacom-io/ttfx), the Rust port Omarchy ships. Both are MIT. The Linux wrapper this copies is [Omarchy](https://github.com/basecamp/omarchy), also MIT.
+The motion is [Terminal Text Effects](https://github.com/ChrisBuilds/terminaltexteffects) by ChrisBuilds, running on [ttfx](https://github.com/omacom-io/ttfx), the Rust port Omarchy ships. Both are MIT. The Linux wrapper this copies is [Omarchy](https://github.com/basecamp/omarchy), also MIT. The bundled font is Fairfax HD by Kreative Software, SIL OFL.
## License
-MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE). Font: [assets/fonts/OFL.txt](assets/fonts/OFL.txt).
diff --git a/apps/Omacy/.gitattributes b/apps/Omacy/.gitattributes
new file mode 100644
index 0000000..dfe0770
--- /dev/null
+++ b/apps/Omacy/.gitattributes
@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto
diff --git a/apps/Omacy/.gitignore b/apps/Omacy/.gitignore
new file mode 100644
index 0000000..d32ab36
--- /dev/null
+++ b/apps/Omacy/.gitignore
@@ -0,0 +1,6 @@
+/.build
+.DS_Store
+DerivedData/
+xcuserdata/
+*.xcuserstate
+*.xcbkptlist
diff --git a/apps/Omacy/BACKGROUND.md b/apps/Omacy/BACKGROUND.md
new file mode 100644
index 0000000..7e0e632
--- /dev/null
+++ b/apps/Omacy/BACKGROUND.md
@@ -0,0 +1,284 @@
+# macOS Appex Screensaver — Technical Background
+
+This document captures what's known about developing screensavers for macOS Sonoma and later using the modern ExtensionKit (`.appex`) format. It is meant as a companion to the sample code in this repository.
+
+---
+
+## 1. Architecture
+
+### `.appex` vs. legacy `.saver`
+
+Modern macOS (Sonoma+) supports screensavers packaged as ExtensionKit `.appex` bundles in addition to the legacy `.saver` plug-in format. Apple's own first-party savers (Hello, Arabesque, Drift, Monterey, Ventura, Shell, Flurry) all use the appex format.
+
+| | `.appex` | `.saver` |
+|---|---|---|
+| **Bundle type** | `CFBundlePackageType = XPC!` | `CFBundlePackageType = BNDL` |
+| **Process model** | Separate sandboxed XPC process | Loaded into `legacyScreenSaver.appex` |
+| **Framework** | `ScreenSaver.framework` + ExtensionKit | `ScreenSaver.framework` |
+| **Min macOS** | 14.0 (Sonoma) | All supported macOS |
+| **Distribution** | Embedded inside a host `.app`, registered via `pluginkit` | Standalone `.saver` file |
+
+### Extension Point
+
+- **Identifier:** `com.apple.screensaver`
+- **Version:** `1.0`
+
+### Process Isolation
+
+Each appex screensaver runs in its own sandboxed process. The framework handles all inter-process communication via XPC; you don't write XPC code yourself. View rendering, input events, and lifecycle messages all flow through the framework transparently.
+
+---
+
+## 2. Class Hierarchy
+
+### Public API (`ScreenSaver.framework`)
+
+| Class | Purpose |
+|-------|---------|
+| `ScreenSaverView` | Your main view. NSView subclass with `animateOneFrame()`, `startAnimation()`, `stopAnimation()`, `draw(_:)`. |
+| `ScreenSaverDefaults` | `UserDefaults` subclass for screensaver preferences. |
+
+### ExtensionKit classes used by appex screensavers
+
+These are still partly underdocumented; their declarations live in `OmacyScreensaver/PrivateHeaders/ScreenSaverPrivate.h` in this repo. On recent SDKs the symbols are also available without the bridging header.
+
+| Class | Purpose |
+|-------|---------|
+| `ScreenSaverExtension` | Principal class. Set as `NSExtensionPrincipalClass` in Info.plist. |
+| `ScreenSaverViewController` | View controller managing the screensaver view. Set as `ScreenSaverViewControllerClass` in Info.plist. |
+| `ScreenSaverConfigurationViewController` | Base class for the optional configuration sheet. |
+
+---
+
+## 3. Info.plist Configuration
+
+### `NSExtension` dictionary
+
+```xml
+NSExtension
+
+ NSExtensionPointIdentifier
+ com.apple.screensaver
+ NSExtensionPointVersion
+ 1.0
+ NSExtensionPrincipalClass
+ $(PRODUCT_MODULE_NAME).YourScreenSaverExtension
+
+```
+
+### Root-level screensaver keys
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `ScreenSaverViewControllerClass` | String | Fully-qualified name of the main view controller. |
+| `ScreenSaverConfigurationSheetViewControllerClass` | String | Fully-qualified name of the configuration sheet controller. |
+| `SSEHasConfigureSheet` | Boolean | Whether the screensaver has a configuration UI. |
+| `SSENeedsAnimationTimer` | Boolean | Whether the framework should drive a per-frame animation timer (see §5). |
+
+Use `$(PRODUCT_MODULE_NAME).ClassName` so the module prefix tracks your target name automatically.
+
+---
+
+## 4. Apple's Built-in Screensavers (Reference)
+
+Located in `/System/Library/ExtensionKit/Extensions/`.
+
+| Name | Principal Class | View Controller | Has Config |
+|------|-----------------|-----------------|------------|
+| Arabesque | `Arabesque.ArabesqueExtension` | `ArabesqueViewController` | No |
+| Flurry | `Flurry.FlurryExtension` | `FlurryViewController` | Yes |
+| Drift | `Drift.FlowExtension` | `FlowViewController` | Yes |
+| Hello | `Hello.HelloExtension` | `HelloViewController` | Yes |
+| Monterey | `Monterey.CanyonExtension` | `CanyonViewController` | No |
+| Ventura | `Ventura.PetalExtension` | `PetalViewController` | No |
+| Shell | `Shell.ShellExtension` | `ShellViewController` | No |
+
+**Naming conventions** Apple uses:
+
+- Principal class: `Module.ModuleExtension` (e.g. `Arabesque.ArabesqueExtension`)
+- View controller: `ModuleViewController`
+- View class: `Module.ModuleView`
+
+---
+
+## 5. Rendering: three valid approaches
+
+There is no single "right" way to render an appex screensaver. Pick whichever fits your animation model.
+
+### A. Direct CALayer animation (what this sample uses)
+
+Manipulate the backing CALayer directly — either with `CABasicAnimation` (Aerial's fallback and this sample's `OmacyCanaryAnimator`) or with your own `Timer` updating layer properties. Set `SSENeedsAnimationTimer = false` because the layer or your timer drives frames itself.
+
+```swift
+class YourScreenSaverView: ScreenSaverView {
+ override init?(frame: NSRect, isPreview: Bool) {
+ super.init(frame: frame, isPreview: isPreview)
+ wantsLayer = true
+ }
+
+ override func viewDidMoveToWindow() {
+ super.viewDidMoveToWindow()
+ guard let layer = self.layer, window != nil else { return }
+ let animation = CABasicAnimation(keyPath: "backgroundColor")
+ animation.fromValue = NSColor.red.cgColor
+ animation.toValue = NSColor.blue.cgColor
+ animation.duration = 2.0
+ animation.autoreverses = true
+ animation.repeatCount = .infinity
+ layer.add(animation, forKey: "demo")
+ }
+}
+```
+
+### B. Traditional `ScreenSaverView` overrides
+
+Override `startAnimation()`, `stopAnimation()`, `animateOneFrame()`, and `draw(_:)`. These **do** get called by the framework when `SSENeedsAnimationTimer = true`; they're the same calls a `.saver` plug-in would receive.
+
+```swift
+class YourScreenSaverView: ScreenSaverView {
+ override init?(frame: NSRect, isPreview: Bool) {
+ super.init(frame: frame, isPreview: isPreview)
+ animationTimeInterval = 1.0 / 30.0
+ }
+
+ override func animateOneFrame() {
+ super.animateOneFrame()
+ // Update model state, then trigger a redraw:
+ setNeedsDisplay(bounds)
+ }
+
+ override func draw(_ rect: NSRect) {
+ NSColor.black.setFill()
+ bounds.fill()
+ // ...your drawing here...
+ }
+}
+```
+
+### C. SwiftUI via `NSHostingView`
+
+You can host SwiftUI inside an appex screensaver by wrapping your SwiftUI root view in `NSHostingView` and adding it as a subview of the `ScreenSaverView`. The [Aerial](https://github.com/AerialScreensaver/Aerial) screensaver uses this pattern for weather, music, and clock overlays painted on top of its video player.
+
+```swift
+import SwiftUI
+
+class YourScreenSaverView: ScreenSaverView {
+ private var hosting: NSHostingView?
+
+ override init?(frame: NSRect, isPreview: Bool) {
+ super.init(frame: frame, isPreview: isPreview)
+ wantsLayer = true
+
+ let host = NSHostingView(rootView: YourSwiftUIView())
+ host.translatesAutoresizingMaskIntoConstraints = false
+ addSubview(host)
+ NSLayoutConstraint.activate([
+ host.leadingAnchor.constraint(equalTo: leadingAnchor),
+ host.trailingAnchor.constraint(equalTo: trailingAnchor),
+ host.topAnchor.constraint(equalTo: topAnchor),
+ host.bottomAnchor.constraint(equalTo: bottomAnchor),
+ ])
+ hosting = host
+ }
+}
+```
+
+Note that SwiftUI is hosted *inside* the `ScreenSaverView`; it is not the principal class. The principal class must still be a `ScreenSaverExtension` subclass.
+
+### View controller setup
+
+The view controller overrides `loadView()` to instantiate and assign the screensaver view:
+
+```swift
+@objc(YourViewController)
+class YourViewController: ScreenSaverViewController {
+ override func loadView() {
+ let frame = NSScreen.main?.frame ?? NSRect(x: 0, y: 0, width: 1920, height: 1080)
+ let isPreview = frame.width < 400
+ self.view = YourScreenSaverView(frame: frame, isPreview: isPreview)
+ ?? NSView(frame: frame)
+ }
+}
+```
+
+---
+
+## 6. Registration and Discovery
+
+### Using `pluginkit`
+
+```bash
+# Register an appex
+pluginkit -a /path/to/YourScreensaver.app/Contents/PlugIns/YourScreensaver.appex
+
+# List all registered screensavers
+pluginkit -m -v -p com.apple.screensaver
+
+# Unregister
+pluginkit -r /path/to/YourScreensaver.appex
+```
+
+In production the appex must be embedded inside an application bundle:
+
+```
+YourApp.app/Contents/PlugIns/YourScreensaver.appex
+```
+
+You typically ship the host app to `/Applications/`, and macOS picks the appex up automatically (or your host app calls `pluginkit -a` on first launch, as this sample does in `PluginManager.swift`).
+
+---
+
+## 7. Thumbnails
+
+### Required dimensions
+
+System Settings displays screensaver thumbnails at a specific landscape aspect ratio. Square images won't appear.
+
+| Scale | Dimensions |
+|-------|------------|
+| 1x | 107 × 65 |
+| 2x | 214 × 130 |
+
+### Asset catalog setup
+
+Place thumbnails in an asset catalog imageset named `thumbnail`:
+
+```
+Assets.xcassets/
+└── thumbnail.imageset/
+ ├── Contents.json
+ ├── thumbnail.png (107 × 65)
+ └── thumbnail@2x.png (214 × 130)
+```
+
+`Contents.json`:
+
+```json
+{
+ "images": [
+ { "filename": "thumbnail.png", "idiom": "universal", "scale": "1x" },
+ { "filename": "thumbnail@2x.png", "idiom": "universal", "scale": "2x" }
+ ],
+ "info": { "author": "xcode", "version": 1 }
+}
+```
+
+Some Apple screensavers ship both explicit PNGs in `Resources/` and entries inside the compiled `Assets.car`; the explicit PNGs appear to take priority when present.
+
+### Caching
+
+macOS caches screensaver thumbnails aggressively. If yours doesn't appear after changes:
+
+1. Rebuild and re-register: `pluginkit -a /path/to/Extension.appex`
+2. Close and reopen System Settings
+3. Log out and back in if the cached version persists
+
+---
+
+## References
+
+- `ScreenSaver.framework` headers in the macOS SDK
+- Apple's built-in screensaver extensions at `/System/Library/ExtensionKit/Extensions/`
+- ExtensionKit documentation in the Xcode SDK
+- [Aerial](https://github.com/AerialScreensaver/Aerial) — full appex screensaver using approaches A and C together
+- [ScreenSaverMinimal](https://github.com/AerialScreensaver/ScreenSaverMinimal) — same author's sample for the legacy `.saver` format
diff --git a/apps/Omacy/BuildNumber.xcconfig b/apps/Omacy/BuildNumber.xcconfig
new file mode 100644
index 0000000..32736bb
--- /dev/null
+++ b/apps/Omacy/BuildNumber.xcconfig
@@ -0,0 +1 @@
+CURRENT_PROJECT_VERSION = 260827.2045
diff --git a/apps/Omacy/LICENSE b/apps/Omacy/LICENSE
new file mode 100644
index 0000000..1a6259a
--- /dev/null
+++ b/apps/Omacy/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guillaume Louel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/apps/Omacy/Omacy.xcodeproj/project.pbxproj b/apps/Omacy/Omacy.xcodeproj/project.pbxproj
new file mode 100644
index 0000000..feb4790
--- /dev/null
+++ b/apps/Omacy/Omacy.xcodeproj/project.pbxproj
@@ -0,0 +1,825 @@
+// !$*UTF8*$!
+{
+ archiveVersion = 1;
+ classes = {
+ };
+ objectVersion = 56;
+ objects = {
+
+/* Begin PBXBuildFile section */
+ 1A000001000000000000000A /* OmacyApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000001000000000000000B /* OmacyApp.swift */; };
+ 1A000002000000000000000A /* ContentView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000002000000000000000B /* ContentView.swift */; };
+ 1A000003000000000000000A /* OmacyScreensaver.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000003000000000000000B /* OmacyScreensaver.swift */; };
+ 1A000004000000000000000A /* OmacySaverViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000004000000000000000B /* OmacySaverViewController.swift */; };
+ 1A000005000000000000000A /* OmacySaverView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000005000000000000000B /* OmacySaverView.swift */; };
+ 1A000006000000000000000A /* ScreenSaver.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 1A000006000000000000000B /* ScreenSaver.framework */; };
+ 1A000007000000000000000A /* OmacyScreensaver.appex in Embed PlugIns */ = {isa = PBXBuildFile; fileRef = 1A000007000000000000000B /* OmacyScreensaver.appex */; settings = {ATTRIBUTES = (RemoveHeadersOnCopy, ); }; };
+ 1A000030000000000000000A /* OmacyConfigurationViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000030000000000000000B /* OmacyConfigurationViewController.swift */; };
+ 1A000031000000000000000A /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 1A000031000000000000000B /* Assets.xcassets */; };
+ 1A000032000000000000000A /* PluginManager.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000032000000000000000B /* PluginManager.swift */; };
+ 1A000060000000000000000A /* OmacyCanaryAnimator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000060000000000000000B /* OmacyCanaryAnimator.swift */; };
+ 1A000061000000000000000A /* OmacyCanaryAnimator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000060000000000000000B /* OmacyCanaryAnimator.swift */; };
+ 1A000062000000000000000A /* PreviewView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000062000000000000000B /* PreviewView.swift */; };
+ 1A000063000000000000000A /* PreviewViewRepresentable.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000063000000000000000B /* PreviewViewRepresentable.swift */; };
+ 1A000066000000000000000A /* Logger.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000064000000000000000B /* Logger.swift */; };
+ 1A000067000000000000000A /* Logger.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000064000000000000000B /* Logger.swift */; };
+ 1A000070000000000000000A /* PaperSaverKit in Frameworks */ = {isa = PBXBuildFile; productRef = 1A000070000000000000000B /* PaperSaverKit */; };
+ 1A0000A0000000000000000A /* OmacyRenderer.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000090000000000000000B /* OmacyRenderer.swift */; };
+ 1A0000A1000000000000000A /* OmacyRenderer.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000090000000000000000B /* OmacyRenderer.swift */; };
+ 1A0000A2000000000000000A /* OmacyLayout.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000091000000000000000B /* OmacyLayout.swift */; };
+ 1A0000A3000000000000000A /* OmacyLayout.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000091000000000000000B /* OmacyLayout.swift */; };
+ 1A0000A4000000000000000A /* OmacyStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000092000000000000000B /* OmacyStore.swift */; };
+ 1A0000A5000000000000000A /* OmacyStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000092000000000000000B /* OmacyStore.swift */; };
+ 1A0000A6000000000000000A /* OmacyAtlas.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000093000000000000000B /* OmacyAtlas.swift */; };
+ 1A0000A7000000000000000A /* OmacyAtlas.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000093000000000000000B /* OmacyAtlas.swift */; };
+ 1A0000A8000000000000000A /* OmacyShaders.metal in Sources */ = {isa = PBXBuildFile; fileRef = 1A000094000000000000000B /* OmacyShaders.metal */; };
+ 1A0000A9000000000000000A /* OmacyShaders.metal in Sources */ = {isa = PBXBuildFile; fileRef = 1A000094000000000000000B /* OmacyShaders.metal */; };
+ 1A0000AA000000000000000A /* OmacyHostView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000095000000000000000B /* OmacyHostView.swift */; };
+ 1A0000AB000000000000000A /* ConfigView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A000096000000000000000B /* ConfigView.swift */; };
+ 1A0000AC000000000000000A /* FairfaxHD.ttf in Resources */ = {isa = PBXBuildFile; fileRef = 1A000097000000000000000B /* FairfaxHD.ttf */; };
+ 1A0000AD000000000000000A /* FairfaxHD.ttf in Resources */ = {isa = PBXBuildFile; fileRef = 1A000097000000000000000B /* FairfaxHD.ttf */; };
+ 1A0000AE000000000000000A /* screensaver.txt in Resources */ = {isa = PBXBuildFile; fileRef = 1A000098000000000000000B /* screensaver.txt */; };
+ 1A0000AF000000000000000A /* screensaver.txt in Resources */ = {isa = PBXBuildFile; fileRef = 1A000098000000000000000B /* screensaver.txt */; };
+ 1A0000B0000000000000000A /* OFL.txt in Resources */ = {isa = PBXBuildFile; fileRef = 1A000099000000000000000B /* OFL.txt */; };
+ 1A0000B1000000000000000A /* OFL.txt in Resources */ = {isa = PBXBuildFile; fileRef = 1A000099000000000000000B /* OFL.txt */; };
+ 1A0000B2000000000000000A /* Metal.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 1A00009A000000000000000B /* Metal.framework */; };
+ 1A0000B3000000000000000A /* Metal.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 1A00009A000000000000000B /* Metal.framework */; };
+ 1A0000B4000000000000000A /* libomacy_engine.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 1A00009B000000000000000B /* libomacy_engine.a */; };
+ 1A0000B5000000000000000A /* libomacy_engine.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 1A00009B000000000000000B /* libomacy_engine.a */; };
+ 1A0000B6000000000000000A /* OmacyCanaryAnimator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A00009D000000000000000B /* OmacyCanaryAnimator.swift */; };
+ 1A0000B7000000000000000A /* OmacyCanaryAnimator.swift in Sources */ = {isa = PBXBuildFile; fileRef = 1A00009D000000000000000B /* OmacyCanaryAnimator.swift */; };
+ 1A0000E0000000000000000A /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 1A0000E0000000000000000B /* Assets.xcassets */; };
+/* End PBXBuildFile section */
+
+/* Begin PBXContainerItemProxy section */
+ 1A000008000000000000000A /* PBXContainerItemProxy */ = {
+ isa = PBXContainerItemProxy;
+ containerPortal = 1A000000000000000000000A /* Project object */;
+ proxyType = 1;
+ remoteGlobalIDString = 1A000010000000000000000A;
+ remoteInfo = OmacyScreensaver;
+ };
+/* End PBXContainerItemProxy section */
+
+/* Begin PBXCopyFilesBuildPhase section */
+ 1A000009000000000000000A /* Embed PlugIns */ = {
+ isa = PBXCopyFilesBuildPhase;
+ buildActionMask = 2147483647;
+ dstPath = "";
+ dstSubfolderSpec = 13;
+ files = (
+ 1A000007000000000000000A /* OmacyScreensaver.appex in Embed PlugIns */,
+ );
+ name = "Embed PlugIns";
+ runOnlyForDeploymentPostprocessing = 0;
+ };
+/* End PBXCopyFilesBuildPhase section */
+
+/* Begin PBXFileReference section */
+ 1A000001000000000000000B /* OmacyApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyApp.swift; sourceTree = ""; };
+ 1A000002000000000000000B /* ContentView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ContentView.swift; sourceTree = ""; };
+ 1A000003000000000000000B /* OmacyScreensaver.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyScreensaver.swift; sourceTree = ""; };
+ 1A000004000000000000000B /* OmacySaverViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacySaverViewController.swift; sourceTree = ""; };
+ 1A000005000000000000000B /* OmacySaverView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacySaverView.swift; sourceTree = ""; };
+ 1A000006000000000000000B /* ScreenSaver.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = ScreenSaver.framework; path = System/Library/Frameworks/ScreenSaver.framework; sourceTree = SDKROOT; };
+ 1A000007000000000000000B /* OmacyScreensaver.appex */ = {isa = PBXFileReference; explicitFileType = "wrapper.app-extension"; includeInIndex = 0; path = OmacyScreensaver.appex; sourceTree = BUILT_PRODUCTS_DIR; };
+ 1A00000A000000000000000B /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = ""; };
+ 1A00000B000000000000000B /* Omacy.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = Omacy.entitlements; sourceTree = ""; };
+ 1A00000C000000000000000B /* Omacy.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = Omacy.app; sourceTree = BUILT_PRODUCTS_DIR; };
+ 1A00000D000000000000000B /* ScreenSaverPrivate.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = ScreenSaverPrivate.h; sourceTree = ""; };
+ 1A00000E000000000000000B /* OmacyScreensaver-Bridging-Header.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "OmacyScreensaver-Bridging-Header.h"; sourceTree = ""; };
+ 1A00000F000000000000000B /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = ""; };
+ 1A000011000000000000000B /* OmacyScreensaver.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = OmacyScreensaver.entitlements; sourceTree = ""; };
+ 1A000030000000000000000B /* OmacyConfigurationViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyConfigurationViewController.swift; sourceTree = ""; };
+ 1A000031000000000000000B /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = ""; };
+ 1A000032000000000000000B /* PluginManager.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PluginManager.swift; sourceTree = ""; };
+ 1A000050000000000000000B /* BuildNumber.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = BuildNumber.xcconfig; sourceTree = ""; };
+ 1A000060000000000000000B /* OmacyCanaryAnimator.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyCanaryAnimator.swift; sourceTree = ""; };
+ 1A000062000000000000000B /* PreviewView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PreviewView.swift; sourceTree = ""; };
+ 1A000063000000000000000B /* PreviewViewRepresentable.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = PreviewViewRepresentable.swift; sourceTree = ""; };
+ 1A000064000000000000000B /* Logger.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Logger.swift; sourceTree = ""; };
+ 1A000090000000000000000B /* OmacyRenderer.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyRenderer.swift; sourceTree = ""; };
+ 1A000091000000000000000B /* OmacyLayout.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyLayout.swift; sourceTree = ""; };
+ 1A000092000000000000000B /* OmacyStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyStore.swift; sourceTree = ""; };
+ 1A000093000000000000000B /* OmacyAtlas.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyAtlas.swift; sourceTree = ""; };
+ 1A000094000000000000000B /* OmacyShaders.metal */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.metal; path = OmacyShaders.metal; sourceTree = ""; };
+ 1A000095000000000000000B /* OmacyHostView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyHostView.swift; sourceTree = ""; };
+ 1A000096000000000000000B /* ConfigView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ConfigView.swift; sourceTree = ""; };
+ 1A000097000000000000000B /* FairfaxHD.ttf */ = {isa = PBXFileReference; lastKnownFileType = file; name = FairfaxHD.ttf; path = ../../assets/fonts/FairfaxHD.ttf; sourceTree = SOURCE_ROOT; };
+ 1A000098000000000000000B /* screensaver.txt */ = {isa = PBXFileReference; lastKnownFileType = text; name = screensaver.txt; path = ../../assets/branding/screensaver.txt; sourceTree = SOURCE_ROOT; };
+ 1A000099000000000000000B /* OFL.txt */ = {isa = PBXFileReference; lastKnownFileType = text; name = OFL.txt; path = ../../assets/fonts/OFL.txt; sourceTree = SOURCE_ROOT; };
+ 1A00009A000000000000000B /* Metal.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Metal.framework; path = System/Library/Frameworks/Metal.framework; sourceTree = SDKROOT; };
+ 1A00009B000000000000000B /* libomacy_engine.a */ = {isa = PBXFileReference; lastKnownFileType = archive.ar; path = libomacy_engine.a; sourceTree = BUILT_PRODUCTS_DIR; };
+ 1A00009C000000000000000B /* Omacy-Bridging-Header.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "Omacy-Bridging-Header.h"; sourceTree = ""; };
+ 1A00009D000000000000000B /* OmacyCanaryAnimator.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = OmacyCanaryAnimator.swift; sourceTree = ""; };
+ 1A0000E0000000000000000B /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; path = Assets.xcassets; sourceTree = ""; };
+/* End PBXFileReference section */
+
+/* Begin PBXFrameworksBuildPhase section */
+ 1A000012000000000000000A /* Frameworks */ = {
+ isa = PBXFrameworksBuildPhase;
+ buildActionMask = 2147483647;
+ files = (
+ 1A000070000000000000000A /* PaperSaverKit in Frameworks */,
+ 1A0000B2000000000000000A /* Metal.framework in Frameworks */,
+ 1A0000B4000000000000000A /* libomacy_engine.a in Frameworks */,
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ };
+ 1A000013000000000000000A /* Frameworks */ = {
+ isa = PBXFrameworksBuildPhase;
+ buildActionMask = 2147483647;
+ files = (
+ 1A000006000000000000000A /* ScreenSaver.framework in Frameworks */,
+ 1A0000B3000000000000000A /* Metal.framework in Frameworks */,
+ 1A0000B5000000000000000A /* libomacy_engine.a in Frameworks */,
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ };
+/* End PBXFrameworksBuildPhase section */
+
+/* Begin PBXGroup section */
+ 1A000014000000000000000C = {
+ isa = PBXGroup;
+ children = (
+ 1A000050000000000000000B /* BuildNumber.xcconfig */,
+ 1A000015000000000000000C /* Omacy */,
+ 1A000016000000000000000C /* OmacyScreensaver */,
+ 1A0000C0000000000000000C /* Shared */,
+ 1A000017000000000000000C /* Frameworks */,
+ 1A000018000000000000000C /* Products */,
+ );
+ sourceTree = "";
+ };
+ 1A000015000000000000000C /* Omacy */ = {
+ isa = PBXGroup;
+ children = (
+ 1A000065000000000000000C /* Helpers */,
+ 1A000001000000000000000B /* OmacyApp.swift */,
+ 1A000002000000000000000B /* ContentView.swift */,
+ 1A000032000000000000000B /* PluginManager.swift */,
+ 1A000095000000000000000B /* OmacyHostView.swift */,
+ 1A000096000000000000000B /* ConfigView.swift */,
+ 1A000062000000000000000B /* PreviewView.swift */,
+ 1A000063000000000000000B /* PreviewViewRepresentable.swift */,
+ 1A00009C000000000000000B /* Omacy-Bridging-Header.h */,
+ 1A0000E0000000000000000B /* Assets.xcassets */,
+ 1A00000A000000000000000B /* Info.plist */,
+ 1A00000B000000000000000B /* Omacy.entitlements */,
+ );
+ path = Omacy;
+ sourceTree = "";
+ };
+ 1A000065000000000000000C /* Helpers */ = {
+ isa = PBXGroup;
+ children = (
+ 1A000064000000000000000B /* Logger.swift */,
+ );
+ path = Helpers;
+ sourceTree = "";
+ };
+ 1A000016000000000000000C /* OmacyScreensaver */ = {
+ isa = PBXGroup;
+ children = (
+ 1A000019000000000000000C /* PrivateHeaders */,
+ 1A000003000000000000000B /* OmacyScreensaver.swift */,
+ 1A000004000000000000000B /* OmacySaverViewController.swift */,
+ 1A000005000000000000000B /* OmacySaverView.swift */,
+ 1A000030000000000000000B /* OmacyConfigurationViewController.swift */,
+ 1A000031000000000000000B /* Assets.xcassets */,
+ 1A00000E000000000000000B /* OmacyScreensaver-Bridging-Header.h */,
+ 1A00000F000000000000000B /* Info.plist */,
+ 1A000011000000000000000B /* OmacyScreensaver.entitlements */,
+ );
+ path = OmacyScreensaver;
+ sourceTree = "";
+ };
+ 1A0000C0000000000000000C /* Shared */ = {
+ isa = PBXGroup;
+ children = (
+ 1A00009D000000000000000B /* OmacyCanaryAnimator.swift */,
+ 1A000090000000000000000B /* OmacyRenderer.swift */,
+ 1A000091000000000000000B /* OmacyLayout.swift */,
+ 1A000092000000000000000B /* OmacyStore.swift */,
+ 1A000093000000000000000B /* OmacyAtlas.swift */,
+ 1A000094000000000000000B /* OmacyShaders.metal */,
+ 1A000097000000000000000B /* FairfaxHD.ttf */,
+ 1A000098000000000000000B /* screensaver.txt */,
+ 1A000099000000000000000B /* OFL.txt */,
+ );
+ path = Shared;
+ sourceTree = "";
+ };
+ 1A000017000000000000000C /* Frameworks */ = {
+ isa = PBXGroup;
+ children = (
+ 1A000006000000000000000B /* ScreenSaver.framework */,
+ 1A00009A000000000000000B /* Metal.framework */,
+ 1A00009B000000000000000B /* libomacy_engine.a */,
+ );
+ name = Frameworks;
+ sourceTree = "";
+ };
+ 1A000018000000000000000C /* Products */ = {
+ isa = PBXGroup;
+ children = (
+ 1A00000C000000000000000B /* Omacy.app */,
+ 1A000007000000000000000B /* OmacyScreensaver.appex */,
+ );
+ name = Products;
+ sourceTree = "";
+ };
+ 1A000019000000000000000C /* PrivateHeaders */ = {
+ isa = PBXGroup;
+ children = (
+ 1A00000D000000000000000B /* ScreenSaverPrivate.h */,
+ );
+ path = PrivateHeaders;
+ sourceTree = "";
+ };
+/* End PBXGroup section */
+
+/* Begin PBXNativeTarget section */
+ 1A000010000000000000000A /* OmacyScreensaver */ = {
+ isa = PBXNativeTarget;
+ buildConfigurationList = 1A00001F000000000000000A /* Build configuration list for PBXNativeTarget "OmacyScreensaver" */;
+ buildPhases = (
+ 1A0000D1000000000000000A /* Build Rust engine */,
+ 1A000020000000000000000A /* Sources */,
+ 1A000013000000000000000A /* Frameworks */,
+ 1A000021000000000000000A /* Resources */,
+ );
+ buildRules = (
+ );
+ dependencies = (
+ );
+ name = OmacyScreensaver;
+ productName = OmacyScreensaver;
+ productReference = 1A000007000000000000000B /* OmacyScreensaver.appex */;
+ productType = "com.apple.product-type.app-extension";
+ };
+ 1A00001A000000000000000A /* Omacy */ = {
+ isa = PBXNativeTarget;
+ buildConfigurationList = 1A00001B000000000000000A /* Build configuration list for PBXNativeTarget "Omacy" */;
+ buildPhases = (
+ 1A00001C000000000000000A /* Sources */,
+ 1A000012000000000000000A /* Frameworks */,
+ 1A00001D000000000000000A /* Resources */,
+ 1A000009000000000000000A /* Embed PlugIns */,
+ 1A000042000000000000000A /* Register Extensions */,
+ );
+ buildRules = (
+ );
+ dependencies = (
+ 1A00001E000000000000000A /* PBXTargetDependency */,
+ );
+ name = Omacy;
+ packageProductDependencies = (
+ 1A000070000000000000000B /* PaperSaverKit */,
+ );
+ productName = Omacy;
+ productReference = 1A00000C000000000000000B /* Omacy.app */;
+ productType = "com.apple.product-type.application";
+ };
+/* End PBXNativeTarget section */
+
+/* Begin PBXProject section */
+ 1A000000000000000000000A /* Project object */ = {
+ isa = PBXProject;
+ attributes = {
+ BuildIndependentTargetsInParallel = 1;
+ LastSwiftUpdateCheck = 1500;
+ LastUpgradeCheck = 1500;
+ TargetAttributes = {
+ 1A000010000000000000000A = {
+ CreatedOnToolsVersion = 15.0;
+ };
+ 1A00001A000000000000000A = {
+ CreatedOnToolsVersion = 15.0;
+ };
+ };
+ };
+ buildConfigurationList = 1A000022000000000000000A /* Build configuration list for PBXProject "Omacy" */;
+ compatibilityVersion = "Xcode 14.0";
+ developmentRegion = en;
+ hasScannedForEncodings = 0;
+ knownRegions = (
+ en,
+ Base,
+ );
+ mainGroup = 1A000014000000000000000C;
+ packageReferences = (
+ 1A000071000000000000000A /* XCRemoteSwiftPackageReference "PaperSaver" */,
+ );
+ productRefGroup = 1A000018000000000000000C /* Products */;
+ projectDirPath = "";
+ projectRoot = "";
+ targets = (
+ 1A00001A000000000000000A /* Omacy */,
+ 1A000010000000000000000A /* OmacyScreensaver */,
+ );
+ };
+/* End PBXProject section */
+
+/* Begin PBXResourcesBuildPhase section */
+ 1A00001D000000000000000A /* Resources */ = {
+ isa = PBXResourcesBuildPhase;
+ buildActionMask = 2147483647;
+ files = (
+ 1A0000AC000000000000000A /* FairfaxHD.ttf in Resources */,
+ 1A0000AE000000000000000A /* screensaver.txt in Resources */,
+ 1A0000B0000000000000000A /* OFL.txt in Resources */,
+ 1A0000E0000000000000000A /* Assets.xcassets in Resources */,
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ };
+ 1A000021000000000000000A /* Resources */ = {
+ isa = PBXResourcesBuildPhase;
+ buildActionMask = 2147483647;
+ files = (
+ 1A000031000000000000000A /* Assets.xcassets in Resources */,
+ 1A0000AD000000000000000A /* FairfaxHD.ttf in Resources */,
+ 1A0000AF000000000000000A /* screensaver.txt in Resources */,
+ 1A0000B1000000000000000A /* OFL.txt in Resources */,
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ };
+/* End PBXResourcesBuildPhase section */
+
+/* Begin PBXShellScriptBuildPhase section */
+ 1A0000D1000000000000000A /* Build Rust engine */ = {
+ isa = PBXShellScriptBuildPhase;
+ alwaysOutOfDate = 1;
+ buildActionMask = 2147483647;
+ files = (
+ );
+ inputFileListPaths = (
+ );
+ inputPaths = (
+ );
+ name = "Build Rust engine";
+ outputFileListPaths = (
+ );
+ outputPaths = (
+ "$(BUILT_PRODUCTS_DIR)/libomacy_engine.a",
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ shellPath = /bin/sh;
+ shellScript = "sh \"${SRCROOT}/scripts/build-engine.sh\"\n";
+ };
+ 1A000042000000000000000A /* Register Extensions */ = {
+ isa = PBXShellScriptBuildPhase;
+ buildActionMask = 2147483647;
+ files = (
+ );
+ inputFileListPaths = (
+ );
+ inputPaths = (
+ );
+ name = "Register Extensions";
+ outputFileListPaths = (
+ );
+ outputPaths = (
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ shellPath = /bin/sh;
+ shellScript = "if [ -n \"$CI\" ]; then echo \"skip pluginkit on CI\"; exit 0; fi\nfind \"$CODESIGNING_FOLDER_PATH\" -name '*.appex' -exec pluginkit -a {} \\; || true\n";
+ };
+/* End PBXShellScriptBuildPhase section */
+
+/* Begin PBXSourcesBuildPhase section */
+ 1A00001C000000000000000A /* Sources */ = {
+ isa = PBXSourcesBuildPhase;
+ buildActionMask = 2147483647;
+ files = (
+ 1A000001000000000000000A /* OmacyApp.swift in Sources */,
+ 1A000002000000000000000A /* ContentView.swift in Sources */,
+ 1A000032000000000000000A /* PluginManager.swift in Sources */,
+ 1A000066000000000000000A /* Logger.swift in Sources */,
+ 1A0000A0000000000000000A /* OmacyRenderer.swift in Sources */,
+ 1A0000A2000000000000000A /* OmacyLayout.swift in Sources */,
+ 1A0000A4000000000000000A /* OmacyStore.swift in Sources */,
+ 1A0000A6000000000000000A /* OmacyAtlas.swift in Sources */,
+ 1A0000A8000000000000000A /* OmacyShaders.metal in Sources */,
+ 1A0000AA000000000000000A /* OmacyHostView.swift in Sources */,
+ 1A0000AB000000000000000A /* ConfigView.swift in Sources */,
+ 1A000062000000000000000A /* PreviewView.swift in Sources */,
+ 1A000063000000000000000A /* PreviewViewRepresentable.swift in Sources */,
+ 1A0000B6000000000000000A /* OmacyCanaryAnimator.swift in Sources */,
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ };
+ 1A000020000000000000000A /* Sources */ = {
+ isa = PBXSourcesBuildPhase;
+ buildActionMask = 2147483647;
+ files = (
+ 1A000003000000000000000A /* OmacyScreensaver.swift in Sources */,
+ 1A000004000000000000000A /* OmacySaverViewController.swift in Sources */,
+ 1A000005000000000000000A /* OmacySaverView.swift in Sources */,
+ 1A000030000000000000000A /* OmacyConfigurationViewController.swift in Sources */,
+ 1A000067000000000000000A /* Logger.swift in Sources */,
+ 1A0000B7000000000000000A /* OmacyCanaryAnimator.swift in Sources */,
+ 1A0000A1000000000000000A /* OmacyRenderer.swift in Sources */,
+ 1A0000A3000000000000000A /* OmacyLayout.swift in Sources */,
+ 1A0000A5000000000000000A /* OmacyStore.swift in Sources */,
+ 1A0000A7000000000000000A /* OmacyAtlas.swift in Sources */,
+ 1A0000A9000000000000000A /* OmacyShaders.metal in Sources */,
+ );
+ runOnlyForDeploymentPostprocessing = 0;
+ };
+/* End PBXSourcesBuildPhase section */
+
+/* Begin PBXTargetDependency section */
+ 1A00001E000000000000000A /* PBXTargetDependency */ = {
+ isa = PBXTargetDependency;
+ target = 1A000010000000000000000A /* OmacyScreensaver */;
+ targetProxy = 1A000008000000000000000A /* PBXContainerItemProxy */;
+ };
+/* End PBXTargetDependency section */
+
+/* Begin XCBuildConfiguration section */
+ 1A000023000000000000000A /* Debug */ = {
+ isa = XCBuildConfiguration;
+ baseConfigurationReference = 1A000050000000000000000B /* BuildNumber.xcconfig */;
+ buildSettings = {
+ ALWAYS_SEARCH_USER_PATHS = NO;
+ ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
+ CLANG_ANALYZER_NONNULL = YES;
+ CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+ CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
+ CLANG_ENABLE_MODULES = YES;
+ CLANG_ENABLE_OBJC_ARC = YES;
+ CLANG_ENABLE_OBJC_WEAK = YES;
+ CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+ CLANG_WARN_BOOL_CONVERSION = YES;
+ CLANG_WARN_COMMA = YES;
+ CLANG_WARN_CONSTANT_CONVERSION = YES;
+ CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+ CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+ CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+ CLANG_WARN_EMPTY_BODY = YES;
+ CLANG_WARN_ENUM_CONVERSION = YES;
+ CLANG_WARN_INFINITE_RECURSION = YES;
+ CLANG_WARN_INT_CONVERSION = YES;
+ CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+ CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+ CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+ CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+ CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+ CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+ CLANG_WARN_STRICT_PROTOTYPES = YES;
+ CLANG_WARN_SUSPICIOUS_MOVE = YES;
+ CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+ CLANG_WARN_UNREACHABLE_CODE = YES;
+ CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+ COPY_PHASE_STRIP = NO;
+ DEBUG_INFORMATION_FORMAT = dwarf;
+ ENABLE_STRICT_OBJC_MSGSEND = YES;
+ ENABLE_TESTABILITY = YES;
+ ENABLE_USER_SCRIPT_SANDBOXING = NO;
+ GCC_C_LANGUAGE_STANDARD = gnu17;
+ GCC_DYNAMIC_NO_PIC = NO;
+ GCC_NO_COMMON_BLOCKS = YES;
+ GCC_OPTIMIZATION_LEVEL = 0;
+ GCC_PREPROCESSOR_DEFINITIONS = (
+ "DEBUG=1",
+ "$(inherited)",
+ );
+ GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+ GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+ GCC_WARN_UNDECLARED_SELECTOR = YES;
+ GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+ GCC_WARN_UNUSED_FUNCTION = YES;
+ GCC_WARN_UNUSED_VARIABLE = YES;
+ LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
+ MACOSX_DEPLOYMENT_TARGET = 15.0;
+ MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
+ MTL_FAST_MATH = YES;
+ ONLY_ACTIVE_ARCH = YES;
+ SDKROOT = macosx;
+ SWIFT_ACTIVE_COMPILATION_CONDITIONS = "DEBUG $(inherited)";
+ SWIFT_OPTIMIZATION_LEVEL = "-Onone";
+ };
+ name = Debug;
+ };
+ 1A000024000000000000000A /* Release */ = {
+ isa = XCBuildConfiguration;
+ baseConfigurationReference = 1A000050000000000000000B /* BuildNumber.xcconfig */;
+ buildSettings = {
+ ALWAYS_SEARCH_USER_PATHS = NO;
+ ASSETCATALOG_COMPILER_GENERATE_SWIFT_ASSET_SYMBOL_EXTENSIONS = YES;
+ CLANG_ANALYZER_NONNULL = YES;
+ CLANG_ANALYZER_NUMBER_OBJECT_CONVERSION = YES_AGGRESSIVE;
+ CLANG_CXX_LANGUAGE_STANDARD = "gnu++20";
+ CLANG_ENABLE_MODULES = YES;
+ CLANG_ENABLE_OBJC_ARC = YES;
+ CLANG_ENABLE_OBJC_WEAK = YES;
+ CLANG_WARN_BLOCK_CAPTURE_AUTORELEASING = YES;
+ CLANG_WARN_BOOL_CONVERSION = YES;
+ CLANG_WARN_COMMA = YES;
+ CLANG_WARN_CONSTANT_CONVERSION = YES;
+ CLANG_WARN_DEPRECATED_OBJC_IMPLEMENTATIONS = YES;
+ CLANG_WARN_DIRECT_OBJC_ISA_USAGE = YES_ERROR;
+ CLANG_WARN_DOCUMENTATION_COMMENTS = YES;
+ CLANG_WARN_EMPTY_BODY = YES;
+ CLANG_WARN_ENUM_CONVERSION = YES;
+ CLANG_WARN_INFINITE_RECURSION = YES;
+ CLANG_WARN_INT_CONVERSION = YES;
+ CLANG_WARN_NON_LITERAL_NULL_CONVERSION = YES;
+ CLANG_WARN_OBJC_IMPLICIT_RETAIN_SELF = YES;
+ CLANG_WARN_OBJC_LITERAL_CONVERSION = YES;
+ CLANG_WARN_OBJC_ROOT_CLASS = YES_ERROR;
+ CLANG_WARN_QUOTED_INCLUDE_IN_FRAMEWORK_HEADER = YES;
+ CLANG_WARN_RANGE_LOOP_ANALYSIS = YES;
+ CLANG_WARN_STRICT_PROTOTYPES = YES;
+ CLANG_WARN_SUSPICIOUS_MOVE = YES;
+ CLANG_WARN_UNGUARDED_AVAILABILITY = YES_AGGRESSIVE;
+ CLANG_WARN_UNREACHABLE_CODE = YES;
+ CLANG_WARN__DUPLICATE_METHOD_MATCH = YES;
+ COPY_PHASE_STRIP = NO;
+ DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
+ ENABLE_NS_ASSERTIONS = NO;
+ ENABLE_STRICT_OBJC_MSGSEND = YES;
+ ENABLE_USER_SCRIPT_SANDBOXING = NO;
+ GCC_C_LANGUAGE_STANDARD = gnu17;
+ GCC_NO_COMMON_BLOCKS = YES;
+ GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
+ GCC_WARN_ABOUT_RETURN_TYPE = YES_ERROR;
+ GCC_WARN_UNDECLARED_SELECTOR = YES;
+ GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
+ GCC_WARN_UNUSED_FUNCTION = YES;
+ GCC_WARN_UNUSED_VARIABLE = YES;
+ LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
+ MACOSX_DEPLOYMENT_TARGET = 15.0;
+ MTL_ENABLE_DEBUG_INFO = NO;
+ MTL_FAST_MATH = YES;
+ SDKROOT = macosx;
+ SWIFT_COMPILATION_MODE = wholemodule;
+ };
+ name = Release;
+ };
+ 1A000025000000000000000A /* Debug */ = {
+ isa = XCBuildConfiguration;
+ buildSettings = {
+ ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+ ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+ CODE_SIGN_ENTITLEMENTS = Omacy/Omacy.entitlements;
+ CODE_SIGN_STYLE = Automatic;
+ COMBINE_HIDPI_IMAGES = YES;
+ DEVELOPMENT_TEAM = 25TVW8MSGJ;
+ ENABLE_HARDENED_RUNTIME = YES;
+ ENABLE_USER_SCRIPT_SANDBOXING = NO;
+ GENERATE_INFOPLIST_FILE = NO;
+ INFOPLIST_FILE = Omacy/Info.plist;
+ INFOPLIST_KEY_NSHumanReadableCopyright = "";
+ INFOPLIST_KEY_NSPrincipalClass = NSApplication;
+ LD_RUNPATH_SEARCH_PATHS = (
+ "$(inherited)",
+ "@executable_path/../Frameworks",
+ );
+ MARKETING_VERSION = 1.0;
+ PRODUCT_BUNDLE_IDENTIFIER = be.zenjoy.omacy;
+ PRODUCT_NAME = "$(TARGET_NAME)";
+ HEADER_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(SRCROOT)/OmacyScreensaver",
+ "$(SRCROOT)/../../crates/omacy-engine/include",
+ );
+ LIBRARY_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(BUILT_PRODUCTS_DIR)",
+ );
+ OTHER_LDFLAGS = (
+ "$(inherited)",
+ "-lc++",
+ "-framework",
+ Security,
+ "-framework",
+ CoreFoundation,
+ "-framework",
+ SystemConfiguration,
+ );
+ SWIFT_EMIT_LOC_STRINGS = YES;
+ SWIFT_OBJC_BRIDGING_HEADER = "Omacy/Omacy-Bridging-Header.h";
+ SWIFT_VERSION = 5.0;
+ };
+ name = Debug;
+ };
+ 1A000026000000000000000A /* Release */ = {
+ isa = XCBuildConfiguration;
+ buildSettings = {
+ ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+ ASSETCATALOG_COMPILER_GLOBAL_ACCENT_COLOR_NAME = AccentColor;
+ CODE_SIGN_ENTITLEMENTS = Omacy/Omacy.entitlements;
+ CODE_SIGN_IDENTITY = "Developer ID Application";
+ CODE_SIGN_STYLE = Manual;
+ COMBINE_HIDPI_IMAGES = YES;
+ DEVELOPMENT_TEAM = 25TVW8MSGJ;
+ ENABLE_HARDENED_RUNTIME = YES;
+ PROVISIONING_PROFILE_SPECIFIER = "match Direct be.zenjoy.omacy macos";
+ ENABLE_USER_SCRIPT_SANDBOXING = NO;
+ GENERATE_INFOPLIST_FILE = NO;
+ INFOPLIST_FILE = Omacy/Info.plist;
+ INFOPLIST_KEY_NSHumanReadableCopyright = "";
+ INFOPLIST_KEY_NSPrincipalClass = NSApplication;
+ LD_RUNPATH_SEARCH_PATHS = (
+ "$(inherited)",
+ "@executable_path/../Frameworks",
+ );
+ MARKETING_VERSION = 1.0;
+ PRODUCT_BUNDLE_IDENTIFIER = be.zenjoy.omacy;
+ PRODUCT_NAME = "$(TARGET_NAME)";
+ HEADER_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(SRCROOT)/OmacyScreensaver",
+ "$(SRCROOT)/../../crates/omacy-engine/include",
+ );
+ LIBRARY_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(BUILT_PRODUCTS_DIR)",
+ );
+ OTHER_LDFLAGS = (
+ "$(inherited)",
+ "-lc++",
+ "-framework",
+ Security,
+ "-framework",
+ CoreFoundation,
+ "-framework",
+ SystemConfiguration,
+ );
+ SWIFT_EMIT_LOC_STRINGS = YES;
+ SWIFT_OBJC_BRIDGING_HEADER = "Omacy/Omacy-Bridging-Header.h";
+ SWIFT_VERSION = 5.0;
+ };
+ name = Release;
+ };
+ 1A000027000000000000000A /* Debug */ = {
+ isa = XCBuildConfiguration;
+ buildSettings = {
+ CODE_SIGN_ENTITLEMENTS = OmacyScreensaver/OmacyScreensaver.entitlements;
+ CODE_SIGN_STYLE = Automatic;
+ DEVELOPMENT_TEAM = 25TVW8MSGJ;
+ ENABLE_APP_SANDBOX = YES;
+ ENABLE_HARDENED_RUNTIME = YES;
+ ENABLE_INCOMING_NETWORK_CONNECTIONS = YES;
+ ENABLE_OUTGOING_NETWORK_CONNECTIONS = YES;
+ ENABLE_RESOURCE_ACCESS_AUDIO_INPUT = NO;
+ ENABLE_RESOURCE_ACCESS_BLUETOOTH = NO;
+ ENABLE_RESOURCE_ACCESS_CALENDARS = NO;
+ ENABLE_RESOURCE_ACCESS_CAMERA = NO;
+ ENABLE_RESOURCE_ACCESS_CONTACTS = NO;
+ ENABLE_RESOURCE_ACCESS_LOCATION = NO;
+ ENABLE_RESOURCE_ACCESS_PRINTING = NO;
+ ENABLE_RESOURCE_ACCESS_USB = NO;
+ ENABLE_USER_SCRIPT_SANDBOXING = NO;
+ GENERATE_INFOPLIST_FILE = NO;
+ INFOPLIST_FILE = OmacyScreensaver/Info.plist;
+ INFOPLIST_KEY_CFBundleDisplayName = Omacy;
+ INFOPLIST_KEY_NSHumanReadableCopyright = "";
+ LD_RUNPATH_SEARCH_PATHS = (
+ "$(inherited)",
+ "@executable_path/../Frameworks",
+ "@executable_path/../../../../Frameworks",
+ );
+ MARKETING_VERSION = 1.0;
+ PRODUCT_BUNDLE_IDENTIFIER = be.zenjoy.omacy.screensaver;
+ PRODUCT_NAME = "$(TARGET_NAME)";
+ SKIP_INSTALL = YES;
+ HEADER_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(SRCROOT)/OmacyScreensaver",
+ "$(SRCROOT)/../../crates/omacy-engine/include",
+ );
+ LIBRARY_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(BUILT_PRODUCTS_DIR)",
+ );
+ OTHER_LDFLAGS = (
+ "$(inherited)",
+ "-lc++",
+ "-framework",
+ Security,
+ "-framework",
+ CoreFoundation,
+ "-framework",
+ SystemConfiguration,
+ );
+ SWIFT_EMIT_LOC_STRINGS = YES;
+ SWIFT_OBJC_BRIDGING_HEADER = "OmacyScreensaver/OmacyScreensaver-Bridging-Header.h";
+ SWIFT_VERSION = 5.0;
+ };
+ name = Debug;
+ };
+ 1A000028000000000000000A /* Release */ = {
+ isa = XCBuildConfiguration;
+ buildSettings = {
+ CODE_SIGN_ENTITLEMENTS = OmacyScreensaver/OmacyScreensaver.entitlements;
+ CODE_SIGN_IDENTITY = "Developer ID Application";
+ CODE_SIGN_STYLE = Manual;
+ DEVELOPMENT_TEAM = 25TVW8MSGJ;
+ ENABLE_APP_SANDBOX = YES;
+ ENABLE_HARDENED_RUNTIME = YES;
+ PROVISIONING_PROFILE_SPECIFIER = "match Direct be.zenjoy.omacy.screensaver macos";
+ ENABLE_INCOMING_NETWORK_CONNECTIONS = YES;
+ ENABLE_OUTGOING_NETWORK_CONNECTIONS = YES;
+ ENABLE_RESOURCE_ACCESS_AUDIO_INPUT = NO;
+ ENABLE_RESOURCE_ACCESS_BLUETOOTH = NO;
+ ENABLE_RESOURCE_ACCESS_CALENDARS = NO;
+ ENABLE_RESOURCE_ACCESS_CAMERA = NO;
+ ENABLE_RESOURCE_ACCESS_CONTACTS = NO;
+ ENABLE_RESOURCE_ACCESS_LOCATION = NO;
+ ENABLE_RESOURCE_ACCESS_PRINTING = NO;
+ ENABLE_RESOURCE_ACCESS_USB = NO;
+ ENABLE_USER_SCRIPT_SANDBOXING = NO;
+ GENERATE_INFOPLIST_FILE = NO;
+ INFOPLIST_FILE = OmacyScreensaver/Info.plist;
+ INFOPLIST_KEY_CFBundleDisplayName = Omacy;
+ INFOPLIST_KEY_NSHumanReadableCopyright = "";
+ LD_RUNPATH_SEARCH_PATHS = (
+ "$(inherited)",
+ "@executable_path/../Frameworks",
+ "@executable_path/../../../../Frameworks",
+ );
+ MARKETING_VERSION = 1.0;
+ PRODUCT_BUNDLE_IDENTIFIER = be.zenjoy.omacy.screensaver;
+ PRODUCT_NAME = "$(TARGET_NAME)";
+ SKIP_INSTALL = YES;
+ HEADER_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(SRCROOT)/OmacyScreensaver",
+ "$(SRCROOT)/../../crates/omacy-engine/include",
+ );
+ LIBRARY_SEARCH_PATHS = (
+ "$(inherited)",
+ "$(BUILT_PRODUCTS_DIR)",
+ );
+ OTHER_LDFLAGS = (
+ "$(inherited)",
+ "-lc++",
+ "-framework",
+ Security,
+ "-framework",
+ CoreFoundation,
+ "-framework",
+ SystemConfiguration,
+ );
+ SWIFT_EMIT_LOC_STRINGS = YES;
+ SWIFT_OBJC_BRIDGING_HEADER = "OmacyScreensaver/OmacyScreensaver-Bridging-Header.h";
+ SWIFT_VERSION = 5.0;
+ };
+ name = Release;
+ };
+/* End XCBuildConfiguration section */
+
+/* Begin XCConfigurationList section */
+ 1A00001B000000000000000A /* Build configuration list for PBXNativeTarget "Omacy" */ = {
+ isa = XCConfigurationList;
+ buildConfigurations = (
+ 1A000025000000000000000A /* Debug */,
+ 1A000026000000000000000A /* Release */,
+ );
+ defaultConfigurationIsVisible = 0;
+ defaultConfigurationName = Release;
+ };
+ 1A00001F000000000000000A /* Build configuration list for PBXNativeTarget "OmacyScreensaver" */ = {
+ isa = XCConfigurationList;
+ buildConfigurations = (
+ 1A000027000000000000000A /* Debug */,
+ 1A000028000000000000000A /* Release */,
+ );
+ defaultConfigurationIsVisible = 0;
+ defaultConfigurationName = Release;
+ };
+ 1A000022000000000000000A /* Build configuration list for PBXProject "Omacy" */ = {
+ isa = XCConfigurationList;
+ buildConfigurations = (
+ 1A000023000000000000000A /* Debug */,
+ 1A000024000000000000000A /* Release */,
+ );
+ defaultConfigurationIsVisible = 0;
+ defaultConfigurationName = Release;
+ };
+/* End XCConfigurationList section */
+
+/* Begin XCRemoteSwiftPackageReference section */
+ 1A000071000000000000000A /* XCRemoteSwiftPackageReference "PaperSaver" */ = {
+ isa = XCRemoteSwiftPackageReference;
+ repositoryURL = "https://github.com/AerialScreensaver/PaperSaver.git";
+ requirement = {
+ kind = exactVersion;
+ version = 0.2.0;
+ };
+ };
+/* End XCRemoteSwiftPackageReference section */
+
+/* Begin XCSwiftPackageProductDependency section */
+ 1A000070000000000000000B /* PaperSaverKit */ = {
+ isa = XCSwiftPackageProductDependency;
+ package = 1A000071000000000000000A /* XCRemoteSwiftPackageReference "PaperSaver" */;
+ productName = PaperSaverKit;
+ };
+/* End XCSwiftPackageProductDependency section */
+ };
+ rootObject = 1A000000000000000000000A /* Project object */;
+}
diff --git a/apps/Omacy/Omacy.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved b/apps/Omacy/Omacy.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
new file mode 100644
index 0000000..86faf97
--- /dev/null
+++ b/apps/Omacy/Omacy.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved
@@ -0,0 +1,24 @@
+{
+ "originHash" : "58d483173683d9748f852a167c8263542e3ef789aabcff2c1cc4cc0b5dad32d0",
+ "pins" : [
+ {
+ "identity" : "papersaver",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/AerialScreensaver/PaperSaver.git",
+ "state" : {
+ "revision" : "1f10d1537fdfa2df8165b46572a9de491ce2d084",
+ "version" : "0.2.0"
+ }
+ },
+ {
+ "identity" : "swift-argument-parser",
+ "kind" : "remoteSourceControl",
+ "location" : "https://github.com/apple/swift-argument-parser",
+ "state" : {
+ "revision" : "c5d11a805e765f52ba34ec7284bd4fcd6ba68615",
+ "version" : "1.7.0"
+ }
+ }
+ ],
+ "version" : 3
+}
diff --git a/apps/Omacy/Omacy.xcodeproj/xcshareddata/xcschemes/Omacy.xcscheme b/apps/Omacy/Omacy.xcodeproj/xcshareddata/xcschemes/Omacy.xcscheme
new file mode 100644
index 0000000..0fc50e2
--- /dev/null
+++ b/apps/Omacy/Omacy.xcodeproj/xcshareddata/xcschemes/Omacy.xcscheme
@@ -0,0 +1,95 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/apps/Omacy/Omacy.xcodeproj/xcshareddata/xcschemes/OmacyScreensaver.xcscheme b/apps/Omacy/Omacy.xcodeproj/xcshareddata/xcschemes/OmacyScreensaver.xcscheme
new file mode 100644
index 0000000..18f4515
--- /dev/null
+++ b/apps/Omacy/Omacy.xcodeproj/xcshareddata/xcschemes/OmacyScreensaver.xcscheme
@@ -0,0 +1,73 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AccentColor.colorset/Contents.json b/apps/Omacy/Omacy/Assets.xcassets/AccentColor.colorset/Contents.json
new file mode 100644
index 0000000..2b75839
--- /dev/null
+++ b/apps/Omacy/Omacy/Assets.xcassets/AccentColor.colorset/Contents.json
@@ -0,0 +1,20 @@
+{
+ "colors" : [
+ {
+ "color" : {
+ "color-space" : "srgb",
+ "components" : {
+ "alpha" : "1.000",
+ "blue" : "0.949",
+ "green" : "0.451",
+ "red" : "0.149"
+ }
+ },
+ "idiom" : "universal"
+ }
+ ],
+ "info" : {
+ "author" : "xcode",
+ "version" : 1
+ }
+}
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/Contents.json b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/Contents.json
new file mode 100644
index 0000000..e8aaf0c
--- /dev/null
+++ b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/Contents.json
@@ -0,0 +1,18 @@
+{
+ "images" : [
+ { "idiom" : "mac", "size" : "16x16", "scale" : "1x", "filename" : "icon_16.png" },
+ { "idiom" : "mac", "size" : "16x16", "scale" : "2x", "filename" : "icon_32.png" },
+ { "idiom" : "mac", "size" : "32x32", "scale" : "1x", "filename" : "icon_32.png" },
+ { "idiom" : "mac", "size" : "32x32", "scale" : "2x", "filename" : "icon_64.png" },
+ { "idiom" : "mac", "size" : "128x128", "scale" : "1x", "filename" : "icon_128.png" },
+ { "idiom" : "mac", "size" : "128x128", "scale" : "2x", "filename" : "icon_256.png" },
+ { "idiom" : "mac", "size" : "256x256", "scale" : "1x", "filename" : "icon_256.png" },
+ { "idiom" : "mac", "size" : "256x256", "scale" : "2x", "filename" : "icon_512.png" },
+ { "idiom" : "mac", "size" : "512x512", "scale" : "1x", "filename" : "icon_512.png" },
+ { "idiom" : "mac", "size" : "512x512", "scale" : "2x", "filename" : "icon_1024.png" }
+ ],
+ "info" : {
+ "author" : "xcode",
+ "version" : 1
+ }
+}
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_1024.png b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_1024.png
new file mode 100644
index 0000000..94ee268
Binary files /dev/null and b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_1024.png differ
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_128.png b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_128.png
new file mode 100644
index 0000000..ba2ad9c
Binary files /dev/null and b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_128.png differ
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_16.png b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_16.png
new file mode 100644
index 0000000..65cbaee
Binary files /dev/null and b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_16.png differ
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_256.png b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_256.png
new file mode 100644
index 0000000..44e1d5d
Binary files /dev/null and b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_256.png differ
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_32.png b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_32.png
new file mode 100644
index 0000000..fea4966
Binary files /dev/null and b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_32.png differ
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_512.png b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_512.png
new file mode 100644
index 0000000..ddb4716
Binary files /dev/null and b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_512.png differ
diff --git a/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_64.png b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_64.png
new file mode 100644
index 0000000..d9f115b
Binary files /dev/null and b/apps/Omacy/Omacy/Assets.xcassets/AppIcon.appiconset/icon_64.png differ
diff --git a/apps/Omacy/Omacy/Assets.xcassets/Contents.json b/apps/Omacy/Omacy/Assets.xcassets/Contents.json
new file mode 100644
index 0000000..73c0059
--- /dev/null
+++ b/apps/Omacy/Omacy/Assets.xcassets/Contents.json
@@ -0,0 +1,6 @@
+{
+ "info" : {
+ "author" : "xcode",
+ "version" : 1
+ }
+}
diff --git a/apps/Omacy/Omacy/ConfigView.swift b/apps/Omacy/Omacy/ConfigView.swift
new file mode 100644
index 0000000..66b0589
--- /dev/null
+++ b/apps/Omacy/Omacy/ConfigView.swift
@@ -0,0 +1,130 @@
+import SwiftUI
+import UniformTypeIdentifiers
+
+struct ConfigView: View {
+ @State private var settings = OmacyStore.loadSettings()
+ @State private var art = OmacyStore.loadArt()
+ @State private var status = "Ready"
+ @State private var importer = false
+
+ var body: some View {
+ Form {
+ Section("Art") {
+ TextEditor(text: $art)
+ .font(.system(.body, design: .monospaced))
+ .frame(minHeight: 160)
+ HStack {
+ Button("Restore default wordmark") {
+ art = OmacyStore.bundledArt
+ persist()
+ }
+ Button("Open PNG or SVG…") { importer = true }
+ }
+ }
+ Section("Effect") {
+ TextField("random or ttfx name", text: $settings.effect)
+ ColorPicker(
+ "Background",
+ selection: Binding(
+ get: { color(from: settings.background) },
+ set: { settings.background = hex(from: $0) }
+ ),
+ supportsOpacity: false
+ )
+ }
+ Section("Conversion") {
+ Picker("Mode", selection: $settings.asciiMode) {
+ Text("Braille").tag("braille")
+ Text("Block").tag("block")
+ }
+ Stepper("Threshold \(settings.threshold)%", value: $settings.threshold, in: 0...100)
+ Toggle("Invert", isOn: $settings.invert)
+ }
+ Section("Type") {
+ Stepper("Font size \(Int(settings.fontSize)) pt", value: $settings.fontSize, in: 8...48)
+ }
+ Section("About") {
+ Text("Effects by Terminal Text Effects (ChrisBuilds), Rust engine ttfx.")
+ .font(.caption)
+ .foregroundStyle(.secondary)
+ }
+ if let error = OmacyStore.lastLoadError {
+ Text(error).font(.caption).foregroundStyle(.red)
+ }
+ Text(status).font(.caption).foregroundStyle(.secondary)
+ Button("Save") { persist() }
+ .keyboardShortcut(.defaultAction)
+ }
+ .padding()
+ .frame(minWidth: 520, minHeight: 560)
+ .fileImporter(isPresented: $importer, allowedContentTypes: [.png, UTType(filenameExtension: "svg") ?? .xml]) { result in
+ switch result {
+ case .success(let url):
+ convert(url)
+ case .failure(let error):
+ status = error.localizedDescription
+ }
+ }
+ }
+
+ private func persist() {
+ do {
+ try OmacyStore.save(settings: settings, art: art)
+ status = "Saved to App Group"
+ } catch {
+ status = error.localizedDescription
+ }
+ }
+
+ private func convert(_ url: URL) {
+ guard url.startAccessingSecurityScopedResource() else {
+ status = "Could not read file"
+ return
+ }
+ defer { url.stopAccessingSecurityScopedResource() }
+ guard let data = try? Data(contentsOf: url) else {
+ status = "Could not read file"
+ return
+ }
+ var cfg = OmacyAsciiConfig()
+ cfg.mode = settings.asciiModeCode
+ cfg.width = 80
+ cfg.height = 26
+ cfg.threshold = UInt8(settings.threshold)
+ cfg.invert = settings.invert ? 1 : 0
+ cfg.trim = 1
+ var text: OpaquePointer?
+ let statusCode = data.withUnsafeBytes { raw in
+ omacy_ascii_from_bytes(&cfg, raw.bindMemory(to: UInt8.self).baseAddress, data.count, &text)
+ }
+ defer { omacy_text_free(text) }
+ guard statusCode == OMACY_OK, let text, let ptr = omacy_text_utf8(text) else {
+ status = "Conversion failed"
+ return
+ }
+ let n = omacy_text_len(text)
+ art = String(bytes: UnsafeBufferPointer(start: ptr, count: n).map { UInt8(bitPattern: $0) }, encoding: .utf8) ?? art
+ persist()
+ }
+
+ private func color(from hex: String) -> Color {
+ let t = hex.trimmingCharacters(in: CharacterSet(charactersIn: "#"))
+ guard t.count == 6, let n = UInt32(t, radix: 16) else { return .black }
+ return Color(
+ red: Double((n >> 16) & 0xFF) / 255,
+ green: Double((n >> 8) & 0xFF) / 255,
+ blue: Double(n & 0xFF) / 255
+ )
+ }
+
+ private func hex(from color: Color) -> String {
+ let ns = NSColor(color)
+ guard let rgb = ns.usingColorSpace(.sRGB) else { return "#000000" }
+ return String(
+ format: "#%02X%02X%02X",
+ Int(rgb.redComponent * 255),
+ Int(rgb.greenComponent * 255),
+ Int(rgb.blueComponent * 255)
+ )
+ }
+}
diff --git a/apps/Omacy/Omacy/ContentView.swift b/apps/Omacy/Omacy/ContentView.swift
new file mode 100644
index 0000000..8227970
--- /dev/null
+++ b/apps/Omacy/Omacy/ContentView.swift
@@ -0,0 +1,292 @@
+//
+// ContentView.swift
+// Omacy
+//
+// Copyright © 2026 Guillaume Louel. Licensed under the MIT License.
+//
+// Main view for the host application. Shows extension registration status
+// and provides install / uninstall and "set as active screensaver" actions.
+//
+
+import SwiftUI
+
+private let logger = AppexLog.logger("HostApp")
+
+struct ContentView: View {
+ @Environment(\.openWindow) private var openWindow
+ @StateObject private var pluginManager = PluginManager()
+ @State private var statusMessage = "Ready"
+
+ var body: some View {
+ VStack(spacing: 20) {
+ // MARK: - Header
+ Image(systemName: "tv")
+ .font(.system(size: 60))
+ .foregroundColor(.accentColor)
+
+ Text("Omacy")
+ .font(.largeTitle)
+ .fontWeight(.bold)
+
+ Text("Screensaver Extension")
+ .font(.title2)
+ .foregroundColor(.secondary)
+
+ Divider()
+ .padding(.horizontal, 40)
+
+ // MARK: - Extension Status
+ Text("Extension Status")
+ .font(.headline)
+
+ extensionStatusView
+ .padding(.horizontal, 20)
+
+ Divider()
+ .padding(.horizontal, 40)
+
+ // MARK: - Screensaver Activation
+ Text("Screensaver Activation")
+ .font(.headline)
+
+ screensaverActivationView
+ .padding(.horizontal, 20)
+
+ Divider()
+ .padding(.horizontal, 40)
+
+ // MARK: - Actions
+ HStack(spacing: 12) {
+ Button("Open Preview") {
+ openWindow(id: "preview")
+ }
+ .buttonStyle(.borderedProminent)
+
+ Button("Edit art") {
+ openWindow(id: "config")
+ }
+ .buttonStyle(.bordered)
+
+ Button("Open Screen Saver Settings") {
+ openScreenSaverSettings()
+ }
+ .buttonStyle(.bordered)
+ }
+
+ Text(statusMessage)
+ .font(.caption)
+ .foregroundColor(.secondary)
+ .padding(.top, 10)
+ .frame(maxWidth: .infinity)
+ .multilineTextAlignment(.center)
+
+ Text("Effects by Terminal Text Effects (ChrisBuilds), Rust engine ttfx.")
+ .font(.caption2)
+ .foregroundColor(.secondary)
+ .multilineTextAlignment(.center)
+ }
+ .padding(40)
+ .fixedSize()
+ }
+
+ @ViewBuilder
+ private var extensionStatusView: some View {
+ GroupBox {
+ VStack(alignment: .leading, spacing: 12) {
+ HStack {
+ Circle()
+ .fill(pluginManager.isInstalled ? Color.green : Color.gray)
+ .frame(width: 10, height: 10)
+
+ if pluginManager.isInstalled {
+ Text("Installed")
+ .fontWeight(.medium)
+ if let version = pluginManager.installedVersion {
+ Text("(v\(version))")
+ .foregroundColor(.secondary)
+ }
+ } else {
+ Text("Not registered")
+ .fontWeight(.medium)
+ .foregroundColor(.secondary)
+ }
+
+ Spacer()
+
+ if pluginManager.isLoading {
+ ProgressView()
+ .scaleEffect(0.7)
+ } else {
+ Button {
+ pluginManager.checkInstallationStatus()
+ } label: {
+ Image(systemName: "arrow.clockwise")
+ }
+ .buttonStyle(.borderless)
+ .help("Refresh status")
+ }
+ }
+
+ if pluginManager.isInstalled {
+ if pluginManager.isPluginMissing {
+ Text("The registered screensaver extension is missing. Re-register it from this app.")
+ .font(.caption)
+ .foregroundColor(.orange)
+ }
+ if let path = pluginManager.installedPath {
+ HStack(alignment: .top) {
+ Text("Path:")
+ .foregroundColor(.secondary)
+ Text(path)
+ .lineLimit(2)
+ .truncationMode(.middle)
+ .textSelection(.enabled)
+ }
+ .font(.caption)
+ }
+ if pluginManager.hasConflictingRegistrations {
+ Text("Registered in more than one place. Unregister extras so only /Applications or DerivedData remains.")
+ .font(.caption)
+ .foregroundColor(.orange)
+ ForEach(pluginManager.registeredPaths, id: \.self) { path in
+ Text(path)
+ .font(.caption2)
+ .lineLimit(2)
+ .truncationMode(.middle)
+ .textSelection(.enabled)
+ }
+ }
+ } else {
+ Text("Omacy is not in System Settings yet. Register the extension from this app — the preview still runs either way.")
+ .font(.caption)
+ .foregroundColor(.secondary)
+ if let embeddedVersion = pluginManager.embeddedVersion {
+ Text("Embedded version: \(embeddedVersion)")
+ .font(.caption)
+ .foregroundColor(.secondary)
+ }
+ }
+
+ if let error = pluginManager.lastError {
+ Text(error)
+ .font(.caption)
+ .foregroundColor(.red)
+ }
+
+ HStack {
+ Spacer()
+ if pluginManager.isInstalled && !pluginManager.isPluginMissing {
+ Button("Uninstall") {
+ uninstallExtension()
+ }
+ .buttonStyle(.bordered)
+ .disabled(pluginManager.isLoading)
+ } else {
+ Button(pluginManager.isPluginMissing ? "Re-register" : "Install") {
+ installExtension()
+ }
+ .buttonStyle(.borderedProminent)
+ .disabled(pluginManager.isLoading)
+ }
+ Spacer()
+ }
+ .padding(.top, 4)
+ }
+ .padding(8)
+ }
+ }
+
+ @ViewBuilder
+ private var screensaverActivationView: some View {
+ GroupBox {
+ VStack(alignment: .leading, spacing: 12) {
+ HStack {
+ Circle()
+ .fill(pluginManager.isActiveScreensaver ? Color.green : Color.gray)
+ .frame(width: 10, height: 10)
+
+ if pluginManager.isActiveScreensaver {
+ Text("Active")
+ .fontWeight(.medium)
+ } else {
+ Text("Not Active")
+ .fontWeight(.medium)
+ .foregroundColor(.secondary)
+ }
+
+ Spacer()
+
+ if pluginManager.isCheckingScreensaver {
+ ProgressView()
+ .scaleEffect(0.7)
+ } else {
+ Button {
+ pluginManager.checkScreensaverStatus()
+ } label: {
+ Image(systemName: "arrow.clockwise")
+ }
+ .buttonStyle(.borderless)
+ .help("Refresh status")
+ }
+ }
+
+ if let error = pluginManager.screensaverError {
+ Text(error)
+ .font(.caption)
+ .foregroundColor(.red)
+ }
+
+ if pluginManager.isInstalled && !pluginManager.isActiveScreensaver {
+ HStack {
+ Spacer()
+ Button("Enable as Screensaver") {
+ Task {
+ await pluginManager.enableAsScreensaver()
+ }
+ }
+ .buttonStyle(.borderedProminent)
+ .disabled(pluginManager.isCheckingScreensaver)
+ Spacer()
+ }
+ .padding(.top, 4)
+ }
+ }
+ .padding(8)
+ }
+ }
+
+ private func installExtension() {
+ statusMessage = "Installing extension..."
+ do {
+ try pluginManager.install()
+ statusMessage = "Extension installed successfully"
+ } catch {
+ statusMessage = "Install failed: \(error.localizedDescription)"
+ logger.error("Install failed: \(error.localizedDescription, privacy: .public)")
+ }
+ }
+
+ private func uninstallExtension() {
+ statusMessage = "Uninstalling extension..."
+ do {
+ try pluginManager.uninstall()
+ statusMessage = "Unregistered. Move Omacy to Trash to finish removing it. You can also delete the App Group data if you want a clean slate."
+ } catch {
+ statusMessage = "Uninstall failed: \(error.localizedDescription)"
+ logger.error("Uninstall failed: \(error.localizedDescription, privacy: .public)")
+ }
+ }
+
+ private func openScreenSaverSettings() {
+ // Tahoe keeps Screen Saver as a sheet on Wallpaper. The old
+ // ScreenSaver-Settings.extension URL no longer opens that pane.
+ guard let url = URL(string: "x-apple.systempreferences:com.apple.Wallpaper-Settings.extension?ScreenSaver") else {
+ return
+ }
+ NSWorkspace.shared.open(url)
+ }
+}
+
+#Preview {
+ ContentView()
+}
diff --git a/apps/Omacy/Omacy/Helpers/Logger.swift b/apps/Omacy/Omacy/Helpers/Logger.swift
new file mode 100644
index 0000000..b427f2e
--- /dev/null
+++ b/apps/Omacy/Omacy/Helpers/Logger.swift
@@ -0,0 +1,23 @@
+//
+// Logger.swift
+// Omacy
+//
+// Copyright © 2026 Guillaume Louel. Licensed under the MIT License.
+//
+
+import Foundation
+import os.log
+
+/// Logging configuration shared between the host app and the screensaver extension.
+///
+/// Open Console.app and filter by:
+/// subsystem == "be.zenjoy.omacy"
+/// to see logs from the host app and the appex extension at the same time. Every
+/// log entry's category and PID make it clear which process the line came from.
+enum AppexLog {
+ static let subsystem = "be.zenjoy.omacy"
+
+ static func logger(_ category: String) -> Logger {
+ Logger(subsystem: subsystem, category: category)
+ }
+}
diff --git a/apps/Omacy/Omacy/Info.plist b/apps/Omacy/Omacy/Info.plist
new file mode 100644
index 0000000..2a58fe9
--- /dev/null
+++ b/apps/Omacy/Omacy/Info.plist
@@ -0,0 +1,30 @@
+
+
+
+
+ CFBundleDevelopmentRegion
+ $(DEVELOPMENT_LANGUAGE)
+ CFBundleExecutable
+ $(EXECUTABLE_NAME)
+ CFBundleIconFile
+
+ CFBundleIdentifier
+ $(PRODUCT_BUNDLE_IDENTIFIER)
+ CFBundleInfoDictionaryVersion
+ 6.0
+ CFBundleName
+ $(PRODUCT_NAME)
+ CFBundlePackageType
+ APPL
+ CFBundleShortVersionString
+ 1.0
+ CFBundleVersion
+ $(CURRENT_PROJECT_VERSION)
+ LSMinimumSystemVersion
+ $(MACOSX_DEPLOYMENT_TARGET)
+ NSHumanReadableCopyright
+ Copyright 2026 Peter Dedene. Effects by Terminal Text Effects (ChrisBuilds), Rust engine ttfx.
+ NSPrincipalClass
+ NSApplication
+
+
diff --git a/apps/Omacy/Omacy/Omacy-Bridging-Header.h b/apps/Omacy/Omacy/Omacy-Bridging-Header.h
new file mode 100644
index 0000000..14f23ee
--- /dev/null
+++ b/apps/Omacy/Omacy/Omacy-Bridging-Header.h
@@ -0,0 +1 @@
+#import "omacy.h"
diff --git a/apps/Omacy/Omacy/Omacy.entitlements b/apps/Omacy/Omacy/Omacy.entitlements
new file mode 100644
index 0000000..93243a2
--- /dev/null
+++ b/apps/Omacy/Omacy/Omacy.entitlements
@@ -0,0 +1,10 @@
+
+
+
+
+ com.apple.security.app-groups
+
+ group.be.zenjoy.omacy
+
+
+
diff --git a/apps/Omacy/Omacy/OmacyApp.swift b/apps/Omacy/Omacy/OmacyApp.swift
new file mode 100644
index 0000000..7b96a78
--- /dev/null
+++ b/apps/Omacy/Omacy/OmacyApp.swift
@@ -0,0 +1,21 @@
+import SwiftUI
+
+@main
+struct OmacyApp: App {
+ var body: some Scene {
+ WindowGroup {
+ ContentView()
+ }
+
+ Window("Preview", id: "preview") {
+ PreviewViewRepresentable()
+ .ignoresSafeArea()
+ }
+ .defaultSize(width: 960, height: 600)
+
+ Window("Art", id: "config") {
+ ConfigView()
+ }
+ .defaultSize(width: 560, height: 640)
+ }
+}
diff --git a/apps/Omacy/Omacy/OmacyCanaryAnimator.swift b/apps/Omacy/Omacy/OmacyCanaryAnimator.swift
new file mode 100644
index 0000000..8f1ef6d
--- /dev/null
+++ b/apps/Omacy/Omacy/OmacyCanaryAnimator.swift
@@ -0,0 +1 @@
+// Moved to Shared/OmacyCanaryAnimator.swift
diff --git a/apps/Omacy/Omacy/OmacyHostView.swift b/apps/Omacy/Omacy/OmacyHostView.swift
new file mode 100644
index 0000000..d06f3c6
--- /dev/null
+++ b/apps/Omacy/Omacy/OmacyHostView.swift
@@ -0,0 +1,91 @@
+import AppKit
+
+final class OmacyHostView: NSView {
+ private let renderer = OmacyRenderer()
+ private let canary = OmacyCanaryAnimator()
+ private var usingCanary = false
+ private var observingConfig = false
+
+ override init(frame frameRect: NSRect) {
+ super.init(frame: frameRect)
+ wantsLayer = true
+ renderer.onEngineUnavailable = { [weak self] in
+ self?.switchToCanary()
+ }
+ }
+
+ required init?(coder: NSCoder) {
+ super.init(coder: coder)
+ wantsLayer = true
+ renderer.onEngineUnavailable = { [weak self] in
+ self?.switchToCanary()
+ }
+ }
+
+ override func viewDidMoveToWindow() {
+ super.viewDidMoveToWindow()
+ if window != nil {
+ start()
+ } else {
+ stop()
+ }
+ }
+
+ override func layout() {
+ super.layout()
+ if usingCanary {
+ canary.updateBounds(bounds)
+ } else {
+ renderer.updateGeometry()
+ }
+ }
+
+ func applyPendingConfig() {
+ renderer.applyPendingConfig()
+ }
+
+ private func start() {
+ stop()
+ observeConfig()
+ switch renderer.attach(to: self, isPreview: false) {
+ case .engine:
+ usingCanary = false
+ renderer.start()
+ case .canary:
+ switchToCanary()
+ }
+ }
+
+ private func stop() {
+ renderer.stop()
+ canary.stop()
+ if observingConfig {
+ NotificationCenter.default.removeObserver(self, name: .omacyConfigDidChange, object: nil)
+ observingConfig = false
+ }
+ }
+
+ private func switchToCanary() {
+ usingCanary = true
+ if let layer {
+ canary.attach(to: layer)
+ canary.updateBounds(bounds)
+ }
+ canary.start()
+ }
+
+ private func observeConfig() {
+ guard !observingConfig else { return }
+ NotificationCenter.default.addObserver(
+ self,
+ selector: #selector(configDidChange),
+ name: .omacyConfigDidChange,
+ object: nil
+ )
+ observingConfig = true
+ }
+
+ @objc private func configDidChange() {
+ applyPendingConfig()
+ }
+}
diff --git a/apps/Omacy/Omacy/PluginManager.swift b/apps/Omacy/Omacy/PluginManager.swift
new file mode 100644
index 0000000..d482b35
--- /dev/null
+++ b/apps/Omacy/Omacy/PluginManager.swift
@@ -0,0 +1,272 @@
+//
+// PluginManager.swift
+// Omacy
+//
+// Copyright © 2026 Guillaume Louel. Licensed under the MIT License.
+//
+// Drives extension registration (via pluginkit) and screensaver activation
+// (via PaperSaverKit) from the host app's UI.
+//
+
+import Foundation
+import PaperSaverKit
+
+private let logger = AppexLog.logger("PluginManager")
+
+@MainActor
+class PluginManager: ObservableObject {
+ @Published var isInstalled: Bool = false
+ @Published var installedVersion: String?
+ @Published var installedPath: String?
+ @Published var isLoading: Bool = false
+ @Published var lastError: String?
+ @Published var registeredPaths: [String] = []
+
+ /// Registered with PlugInKit but the appex file is gone.
+ var isPluginMissing: Bool {
+ guard isInstalled else { return false }
+ guard let path = installedPath, !path.isEmpty else { return true }
+ return !FileManager.default.fileExists(atPath: path)
+ }
+
+ /// PlugInKit is sticky if DerivedData and /Applications are both registered.
+ var hasConflictingRegistrations: Bool {
+ registeredPaths.count > 1
+ }
+
+ @Published var isActiveScreensaver: Bool = false
+ @Published var isCheckingScreensaver: Bool = false
+ @Published var screensaverError: String?
+
+ private let bundleIdentifier = "be.zenjoy.omacy.screensaver"
+ private let paperSaver = PaperSaver()
+ private let screensaverDisplayName = "Omacy"
+
+ /// Path to the embedded extension in the app bundle.
+ var embeddedExtensionPath: String? {
+ Bundle.main.builtInPlugInsURL?.appendingPathComponent("OmacyScreensaver.appex").path
+ }
+
+ /// Version of the embedded extension.
+ var embeddedVersion: String? {
+ guard let path = embeddedExtensionPath,
+ let bundle = Bundle(path: path),
+ let version = bundle.infoDictionary?["CFBundleShortVersionString"] as? String else {
+ return nil
+ }
+ return version
+ }
+
+ init() {
+ checkInstallationStatus()
+ checkScreensaverStatus()
+ }
+
+ /// Check if the extension is registered with pluginkit.
+ func checkInstallationStatus() {
+ isLoading = true
+ lastError = nil
+
+ Task {
+ do {
+ let matches = try await queryPluginKit()
+ await MainActor.run {
+ self.registeredPaths = matches.map(\.path).compactMap { $0 }
+ self.isInstalled = !matches.isEmpty
+ self.installedPath = matches.first?.path
+ self.installedVersion = matches.first?.version
+ self.isLoading = false
+ if matches.count > 1 {
+ self.lastError = "Registered in more than one place. Unregister extras so only /Applications or DerivedData remains."
+ }
+ }
+ } catch {
+ await MainActor.run {
+ self.isInstalled = false
+ self.installedPath = nil
+ self.installedVersion = nil
+ self.registeredPaths = []
+ self.isLoading = false
+ self.lastError = error.localizedDescription
+ }
+ }
+ }
+ }
+
+ private struct PluginMatch {
+ var path: String?
+ var version: String?
+ }
+
+ /// Query pluginkit for our extension's registration status.
+ /// Line format we look for:
+ /// `+ be.zenjoy.omacy.screensaver(1.0) `
+ private func queryPluginKit() async throws -> [PluginMatch] {
+ let output = try runProcess("/usr/bin/pluginkit", arguments: ["-m", "-v", "-p", "com.apple.screensaver"])
+
+ var matches: [PluginMatch] = []
+ let lines = output.components(separatedBy: "\n")
+ for line in lines {
+ if line.contains(bundleIdentifier) {
+ logger.info("Found extension in pluginkit output: \(line, privacy: .public)")
+
+ var version: String?
+ if let versionStart = line.firstIndex(of: "("),
+ let versionEnd = line.firstIndex(of: ")") {
+ let start = line.index(after: versionStart)
+ version = String(line[start.. Bool {
+ let path = Bundle.main.bundlePath
+ if path.hasPrefix("/Applications/") { return true }
+ if path.contains("/DerivedData/") { return true }
+ return false
+ }
+
+ /// Run a subprocess and return its combined stdout/stderr.
+ private func runProcess(_ path: String, arguments: [String]) throws -> String {
+ let process = Process()
+ process.executableURL = URL(fileURLWithPath: path)
+ process.arguments = arguments
+
+ let pipe = Pipe()
+ process.standardOutput = pipe
+ process.standardError = pipe
+
+ try process.run()
+ process.waitUntilExit()
+
+ let data = pipe.fileHandleForReading.readDataToEndOfFile()
+ let output = String(data: data, encoding: .utf8) ?? ""
+
+ logger.debug("Process output: \(output, privacy: .public)")
+
+ if process.terminationStatus != 0 {
+ // pluginkit returns non-zero when no matches are found, so don't treat it as fatal.
+ logger.warning("Process exited with status: \(process.terminationStatus)")
+ }
+
+ return output
+ }
+}
+
+enum PluginError: LocalizedError {
+ case embeddedExtensionNotFound
+ case extensionPathNotFound
+ case installationFailed(String)
+ case uninstallationFailed(String)
+ case notInApplications
+
+ var errorDescription: String? {
+ switch self {
+ case .embeddedExtensionNotFound:
+ return "Embedded extension not found in app bundle"
+ case .extensionPathNotFound:
+ return "Extension path not found"
+ case .installationFailed(let message):
+ return "Installation failed: \(message)"
+ case .uninstallationFailed(let message):
+ return "Uninstallation failed: \(message)"
+ case .notInApplications:
+ return "Move Omacy.app to /Applications, then register. The host will not register from a random path."
+ }
+ }
+}
diff --git a/apps/Omacy/Omacy/PreviewView.swift b/apps/Omacy/Omacy/PreviewView.swift
new file mode 100644
index 0000000..bc06b43
--- /dev/null
+++ b/apps/Omacy/Omacy/PreviewView.swift
@@ -0,0 +1,3 @@
+import AppKit
+
+typealias PreviewView = OmacyHostView
diff --git a/apps/Omacy/Omacy/PreviewViewRepresentable.swift b/apps/Omacy/Omacy/PreviewViewRepresentable.swift
new file mode 100644
index 0000000..fc7b822
--- /dev/null
+++ b/apps/Omacy/Omacy/PreviewViewRepresentable.swift
@@ -0,0 +1,6 @@
+import SwiftUI
+
+struct PreviewViewRepresentable: NSViewRepresentable {
+ func makeNSView(context: Context) -> PreviewView { PreviewView() }
+ func updateNSView(_ nsView: PreviewView, context: Context) { }
+}
diff --git a/apps/Omacy/OmacyScreensaver/Assets.xcassets/Contents.json b/apps/Omacy/OmacyScreensaver/Assets.xcassets/Contents.json
new file mode 100644
index 0000000..73c0059
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/Assets.xcassets/Contents.json
@@ -0,0 +1,6 @@
+{
+ "info" : {
+ "author" : "xcode",
+ "version" : 1
+ }
+}
diff --git a/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/Contents.json b/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/Contents.json
new file mode 100644
index 0000000..0bbaa31
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/Contents.json
@@ -0,0 +1,18 @@
+{
+ "images" : [
+ {
+ "filename" : "thumbnail.png",
+ "idiom" : "universal",
+ "scale" : "1x"
+ },
+ {
+ "filename" : "thumbnail@2x.png",
+ "idiom" : "universal",
+ "scale" : "2x"
+ }
+ ],
+ "info" : {
+ "author" : "xcode",
+ "version" : 1
+ }
+}
diff --git a/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/thumbnail.png b/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/thumbnail.png
new file mode 100644
index 0000000..91b8863
Binary files /dev/null and b/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/thumbnail.png differ
diff --git a/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/thumbnail@2x.png b/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/thumbnail@2x.png
new file mode 100644
index 0000000..94dae9e
Binary files /dev/null and b/apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset/thumbnail@2x.png differ
diff --git a/apps/Omacy/OmacyScreensaver/Info.plist b/apps/Omacy/OmacyScreensaver/Info.plist
new file mode 100644
index 0000000..394e2c9
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/Info.plist
@@ -0,0 +1,43 @@
+
+
+
+
+ CFBundleDevelopmentRegion
+ $(DEVELOPMENT_LANGUAGE)
+ CFBundleDisplayName
+ Omacy
+ CFBundleExecutable
+ $(EXECUTABLE_NAME)
+ CFBundleIdentifier
+ $(PRODUCT_BUNDLE_IDENTIFIER)
+ CFBundleInfoDictionaryVersion
+ 6.0
+ CFBundleName
+ $(PRODUCT_NAME)
+ CFBundlePackageType
+ XPC!
+ CFBundleShortVersionString
+ 1.0
+ CFBundleVersion
+ $(CURRENT_PROJECT_VERSION)
+ LSMinimumSystemVersion
+ $(MACOSX_DEPLOYMENT_TARGET)
+ NSExtension
+
+ NSExtensionPointIdentifier
+ com.apple.screensaver
+ NSExtensionPointVersion
+ 1.0
+ NSExtensionPrincipalClass
+ $(PRODUCT_MODULE_NAME).OmacyScreensaver
+
+ SSEHasConfigureSheet
+
+ SSENeedsAnimationTimer
+
+ ScreenSaverConfigurationSheetViewControllerClass
+ $(PRODUCT_MODULE_NAME).OmacyConfigurationViewController
+ ScreenSaverViewControllerClass
+ $(PRODUCT_MODULE_NAME).OmacySaverViewController
+
+
diff --git a/apps/Omacy/OmacyScreensaver/OmacyConfigurationViewController.swift b/apps/Omacy/OmacyScreensaver/OmacyConfigurationViewController.swift
new file mode 100644
index 0000000..f4c6bbf
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/OmacyConfigurationViewController.swift
@@ -0,0 +1,82 @@
+import AppKit
+import ScreenSaver
+
+private let logger = AppexLog.logger("Configuration")
+
+@objc(OmacyConfigurationViewController)
+class OmacyConfigurationViewController: ScreenSaverConfigurationViewController {
+ private let effectField = NSTextField()
+ private let statusLabel = NSTextField(labelWithString: "")
+
+ override func loadView() {
+ let container = NSView(frame: NSRect(x: 0, y: 0, width: 360, height: 180))
+ let title = NSTextField(labelWithString: "Omacy")
+ title.font = NSFont.systemFont(ofSize: 18, weight: .medium)
+ title.alignment = .center
+ title.translatesAutoresizingMaskIntoConstraints = false
+ container.addSubview(title)
+
+ let settings = OmacyStore.loadSettings()
+ effectField.stringValue = settings.effect
+ effectField.placeholderString = "random or a ttfx name"
+ effectField.translatesAutoresizingMaskIntoConstraints = false
+ container.addSubview(effectField)
+
+ let restore = NSButton(title: "Restore default art", target: self, action: #selector(restoreArt))
+ restore.bezelStyle = .rounded
+ restore.translatesAutoresizingMaskIntoConstraints = false
+ container.addSubview(restore)
+
+ let ok = NSButton(title: "OK", target: self, action: #selector(saveAndDismiss))
+ ok.bezelStyle = .rounded
+ ok.keyEquivalent = "\r"
+ ok.translatesAutoresizingMaskIntoConstraints = false
+ container.addSubview(ok)
+
+ statusLabel.font = NSFont.systemFont(ofSize: 11)
+ statusLabel.textColor = .secondaryLabelColor
+ statusLabel.translatesAutoresizingMaskIntoConstraints = false
+ container.addSubview(statusLabel)
+
+ NSLayoutConstraint.activate([
+ title.centerXAnchor.constraint(equalTo: container.centerXAnchor),
+ title.topAnchor.constraint(equalTo: container.topAnchor, constant: 16),
+ effectField.leadingAnchor.constraint(equalTo: container.leadingAnchor, constant: 20),
+ effectField.trailingAnchor.constraint(equalTo: container.trailingAnchor, constant: -20),
+ effectField.topAnchor.constraint(equalTo: title.bottomAnchor, constant: 16),
+ restore.leadingAnchor.constraint(equalTo: effectField.leadingAnchor),
+ restore.topAnchor.constraint(equalTo: effectField.bottomAnchor, constant: 12),
+ ok.trailingAnchor.constraint(equalTo: effectField.trailingAnchor),
+ ok.bottomAnchor.constraint(equalTo: container.bottomAnchor, constant: -16),
+ statusLabel.leadingAnchor.constraint(equalTo: effectField.leadingAnchor),
+ statusLabel.bottomAnchor.constraint(equalTo: ok.topAnchor, constant: -8)
+ ])
+ self.view = container
+ self.preferredContentSize = NSSize(width: 360, height: 180)
+ }
+
+ @objc private func restoreArt() {
+ do {
+ try OmacyStore.restoreDefaultArt()
+ statusLabel.stringValue = "Default wordmark restored"
+ } catch {
+ statusLabel.stringValue = error.localizedDescription
+ }
+ }
+
+ @objc private func saveAndDismiss(_ sender: Any?) {
+ var settings = OmacyStore.loadSettings()
+ settings.effect = effectField.stringValue.trimmingCharacters(in: .whitespacesAndNewlines)
+ if settings.effect.isEmpty { settings.effect = "random" }
+ do {
+ try OmacyStore.save(settings: settings, art: OmacyStore.loadArt())
+ } catch {
+ logger.error("save failed: \(error.localizedDescription, privacy: .public)")
+ }
+ if let window = self.view.window, let parent = window.sheetParent {
+ parent.endSheet(window)
+ } else {
+ self.dismiss(nil)
+ }
+ }
+}
diff --git a/apps/Omacy/OmacyScreensaver/OmacySaverView.swift b/apps/Omacy/OmacyScreensaver/OmacySaverView.swift
new file mode 100644
index 0000000..23f3f40
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/OmacySaverView.swift
@@ -0,0 +1,90 @@
+import ScreenSaver
+import QuartzCore
+
+private let logger = AppexLog.logger("View")
+
+final class OmacySaverView: ScreenSaverView {
+ private let renderer = OmacyRenderer()
+ private let canary = OmacyCanaryAnimator()
+ private var usingCanary = true
+
+ override init?(frame: NSRect, isPreview: Bool) {
+ logger.info("init(frame: \(frame.size.width, privacy: .public)x\(frame.size.height, privacy: .public), isPreview: \(isPreview))")
+ super.init(frame: frame, isPreview: isPreview)
+ wantsLayer = true
+ animationTimeInterval = 1.0 / 60.0
+ renderer.onEngineUnavailable = { [weak self] in
+ self?.switchToCanary()
+ }
+ }
+
+ required init?(coder: NSCoder) {
+ super.init(coder: coder)
+ wantsLayer = true
+ renderer.onEngineUnavailable = { [weak self] in
+ self?.switchToCanary()
+ }
+ }
+
+ deinit {
+ // teardown() is @MainActor (OmacyRenderer). stopAnimation / window-nil already ran.
+ logger.info("deinit")
+ }
+
+ override func startAnimation() {
+ logger.info("startAnimation()")
+ super.startAnimation()
+ start()
+ }
+
+ override func stopAnimation() {
+ logger.info("stopAnimation()")
+ teardown()
+ super.stopAnimation()
+ }
+
+ override func viewDidMoveToWindow() {
+ super.viewDidMoveToWindow()
+ logger.info("viewDidMoveToWindow() hasWindow=\(self.window != nil)")
+ if window != nil {
+ start()
+ } else {
+ teardown()
+ }
+ }
+
+ override func layout() {
+ super.layout()
+ if usingCanary {
+ canary.updateBounds(bounds)
+ } else {
+ renderer.updateGeometry()
+ }
+ }
+
+ private func start() {
+ teardown()
+ let preview = isPreview || (bounds.width > 0 && bounds.width < 400)
+ switch renderer.attach(to: self, isPreview: preview) {
+ case .engine:
+ usingCanary = false
+ renderer.start()
+ case .canary:
+ switchToCanary()
+ }
+ }
+
+ private func switchToCanary() {
+ usingCanary = true
+ if let layer {
+ canary.attach(to: layer)
+ canary.updateBounds(bounds)
+ }
+ canary.start()
+ }
+
+ private func teardown() {
+ renderer.stop()
+ canary.stop()
+ }
+}
diff --git a/apps/Omacy/OmacyScreensaver/OmacySaverViewController.swift b/apps/Omacy/OmacyScreensaver/OmacySaverViewController.swift
new file mode 100644
index 0000000..4154fc8
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/OmacySaverViewController.swift
@@ -0,0 +1,57 @@
+//
+// OmacySaverViewController.swift
+// OmacyScreensaver
+//
+// Copyright © 2026 Guillaume Louel. Licensed under the MIT License.
+//
+// Main view controller for the screensaver. Specified as
+// ScreenSaverViewControllerClass in Info.plist as
+// `$(PRODUCT_MODULE_NAME).OmacySaverViewController`.
+//
+// Mirrors Apple's Arabesque.appex pattern. Prefer loadView(forFrame:isPreview:)
+// so each display and the Settings preview get the real frame; loadView() is
+// the fallback when the framework only calls the NSViewController path.
+//
+
+import AppKit
+import ScreenSaver
+
+private let logger = AppexLog.logger("ViewController")
+
+@objc(OmacySaverViewController)
+class OmacySaverViewController: ScreenSaverViewController {
+
+ /// Strong reference so the framework can't drop our view while we still own it.
+ private var saverView: OmacySaverView?
+
+ override init(nibName nibNameOrNil: NSNib.Name?, bundle nibBundleOrNil: Bundle?) {
+ logger.info("init(nibName:bundle:)")
+ super.init(nibName: nibNameOrNil, bundle: nibBundleOrNil)
+ }
+
+ required init?(coder: NSCoder) {
+ logger.info("init(coder:)")
+ super.init(coder: coder)
+ }
+
+ deinit {
+ logger.info("deinit")
+ }
+
+ override func loadView() {
+ logger.info("loadView()")
+ let frame = NSScreen.main?.frame ?? NSRect(x: 0, y: 0, width: 1920, height: 1080)
+ installView(frame: frame, isPreview: frame.width < 400)
+ }
+
+ override func loadView(forFrame frame: NSRect, isPreview: Bool) {
+ logger.info("loadView(forFrame: \(frame.size.width, privacy: .public)x\(frame.size.height, privacy: .public), isPreview: \(isPreview))")
+ installView(frame: frame, isPreview: isPreview)
+ }
+
+ private func installView(frame: NSRect, isPreview: Bool) {
+ let view = OmacySaverView(frame: frame, isPreview: isPreview)
+ saverView = view
+ self.view = view ?? NSView(frame: frame)
+ }
+}
diff --git a/apps/Omacy/OmacyScreensaver/OmacyScreensaver-Bridging-Header.h b/apps/Omacy/OmacyScreensaver/OmacyScreensaver-Bridging-Header.h
new file mode 100644
index 0000000..9d6a025
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/OmacyScreensaver-Bridging-Header.h
@@ -0,0 +1,10 @@
+//
+// AppexSaverExtension-Bridging-Header.h
+// AppexSaverExtension
+//
+// Bridging header to expose private ScreenSaver API to Swift.
+//
+
+#import "PrivateHeaders/ScreenSaverPrivate.h"
+#import "omacy.h"
+
diff --git a/apps/Omacy/OmacyScreensaver/OmacyScreensaver.entitlements b/apps/Omacy/OmacyScreensaver/OmacyScreensaver.entitlements
new file mode 100644
index 0000000..54cca65
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/OmacyScreensaver.entitlements
@@ -0,0 +1,20 @@
+
+
+
+
+ com.apple.security.app-sandbox
+
+ com.apple.security.app-groups
+
+ group.be.zenjoy.omacy
+
+ com.apple.security.cs.disable-library-validation
+
+ com.apple.security.temporary-exception.mach-lookup.global-name
+
+ com.apple.CARenderServer
+ com.apple.CoreDisplay.master
+ com.apple.ViewBridgeAuxiliary
+
+
+
diff --git a/apps/Omacy/OmacyScreensaver/OmacyScreensaver.swift b/apps/Omacy/OmacyScreensaver/OmacyScreensaver.swift
new file mode 100644
index 0000000..7619901
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/OmacyScreensaver.swift
@@ -0,0 +1,31 @@
+//
+// OmacyScreensaver.swift
+// OmacyScreensaver
+//
+// Copyright © 2026 Guillaume Louel. Licensed under the MIT License.
+//
+// Principal class for the screensaver extension. Specified as
+// NSExtensionPrincipalClass in Info.plist as
+// `$(PRODUCT_MODULE_NAME).OmacyScreensaver`.
+//
+// Following Apple's own screensavers (e.g. Arabesque.appex) we keep this
+// minimal — only implement init() and let the framework drive lifecycle.
+//
+
+import Foundation
+import ScreenSaver
+
+private let logger = AppexLog.logger("Extension")
+
+@objc(OmacyScreensaver)
+class OmacyScreensaver: ScreenSaverExtension {
+
+ @objc override init() {
+ logger.info("OmacyScreensaver.init() PID=\(ProcessInfo.processInfo.processIdentifier, privacy: .public)")
+ super.init()
+ }
+
+ deinit {
+ logger.info("OmacyScreensaver.deinit")
+ }
+}
diff --git a/apps/Omacy/OmacyScreensaver/PrivateHeaders/ScreenSaverPrivate.h b/apps/Omacy/OmacyScreensaver/PrivateHeaders/ScreenSaverPrivate.h
new file mode 100644
index 0000000..b08741e
--- /dev/null
+++ b/apps/Omacy/OmacyScreensaver/PrivateHeaders/ScreenSaverPrivate.h
@@ -0,0 +1,51 @@
+//
+// ScreenSaverPrivate.h
+// AppexSaverExtension
+//
+// Private API declarations for macOS screensaver extensions.
+// These classes exist in ScreenSaver.framework but are not publicly declared.
+// Discovered via reverse engineering Apple's screensaver appex bundles.
+//
+
+#import
+#import
+
+NS_ASSUME_NONNULL_BEGIN
+
+#pragma mark - ScreenSaverExtension
+
+/// Principal class for modern screensaver app extensions.
+/// Subclass this and specify it as NSExtensionPrincipalClass in Info.plist.
+@interface ScreenSaverExtension : NSObject
+
+- (instancetype)init;
+
+@end
+
+#pragma mark - ScreenSaverViewController
+
+/// Main view controller for screensaver animation.
+/// Specify your subclass name as ScreenSaverViewControllerClass in Info.plist.
+@interface ScreenSaverViewController : NSViewController
+
+/// The ScreenSaverView that provides the animation.
+@property (nonatomic, weak, nullable) ScreenSaverView *representedView;
+
+/// Whether the screensaver is currently animating.
+@property (nonatomic, getter=isAnimating) BOOL animating;
+
+/// Called to create the view for the given frame.
+/// Swift name: loadView(forFrame:isPreview:)
+- (void)loadViewForFrame:(NSRect)frame isPreview:(BOOL)isPreview NS_SWIFT_NAME(loadView(forFrame:isPreview:));
+
+@end
+
+#pragma mark - ScreenSaverConfigurationViewController
+
+/// View controller for the screensaver configuration sheet.
+/// Subclass this if SSEHasConfigureSheet is true in Info.plist.
+@interface ScreenSaverConfigurationViewController : NSViewController
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/apps/Omacy/README.md b/apps/Omacy/README.md
new file mode 100644
index 0000000..2dc89fc
--- /dev/null
+++ b/apps/Omacy/README.md
@@ -0,0 +1,17 @@
+# Omacy Mac host
+
+Xcode project for the host app and `com.apple.screensaver` appex.
+
+Build on macOS 15+ (deployment target 15.0). PaperSaver 0.2.0 needs Swift 6.2, so resolving packages wants Xcode 26. The appex target’s “Build Rust engine” phase runs `scripts/build-engine.sh` once; the host depends on the appex and links the same `libomacy_engine.a`.
+
+## Run
+
+1. Team is `25TVW8MSGJ` (Zenjoy). Sync Developer ID profiles with `bundle exec fastlane mac generate_signing` (once) or `mac sync_signing` (readonly).
+2. Build the Omacy scheme.
+3. For iteration, stay in DerivedData **or** copy the app to `/Applications` — not both.
+4. Use the host to register (`pluginkit`) and enable (PaperSaver). Registration from a random path is refused.
+5. Preview in the host. Idle / System Settings listing is the canary gate: see `docs/macos-gates.md` in the repo root.
+
+Force the asymmetric fixture (no engine) with UserDefaults `omacy.forceCanary`.
+
+App Group: `group.be.zenjoy.omacy` (`screensaver.txt`, `settings.json`).
diff --git a/apps/Omacy/Shared/OmacyAtlas.swift b/apps/Omacy/Shared/OmacyAtlas.swift
new file mode 100644
index 0000000..84bf3e4
--- /dev/null
+++ b/apps/Omacy/Shared/OmacyAtlas.swift
@@ -0,0 +1,164 @@
+import AppKit
+import CoreText
+import Metal
+
+struct AtlasGlyph {
+ var uvOrigin: SIMD2
+ var uvSize: SIMD2
+}
+
+final class OmacyAtlas {
+ private(set) var texture: MTLTexture?
+ private var map: [UInt32: AtlasGlyph] = [:]
+ private var extraCount = 0
+ private let extraCap = 256
+ private var cell: CGSize = .zero
+ private var pixels: [UInt8] = []
+ private var texWidth = 1
+ private var texHeight = 1
+ private var glyphW = 1
+ private var glyphH = 1
+ private var cols = 1
+ private var nextSlot = 1
+ private var builtCell: CGSize = .zero
+ private var builtScale: CGFloat = 0
+ private var builtFontName = ""
+ private var builtFontSize: CGFloat = 0
+
+ private let preload: [UInt32] = {
+ var codes: [UInt32] = Array(0x20...0x7E)
+ codes.append(contentsOf: 0x2800...0x28FF)
+ codes.append(contentsOf: [0x2580, 0x2584, 0x2588, 0x2591, 0x2592, 0x2593])
+ return codes
+ }()
+
+ func needsRebuild(font: NSFont, cell: CGSize, scale: CGFloat) -> Bool {
+ abs(cell.width - builtCell.width) >= 0.5
+ || abs(cell.height - builtCell.height) >= 0.5
+ || abs(scale - builtScale) >= 0.01
+ || font.fontName != builtFontName
+ || abs(font.pointSize - builtFontSize) >= 0.01
+ }
+
+ func rebuild(device: MTLDevice, font: NSFont, cell: CGSize, scale: CGFloat) {
+ self.cell = cell
+ builtCell = cell
+ builtScale = scale
+ builtFontName = font.fontName
+ builtFontSize = font.pointSize
+ extraCount = 0
+ map.removeAll()
+ nextSlot = 1
+ let scale = max(scale, 1)
+ glyphW = max(Int(ceil(cell.width * scale)), 1)
+ glyphH = max(Int(ceil(cell.height * scale)), 1)
+ let count = preload.count + extraCap + 1
+ cols = Int(ceil(sqrt(Double(count))))
+ let rows = Int(ceil(Double(count) / Double(cols)))
+ texWidth = max(cols * glyphW, 1)
+ texHeight = max(rows * glyphH, 1)
+ pixels = Array(repeating: 0, count: texWidth * texHeight * 4)
+ writeWhitePixel(x: 0, y: 0)
+ map[0] = AtlasGlyph(
+ uvOrigin: SIMD2(0, 0),
+ uvSize: SIMD2(1 / Float(texWidth), 1 / Float(texHeight))
+ )
+ let ctFont = font as CTFont
+ for scalar in preload {
+ _ = stamp(font: ctFont, scalar: scalar)
+ }
+ upload(device: device)
+ }
+
+ var whitePixel: AtlasGlyph {
+ map[0] ?? AtlasGlyph(uvOrigin: SIMD2(0, 0), uvSize: SIMD2(1 / Float(max(texWidth, 1)), 1 / Float(max(texHeight, 1))))
+ }
+
+ func glyph(for scalar: UInt32, font: NSFont, device: MTLDevice) -> AtlasGlyph? {
+ if let hit = map[scalar] { return hit }
+ if extraCount >= extraCap { return nil }
+ extraCount += 1
+ let g = stamp(font: font as CTFont, scalar: scalar)
+ upload(device: device)
+ return g
+ }
+
+ private func upload(device: MTLDevice) {
+ let desc = MTLTextureDescriptor.texture2DDescriptor(
+ pixelFormat: .rgba8Unorm,
+ width: texWidth,
+ height: texHeight,
+ mipmapped: false
+ )
+ desc.usage = [.shaderRead]
+ desc.storageMode = .shared
+ guard let texture = device.makeTexture(descriptor: desc) else { return }
+ pixels.withUnsafeBytes { raw in
+ texture.replace(
+ region: MTLRegionMake2D(0, 0, texWidth, texHeight),
+ mipmapLevel: 0,
+ withBytes: raw.baseAddress!,
+ bytesPerRow: texWidth * 4
+ )
+ }
+ self.texture = texture
+ }
+
+ private func writeWhitePixel(x: Int, y: Int) {
+ let i = (y * texWidth + x) * 4
+ if i + 3 < pixels.count {
+ pixels[i] = 255
+ pixels[i + 1] = 255
+ pixels[i + 2] = 255
+ pixels[i + 3] = 255
+ }
+ }
+
+ private func stamp(font: CTFont, scalar: UInt32) -> AtlasGlyph? {
+ guard UnicodeScalar(scalar) != nil else { return nil }
+ let slot = nextSlot
+ nextSlot += 1
+ let col = slot % cols
+ let row = slot / cols
+ let colorSpace = CGColorSpaceCreateDeviceRGB()
+ guard let ctx = CGContext(
+ data: nil,
+ width: glyphW,
+ height: glyphH,
+ bitsPerComponent: 8,
+ bytesPerRow: glyphW * 4,
+ space: colorSpace,
+ bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+ ) else { return nil }
+ ctx.clear(CGRect(x: 0, y: 0, width: glyphW, height: glyphH))
+ ctx.setFillColor(CGColor(gray: 1, alpha: 1))
+ var utf16 = Array(String(UnicodeScalar(scalar)!).utf16)
+ var glyph: CGGlyph = 0
+ _ = utf16.withUnsafeMutableBufferPointer { buf in
+ CTFontGetGlyphsForCharacters(font, buf.baseAddress!, &glyph, 1)
+ }
+ var point = CGPoint(x: 0, y: CGFloat(glyphH) * 0.18)
+ CTFontDrawGlyphs(font, &glyph, &point, 1, ctx)
+ if let data = ctx.data {
+ let src = data.bindMemory(to: UInt8.self, capacity: glyphW * glyphH * 4)
+ let destX = col * glyphW
+ let destY = row * glyphH
+ for gy in 0.. NSFont {
+ if let url = OmacyStore.bundledFontURL,
+ let data = try? Data(contentsOf: url) as CFData,
+ let provider = CGDataProvider(data: data),
+ let cg = CGFont(provider),
+ let font = CTFontCreateWithGraphicsFont(cg, size, nil, nil) as NSFont? {
+ return font
+ }
+ return NSFont.monospacedSystemFont(ofSize: size, weight: .regular)
+ }
+}
diff --git a/apps/Omacy/Shared/OmacyLayout.swift b/apps/Omacy/Shared/OmacyLayout.swift
new file mode 100644
index 0000000..345a0ec
--- /dev/null
+++ b/apps/Omacy/Shared/OmacyLayout.swift
@@ -0,0 +1,73 @@
+import AppKit
+
+enum OmacyLayout {
+ static let defaultFontSize: CGFloat = 18
+ static let minCells = 1
+ static let maxAxis = 512
+ static let maxCells = 32_768
+
+ static func cellSize(font: NSFont) -> CGSize {
+ let advance = font.advancement(forGlyph: font.glyph(withName: "M")).width
+ let width = advance > 0 ? advance : font.maximumAdvancement.width
+ return CGSize(width: max(width, 1), height: max(font.pointSize, 1))
+ }
+
+ static func grid(view: NSView, font: NSFont) -> (cols: UInt32, rows: UInt32, cell: CGSize, origin: CGPoint) {
+ let scale = view.window?.backingScaleFactor ?? view.layer?.contentsScale ?? 2
+ let backing = view.convertToBacking(view.bounds.size)
+ return grid(viewSize: view.bounds.size, backing: backing, scale: scale, font: font)
+ }
+
+ static func grid(viewSize: CGSize, scale: CGFloat, font: NSFont) -> (cols: UInt32, rows: UInt32, cell: CGSize, origin: CGPoint) {
+ grid(viewSize: viewSize, backing: CGSize(width: viewSize.width * scale, height: viewSize.height * scale), scale: scale, font: font)
+ }
+
+ static func grid(
+ viewSize: CGSize,
+ backing: CGSize,
+ scale: CGFloat,
+ font: NSFont
+ ) -> (cols: UInt32, rows: UInt32, cell: CGSize, origin: CGPoint) {
+ let points = treatedAsPoints(viewSize: viewSize, backing: backing, scale: scale)
+ let cell = cellSize(font: font)
+ var cols = max(Self.minCells, Int(floor(points.width / cell.width)))
+ var rows = max(Self.minCells, Int(floor(points.height / cell.height)))
+ cols = min(cols, Self.maxAxis)
+ rows = min(rows, Self.maxAxis)
+ if cols * rows > Self.maxCells {
+ let ratio = sqrt(Double(Self.maxCells) / Double(cols * rows))
+ cols = max(Self.minCells, Int(Double(cols) * ratio))
+ rows = max(Self.minCells, Int(Double(rows) * ratio))
+ }
+ let gridWidth = CGFloat(cols) * cell.width
+ let gridHeight = CGFloat(rows) * cell.height
+ let origin = CGPoint(
+ x: (points.width - gridWidth) / 2,
+ y: (points.height - gridHeight) / 2
+ )
+ return (UInt32(cols), UInt32(rows), cell, origin)
+ }
+
+ /// Tahoe may hand backing pixels as bounds. An exact 2× jump vs backingScale is scale, not a giant canvas.
+ static func treatedAsPoints(viewSize: CGSize, backing: CGSize, scale: CGFloat) -> CGSize {
+ guard scale > 1 else { return viewSize }
+ if abs(backing.width - viewSize.width * scale) < 1, abs(backing.height - viewSize.height * scale) < 1 {
+ return viewSize
+ }
+ if abs(backing.width - viewSize.width) < 1, abs(backing.height - viewSize.height) < 1 {
+ return CGSize(width: viewSize.width / scale, height: viewSize.height / scale)
+ }
+ return viewSize
+ }
+
+ static func drawableSize(viewSize: CGSize, scale: CGFloat) -> CGSize {
+ CGSize(
+ width: max((viewSize.width * scale).rounded(), 1),
+ height: max((viewSize.height * scale).rounded(), 1)
+ )
+ }
+
+ static func drawableSizeChanged(current: CGSize, proposed: CGSize) -> Bool {
+ abs(current.width - proposed.width) >= 1 || abs(current.height - proposed.height) >= 1
+ }
+}
diff --git a/apps/Omacy/Shared/OmacyRenderer.swift b/apps/Omacy/Shared/OmacyRenderer.swift
new file mode 100644
index 0000000..5a89f7f
--- /dev/null
+++ b/apps/Omacy/Shared/OmacyRenderer.swift
@@ -0,0 +1,461 @@
+import AppKit
+import Metal
+import QuartzCore
+
+private let log = AppexLog.logger("Renderer")
+private let occupancyBackground = UInt8(OMACY_CELL_HAS_BACKGROUND)
+private let occupancyGlyph = UInt8(OMACY_CELL_HAS_GLYPH)
+
+private struct QuadInstance {
+ var origin: SIMD2
+ var size: SIMD2
+ var uvOrigin: SIMD2
+ var uvSize: SIMD2
+ var color: SIMD4
+}
+
+enum OmacyAttachMode {
+ case engine
+ case canary
+}
+
+@MainActor
+final class OmacyRenderer: NSObject {
+ var onEngineUnavailable: (() -> Void)?
+
+ override init() {
+ super.init()
+ }
+
+ private weak var view: NSView?
+ private var session: OpaquePointer?
+ private var displayLink: CADisplayLink?
+ private var device: MTLDevice?
+ private var queue: MTLCommandQueue?
+ private var pipeline: MTLRenderPipelineState?
+ private var metalLayer: CAMetalLayer?
+ private let atlas = OmacyAtlas()
+ private var instanceBuffers: [MTLBuffer?] = [nil, nil, nil]
+ private var bufferBusy = [false, false, false]
+ private var bufferIndex = 0
+ private var lastTimestamp: CFTimeInterval?
+ private var fontSize: CGFloat = OmacyLayout.defaultFontSize
+ private var cols: UInt32 = 1
+ private var rows: UInt32 = 1
+ private var pendingCols: UInt32?
+ private var pendingRows: UInt32?
+ private var debounce: TimeInterval = 0
+ private var isPreview = false
+ private var stopped = true
+ private var copiedCells: [OmacyCell] = []
+ private var lastSettings = OmacySettings()
+ private var lastArt = ""
+
+ var usesEngine: Bool { session != nil }
+
+ @discardableResult
+ func attach(to view: NSView, isPreview: Bool) -> OmacyAttachMode {
+ stopSessionAndLink()
+ self.view = view
+ self.isPreview = isPreview
+ view.wantsLayer = true
+ lastSettings = OmacyStore.loadSettings()
+ lastArt = OmacyStore.loadArt()
+ fontSize = CGFloat(lastSettings.fontSize)
+ let font = OmacyFont.makeFont(size: fontSize)
+ let layout = OmacyLayout.grid(view: view, font: font)
+ cols = layout.cols
+ rows = layout.rows
+
+ if OmacyStore.forceCanary || !createSession(cols: cols, rows: rows, settings: lastSettings, art: lastArt) {
+ installPlainLayer(on: view)
+ return .canary
+ }
+ guard installMetal(on: view, font: font, cell: layout.cell) else {
+ destroySession()
+ installPlainLayer(on: view)
+ return .canary
+ }
+ return .engine
+ }
+
+ func start() {
+ guard let view, session != nil else { return }
+ stopped = false
+ displayLink?.invalidate()
+ let link = view.displayLink(target: self, selector: #selector(tick(_:)))
+ link.add(to: .main, forMode: .common)
+ if isPreview {
+ link.preferredFrameRateRange = CAFrameRateRange(minimum: 30, maximum: 30, preferred: 30)
+ }
+ displayLink = link
+ NotificationCenter.default.addObserver(
+ self,
+ selector: #selector(willStop),
+ name: Notification.Name("com.apple.screensaver.willstop"),
+ object: nil
+ )
+ }
+
+ func stop() {
+ stopped = true
+ NotificationCenter.default.removeObserver(self)
+ stopSessionAndLink()
+ metalLayer = nil
+ pipeline = nil
+ queue = nil
+ device = nil
+ instanceBuffers = [nil, nil, nil]
+ bufferBusy = [false, false, false]
+ }
+
+ deinit {
+ if session != nil {
+ assertionFailure("OmacyRenderer.deinit with live session")
+ if Thread.isMainThread {
+ omacy_session_destroy(session)
+ }
+ }
+ }
+
+ func updateGeometry() {
+ guard let view, view.bounds.width > 1, view.bounds.height > 1 else { return }
+ let font = OmacyFont.makeFont(size: fontSize)
+ let layout = OmacyLayout.grid(view: view, font: font)
+ let scale = view.window?.backingScaleFactor ?? metalLayer?.contentsScale ?? view.layer?.contentsScale ?? 2
+ let size = OmacyLayout.drawableSize(viewSize: view.bounds.size, scale: scale)
+ if metalLayer?.contentsScale != scale {
+ metalLayer?.contentsScale = scale
+ }
+ if let metalLayer, OmacyLayout.drawableSizeChanged(current: metalLayer.drawableSize, proposed: size) {
+ metalLayer.drawableSize = size
+ }
+ metalLayer?.frame = view.bounds
+ if layout.cols != cols || layout.rows != rows {
+ pendingCols = layout.cols
+ pendingRows = layout.rows
+ debounce = CACurrentMediaTime()
+ }
+ if let device, atlas.needsRebuild(font: font, cell: layout.cell, scale: scale) {
+ atlas.rebuild(device: device, font: font, cell: layout.cell, scale: scale)
+ }
+ }
+
+ func applyPendingConfig() {
+ lastSettings = OmacyStore.loadSettings()
+ lastArt = OmacyStore.loadArt()
+ fontSize = CGFloat(lastSettings.fontSize)
+ guard let session else { return }
+ var cfg = OmacyPendingConfig()
+ lastArt.withCString { ptr in
+ cfg.ascii = UnsafeRawPointer(ptr).assumingMemoryBound(to: UInt8.self)
+ cfg.ascii_len = lastArt.utf8.count
+ lastSettings.effect.withCString { eptr in
+ cfg.effect = UnsafeRawPointer(eptr).assumingMemoryBound(to: UInt8.self)
+ cfg.effect_len = lastSettings.effect.utf8.count
+ let bg = lastSettings.backgroundRGBA
+ cfg.bg_r = bg.0
+ cfg.bg_g = bg.1
+ cfg.bg_b = bg.2
+ cfg.bg_a = bg.3
+ _ = omacy_session_set_pending_config(session, &cfg)
+ }
+ }
+ updateGeometry()
+ }
+
+ @objc private func willStop() {
+ stop()
+ }
+
+ @objc private func tick(_ link: CADisplayLink) {
+ guard !stopped else { return }
+ guard let session else { return }
+ let now = link.timestamp
+ let elapsed: Double
+ if let lastTimestamp {
+ elapsed = now - lastTimestamp
+ } else {
+ elapsed = 1.0 / 60.0
+ }
+ lastTimestamp = now
+
+ var result = OmacyStepResult()
+ let status = omacy_session_step(session, elapsed, &result)
+ if status == OMACY_ERR_DEAD || status == OMACY_ERR_PANIC {
+ recoverDeadSession()
+ return
+ }
+ guard status == OMACY_OK, let cells = result.frame.cells else { return }
+
+ let count = Int(result.frame.cols) * Int(result.frame.rows)
+ copiedCells = Array(UnsafeBufferPointer(start: cells, count: count))
+ present(frame: result.frame, cells: copiedCells)
+ applyWaitingWork(result)
+ }
+
+ private func applyWaitingWork(_ result: OmacyStepResult) {
+ guard let session else { return }
+ if result.needs_begin_next != 0 {
+ let settings = OmacyStore.loadSettings()
+ if CGFloat(settings.fontSize) != fontSize {
+ fontSize = CGFloat(settings.fontSize)
+ lastSettings = settings
+ updateGeometry()
+ }
+ if CACurrentMediaTime() - debounce >= 0.05, let pc = pendingCols, let pr = pendingRows {
+ _ = omacy_session_resize(session, pc, pr)
+ cols = pc
+ rows = pr
+ pendingCols = nil
+ pendingRows = nil
+ }
+ _ = omacy_session_begin_next(session)
+ } else if let pc = pendingCols, let pr = pendingRows, CACurrentMediaTime() - debounce >= 0.05 {
+ _ = omacy_session_resize(session, pc, pr)
+ }
+ }
+
+ private func present(frame: OmacyFrame, cells: [OmacyCell]) {
+ guard let view, let metalLayer, let queue, let pipeline else { return }
+ let font = OmacyFont.makeFont(size: fontSize)
+ let layout = OmacyLayout.grid(view: view, font: font)
+ var instances: [QuadInstance] = []
+ instances.reserveCapacity(cells.count * 2)
+ let cell = layout.cell
+ let origin = layout.origin
+ let cols = Int(frame.cols)
+ let rows = Int(frame.rows)
+ let white = atlas.whitePixel
+ for r in 0..(Float(cell.width), Float(cell.height))
+ if cellData.occupancy & occupancyBackground != 0 {
+ instances.append(QuadInstance(
+ origin: SIMD2(px, py),
+ size: size,
+ uvOrigin: white.uvOrigin,
+ uvSize: white.uvSize,
+ color: SIMD4(
+ Float(cellData.bg_r) / 255,
+ Float(cellData.bg_g) / 255,
+ Float(cellData.bg_b) / 255,
+ Float(cellData.bg_a) / 255
+ )
+ ))
+ }
+ if cellData.occupancy & occupancyGlyph != 0, cellData.glyph != 0,
+ let device, let g = atlas.glyph(for: cellData.glyph, font: font, device: device) {
+ instances.append(QuadInstance(
+ origin: SIMD2(px, py),
+ size: size,
+ uvOrigin: g.uvOrigin,
+ uvSize: g.uvSize,
+ color: SIMD4(
+ Float(cellData.fg_r) / 255,
+ Float(cellData.fg_g) / 255,
+ Float(cellData.fg_b) / 255,
+ Float(cellData.fg_a) / 255
+ )
+ ))
+ }
+ }
+ }
+ var upload: (index: Int, buffer: MTLBuffer)?
+ if !instances.isEmpty {
+ guard let chosen = freeInstanceBufferIndex(), let device else { return }
+ let bytes = instances.count * MemoryLayout.stride
+ if instanceBuffers[chosen] == nil || instanceBuffers[chosen]!.length < bytes {
+ instanceBuffers[chosen] = device.makeBuffer(length: max(bytes, 4096), options: .storageModeShared)
+ }
+ guard let buffer = instanceBuffers[chosen] else { return }
+ instances.withUnsafeBytes { raw in
+ buffer.contents().copyMemory(from: raw.baseAddress!, byteCount: bytes)
+ }
+ upload = (chosen, buffer)
+ }
+
+ guard let drawable = metalLayer.nextDrawable(),
+ let cmd = queue.makeCommandBuffer() else { return }
+ let pass = MTLRenderPassDescriptor()
+ pass.colorAttachments[0].texture = drawable.texture
+ pass.colorAttachments[0].loadAction = .clear
+ pass.colorAttachments[0].clearColor = MTLClearColor(
+ red: Double(frame.clear_r) / 255,
+ green: Double(frame.clear_g) / 255,
+ blue: Double(frame.clear_b) / 255,
+ alpha: Double(max(frame.clear_a, 255)) / 255
+ )
+ pass.colorAttachments[0].storeAction = .store
+ guard let enc = cmd.makeRenderCommandEncoder(descriptor: pass) else { return }
+ enc.setRenderPipelineState(pipeline)
+ if let upload {
+ bufferBusy[upload.index] = true
+ bufferIndex = (upload.index + 1) % 3
+ enc.setVertexBuffer(upload.buffer, offset: 0, index: 0)
+ var viewport = SIMD2(Float(view.bounds.width), Float(view.bounds.height))
+ enc.setVertexBytes(&viewport, length: MemoryLayout>.size, index: 1)
+ enc.setFragmentTexture(atlas.texture, index: 0)
+ enc.drawPrimitives(type: .triangle, vertexStart: 0, vertexCount: 6, instanceCount: instances.count)
+ let chosen = upload.index
+ cmd.addCompletedHandler { [weak self] _ in
+ DispatchQueue.main.async {
+ self?.bufferBusy[chosen] = false
+ }
+ }
+ }
+ enc.endEncoding()
+ cmd.present(drawable)
+ cmd.commit()
+ }
+
+ private func freeInstanceBufferIndex() -> Int? {
+ for offset in 0..<3 {
+ let idx = (bufferIndex + offset) % 3
+ if !bufferBusy[idx] {
+ return idx
+ }
+ }
+ return nil
+ }
+
+ @discardableResult
+ private func createSession(cols: UInt32, rows: UInt32, settings: OmacySettings, art: String) -> Bool {
+ destroySession()
+ let bg = settings.backgroundRGBA
+ var cfg = OmacySessionConfig()
+ let artBytes = Array(art.utf8)
+ let effectBytes = Array(settings.effect.utf8)
+ let dir = OmacyStore.containerURL?.path
+ let dirBytes = dir.map { Array($0.utf8) }
+ var created = false
+ artBytes.withUnsafeBufferPointer { artPtr in
+ effectBytes.withUnsafeBufferPointer { effectPtr in
+ cfg.ascii = artPtr.baseAddress
+ cfg.ascii_len = artBytes.count
+ cfg.effect = effectPtr.baseAddress
+ cfg.effect_len = effectBytes.count
+ cfg.bg_r = bg.0
+ cfg.bg_g = bg.1
+ cfg.bg_b = bg.2
+ cfg.bg_a = bg.3
+ cfg.has_seed = 0
+ if let dirBytes {
+ dirBytes.withUnsafeBufferPointer { dirPtr in
+ cfg.config_dir = dirPtr.baseAddress
+ cfg.config_dir_len = dirBytes.count
+ created = finishCreate(&cfg, cols: cols, rows: rows)
+ }
+ } else {
+ created = finishCreate(&cfg, cols: cols, rows: rows)
+ }
+ }
+ }
+ return created
+ }
+
+ private func finishCreate(_ cfg: inout OmacySessionConfig, cols: UInt32, rows: UInt32) -> Bool {
+ var out: OpaquePointer?
+ let status = omacy_session_create(&cfg, cols, rows, &out)
+ if status == OMACY_OK, let out {
+ session = out
+ return true
+ }
+ log.error("session create failed: \(String(describing: status), privacy: .public)")
+ return false
+ }
+
+ private func recoverDeadSession() {
+ let geometryCols = pendingCols ?? cols
+ let geometryRows = pendingRows ?? rows
+ if createSession(cols: geometryCols, rows: geometryRows, settings: lastSettings, art: lastArt) {
+ cols = geometryCols
+ rows = geometryRows
+ pendingCols = nil
+ pendingRows = nil
+ return
+ }
+ failToCanary()
+ }
+
+ private func failToCanary() {
+ stopSessionAndLink()
+ stopped = true
+ metalLayer = nil
+ if let view {
+ installPlainLayer(on: view)
+ }
+ onEngineUnavailable?()
+ }
+
+ private func stopSessionAndLink() {
+ destroySession()
+ displayLink?.invalidate()
+ displayLink = nil
+ lastTimestamp = nil
+ }
+
+ private func destroySession() {
+ if let session {
+ omacy_session_destroy(session)
+ self.session = nil
+ }
+ }
+
+ private func installPlainLayer(on view: NSView) {
+ let layer = CALayer()
+ layer.backgroundColor = NSColor.black.cgColor
+ layer.isOpaque = true
+ view.layer = layer
+ metalLayer = nil
+ }
+
+ private func installMetal(on view: NSView, font: NSFont, cell: CGSize) -> Bool {
+ guard let device = MTLCreateSystemDefaultDevice() else {
+ log.error("no Metal device")
+ return false
+ }
+ self.device = device
+ queue = device.makeCommandQueue()
+ let scale = view.window?.backingScaleFactor ?? view.layer?.contentsScale ?? 2
+ let container = CALayer()
+ container.backgroundColor = NSColor.black.cgColor
+ container.isOpaque = true
+ let layer = CAMetalLayer()
+ layer.device = device
+ layer.pixelFormat = .bgra8Unorm
+ layer.framebufferOnly = true
+ layer.isOpaque = true
+ layer.contentsScale = scale
+ layer.drawableSize = OmacyLayout.drawableSize(viewSize: view.bounds.size, scale: scale)
+ layer.frame = view.bounds
+ layer.autoresizingMask = [.layerWidthSizable, .layerHeightSizable]
+ view.layer = container
+ container.addSublayer(layer)
+ metalLayer = layer
+ pipeline = makePipeline(device: device)
+ atlas.rebuild(device: device, font: font, cell: cell, scale: scale)
+ return pipeline != nil
+ }
+
+ private func makePipeline(device: MTLDevice) -> MTLRenderPipelineState? {
+ guard let library = device.makeDefaultLibrary() else { return nil }
+ return build(device: device, library: library)
+ }
+
+ private func build(device: MTLDevice, library: MTLLibrary) -> MTLRenderPipelineState? {
+ let desc = MTLRenderPipelineDescriptor()
+ desc.vertexFunction = library.makeFunction(name: "omacy_vertex")
+ desc.fragmentFunction = library.makeFunction(name: "omacy_fragment")
+ desc.colorAttachments[0].pixelFormat = .bgra8Unorm
+ desc.colorAttachments[0].isBlendingEnabled = true
+ desc.colorAttachments[0].sourceRGBBlendFactor = .sourceAlpha
+ desc.colorAttachments[0].destinationRGBBlendFactor = .oneMinusSourceAlpha
+ desc.colorAttachments[0].sourceAlphaBlendFactor = .one
+ desc.colorAttachments[0].destinationAlphaBlendFactor = .oneMinusSourceAlpha
+ return try? device.makeRenderPipelineState(descriptor: desc)
+ }
+}
diff --git a/apps/Omacy/Shared/OmacyShaders.metal b/apps/Omacy/Shared/OmacyShaders.metal
new file mode 100644
index 0000000..8269bdf
--- /dev/null
+++ b/apps/Omacy/Shared/OmacyShaders.metal
@@ -0,0 +1,45 @@
+#include
+using namespace metal;
+
+struct Instance {
+ float2 origin;
+ float2 size;
+ float2 uvOrigin;
+ float2 uvSize;
+ float4 color;
+};
+
+struct VertexOut {
+ float4 position [[position]];
+ float2 uv;
+ float4 color;
+};
+
+vertex VertexOut omacy_vertex(uint vid [[vertex_id]],
+ uint iid [[instance_id]],
+ constant Instance *instances [[buffer(0)]],
+ constant float2 &viewport [[buffer(1)]]) {
+ const float2 corners[6] = {
+ float2(0.0, 0.0), float2(1.0, 0.0), float2(0.0, 1.0),
+ float2(1.0, 0.0), float2(1.0, 1.0), float2(0.0, 1.0)
+ };
+ Instance inst = instances[iid];
+ float2 pixel = inst.origin + corners[vid] * inst.size;
+ VertexOut out;
+ out.position = float4(
+ pixel.x / viewport.x * 2.0 - 1.0,
+ 1.0 - pixel.y / viewport.y * 2.0,
+ 0.0,
+ 1.0
+ );
+ out.uv = inst.uvOrigin + corners[vid] * inst.uvSize;
+ out.color = inst.color;
+ return out;
+}
+
+fragment float4 omacy_fragment(VertexOut in [[stage_in]],
+ texture2d atlas [[texture(0)]]) {
+ constexpr sampler s(address::clamp_to_edge, filter::linear);
+ float coverage = atlas.sample(s, in.uv).a;
+ return float4(in.color.rgb, in.color.a * coverage);
+}
diff --git a/apps/Omacy/Shared/OmacyStore.swift b/apps/Omacy/Shared/OmacyStore.swift
new file mode 100644
index 0000000..efbefc9
--- /dev/null
+++ b/apps/Omacy/Shared/OmacyStore.swift
@@ -0,0 +1,136 @@
+import Foundation
+import AppKit
+
+struct OmacySettings: Equatable {
+ var effect: String = "random"
+ var background: String = "#000000"
+ var fontSize: Double = 18
+ var asciiMode: String = "braille"
+ var threshold: Int = 50
+ var invert: Bool = false
+
+ var backgroundRGBA: (UInt8, UInt8, UInt8, UInt8) {
+ let hex = background.trimmingCharacters(in: CharacterSet(charactersIn: "#"))
+ guard hex.count == 6, let n = UInt32(hex, radix: 16) else {
+ return (0, 0, 0, 255)
+ }
+ return (UInt8((n >> 16) & 0xFF), UInt8((n >> 8) & 0xFF), UInt8(n & 0xFF), 255)
+ }
+
+ var asciiModeCode: UInt32 {
+ asciiMode == "block" ? 1 : 0
+ }
+}
+
+extension Notification.Name {
+ static let omacyConfigDidChange = Notification.Name("omacy.configDidChange")
+}
+
+enum OmacyStore {
+ static let appGroup = "group.be.zenjoy.omacy"
+ static let forceCanaryKey = "omacy.forceCanary"
+
+ private static var lastGoodSettings = OmacySettings()
+ private static var lastGoodArt: String?
+ static private(set) var lastLoadError: String?
+
+ static var containerURL: URL? {
+ FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: appGroup)
+ }
+
+ static var settingsURL: URL? { containerURL?.appendingPathComponent("settings.json") }
+ static var artURL: URL? { containerURL?.appendingPathComponent("screensaver.txt") }
+
+ static var bundledArt: String {
+ if let url = Bundle.main.url(forResource: "screensaver", withExtension: "txt", subdirectory: nil)
+ ?? Bundle.main.url(forResource: "screensaver", withExtension: "txt"),
+ let text = try? String(contentsOf: url, encoding: .utf8) {
+ return text
+ }
+ return "OMACY"
+ }
+
+ static var bundledFontURL: URL? {
+ Bundle.main.url(forResource: "FairfaxHD", withExtension: "ttf")
+ ?? Bundle.main.url(forResource: "Fairfax", withExtension: "ttf")
+ }
+
+ static func loadSettings() -> OmacySettings {
+ guard let url = settingsURL else { return lastGoodSettings }
+ guard FileManager.default.fileExists(atPath: url.path) else { return lastGoodSettings }
+ do {
+ let data = try Data(contentsOf: url)
+ guard let obj = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+ lastLoadError = "settings.json is invalid; keeping last-known-good"
+ return lastGoodSettings
+ }
+ var s = OmacySettings()
+ if let effect = obj["effect"] as? String { s.effect = effect }
+ if let background = obj["background"] as? String { s.background = background }
+ if let fontSize = obj["fontSize"] as? Double { s.fontSize = fontSize }
+ if let asciiMode = obj["asciiMode"] as? String { s.asciiMode = asciiMode }
+ if let threshold = obj["threshold"] as? Int { s.threshold = threshold }
+ if let invert = obj["invert"] as? Bool { s.invert = invert }
+ lastGoodSettings = s
+ lastLoadError = nil
+ return s
+ } catch {
+ lastLoadError = "Could not read settings.json; keeping last-known-good"
+ return lastGoodSettings
+ }
+ }
+
+ static func loadArt() -> String {
+ if let url = artURL {
+ if let text = try? String(contentsOf: url, encoding: .utf8), !text.isEmpty {
+ lastGoodArt = text
+ return text
+ }
+ }
+ if let lastGoodArt { return lastGoodArt }
+ return bundledArt
+ }
+
+ static func save(settings: OmacySettings, art: String) throws {
+ guard let dir = containerURL else {
+ throw NSError(domain: "Omacy", code: 1, userInfo: [NSLocalizedDescriptionKey: "App Group container missing"])
+ }
+ try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+ let payload: [String: Any] = [
+ "effect": settings.effect,
+ "background": settings.background,
+ "fontSize": settings.fontSize,
+ "asciiMode": settings.asciiMode,
+ "threshold": settings.threshold,
+ "invert": settings.invert
+ ]
+ let data = try JSONSerialization.data(withJSONObject: payload, options: [.prettyPrinted, .sortedKeys])
+ try atomicWrite(data, to: settingsURL!)
+ try atomicWrite(Data(art.utf8), to: artURL!)
+ lastGoodSettings = settings
+ lastGoodArt = art
+ lastLoadError = nil
+ NotificationCenter.default.post(name: .omacyConfigDidChange, object: nil)
+ }
+
+ static func restoreDefaultArt() throws {
+ try save(settings: loadSettings(), art: bundledArt)
+ }
+
+ static var forceCanary: Bool {
+ UserDefaults.standard.bool(forKey: forceCanaryKey)
+ }
+
+ private static func atomicWrite(_ data: Data, to url: URL) throws {
+ let tmp = url.deletingLastPathComponent().appendingPathComponent(".\(url.lastPathComponent).tmp")
+ if FileManager.default.fileExists(atPath: tmp.path) {
+ try FileManager.default.removeItem(at: tmp)
+ }
+ try data.write(to: tmp)
+ if FileManager.default.fileExists(atPath: url.path) {
+ _ = try FileManager.default.replaceItemAt(url, withItemAt: tmp)
+ } else {
+ try FileManager.default.moveItem(at: tmp, to: url)
+ }
+ }
+}
diff --git a/apps/Omacy/scripts/build-engine.sh b/apps/Omacy/scripts/build-engine.sh
new file mode 100755
index 0000000..9eefa17
--- /dev/null
+++ b/apps/Omacy/scripts/build-engine.sh
@@ -0,0 +1,31 @@
+#!/bin/sh
+# Xcode run script: build libomacy_engine.a for the active Mac architecture.
+# Xcode script phases reset PATH to Apple's toolchain dirs, so rustup/cargo
+# from the developer machine or GitHub Actions must be put back explicitly.
+set -euo pipefail
+CARGO_BIN="${CARGO_HOME:-$HOME/.cargo}/bin"
+export PATH="${CARGO_BIN}:/opt/homebrew/bin:/usr/local/bin:${PATH}"
+if [ -f "${HOME}/.cargo/env" ]; then
+ # shellcheck source=/dev/null
+ . "${HOME}/.cargo/env"
+fi
+if ! command -v cargo >/dev/null 2>&1; then
+ echo "error: cargo not found on PATH=${PATH}" >&2
+ echo "error: install Rust 1.88.0 via rustup, then rebuild" >&2
+ exit 1
+fi
+ROOT="${SRCROOT}/../.."
+cd "$ROOT"
+ARCHS_EFFECTIVE="${ARCHS:-arm64}"
+case "$ARCHS_EFFECTIVE" in
+ *arm64*) RUST_TARGET="aarch64-apple-darwin" ;;
+ *x86_64*) RUST_TARGET="x86_64-apple-darwin" ;;
+ *) RUST_TARGET="aarch64-apple-darwin" ;;
+esac
+export MACOSX_DEPLOYMENT_TARGET="${MACOSX_DEPLOYMENT_TARGET:-15.0}"
+if command -v rustup >/dev/null 2>&1; then
+ rustup target add "$RUST_TARGET" >/dev/null 2>&1 || true
+fi
+cargo build --release --target "$RUST_TARGET" -p omacy-engine
+mkdir -p "${BUILT_PRODUCTS_DIR}"
+cp -f "target/${RUST_TARGET}/release/libomacy_engine.a" "${BUILT_PRODUCTS_DIR}/libomacy_engine.a"
diff --git a/assets/branding/screensaver.txt b/assets/branding/screensaver.txt
new file mode 100644
index 0000000..47433aa
--- /dev/null
+++ b/assets/branding/screensaver.txt
@@ -0,0 +1,10 @@
+ ▄▄▄
+ ▄█████▄ ▄███████████▄ ▄███████ ▄███████ ▄███████ ▄█ █▄ ▄█ █▄
+███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███
+███ ███ ███ ███ ███ ███ ███ ███ ███ ███ █▀ ███ ███ ███ ███
+███ ███ ███ ███ ███ ▄███▄▄▄███ ▄███▄▄▄██▀ ███ ▄███▄▄▄███▄ ███▄▄▄███
+███ ███ ███ ███ ███ ▀███▀▀▀███ ▀███▀▀▀▀ ███ ▀▀███▀▀▀███ ▀▀▀▀▀▀███
+███ ███ ███ ███ ███ ███ ███ ██████████ ███ █▄ ███ ███ ▄██ ███
+███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███ ███
+ ▀█████▀ ▀█ ███ █▀ ███ █▀ ███ ███ ███████▀ ███ █▀ ▀█████▀
+ ███ █▀
diff --git a/assets/fixtures/asymmetric.txt b/assets/fixtures/asymmetric.txt
new file mode 100644
index 0000000..e14d4a9
--- /dev/null
+++ b/assets/fixtures/asymmetric.txt
@@ -0,0 +1,3 @@
+X
+
+ Y
\ No newline at end of file
diff --git a/assets/fixtures/conversion/alpha-logo.braille.t50.inv0.trim1.txt b/assets/fixtures/conversion/alpha-logo.braille.t50.inv0.trim1.txt
new file mode 100644
index 0000000..a768787
--- /dev/null
+++ b/assets/fixtures/conversion/alpha-logo.braille.t50.inv0.trim1.txt
@@ -0,0 +1,4 @@
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
\ No newline at end of file
diff --git a/assets/fixtures/conversion/alpha-logo.png b/assets/fixtures/conversion/alpha-logo.png
new file mode 100644
index 0000000..a56f178
Binary files /dev/null and b/assets/fixtures/conversion/alpha-logo.png differ
diff --git a/assets/fixtures/conversion/logo.svg b/assets/fixtures/conversion/logo.svg
new file mode 100644
index 0000000..48d95ec
--- /dev/null
+++ b/assets/fixtures/conversion/logo.svg
@@ -0,0 +1,3 @@
+
\ No newline at end of file
diff --git a/assets/fixtures/conversion/logo.svg.braille.t50.inv0.trim1.txt b/assets/fixtures/conversion/logo.svg.braille.t50.inv0.trim1.txt
new file mode 100644
index 0000000..a768787
--- /dev/null
+++ b/assets/fixtures/conversion/logo.svg.braille.t50.inv0.trim1.txt
@@ -0,0 +1,4 @@
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
\ No newline at end of file
diff --git a/assets/fixtures/conversion/manifest.md b/assets/fixtures/conversion/manifest.md
new file mode 100644
index 0000000..4d79787
--- /dev/null
+++ b/assets/fixtures/conversion/manifest.md
@@ -0,0 +1,21 @@
+# Conversion goldens
+
+Each row is one accepted `(input, mode, threshold, invert, trim)` tuple.
+Omacy’s ascii module must emit the committed `.txt` byte-for-byte.
+
+| Input | Mode | threshold | invert | trim | Expected |
+|---|---|---|---|---|---|
+| `solid-black-on-white.png` | braille | 50 | 0 | 1 | `solid-black-on-white.braille.t50.inv0.trim1.txt` |
+| `solid-black-on-white.png` | block | 50 | 0 | 1 | `solid-black-on-white.block.t50.inv0.trim1.txt` |
+| `solid-black-on-white.png` | braille | 50 | 1 | 1 | `solid-black-on-white.braille.t50.inv1.trim1.txt` |
+| `solid-black-on-white.png` | block | 80 | 0 | 0 | `solid-black-on-white.block.t80.inv0.trim0.txt` |
+| `alpha-logo.png` | braille | 50 | 0 | 1 | `alpha-logo.braille.t50.inv0.trim1.txt` |
+| `logo.svg` | braille | 50 | 0 | 1 | `logo.svg.braille.t50.inv0.trim1.txt` |
+
+Regeneration (manual, reviewed):
+
+```
+cargo run -p omacy-engine --example write_conversion_fixtures
+```
+
+Do not replay live ImageMagick in CI. The Omarchy converter SHA is recorded in [parity.md](../../../docs/parity.md).
diff --git a/assets/fixtures/conversion/solid-black-on-white.block.t50.inv0.trim1.txt b/assets/fixtures/conversion/solid-black-on-white.block.t50.inv0.trim1.txt
new file mode 100644
index 0000000..a2ccd30
--- /dev/null
+++ b/assets/fixtures/conversion/solid-black-on-white.block.t50.inv0.trim1.txt
@@ -0,0 +1,4 @@
+████████
+████████
+████████
+████████
\ No newline at end of file
diff --git a/assets/fixtures/conversion/solid-black-on-white.block.t80.inv0.trim0.txt b/assets/fixtures/conversion/solid-black-on-white.block.t80.inv0.trim0.txt
new file mode 100644
index 0000000..ddd38d5
--- /dev/null
+++ b/assets/fixtures/conversion/solid-black-on-white.block.t80.inv0.trim0.txt
@@ -0,0 +1,4 @@
+ ████████
+ ████████
+ ████████
+ ████████
\ No newline at end of file
diff --git a/assets/fixtures/conversion/solid-black-on-white.braille.t50.inv0.trim1.txt b/assets/fixtures/conversion/solid-black-on-white.braille.t50.inv0.trim1.txt
new file mode 100644
index 0000000..a768787
--- /dev/null
+++ b/assets/fixtures/conversion/solid-black-on-white.braille.t50.inv0.trim1.txt
@@ -0,0 +1,4 @@
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
\ No newline at end of file
diff --git a/assets/fixtures/conversion/solid-black-on-white.braille.t50.inv1.trim1.txt b/assets/fixtures/conversion/solid-black-on-white.braille.t50.inv1.trim1.txt
new file mode 100644
index 0000000..8199d25
--- /dev/null
+++ b/assets/fixtures/conversion/solid-black-on-white.braille.t50.inv1.trim1.txt
@@ -0,0 +1,4 @@
+⣿⣿⣿⣿⣿⣿⣿⣿
+⣿⣿ ⣿⣿
+⣿⣿ ⣿⣿
+⣿⣿⣿⣿⣿⣿⣿⣿
\ No newline at end of file
diff --git a/assets/fixtures/conversion/solid-black-on-white.png b/assets/fixtures/conversion/solid-black-on-white.png
new file mode 100644
index 0000000..3b16944
Binary files /dev/null and b/assets/fixtures/conversion/solid-black-on-white.png differ
diff --git a/assets/fonts/FairfaxHD.ttf b/assets/fonts/FairfaxHD.ttf
new file mode 100644
index 0000000..844fc92
Binary files /dev/null and b/assets/fonts/FairfaxHD.ttf differ
diff --git a/assets/fonts/OFL.txt b/assets/fonts/OFL.txt
new file mode 100644
index 0000000..a694297
--- /dev/null
+++ b/assets/fonts/OFL.txt
@@ -0,0 +1,93 @@
+Copyright (c) 2017-2020 Kreative Software.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/crates/omacy-engine/Cargo.toml b/crates/omacy-engine/Cargo.toml
new file mode 100644
index 0000000..1e3cb56
--- /dev/null
+++ b/crates/omacy-engine/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "omacy-engine"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+publish = false
+
+[lib]
+name = "omacy_engine"
+crate-type = ["rlib", "staticlib"]
+
+[dependencies]
+libc = "0.2"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+image = { version = "0.25", default-features = false, features = ["png"] }
+resvg = "0.45"
+tiny-skia = "0.11"
+ttfx = { path = "../../vendor/ttfx" }
+
+[dev-dependencies]
+image = { version = "0.25", default-features = false, features = ["png"] }
diff --git a/crates/omacy-engine/examples/write_conversion_fixtures.rs b/crates/omacy-engine/examples/write_conversion_fixtures.rs
new file mode 100644
index 0000000..047d3e3
--- /dev/null
+++ b/crates/omacy-engine/examples/write_conversion_fixtures.rs
@@ -0,0 +1,117 @@
+//! Generate committed conversion goldens. Run from repo root:
+//! `cargo run -p omacy-engine --example write_conversion_fixtures`
+
+use omacy_engine::abi::{OmacyAsciiConfig, OMACY_ASCII_BLOCK, OMACY_ASCII_BRAILLE};
+use omacy_engine::ascii::ascii_from_bytes;
+use std::fs;
+use std::path::PathBuf;
+
+fn repo_root() -> PathBuf {
+ PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..")
+}
+
+fn solid_png(w: u32, h: u32, bg: [u8; 4], fg: [u8; 4]) -> Vec {
+ let mut img = image::RgbaImage::from_pixel(w, h, image::Rgba(bg));
+ for y in h / 4..h * 3 / 4 {
+ for x in w / 4..w * 3 / 4 {
+ img.put_pixel(x, y, image::Rgba(fg));
+ }
+ }
+ let mut buf = Vec::new();
+ image::DynamicImage::ImageRgba8(img)
+ .write_to(&mut std::io::Cursor::new(&mut buf), image::ImageFormat::Png)
+ .unwrap();
+ buf
+}
+
+fn alpha_png(w: u32, h: u32) -> Vec {
+ let mut img = image::RgbaImage::from_pixel(w, h, image::Rgba([0, 0, 0, 0]));
+ for y in h / 4..h * 3 / 4 {
+ for x in w / 4..w * 3 / 4 {
+ img.put_pixel(x, y, image::Rgba([255, 255, 255, 255]));
+ }
+ }
+ let mut buf = Vec::new();
+ image::DynamicImage::ImageRgba8(img)
+ .write_to(&mut std::io::Cursor::new(&mut buf), image::ImageFormat::Png)
+ .unwrap();
+ buf
+}
+
+fn cfg(mode: u32, width: u32, height: u32, threshold: u8, invert: u8, trim: u8) -> OmacyAsciiConfig {
+ OmacyAsciiConfig {
+ mode,
+ width,
+ height,
+ threshold,
+ invert,
+ trim,
+ _pad: 0,
+ }
+}
+
+fn write_pair(dir: &std::path::Path, stem: &str, bytes: &[u8], c: OmacyAsciiConfig, label: &str) {
+ let text = ascii_from_bytes(c, bytes).expect(label);
+ fs::write(dir.join(format!("{stem}.{label}.txt")), text).unwrap();
+}
+
+fn main() {
+ let dir = repo_root().join("assets/fixtures/conversion");
+ fs::create_dir_all(&dir).unwrap();
+
+ let opaque = solid_png(32, 32, [255, 255, 255, 255], [0, 0, 0, 255]);
+ fs::write(dir.join("solid-black-on-white.png"), &opaque).unwrap();
+
+ let alpha = alpha_png(32, 32);
+ fs::write(dir.join("alpha-logo.png"), &alpha).unwrap();
+
+ let svg = r#""#;
+ fs::write(dir.join("logo.svg"), svg).unwrap();
+
+ write_pair(
+ &dir,
+ "solid-black-on-white",
+ &opaque,
+ cfg(OMACY_ASCII_BRAILLE, 8, 4, 50, 0, 1),
+ "braille.t50.inv0.trim1",
+ );
+ write_pair(
+ &dir,
+ "solid-black-on-white",
+ &opaque,
+ cfg(OMACY_ASCII_BLOCK, 8, 4, 50, 0, 1),
+ "block.t50.inv0.trim1",
+ );
+ write_pair(
+ &dir,
+ "solid-black-on-white",
+ &opaque,
+ cfg(OMACY_ASCII_BRAILLE, 8, 4, 50, 1, 1),
+ "braille.t50.inv1.trim1",
+ );
+ write_pair(
+ &dir,
+ "solid-black-on-white",
+ &opaque,
+ cfg(OMACY_ASCII_BLOCK, 16, 8, 80, 0, 0),
+ "block.t80.inv0.trim0",
+ );
+ write_pair(
+ &dir,
+ "alpha-logo",
+ &alpha,
+ cfg(OMACY_ASCII_BRAILLE, 8, 4, 50, 0, 1),
+ "braille.t50.inv0.trim1",
+ );
+ write_pair(
+ &dir,
+ "logo.svg",
+ svg.as_bytes(),
+ cfg(OMACY_ASCII_BRAILLE, 8, 4, 50, 0, 1),
+ "braille.t50.inv0.trim1",
+ );
+
+ println!("wrote {}", dir.display());
+}
diff --git a/crates/omacy-engine/include/omacy.h b/crates/omacy-engine/include/omacy.h
new file mode 100644
index 0000000..c43d121
--- /dev/null
+++ b/crates/omacy-engine/include/omacy.h
@@ -0,0 +1,111 @@
+#ifndef OMACY_H
+#define OMACY_H
+
+#include
+#include
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+ OMACY_OK = 0,
+ OMACY_ERR_NULL = 1,
+ OMACY_ERR_INVALID_ARG = 2,
+ OMACY_ERR_LIMIT = 3,
+ OMACY_ERR_ENGINE = 4,
+ OMACY_ERR_PANIC = 5,
+ OMACY_ERR_DEAD = 6,
+ OMACY_ERR_WRONG_THREAD = 7
+} omacy_status;
+
+#define OMACY_CELL_HAS_BACKGROUND 1
+#define OMACY_CELL_HAS_GLYPH 2
+
+typedef struct {
+ uint32_t glyph;
+ uint8_t fg_r, fg_g, fg_b, fg_a;
+ uint8_t bg_r, bg_g, bg_b, bg_a;
+ uint8_t flags;
+ uint8_t occupancy;
+ uint8_t _pad[2];
+} OmacyCell;
+
+typedef struct {
+ uint32_t cols;
+ uint32_t rows;
+ uint8_t clear_r, clear_g, clear_b, clear_a;
+ uint32_t _pad;
+ const OmacyCell *cells;
+} OmacyFrame;
+
+typedef struct {
+ OmacyFrame frame;
+ uint8_t needs_begin_next;
+ uint8_t _pad[3];
+} OmacyStepResult;
+
+typedef struct {
+ const uint8_t *config_dir;
+ size_t config_dir_len;
+ const uint8_t *ascii;
+ size_t ascii_len;
+ const uint8_t *effect;
+ size_t effect_len;
+ uint8_t bg_r, bg_g, bg_b, bg_a;
+ uint8_t has_seed;
+ uint8_t _pad[3];
+ uint64_t seed;
+} OmacySessionConfig;
+
+typedef struct {
+ const uint8_t *ascii;
+ size_t ascii_len;
+ const uint8_t *effect;
+ size_t effect_len;
+ uint8_t bg_r, bg_g, bg_b, bg_a;
+ uint8_t _pad[3];
+} OmacyPendingConfig;
+
+#define OMACY_ASCII_BRAILLE 0u
+#define OMACY_ASCII_BLOCK 1u
+
+typedef struct {
+ uint32_t mode;
+ uint32_t width;
+ uint32_t height;
+ uint8_t threshold;
+ uint8_t invert;
+ uint8_t trim;
+ uint8_t _pad;
+} OmacyAsciiConfig;
+
+typedef struct OmacySession OmacySession;
+typedef struct OmacyText OmacyText;
+
+omacy_status omacy_session_create(const OmacySessionConfig *cfg,
+ uint32_t cols, uint32_t rows,
+ OmacySession **out);
+omacy_status omacy_session_resize(OmacySession *s, uint32_t cols, uint32_t rows);
+omacy_status omacy_session_step(OmacySession *s, double elapsed_seconds,
+ OmacyStepResult *out);
+omacy_status omacy_session_set_pending_config(OmacySession *s,
+ const OmacyPendingConfig *cfg);
+omacy_status omacy_session_begin_next(OmacySession *s);
+omacy_status omacy_session_generation(const OmacySession *s, uint64_t *out);
+omacy_status omacy_session_error_message(const OmacySession *s, char *buf, size_t buf_len);
+void omacy_session_destroy(OmacySession *s);
+const char *omacy_status_string(omacy_status status);
+
+omacy_status omacy_ascii_from_bytes(const OmacyAsciiConfig *cfg,
+ const uint8_t *bytes, size_t len,
+ OmacyText **out);
+void omacy_text_free(OmacyText *t);
+const char *omacy_text_utf8(const OmacyText *t);
+size_t omacy_text_len(const OmacyText *t);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif
diff --git a/crates/omacy-engine/src/abi.rs b/crates/omacy-engine/src/abi.rs
new file mode 100644
index 0000000..f79cb3f
--- /dev/null
+++ b/crates/omacy-engine/src/abi.rs
@@ -0,0 +1,155 @@
+use std::os::raw::c_char;
+
+use ttfx::engine::PackedCell;
+
+pub type OmacyCell = PackedCell;
+
+pub const OMACY_CELL_HAS_BACKGROUND: u8 = ttfx::engine::CELL_HAS_BACKGROUND;
+pub const OMACY_CELL_HAS_GLYPH: u8 = ttfx::engine::CELL_HAS_GLYPH;
+
+pub const OMACY_ASCII_BRAILLE: u32 = 0;
+pub const OMACY_ASCII_BLOCK: u32 = 1;
+
+#[repr(C)]
+#[derive(Clone, Copy, Debug)]
+pub struct OmacyFrame {
+ pub cols: u32,
+ pub rows: u32,
+ pub clear_r: u8,
+ pub clear_g: u8,
+ pub clear_b: u8,
+ pub clear_a: u8,
+ pub _pad: u32,
+ pub cells: *const OmacyCell,
+}
+
+impl OmacyFrame {
+ pub fn zeroed() -> Self {
+ Self {
+ cols: 0,
+ rows: 0,
+ clear_r: 0,
+ clear_g: 0,
+ clear_b: 0,
+ clear_a: 0,
+ _pad: 0,
+ cells: std::ptr::null(),
+ }
+ }
+}
+
+#[repr(C)]
+#[derive(Clone, Copy)]
+pub struct OmacyStepResult {
+ pub frame: OmacyFrame,
+ pub needs_begin_next: u8,
+ pub _pad: [u8; 3],
+}
+
+impl OmacyStepResult {
+ pub fn zeroed() -> Self {
+ Self {
+ frame: OmacyFrame::zeroed(),
+ needs_begin_next: 0,
+ _pad: [0; 3],
+ }
+ }
+}
+
+#[repr(C)]
+pub struct OmacySessionConfig {
+ pub config_dir: *const u8,
+ pub config_dir_len: usize,
+ pub ascii: *const u8,
+ pub ascii_len: usize,
+ pub effect: *const u8,
+ pub effect_len: usize,
+ pub bg_r: u8,
+ pub bg_g: u8,
+ pub bg_b: u8,
+ pub bg_a: u8,
+ pub has_seed: u8,
+ pub _pad: [u8; 3],
+ pub seed: u64,
+}
+
+#[repr(C)]
+pub struct OmacyPendingConfig {
+ pub ascii: *const u8,
+ pub ascii_len: usize,
+ pub effect: *const u8,
+ pub effect_len: usize,
+ pub bg_r: u8,
+ pub bg_g: u8,
+ pub bg_b: u8,
+ pub bg_a: u8,
+ pub _pad: [u8; 3],
+}
+
+#[repr(C)]
+#[derive(Clone, Copy)]
+pub struct OmacyAsciiConfig {
+ pub mode: u32,
+ pub width: u32,
+ pub height: u32,
+ pub threshold: u8,
+ pub invert: u8,
+ pub trim: u8,
+ pub _pad: u8,
+}
+
+#[repr(C)]
+pub struct OmacyText {
+ pub bytes: Vec,
+}
+
+pub unsafe fn slice_ptr_len<'a>(
+ ptr: *const u8,
+ len: usize,
+) -> Result, super::status::EngineError> {
+ if ptr.is_null() {
+ if len == 0 {
+ Ok(None)
+ } else {
+ Err(super::status::EngineError::InvalidArg(
+ "null pointer with nonzero length".into(),
+ ))
+ }
+ } else {
+ Ok(Some(std::slice::from_raw_parts(ptr, len)))
+ }
+}
+
+pub fn c_str_static(s: &'static str) -> *const c_char {
+ s.as_ptr() as *const c_char
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::mem::{align_of, offset_of, size_of};
+
+ #[test]
+ fn cell_layout() {
+ assert_eq!(size_of::(), 16);
+ assert_eq!(align_of::(), 4);
+ assert_eq!(offset_of!(OmacyCell, glyph), 0);
+ assert_eq!(offset_of!(OmacyCell, occupancy), 13);
+ }
+
+ #[test]
+ fn ascii_config_layout() {
+ assert_eq!(size_of::(), 16);
+ assert_eq!(align_of::(), 4);
+ assert_eq!(offset_of!(OmacyAsciiConfig, mode), 0);
+ assert_eq!(offset_of!(OmacyAsciiConfig, threshold), 12);
+ }
+
+ #[test]
+ fn occupancy_constants_match_ttfx() {
+ assert_eq!(OMACY_CELL_HAS_BACKGROUND, 1);
+ assert_eq!(OMACY_CELL_HAS_GLYPH, 2);
+ assert_eq!(OMACY_CELL_HAS_BACKGROUND, ttfx::engine::CELL_HAS_BACKGROUND);
+ assert_eq!(OMACY_CELL_HAS_GLYPH, ttfx::engine::CELL_HAS_GLYPH);
+ }
+}
diff --git a/crates/omacy-engine/src/ascii.rs b/crates/omacy-engine/src/ascii.rs
new file mode 100644
index 0000000..b33b70c
--- /dev/null
+++ b/crates/omacy-engine/src/ascii.rs
@@ -0,0 +1,306 @@
+use std::io::Cursor;
+
+use image::{DynamicImage, GenericImageView, ImageFormat, RgbaImage};
+use resvg::{tiny_skia, usvg};
+
+use crate::abi::{OmacyAsciiConfig, OMACY_ASCII_BLOCK, OMACY_ASCII_BRAILLE};
+use crate::limits;
+use crate::status::EngineError;
+
+pub fn validate_ascii_config(cfg: OmacyAsciiConfig) -> Result {
+ if cfg.mode != OMACY_ASCII_BRAILLE && cfg.mode != OMACY_ASCII_BLOCK {
+ return Err(EngineError::InvalidArg("ascii mode must be braille or block".into()));
+ }
+ if cfg.width < 1 || cfg.width > limits::CONV_COLUMNS {
+ return Err(EngineError::Limit("conversion width out of range".into()));
+ }
+ if cfg.height < 1 || cfg.height > limits::CONV_ROWS {
+ return Err(EngineError::Limit("conversion height out of range".into()));
+ }
+ let cells = cfg
+ .width
+ .checked_mul(cfg.height)
+ .ok_or_else(|| EngineError::Limit("conversion cell count overflow".into()))?;
+ if cells > limits::CONV_CELLS {
+ return Err(EngineError::Limit("conversion cell count exceeds cap".into()));
+ }
+ if cfg.threshold > 100 {
+ return Err(EngineError::InvalidArg("threshold must be 0..=100".into()));
+ }
+ if cfg.invert > 1 || cfg.trim > 1 {
+ return Err(EngineError::InvalidArg("invert and trim must be 0 or 1".into()));
+ }
+ Ok(cfg)
+}
+
+pub fn ascii_from_bytes(cfg: OmacyAsciiConfig, bytes: &[u8]) -> Result {
+ let cfg = validate_ascii_config(cfg)?;
+ if bytes.len() > limits::PNG_BYTES && looks_like_png(bytes) {
+ return Err(EngineError::Limit("PNG exceeds 8 MiB".into()));
+ }
+ if !looks_like_png(bytes) && bytes.len() > limits::SVG_BYTES {
+ return Err(EngineError::Limit("SVG exceeds 2 MiB".into()));
+ }
+ let image = if looks_like_png(bytes) {
+ decode_png(bytes)?
+ } else {
+ decode_svg(bytes)?
+ };
+ raster_to_text(&image, cfg)
+}
+
+fn looks_like_png(bytes: &[u8]) -> bool {
+ bytes.starts_with(&[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A])
+}
+
+fn decode_png(bytes: &[u8]) -> Result {
+ if bytes.len() > limits::PNG_BYTES {
+ return Err(EngineError::Limit("PNG exceeds 8 MiB".into()));
+ }
+ let img = image::load(Cursor::new(bytes), ImageFormat::Png)
+ .map_err(|e| EngineError::Engine(e.to_string()))?;
+ let (w, h) = img.dimensions();
+ let pixels = w
+ .checked_mul(h)
+ .ok_or_else(|| EngineError::Limit("decoded pixel overflow".into()))?;
+ if pixels > limits::DECODED_PIXELS {
+ return Err(EngineError::Limit("decoded pixels exceed cap".into()));
+ }
+ Ok(img.to_rgba8())
+}
+
+fn decode_svg(bytes: &[u8]) -> Result {
+ if bytes.len() > limits::SVG_BYTES {
+ return Err(EngineError::Limit("SVG exceeds 2 MiB".into()));
+ }
+ let mut options = usvg::Options {
+ resources_dir: None,
+ image_href_resolver: usvg::ImageHrefResolver {
+ resolve_data: Box::new(|_, _, _| None),
+ resolve_string: Box::new(|_, _| None),
+ },
+ ..usvg::Options::default()
+ };
+ options.fontdb_mut().set_serif_family("");
+ options.fontdb_mut().set_sans_serif_family("");
+ options.fontdb_mut().set_cursive_family("");
+ options.fontdb_mut().set_fantasy_family("");
+ options.fontdb_mut().set_monospace_family("");
+ let tree = usvg::Tree::from_data(bytes, &options)
+ .map_err(|e| EngineError::Engine(e.to_string()))?;
+ if count_svg_nodes(&tree.root()) > limits::SVG_ELEMENTS {
+ return Err(EngineError::Limit("SVG element count exceeds cap".into()));
+ }
+ let size = tree.size();
+ let width = size.width().ceil().max(1.0) as u32;
+ let height = size.height().ceil().max(1.0) as u32;
+ let pixels = width
+ .checked_mul(height)
+ .ok_or_else(|| EngineError::Limit("decoded pixel overflow".into()))?;
+ if pixels > limits::DECODED_PIXELS {
+ return Err(EngineError::Limit("decoded pixels exceed cap".into()));
+ }
+ let mut pixmap = tiny_skia::Pixmap::new(width, height)
+ .ok_or_else(|| EngineError::Engine("failed to allocate SVG pixmap".into()))?;
+ resvg::render(&tree, tiny_skia::Transform::default(), &mut pixmap.as_mut());
+ let mut img = RgbaImage::new(width, height);
+ for (i, px) in pixmap.pixels().iter().enumerate() {
+ let x = (i as u32) % width;
+ let y = (i as u32) / width;
+ let rgba = px.demultiply();
+ img.put_pixel(x, y, image::Rgba([rgba.red(), rgba.green(), rgba.blue(), rgba.alpha()]));
+ }
+ Ok(img)
+}
+
+fn count_svg_nodes(root: &usvg::Group) -> u32 {
+ let mut n = 1u32;
+ for child in root.children() {
+ n = n.saturating_add(1);
+ if let usvg::Node::Group(g) = child {
+ n = n.saturating_add(count_svg_nodes(g).saturating_sub(1));
+ }
+ }
+ n
+}
+
+fn raster_to_text(img: &RgbaImage, cfg: OmacyAsciiConfig) -> Result {
+ let (pixel_w, pixel_h) = if cfg.mode == OMACY_ASCII_BRAILLE {
+ (cfg.width.saturating_mul(2), cfg.height.saturating_mul(4))
+ } else {
+ (cfg.width, cfg.height.saturating_mul(2))
+ };
+
+ let mut luma = to_luma(img, cfg.invert != 0);
+ if cfg.trim != 0 {
+ luma = trim_black(&add_black_border(&luma, 1));
+ }
+ let resized = resize_nearest_then_lanczos(&luma, pixel_w.max(1), pixel_h.max(1));
+ let threshold = (cfg.threshold as f32 / 100.0 * 255.0).round() as u8;
+ let bits = threshold_bits(&resized, threshold);
+ let packed = if cfg.mode == OMACY_ASCII_BRAILLE {
+ pack_braille(&bits)
+ } else {
+ pack_block(&bits)
+ };
+ Ok(trim_output_lines(&packed))
+}
+
+fn to_luma(img: &RgbaImage, invert: bool) -> image::GrayImage {
+ let (w, h) = img.dimensions();
+ let mut min_a = 255u8;
+ let mut max_a = 0u8;
+ for p in img.pixels() {
+ min_a = min_a.min(p.0[3]);
+ max_a = max_a.max(p.0[3]);
+ }
+ let use_alpha = (min_a as f32 / 255.0) < 0.999 && max_a > min_a;
+ let mut out = image::GrayImage::new(w, h);
+ for (x, y, p) in img.enumerate_pixels() {
+ let v = if use_alpha {
+ p.0[3]
+ } else {
+ let a = p.0[3] as u16;
+ let r = p.0[0] as u16;
+ let g = p.0[1] as u16;
+ let b = p.0[2] as u16;
+ let gray = (r * 30 + g * 59 + b * 11) / 100;
+ ((gray * a) / 255) as u8
+ };
+ let mut v = v;
+ if use_alpha {
+ if invert {
+ v = 255 - v;
+ }
+ } else if !invert {
+ v = 255 - v;
+ }
+ out.put_pixel(x, y, image::Luma([v]));
+ }
+ out
+}
+
+fn trim_black(img: &image::GrayImage) -> image::GrayImage {
+ let (w, h) = img.dimensions();
+ if w == 0 || h == 0 {
+ return img.clone();
+ }
+ let mut min_x = w;
+ let mut min_y = h;
+ let mut max_x = 0u32;
+ let mut max_y = 0u32;
+ for (x, y, p) in img.enumerate_pixels() {
+ if p.0[0] > 0 {
+ min_x = min_x.min(x);
+ min_y = min_y.min(y);
+ max_x = max_x.max(x);
+ max_y = max_y.max(y);
+ }
+ }
+ if min_x > max_x {
+ return image::GrayImage::new(1, 1);
+ }
+ DynamicImage::ImageLuma8(img.clone())
+ .crop_imm(min_x, min_y, max_x - min_x + 1, max_y - min_y + 1)
+ .to_luma8()
+}
+
+fn resize_nearest_then_lanczos(img: &image::GrayImage, w: u32, h: u32) -> image::GrayImage {
+ if img.width() == w && img.height() == h {
+ return img.clone();
+ }
+ DynamicImage::ImageLuma8(img.clone())
+ .resize(w, h, image::imageops::FilterType::Lanczos3)
+ .to_luma8()
+}
+
+fn add_black_border(img: &image::GrayImage, px: u32) -> image::GrayImage {
+ let w = img.width() + px * 2;
+ let h = img.height() + px * 2;
+ let mut out = image::GrayImage::from_pixel(w, h, image::Luma([0]));
+ for (x, y, p) in img.enumerate_pixels() {
+ out.put_pixel(x + px, y + px, *p);
+ }
+ out
+}
+
+fn threshold_bits(img: &image::GrayImage, threshold: u8) -> image::GrayImage {
+ let mut out = img.clone();
+ for p in out.pixels_mut() {
+ // magick -threshold then -negate then PBM (black=1) is: above threshold → on.
+ p.0[0] = if p.0[0] > threshold { 255 } else { 0 };
+ }
+ out
+}
+
+fn pack_braille(img: &image::GrayImage) -> String {
+ let w = img.width();
+ let h = img.height();
+ let mut lines = Vec::new();
+ let mut y = 0;
+ while y < h {
+ let mut line = String::new();
+ let mut x = 0;
+ while x < w {
+ let mut code = 0u32;
+ const DOTS: [[u32; 4]; 2] = [[1, 2, 4, 64], [8, 16, 32, 128]];
+ for dx in 0..2 {
+ for dy in 0..4 {
+ if y + dy < h && x + dx < w && img.get_pixel(x + dx, y + dy).0[0] > 0 {
+ code += DOTS[dx as usize][dy as usize];
+ }
+ }
+ }
+ if code == 0 {
+ line.push(' ');
+ } else {
+ line.push(char::from_u32(0x2800 + code).unwrap_or(' '));
+ }
+ x += 2;
+ }
+ lines.push(line);
+ y += 4;
+ }
+ lines.join("\n")
+}
+
+fn pack_block(img: &image::GrayImage) -> String {
+ let w = img.width();
+ let h = img.height();
+ let mut lines = Vec::new();
+ let mut y = 0;
+ while y < h {
+ let mut line = String::new();
+ for x in 0..w {
+ let top = y < h && img.get_pixel(x, y).0[0] > 0;
+ let bot = y + 1 < h && img.get_pixel(x, y + 1).0[0] > 0;
+ line.push(match (top, bot) {
+ (true, true) => '█',
+ (true, false) => '▀',
+ (false, true) => '▄',
+ (false, false) => ' ',
+ });
+ }
+ lines.push(line);
+ y += 2;
+ }
+ lines.join("\n")
+}
+
+fn trim_output_lines(text: &str) -> String {
+ let mut lines: Vec = text
+ .lines()
+ .map(|l| l.trim_end().to_string())
+ .collect();
+ while lines.first().is_some_and(|l| l.is_empty()) {
+ lines.remove(0);
+ }
+ while lines.last().is_some_and(|l| l.is_empty()) {
+ lines.pop();
+ }
+ if lines.is_empty() {
+ "No logo pixels found".into()
+ } else {
+ lines.join("\n")
+ }
+}
diff --git a/crates/omacy-engine/src/content.rs b/crates/omacy-engine/src/content.rs
new file mode 100644
index 0000000..84c36e0
--- /dev/null
+++ b/crates/omacy-engine/src/content.rs
@@ -0,0 +1,87 @@
+use crate::limits;
+use crate::status::EngineError;
+use ttfx::effects::EffectCommand;
+
+#[derive(Clone, Debug)]
+pub struct Content {
+ pub art: String,
+ pub effect: String,
+ pub bg: [u8; 4],
+}
+
+pub fn is_known_effect(name: &str) -> bool {
+ name == "random" || EffectCommand::NAMES.contains(&name)
+}
+
+pub fn parse_utf8(bytes: &[u8], what: &str) -> Result {
+ std::str::from_utf8(bytes)
+ .map(|s| s.to_owned())
+ .map_err(|_| EngineError::InvalidArg(format!("{what} is not UTF-8")))
+}
+
+pub fn validate_art(art: &str) -> Result<(), EngineError> {
+ if art.len() > limits::ASCII_BYTES {
+ return Err(EngineError::Limit("ASCII input exceeds 64 KiB".into()));
+ }
+ if art.bytes().any(|b| b == 0x1B) {
+ return Err(EngineError::InvalidArg("ASCII art must not contain ESC".into()));
+ }
+ let mut lines = 0usize;
+ let mut longest = 0usize;
+ for line in art.split('\n') {
+ lines += 1;
+ longest = longest.max(line.chars().count());
+ if lines > limits::ASCII_LINES {
+ return Err(EngineError::Limit("ASCII line count exceeds 128".into()));
+ }
+ if longest > limits::ASCII_COLUMNS {
+ return Err(EngineError::Limit("ASCII column count exceeds 256".into()));
+ }
+ }
+ Ok(())
+}
+
+pub fn validate_effect(name: &str) -> Result<(), EngineError> {
+ if is_known_effect(name) {
+ Ok(())
+ } else {
+ Err(EngineError::InvalidArg(format!("unknown effect '{name}'")))
+ }
+}
+
+pub fn parse_hex_color(s: &str) -> Result<[u8; 4], EngineError> {
+ let t = s.trim().trim_start_matches('#');
+ let err = || EngineError::InvalidArg(format!("invalid background color '{s}'"));
+ match t.len() {
+ 6 => {
+ let n = u32::from_str_radix(t, 16).map_err(|_| err())?;
+ Ok([
+ ((n >> 16) & 0xFF) as u8,
+ ((n >> 8) & 0xFF) as u8,
+ (n & 0xFF) as u8,
+ 255,
+ ])
+ }
+ 8 => {
+ let n = u32::from_str_radix(t, 16).map_err(|_| err())?;
+ Ok([
+ ((n >> 24) & 0xFF) as u8,
+ ((n >> 16) & 0xFF) as u8,
+ ((n >> 8) & 0xFF) as u8,
+ (n & 0xFF) as u8,
+ ])
+ }
+ _ => Err(err()),
+ }
+}
+
+impl Content {
+ pub fn from_parts(art: String, effect: String, bg: [u8; 4]) -> Result {
+ validate_art(&art)?;
+ validate_effect(&effect)?;
+ if art.is_empty() {
+ return Err(EngineError::InvalidArg("ASCII art is empty".into()));
+ }
+ Ok(Content { art, effect, bg })
+ }
+}
diff --git a/crates/omacy-engine/src/ffi.rs b/crates/omacy-engine/src/ffi.rs
new file mode 100644
index 0000000..cb408b6
--- /dev/null
+++ b/crates/omacy-engine/src/ffi.rs
@@ -0,0 +1,534 @@
+use std::cell::RefCell;
+use std::os::raw::c_char;
+use std::panic::{catch_unwind, AssertUnwindSafe};
+use std::path::PathBuf;
+use std::ptr;
+use std::slice;
+
+use crate::abi::{
+ slice_ptr_len, OmacyAsciiConfig, OmacyPendingConfig, OmacySessionConfig, OmacyStepResult,
+ OmacyText,
+};
+use crate::ascii;
+use crate::session::{self, ClockKind, Session};
+use crate::status::{EngineError, OmacyStatus};
+
+thread_local! {
+ static LAST_ERROR: RefCell = const { RefCell::new(String::new()) };
+}
+
+fn set_tls_error(msg: impl Into) {
+ LAST_ERROR.with(|slot| *slot.borrow_mut() = msg.into());
+}
+
+fn write_error_buf(src: &str, buf: *mut c_char, buf_len: usize) -> OmacyStatus {
+ if buf.is_null() {
+ return OmacyStatus::Null;
+ }
+ if buf_len < 1 {
+ return OmacyStatus::InvalidArg;
+ }
+ let bytes = src.as_bytes();
+ let n = bytes.len().min(buf_len - 1);
+ unsafe {
+ ptr::copy_nonoverlapping(bytes.as_ptr(), buf as *mut u8, n);
+ *buf.add(n) = 0;
+ }
+ OmacyStatus::Ok
+}
+
+pub fn is_main_thread() -> bool {
+ #[cfg(target_os = "macos")]
+ unsafe {
+ libc::pthread_main_np() != 0
+ }
+ #[cfg(target_os = "linux")]
+ unsafe {
+ libc::getpid() as i64 == libc::syscall(libc::SYS_gettid)
+ }
+ #[cfg(not(any(target_os = "macos", target_os = "linux")))]
+ {
+ true
+ }
+}
+
+fn require_main() -> Result<(), EngineError> {
+ if is_main_thread() {
+ Ok(())
+ } else {
+ Err(EngineError::WrongThread)
+ }
+}
+
+fn zero_step(out: *mut OmacyStepResult) {
+ if !out.is_null() {
+ unsafe { *out = OmacyStepResult::zeroed() };
+ }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_create(
+ cfg: *const OmacySessionConfig,
+ cols: u32,
+ rows: u32,
+ out: *mut *mut Session,
+) -> OmacyStatus {
+ let result = catch_unwind(AssertUnwindSafe(|| {
+ if out.is_null() {
+ return OmacyStatus::Null;
+ }
+ unsafe { *out = ptr::null_mut() };
+ if cfg.is_null() {
+ set_tls_error("null config");
+ return OmacyStatus::Null;
+ }
+ if let Err(e) = require_main() {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ let cfg = unsafe { &*cfg };
+ if cfg.has_seed > 1 {
+ set_tls_error("has_seed must be 0 or 1");
+ return OmacyStatus::InvalidArg;
+ }
+ let config_dir = match unsafe { slice_ptr_len(cfg.config_dir, cfg.config_dir_len) } {
+ Ok(Some(b)) => match std::str::from_utf8(b) {
+ Ok(s) if !s.is_empty() => Some(PathBuf::from(s)),
+ Ok(_) => None,
+ Err(_) => {
+ set_tls_error("config_dir is not UTF-8");
+ return OmacyStatus::InvalidArg;
+ }
+ },
+ Ok(None) => None,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ };
+ let ascii = match unsafe { slice_ptr_len(cfg.ascii, cfg.ascii_len) } {
+ Ok(v) => v,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ };
+ let effect = match unsafe { slice_ptr_len(cfg.effect, cfg.effect_len) } {
+ Ok(v) => v,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ };
+ if ascii.is_none() && config_dir.is_none() {
+ set_tls_error("ascii or config_dir is required");
+ return OmacyStatus::InvalidArg;
+ }
+ let effect = match session::parse_c_string(effect, true, "effect") {
+ Ok(s) => s,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ };
+ let art = if let Some(bytes) = ascii {
+ match crate::content::parse_utf8(bytes, "ascii") {
+ Ok(s) => s,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ }
+ } else if let Some(dir) = &config_dir {
+ match std::fs::read_to_string(dir.join("screensaver.txt")) {
+ Ok(s) => s,
+ Err(_) => {
+ set_tls_error("screensaver.txt missing from config_dir");
+ return OmacyStatus::InvalidArg;
+ }
+ }
+ } else {
+ String::new()
+ };
+ let seed = if cfg.has_seed == 1 {
+ Some(cfg.seed)
+ } else {
+ None
+ };
+ match Session::create(
+ art,
+ effect,
+ [cfg.bg_r, cfg.bg_g, cfg.bg_b, cfg.bg_a],
+ config_dir,
+ seed,
+ cols,
+ rows,
+ ClockKind::Real,
+ ) {
+ Ok(session) => {
+ unsafe { *out = Box::into_raw(Box::new(session)) };
+ OmacyStatus::Ok
+ }
+ Err(e) => {
+ set_tls_error(e.message());
+ e.status()
+ }
+ }
+ }));
+ match result {
+ Ok(status) => status,
+ Err(_) => {
+ set_tls_error("panic");
+ if !out.is_null() {
+ unsafe { *out = ptr::null_mut() };
+ }
+ OmacyStatus::Panic
+ }
+ }
+}
+
+unsafe fn session_mut<'a>(s: *mut Session) -> Result<&'a mut Session, EngineError> {
+ if s.is_null() {
+ Err(EngineError::Null)
+ } else {
+ Ok(unsafe { &mut *s })
+ }
+}
+
+unsafe fn session_ref<'a>(s: *const Session) -> Result<&'a Session, EngineError> {
+ if s.is_null() {
+ Err(EngineError::Null)
+ } else {
+ Ok(unsafe { &*s })
+ }
+}
+
+fn with_live_session(
+ s: *mut Session,
+ f: impl FnOnce(&mut Session) -> Result<(), EngineError>,
+) -> OmacyStatus {
+ let result = catch_unwind(AssertUnwindSafe(|| {
+ if let Err(e) = require_main() {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ let session = match unsafe { session_mut(s) } {
+ Ok(s) => s,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ };
+ if session.is_dead() {
+ set_tls_error("session is dead");
+ return OmacyStatus::Dead;
+ }
+ match f(session) {
+ Ok(()) => OmacyStatus::Ok,
+ Err(e) => {
+ set_tls_error(e.message());
+ session.set_last_error(e.message());
+ e.status()
+ }
+ }
+ }));
+ match result {
+ Ok(status) => {
+ if status == OmacyStatus::Panic {
+ if let Ok(session) = unsafe { session_mut(s) } {
+ session.mark_dead("panic".into());
+ }
+ }
+ status
+ }
+ Err(_) => {
+ set_tls_error("panic");
+ if let Ok(session) = unsafe { session_mut(s) } {
+ session.mark_dead("panic".into());
+ }
+ OmacyStatus::Panic
+ }
+ }
+}
+
+/// Induces a panic inside the same `catch_unwind` wrapper as session FFI.
+/// Not part of the C ABI; engine tests use it to prove `cells` is invalidated.
+pub unsafe fn debug_induce_panic(s: *mut Session) -> OmacyStatus {
+ with_live_session(s, |_| panic!("omacy induced panic"))
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_resize(s: *mut Session, cols: u32, rows: u32) -> OmacyStatus {
+ with_live_session(s, |session| session.resize(cols, rows))
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_step(
+ s: *mut Session,
+ elapsed_seconds: f64,
+ out: *mut OmacyStepResult,
+) -> OmacyStatus {
+ let result = catch_unwind(AssertUnwindSafe(|| {
+ if out.is_null() {
+ set_tls_error("null out");
+ return OmacyStatus::Null;
+ }
+ if let Err(e) = require_main() {
+ set_tls_error(e.message());
+ zero_step(out);
+ return e.status();
+ }
+ let session = match unsafe { session_mut(s) } {
+ Ok(s) => s,
+ Err(e) => {
+ set_tls_error(e.message());
+ zero_step(out);
+ return e.status();
+ }
+ };
+ if session.is_dead() {
+ set_tls_error("session is dead");
+ zero_step(out);
+ return OmacyStatus::Dead;
+ }
+ match session.step(elapsed_seconds) {
+ Ok((frame, waiting)) => {
+ unsafe {
+ *out = OmacyStepResult {
+ frame,
+ needs_begin_next: u8::from(waiting),
+ _pad: [0; 3],
+ };
+ }
+ OmacyStatus::Ok
+ }
+ Err(e) => {
+ set_tls_error(e.message());
+ session.set_last_error(e.message());
+ zero_step(out);
+ e.status()
+ }
+ }
+ }));
+ match result {
+ Ok(status) => status,
+ Err(_) => {
+ set_tls_error("panic");
+ zero_step(out);
+ if let Ok(session) = unsafe { session_mut(s) } {
+ session.mark_dead("panic".into());
+ }
+ OmacyStatus::Panic
+ }
+ }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_set_pending_config(
+ s: *mut Session,
+ cfg: *const OmacyPendingConfig,
+) -> OmacyStatus {
+ with_live_session(s, |session| {
+ if cfg.is_null() {
+ return Err(EngineError::Null);
+ }
+ let cfg = unsafe { &*cfg };
+ let ascii = unsafe { slice_ptr_len(cfg.ascii, cfg.ascii_len)? };
+ let effect = unsafe { slice_ptr_len(cfg.effect, cfg.effect_len)? };
+ let packet = session::parse_pending(ascii, effect, [cfg.bg_r, cfg.bg_g, cfg.bg_b, cfg.bg_a])?;
+ session.set_pending(packet)
+ })
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_begin_next(s: *mut Session) -> OmacyStatus {
+ with_live_session(s, |session| session.begin_next())
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_generation(
+ s: *const Session,
+ out: *mut u64,
+) -> OmacyStatus {
+ let result = catch_unwind(AssertUnwindSafe(|| {
+ if out.is_null() {
+ set_tls_error("null out");
+ return OmacyStatus::Null;
+ }
+ if let Err(e) = require_main() {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ let session = match unsafe { session_ref(s) } {
+ Ok(s) => s,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ };
+ unsafe { *out = session.generation() };
+ OmacyStatus::Ok
+ }));
+ match result {
+ Ok(status) => status,
+ Err(_) => {
+ set_tls_error("panic");
+ OmacyStatus::Panic
+ }
+ }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_error_message(
+ s: *const Session,
+ buf: *mut c_char,
+ buf_len: usize,
+) -> OmacyStatus {
+ let result = catch_unwind(AssertUnwindSafe(|| {
+ if s.is_null() {
+ let msg = LAST_ERROR.with(|slot| slot.borrow().clone());
+ return write_error_buf(&msg, buf, buf_len);
+ }
+ if let Err(e) = require_main() {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ let session = match unsafe { session_ref(s) } {
+ Ok(s) => s,
+ Err(e) => {
+ set_tls_error(e.message());
+ return e.status();
+ }
+ };
+ write_error_buf(session.error_message(), buf, buf_len)
+ }));
+ match result {
+ Ok(status) => status,
+ Err(_) => {
+ set_tls_error("panic");
+ OmacyStatus::Panic
+ }
+ }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_session_destroy(s: *mut Session) {
+ let _ = catch_unwind(AssertUnwindSafe(|| {
+ if s.is_null() {
+ return;
+ }
+ if !is_main_thread() {
+ set_tls_error("wrong thread");
+ return;
+ }
+ drop(unsafe { Box::from_raw(s) });
+ }));
+}
+
+#[no_mangle]
+pub extern "C" fn omacy_status_string(status: i32) -> *const c_char {
+ let text = match status {
+ 0 => OmacyStatus::Ok.as_c_str(),
+ 1 => OmacyStatus::Null.as_c_str(),
+ 2 => OmacyStatus::InvalidArg.as_c_str(),
+ 3 => OmacyStatus::Limit.as_c_str(),
+ 4 => OmacyStatus::Engine.as_c_str(),
+ 5 => OmacyStatus::Panic.as_c_str(),
+ 6 => OmacyStatus::Dead.as_c_str(),
+ 7 => OmacyStatus::WrongThread.as_c_str(),
+ _ => return ptr::null(),
+ };
+ text.as_ptr()
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_ascii_from_bytes(
+ cfg: *const OmacyAsciiConfig,
+ bytes: *const u8,
+ len: usize,
+ out: *mut *mut OmacyText,
+) -> OmacyStatus {
+ let result = catch_unwind(AssertUnwindSafe(|| {
+ if out.is_null() {
+ return OmacyStatus::Null;
+ }
+ unsafe { *out = ptr::null_mut() };
+ if cfg.is_null() {
+ set_tls_error("null config");
+ return OmacyStatus::Null;
+ }
+ let cfg = unsafe { *cfg };
+ let input = if bytes.is_null() {
+ if len == 0 {
+ &[][..]
+ } else {
+ set_tls_error("null bytes with nonzero length");
+ return OmacyStatus::InvalidArg;
+ }
+ } else {
+ unsafe { slice::from_raw_parts(bytes, len) }
+ };
+ match ascii::ascii_from_bytes(cfg, input) {
+ Ok(text) => {
+ unsafe {
+ *out = Box::into_raw(Box::new(OmacyText {
+ bytes: text.into_bytes(),
+ }));
+ }
+ OmacyStatus::Ok
+ }
+ Err(e) => {
+ set_tls_error(e.message());
+ e.status()
+ }
+ }
+ }));
+ match result {
+ Ok(status) => status,
+ Err(_) => {
+ set_tls_error("panic");
+ if !out.is_null() {
+ unsafe { *out = ptr::null_mut() };
+ }
+ OmacyStatus::Panic
+ }
+ }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_text_free(t: *mut OmacyText) {
+ let _ = catch_unwind(AssertUnwindSafe(|| {
+ if t.is_null() {
+ return;
+ }
+ drop(unsafe { Box::from_raw(t) });
+ }));
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_text_utf8(t: *const OmacyText) -> *const c_char {
+ match catch_unwind(AssertUnwindSafe(|| {
+ if t.is_null() {
+ ptr::null()
+ } else {
+ unsafe { (*t).bytes.as_ptr() as *const c_char }
+ }
+ })) {
+ Ok(p) => p,
+ Err(_) => ptr::null(),
+ }
+}
+
+#[no_mangle]
+pub unsafe extern "C" fn omacy_text_len(t: *const OmacyText) -> usize {
+ match catch_unwind(AssertUnwindSafe(|| {
+ if t.is_null() {
+ 0
+ } else {
+ unsafe { (*t).bytes.len() }
+ }
+ })) {
+ Ok(n) => n,
+ Err(_) => 0,
+ }
+}
diff --git a/crates/omacy-engine/src/lib.rs b/crates/omacy-engine/src/lib.rs
new file mode 100644
index 0000000..0f61f6e
--- /dev/null
+++ b/crates/omacy-engine/src/lib.rs
@@ -0,0 +1,18 @@
+//! Omacy engine: ttfx session, packed cell grid, C ABI.
+
+pub mod abi;
+pub mod ascii;
+mod content;
+pub mod ffi;
+mod limits;
+pub mod session;
+mod settings;
+pub mod status;
+
+pub use abi::{
+ OmacyAsciiConfig, OmacyCell, OmacyFrame, OmacyStepResult, OMACY_CELL_HAS_BACKGROUND,
+ OMACY_CELL_HAS_GLYPH,
+};
+pub use session::{ClockKind, Session};
+pub use settings::write_atomic;
+pub use status::{EngineError, OmacyStatus};
diff --git a/crates/omacy-engine/src/limits.rs b/crates/omacy-engine/src/limits.rs
new file mode 100644
index 0000000..2d18e6b
--- /dev/null
+++ b/crates/omacy-engine/src/limits.rs
@@ -0,0 +1,32 @@
+pub const ASCII_BYTES: usize = 64 * 1024;
+pub const ASCII_LINES: usize = 128;
+pub const ASCII_COLUMNS: usize = 256;
+pub const GRID_AXIS: u32 = 512;
+pub const GRID_CELLS: u32 = 32_768;
+pub const CONV_COLUMNS: u32 = 256;
+pub const CONV_ROWS: u32 = 128;
+pub const CONV_CELLS: u32 = 32_768;
+pub const PNG_BYTES: usize = 8 * 1024 * 1024;
+pub const SVG_BYTES: usize = 2 * 1024 * 1024;
+pub const DECODED_PIXELS: u32 = 4_194_304;
+pub const SVG_ELEMENTS: u32 = 8_192;
+pub const STEP_HZ: f64 = 60.0;
+pub const STEP_DT: f64 = 1.0 / STEP_HZ;
+pub const MAX_STEPS_PER_CALL: u32 = 4;
+
+pub fn check_geometry(cols: u32, rows: u32) -> Result<(u32, u32), super::status::EngineError> {
+ if cols < 1 || rows < 1 || cols > GRID_AXIS || rows > GRID_AXIS {
+ return Err(super::status::EngineError::Limit(
+ "grid width or height exceeds cap".into(),
+ ));
+ }
+ let cells = cols
+ .checked_mul(rows)
+ .ok_or_else(|| super::status::EngineError::Limit("grid cell count overflow".into()))?;
+ if cells > GRID_CELLS {
+ return Err(super::status::EngineError::Limit(
+ "grid cell count exceeds 32768".into(),
+ ));
+ }
+ Ok((cols, rows))
+}
diff --git a/crates/omacy-engine/src/session.rs b/crates/omacy-engine/src/session.rs
new file mode 100644
index 0000000..c99b297
--- /dev/null
+++ b/crates/omacy-engine/src/session.rs
@@ -0,0 +1,417 @@
+use std::path::PathBuf;
+
+use ttfx::effects::EffectCommand;
+use ttfx::engine::ctx::{Clock, EngineCtx};
+use ttfx::engine::effect::Effect;
+use ttfx::engine::terminal::{PackedCell, TerminalConfig};
+use ttfx::utils::graphics::Color;
+use ttfx::utils::rng::Rng;
+
+use crate::abi::OmacyFrame;
+use crate::content::{is_known_effect, parse_utf8, validate_art, validate_effect, Content};
+use crate::limits::{self, check_geometry};
+use crate::settings;
+use crate::status::EngineError;
+
+#[derive(Clone, Copy, Debug)]
+pub enum ClockKind {
+ Real,
+ Virtual60,
+}
+
+enum LiveState {
+ Running {
+ effect: Box,
+ ctx: EngineCtx,
+ },
+ Waiting,
+ Dead,
+}
+
+pub struct Session {
+ state: LiveState,
+ selected: Content,
+ selected_next: Content,
+ pending: Option,
+ pending_geometry: Option<(u32, u32)>,
+ cols: u32,
+ rows: u32,
+ cache: Vec,
+ clear: [u8; 4],
+ accumulator: f64,
+ generation: u64,
+ config_dir: Option,
+ pick_rng: Rng,
+ seed: Option,
+ clock_kind: ClockKind,
+ stepping: bool,
+ last_error: String,
+}
+
+#[derive(Clone, Debug)]
+pub struct ContentPacket {
+ pub art: Option,
+ pub effect: String,
+ pub bg: [u8; 4],
+}
+
+impl Session {
+ pub fn create(
+ art: String,
+ effect: String,
+ bg: [u8; 4],
+ config_dir: Option,
+ seed: Option,
+ cols: u32,
+ rows: u32,
+ clock_kind: ClockKind,
+ ) -> Result {
+ let (cols, rows) = check_geometry(cols, rows)?;
+ let selected = Content::from_parts(art, effect, bg)?;
+ let pick_rng = match seed {
+ Some(s) => Rng::seeded(s),
+ None => Rng::from_entropy(),
+ };
+ let clear = bg_or_opaque(selected.bg);
+ let mut session = Session {
+ state: LiveState::Dead,
+ selected: selected.clone(),
+ selected_next: selected,
+ pending: None,
+ pending_geometry: None,
+ cols,
+ rows,
+ cache: vec![PackedCell::default(); (cols * rows) as usize],
+ clear,
+ accumulator: 0.0,
+ generation: 0,
+ config_dir,
+ pick_rng,
+ seed,
+ clock_kind,
+ stepping: false,
+ last_error: String::new(),
+ };
+ session.install_effect()?;
+ Ok(session)
+ }
+
+ fn install_effect(&mut self) -> Result<(), EngineError> {
+ let (effect, ctx) = construct_effect(
+ &self.selected_next,
+ self.cols,
+ self.rows,
+ self.seed,
+ self.generation,
+ &mut self.pick_rng,
+ self.clock_kind,
+ )?;
+ self.selected = self.selected_next.clone();
+ self.clear = bg_or_opaque(self.selected.bg);
+ self.cache
+ .resize((self.cols * self.rows) as usize, PackedCell::default());
+ self.accumulator = 0.0;
+ self.state = LiveState::Running { effect, ctx };
+ Ok(())
+ }
+
+ pub fn generation(&self) -> u64 {
+ self.generation
+ }
+
+ pub fn error_message(&self) -> &str {
+ &self.last_error
+ }
+
+ pub fn set_last_error(&mut self, msg: String) {
+ self.last_error = msg;
+ }
+
+ pub fn is_dead(&self) -> bool {
+ matches!(self.state, LiveState::Dead)
+ }
+
+ pub fn is_waiting(&self) -> bool {
+ matches!(self.state, LiveState::Waiting)
+ }
+
+ pub fn force_reentrant_step(&mut self) -> Result<(OmacyFrame, bool), EngineError> {
+ self.stepping = true;
+ let result = self.step(1.0 / 60.0);
+ self.stepping = false;
+ result
+ }
+
+ pub fn mark_dead(&mut self, message: String) {
+ self.state = LiveState::Dead;
+ self.last_error = message;
+ self.cache.clear();
+ }
+
+ pub fn set_pending(&mut self, packet: ContentPacket) -> Result<(), EngineError> {
+ self.require_live()?;
+ validate_effect(&packet.effect)?;
+ if let Some(art) = &packet.art {
+ if !art.is_empty() {
+ validate_art(art)?;
+ }
+ }
+ self.pending = Some(packet);
+ Ok(())
+ }
+
+ pub fn resize(&mut self, cols: u32, rows: u32) -> Result<(), EngineError> {
+ self.require_live()?;
+ let (cols, rows) = check_geometry(cols, rows)?;
+ match &self.state {
+ LiveState::Running { .. } => {
+ if (cols, rows) == (self.cols, self.rows) {
+ self.pending_geometry = None;
+ } else {
+ self.pending_geometry = Some((cols, rows));
+ }
+ Ok(())
+ }
+ LiveState::Waiting => {
+ self.apply_geometry(cols, rows);
+ Ok(())
+ }
+ LiveState::Dead => Err(EngineError::Dead),
+ }
+ }
+
+ fn apply_geometry(&mut self, cols: u32, rows: u32) {
+ self.cols = cols;
+ self.rows = rows;
+ self.pending_geometry = None;
+ self.cache = vec![PackedCell::default(); (cols * rows) as usize];
+ }
+
+ pub fn begin_next(&mut self) -> Result<(), EngineError> {
+ if !matches!(self.state, LiveState::Waiting) {
+ return Err(EngineError::InvalidArg(
+ "begin_next is only legal while waiting".into(),
+ ));
+ }
+ let previous_geom = (self.cols, self.rows);
+ let previous_pending = self.pending_geometry;
+ let previous_cache = self.cache.clone();
+ let previous_clear = self.clear;
+ if let Some((cols, rows)) = self.pending_geometry {
+ self.apply_geometry(cols, rows);
+ }
+ match self.install_effect() {
+ Ok(()) => {
+ self.generation = self.generation.saturating_add(1);
+ Ok(())
+ }
+ Err(e) => {
+ self.cols = previous_geom.0;
+ self.rows = previous_geom.1;
+ self.pending_geometry = previous_pending;
+ self.cache = previous_cache;
+ self.clear = previous_clear;
+ self.state = LiveState::Waiting;
+ Err(e)
+ }
+ }
+ }
+
+ pub fn step(&mut self, elapsed: f64) -> Result<(OmacyFrame, bool), EngineError> {
+ if self.stepping {
+ return Err(EngineError::InvalidArg("re-entrant step".into()));
+ }
+ if !elapsed.is_finite() || elapsed < 0.0 {
+ return Err(EngineError::InvalidArg(
+ "elapsed must be finite and non-negative".into(),
+ ));
+ }
+ self.require_live()?;
+ self.stepping = true;
+ let inner = self.step_inner(elapsed);
+ self.stepping = false;
+ let waiting = inner?;
+ Ok((self.published_c_frame(), waiting))
+ }
+
+ fn step_inner(&mut self, elapsed: f64) -> Result {
+ if matches!(self.state, LiveState::Waiting) {
+ return Ok(true);
+ }
+ if matches!(self.state, LiveState::Dead) {
+ return Err(EngineError::Dead);
+ }
+
+ self.accumulator += elapsed;
+ let mut steps = 0u32;
+ let mut ended = false;
+ while self.accumulator >= limits::STEP_DT && steps < limits::MAX_STEPS_PER_CALL {
+ let going = match &mut self.state {
+ LiveState::Running { effect, ctx } => effect.advance(ctx),
+ _ => false,
+ };
+ if !going {
+ ended = true;
+ break;
+ }
+ self.accumulator -= limits::STEP_DT;
+ steps += 1;
+ }
+ if steps == limits::MAX_STEPS_PER_CALL {
+ self.accumulator = 0.0;
+ }
+
+ self.fill_cache()?;
+
+ if ended {
+ self.accumulator = 0.0;
+ self.apply_boundary_content();
+ self.state = LiveState::Waiting;
+ return Ok(true);
+ }
+
+ Ok(false)
+ }
+
+ fn fill_cache(&mut self) -> Result<(), EngineError> {
+ let term_bg = [self.clear[0], self.clear[1], self.clear[2]];
+ match &mut self.state {
+ LiveState::Running { ctx, .. } => {
+ let needed = (self.cols as usize)
+ .checked_mul(self.rows as usize)
+ .ok_or_else(|| EngineError::Limit("grid overflow".into()))?;
+ if self.cache.len() != needed {
+ self.cache.resize(needed, PackedCell::default());
+ }
+ ctx.terminal.fill_grid(&mut self.cache, term_bg);
+ Ok(())
+ }
+ LiveState::Waiting => Ok(()),
+ LiveState::Dead => Err(EngineError::Dead),
+ }
+ }
+
+ fn apply_boundary_content(&mut self) {
+ if let Some(packet) = self.pending.take() {
+ let mut next = self.selected.clone();
+ if let Some(art) = packet.art {
+ if !art.is_empty() {
+ next.art = art;
+ }
+ }
+ next.effect = packet.effect;
+ next.bg = packet.bg;
+ self.selected_next = next;
+ return;
+ }
+ if let Some(dir) = &self.config_dir {
+ self.selected_next = settings::load_from_dir(dir, &self.selected);
+ return;
+ }
+ self.selected_next = self.selected.clone();
+ }
+
+ fn require_live(&self) -> Result<(), EngineError> {
+ match self.state {
+ LiveState::Dead => Err(EngineError::Dead),
+ _ => Ok(()),
+ }
+ }
+
+ pub fn published_c_frame(&self) -> OmacyFrame {
+ let cells = if self.cache.is_empty() || matches!(self.state, LiveState::Dead) {
+ std::ptr::null()
+ } else {
+ self.cache.as_ptr()
+ };
+ OmacyFrame {
+ cols: self.cols,
+ rows: self.rows,
+ clear_r: self.clear[0],
+ clear_g: self.clear[1],
+ clear_b: self.clear[2],
+ clear_a: self.clear[3],
+ _pad: 0,
+ cells,
+ }
+ }
+}
+
+fn bg_or_opaque(bg: [u8; 4]) -> [u8; 4] {
+ if bg[3] == 0 {
+ [bg[0], bg[1], bg[2], 255]
+ } else {
+ bg
+ }
+}
+
+fn construct_effect(
+ content: &Content,
+ cols: u32,
+ rows: u32,
+ seed: Option,
+ generation: u64,
+ pick_rng: &mut Rng,
+ clock_kind: ClockKind,
+) -> Result<(Box, EngineCtx), EngineError> {
+ let name = if content.effect == "random" {
+ EffectCommand::NAMES[pick_rng.choice_index(EffectCommand::NAMES.len())]
+ } else {
+ content.effect.as_str()
+ };
+ let mut effect = EffectCommand::from_name(name)
+ .ok_or_else(|| EngineError::InvalidArg(format!("unknown effect '{name}'")))?;
+ let color = Color::from_hex(&format!(
+ "{:02x}{:02x}{:02x}",
+ content.bg[0], content.bg[1], content.bg[2]
+ ))
+ .map_err(EngineError::Engine)?;
+ let config = TerminalConfig::gui(cols as i64, rows as i64, color);
+ let rng = match seed {
+ Some(s) => Rng::seeded(s.wrapping_add(generation)),
+ None => Rng::from_entropy(),
+ };
+ let clock = match clock_kind {
+ ClockKind::Real => Clock::real(),
+ ClockKind::Virtual60 => Clock::virtual_with_frame_rate(60),
+ };
+ let mut ctx = EngineCtx::new(&content.art, config, rng, clock)
+ .map_err(|e| EngineError::Engine(e.to_string()))?;
+ ctx.suppress_ansi = true;
+ effect
+ .build(&mut ctx)
+ .map_err(|e| EngineError::Engine(e.to_string()))?;
+ Ok((effect, ctx))
+}
+
+pub fn parse_c_string(bytes: Option<&[u8]>, required: bool, what: &str) -> Result {
+ match bytes {
+ None if required => Err(EngineError::InvalidArg(format!("{what} is required"))),
+ None => Ok(String::new()),
+ Some(b) => parse_utf8(b, what),
+ }
+}
+
+pub fn parse_pending(
+ ascii: Option<&[u8]>,
+ effect: Option<&[u8]>,
+ bg: [u8; 4],
+) -> Result {
+ let effect = parse_c_string(effect, true, "effect")?;
+ if effect.is_empty() {
+ return Err(EngineError::InvalidArg("effect is required".into()));
+ }
+ validate_effect(&effect)?;
+ let art = match ascii {
+ None | Some([]) => None,
+ Some(b) => {
+ let s = parse_utf8(b, "ascii")?;
+ validate_art(&s)?;
+ Some(s)
+ }
+ };
+ if !is_known_effect(&effect) {
+ return Err(EngineError::InvalidArg("unknown effect".into()));
+ }
+ Ok(ContentPacket { art, effect, bg })
+}
diff --git a/crates/omacy-engine/src/settings.rs b/crates/omacy-engine/src/settings.rs
new file mode 100644
index 0000000..7556ac0
--- /dev/null
+++ b/crates/omacy-engine/src/settings.rs
@@ -0,0 +1,91 @@
+use std::fs;
+use std::path::Path;
+
+use serde::Deserialize;
+
+use crate::content::{parse_hex_color, validate_art, validate_effect, Content};
+use crate::status::EngineError;
+
+#[derive(Debug, Deserialize)]
+struct SettingsFile {
+ effect: Option,
+ background: Option,
+}
+
+pub fn load_from_dir(dir: &Path, fallback: &Content) -> Content {
+ let art_path = dir.join("screensaver.txt");
+ let settings_path = dir.join("settings.json");
+
+ let mut next = fallback.clone();
+
+ match fs::read_to_string(&art_path) {
+ Ok(art) => match validate_art(&art) {
+ Ok(()) if !art.is_empty() => next.art = art,
+ _ => {}
+ },
+ Err(_) => {}
+ }
+
+ match fs::read_to_string(&settings_path) {
+ Ok(text) => {
+ if let Ok(parsed) = serde_json::from_str::(&text) {
+ if let Some(effect) = parsed.effect {
+ if validate_effect(&effect).is_ok() {
+ next.effect = effect;
+ }
+ }
+ if let Some(bg) = parsed.background {
+ if let Ok(rgba) = parse_hex_color(&bg) {
+ next.bg = rgba;
+ }
+ }
+ }
+ }
+ Err(_) => {}
+ }
+
+ next
+}
+
+pub fn write_atomic(path: &Path, bytes: &[u8]) -> Result<(), EngineError> {
+ let parent = path.parent().unwrap_or_else(|| Path::new("."));
+ let tmp = parent.join(format!(
+ ".{}.tmp",
+ path.file_name().and_then(|s| s.to_str()).unwrap_or("omacy")
+ ));
+ fs::write(&tmp, bytes).map_err(|e| EngineError::Engine(e.to_string()))?;
+ fs::rename(&tmp, path).map_err(|e| EngineError::Engine(e.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::content::Content;
+ use std::env;
+
+ #[test]
+ fn atomic_write_replaces_file() {
+ let dir = env::temp_dir().join(format!("omacy-atomic-{}", std::process::id()));
+ fs::create_dir_all(&dir).unwrap();
+ let path = dir.join("settings.json");
+ write_atomic(&path, b"{\"effect\":\"random\"}").unwrap();
+ assert_eq!(fs::read(&path).unwrap(), b"{\"effect\":\"random\"}");
+ write_atomic(&path, b"{\"effect\":\"beams\"}").unwrap();
+ assert_eq!(fs::read(&path).unwrap(), b"{\"effect\":\"beams\"}");
+ let _ = fs::remove_dir_all(&dir);
+ }
+
+ #[test]
+ fn invalid_json_keeps_last_known_good() {
+ let dir = env::temp_dir().join(format!("omacy-badjson-{}", std::process::id()));
+ fs::create_dir_all(&dir).unwrap();
+ fs::write(dir.join("settings.json"), b"{not json").unwrap();
+ fs::write(dir.join("screensaver.txt"), b"HELLO").unwrap();
+ let fallback = Content::from_parts("FALLBACK".into(), "beams".into(), [1, 2, 3, 255]).unwrap();
+ let next = load_from_dir(&dir, &fallback);
+ assert_eq!(next.effect, "beams");
+ assert_eq!(next.bg, [1, 2, 3, 255]);
+ assert_eq!(next.art, "HELLO");
+ let _ = fs::remove_dir_all(&dir);
+ }
+}
diff --git a/crates/omacy-engine/src/status.rs b/crates/omacy-engine/src/status.rs
new file mode 100644
index 0000000..0f34f6b
--- /dev/null
+++ b/crates/omacy-engine/src/status.rs
@@ -0,0 +1,78 @@
+use std::ffi::c_int;
+
+#[repr(C)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum OmacyStatus {
+ Ok = 0,
+ Null = 1,
+ InvalidArg = 2,
+ Limit = 3,
+ Engine = 4,
+ Panic = 5,
+ Dead = 6,
+ WrongThread = 7,
+}
+
+impl OmacyStatus {
+ pub fn as_c_int(self) -> c_int {
+ self as c_int
+ }
+
+ pub fn as_str(self) -> &'static str {
+ match self {
+ OmacyStatus::Ok => "OMACY_OK",
+ OmacyStatus::Null => "OMACY_ERR_NULL",
+ OmacyStatus::InvalidArg => "OMACY_ERR_INVALID_ARG",
+ OmacyStatus::Limit => "OMACY_ERR_LIMIT",
+ OmacyStatus::Engine => "OMACY_ERR_ENGINE",
+ OmacyStatus::Panic => "OMACY_ERR_PANIC",
+ OmacyStatus::Dead => "OMACY_ERR_DEAD",
+ OmacyStatus::WrongThread => "OMACY_ERR_WRONG_THREAD",
+ }
+ }
+
+ pub fn as_c_str(self) -> &'static std::ffi::CStr {
+ match self {
+ OmacyStatus::Ok => c"OMACY_OK",
+ OmacyStatus::Null => c"OMACY_ERR_NULL",
+ OmacyStatus::InvalidArg => c"OMACY_ERR_INVALID_ARG",
+ OmacyStatus::Limit => c"OMACY_ERR_LIMIT",
+ OmacyStatus::Engine => c"OMACY_ERR_ENGINE",
+ OmacyStatus::Panic => c"OMACY_ERR_PANIC",
+ OmacyStatus::Dead => c"OMACY_ERR_DEAD",
+ OmacyStatus::WrongThread => c"OMACY_ERR_WRONG_THREAD",
+ }
+ }
+}
+
+#[derive(Debug)]
+pub enum EngineError {
+ Null,
+ InvalidArg(String),
+ Limit(String),
+ Engine(String),
+ Dead,
+ WrongThread,
+}
+
+impl EngineError {
+ pub fn status(&self) -> OmacyStatus {
+ match self {
+ EngineError::Null => OmacyStatus::Null,
+ EngineError::InvalidArg(_) => OmacyStatus::InvalidArg,
+ EngineError::Limit(_) => OmacyStatus::Limit,
+ EngineError::Engine(_) => OmacyStatus::Engine,
+ EngineError::Dead => OmacyStatus::Dead,
+ EngineError::WrongThread => OmacyStatus::WrongThread,
+ }
+ }
+
+ pub fn message(&self) -> String {
+ match self {
+ EngineError::Null => "null pointer".into(),
+ EngineError::InvalidArg(m) | EngineError::Limit(m) | EngineError::Engine(m) => m.clone(),
+ EngineError::Dead => "session is dead".into(),
+ EngineError::WrongThread => "wrong thread".into(),
+ }
+ }
+}
diff --git a/crates/omacy-engine/tests/ascii.rs b/crates/omacy-engine/tests/ascii.rs
new file mode 100644
index 0000000..83f8930
--- /dev/null
+++ b/crates/omacy-engine/tests/ascii.rs
@@ -0,0 +1,87 @@
+use omacy_engine::abi::{OmacyAsciiConfig, OMACY_ASCII_BLOCK, OMACY_ASCII_BRAILLE};
+use omacy_engine::ascii::ascii_from_bytes;
+
+fn solid_png(w: u32, h: u32, rgba: [u8; 4]) -> Vec {
+ let mut img = image::RgbaImage::from_pixel(w, h, image::Rgba(rgba));
+ // stamp an opaque black logo block in the middle so both modes emit glyphs
+ for y in h / 4..h * 3 / 4 {
+ for x in w / 4..w * 3 / 4 {
+ img.put_pixel(x, y, image::Rgba([0, 0, 0, 255]));
+ }
+ }
+ let mut buf = Vec::new();
+ image::DynamicImage::ImageRgba8(img)
+ .write_to(&mut std::io::Cursor::new(&mut buf), image::ImageFormat::Png)
+ .unwrap();
+ buf
+}
+
+#[test]
+fn png_braille_emits_cells() {
+ let png = solid_png(16, 16, [255, 255, 255, 255]);
+ let cfg = OmacyAsciiConfig {
+ mode: OMACY_ASCII_BRAILLE,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ _pad: 0,
+ };
+ let text = ascii_from_bytes(cfg, &png).expect("convert");
+ assert!(!text.is_empty());
+ assert_ne!(text, "No logo pixels found");
+}
+
+#[test]
+fn png_block_emits_cells() {
+ let png = solid_png(16, 16, [255, 255, 255, 255]);
+ let cfg = OmacyAsciiConfig {
+ mode: OMACY_ASCII_BLOCK,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ _pad: 0,
+ };
+ let text = ascii_from_bytes(cfg, &png).expect("convert");
+ assert!(text.chars().any(|c| c == '█' || c == '▀' || c == '▄'));
+}
+
+#[test]
+fn oversized_svg_is_limit() {
+ let huge = vec![b'x'; 2 * 1024 * 1024 + 1];
+ let cfg = OmacyAsciiConfig {
+ mode: OMACY_ASCII_BRAILLE,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ _pad: 0,
+ };
+ match ascii_from_bytes(cfg, &huge) {
+ Err(omacy_engine::EngineError::Limit(_)) => {}
+ other => panic!("expected limit, got {other:?}"),
+ }
+}
+
+#[test]
+fn svg_file_href_is_ignored() {
+ let svg = br#""#;
+ let cfg = OmacyAsciiConfig {
+ mode: OMACY_ASCII_BLOCK,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ _pad: 0,
+ };
+ let text = ascii_from_bytes(cfg, svg).expect("svg with file href must not load the file");
+ assert!(!text.is_empty());
+}
diff --git a/crates/omacy-engine/tests/budget.rs b/crates/omacy-engine/tests/budget.rs
new file mode 100644
index 0000000..5424116
--- /dev/null
+++ b/crates/omacy-engine/tests/budget.rs
@@ -0,0 +1,50 @@
+use std::time::Instant;
+
+use omacy_engine::session::{ClockKind, Session};
+
+fn wordmark() -> String {
+ std::fs::read_to_string(format!(
+ "{}/../../assets/branding/screensaver.txt",
+ env!("CARGO_MANIFEST_DIR")
+ ))
+ .unwrap()
+}
+
+fn max_grid_session() -> Session {
+ Session::create(
+ wordmark(),
+ "wipe".into(),
+ [0, 0, 0, 255],
+ None,
+ Some(1),
+ 256,
+ 128,
+ ClockKind::Virtual60,
+ )
+ .expect("max-grid session")
+}
+
+#[test]
+fn three_max_grid_sessions_step_under_budget() {
+ let mut sessions = vec![max_grid_session(), max_grid_session(), max_grid_session()];
+ for session in &mut sessions {
+ session.step(1.0 / 60.0).expect("warmup step");
+ }
+
+ let started = Instant::now();
+ for session in &mut sessions {
+ let (frame, _) = session.step(1.0 / 60.0).expect("budget step");
+ assert_eq!(frame.cols * frame.rows, 32_768);
+ assert!(!frame.cells.is_null());
+ }
+ let elapsed_ms = started.elapsed().as_secs_f64() * 1000.0;
+
+ // Architecture phase-2 gate is 8.3 ms for step + Metal upload + encode.
+ // This Linux job can only time the engine slice. Debug builds are slower;
+ // `cargo test --release` is the production number.
+ let budget_ms = if cfg!(debug_assertions) { 50.0 } else { 8.3 };
+ assert!(
+ elapsed_ms < budget_ms,
+ "step of 3×32768-cell sessions took {elapsed_ms:.3} ms (budget {budget_ms} ms)"
+ );
+}
diff --git a/crates/omacy-engine/tests/conversion.rs b/crates/omacy-engine/tests/conversion.rs
new file mode 100644
index 0000000..7ff5871
--- /dev/null
+++ b/crates/omacy-engine/tests/conversion.rs
@@ -0,0 +1,103 @@
+//! Identity vs committed conversion goldens.
+
+use omacy_engine::abi::{OmacyAsciiConfig, OMACY_ASCII_BLOCK, OMACY_ASCII_BRAILLE};
+use omacy_engine::ascii::ascii_from_bytes;
+
+struct Case {
+ input: &'static str,
+ mode: u32,
+ width: u32,
+ height: u32,
+ threshold: u8,
+ invert: u8,
+ trim: u8,
+ expected: &'static str,
+}
+
+fn load(name: &str) -> Vec {
+ std::fs::read(format!(
+ "{}/../../assets/fixtures/conversion/{name}",
+ env!("CARGO_MANIFEST_DIR")
+ ))
+ .unwrap_or_else(|e| panic!("{name}: {e}"))
+}
+
+#[test]
+fn conversion_matches_committed_fixtures() {
+ let cases = [
+ Case {
+ input: "solid-black-on-white.png",
+ mode: OMACY_ASCII_BRAILLE,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ expected: "solid-black-on-white.braille.t50.inv0.trim1.txt",
+ },
+ Case {
+ input: "solid-black-on-white.png",
+ mode: OMACY_ASCII_BLOCK,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ expected: "solid-black-on-white.block.t50.inv0.trim1.txt",
+ },
+ Case {
+ input: "solid-black-on-white.png",
+ mode: OMACY_ASCII_BRAILLE,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 1,
+ trim: 1,
+ expected: "solid-black-on-white.braille.t50.inv1.trim1.txt",
+ },
+ Case {
+ input: "solid-black-on-white.png",
+ mode: OMACY_ASCII_BLOCK,
+ width: 16,
+ height: 8,
+ threshold: 80,
+ invert: 0,
+ trim: 0,
+ expected: "solid-black-on-white.block.t80.inv0.trim0.txt",
+ },
+ Case {
+ input: "alpha-logo.png",
+ mode: OMACY_ASCII_BRAILLE,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ expected: "alpha-logo.braille.t50.inv0.trim1.txt",
+ },
+ Case {
+ input: "logo.svg",
+ mode: OMACY_ASCII_BRAILLE,
+ width: 8,
+ height: 4,
+ threshold: 50,
+ invert: 0,
+ trim: 1,
+ expected: "logo.svg.braille.t50.inv0.trim1.txt",
+ },
+ ];
+ for case in cases {
+ let cfg = OmacyAsciiConfig {
+ mode: case.mode,
+ width: case.width,
+ height: case.height,
+ threshold: case.threshold,
+ invert: case.invert,
+ trim: case.trim,
+ _pad: 0,
+ };
+ let got = ascii_from_bytes(cfg, &load(case.input)).expect(case.expected);
+ let want = String::from_utf8(load(case.expected)).unwrap();
+ assert_eq!(got, want, "{}", case.expected);
+ }
+}
diff --git a/crates/omacy-engine/tests/ffi.rs b/crates/omacy-engine/tests/ffi.rs
new file mode 100644
index 0000000..42e4662
--- /dev/null
+++ b/crates/omacy-engine/tests/ffi.rs
@@ -0,0 +1,138 @@
+use omacy_engine::abi::{OmacySessionConfig, OmacyStepResult};
+use omacy_engine::ffi::{
+ debug_induce_panic, omacy_session_create, omacy_session_destroy, omacy_session_error_message,
+ omacy_session_step,
+};
+use omacy_engine::session::Session;
+use omacy_engine::OmacyStatus;
+use std::os::raw::c_char;
+use std::ptr;
+
+fn wordmark() -> Vec {
+ std::fs::read(format!(
+ "{}/../../assets/branding/screensaver.txt",
+ env!("CARGO_MANIFEST_DIR")
+ ))
+ .unwrap()
+}
+
+#[test]
+fn step_null_out_does_not_crash() {
+ if !omacy_engine::ffi::is_main_thread() {
+ let status = unsafe { omacy_session_step(ptr::null_mut(), 1.0 / 60.0, ptr::null_mut()) };
+ assert_eq!(status, OmacyStatus::Null);
+ return;
+ }
+ let art = wordmark();
+ let effect = b"wipe";
+ let cfg = OmacySessionConfig {
+ config_dir: ptr::null(),
+ config_dir_len: 0,
+ ascii: art.as_ptr(),
+ ascii_len: art.len(),
+ effect: effect.as_ptr(),
+ effect_len: effect.len(),
+ bg_r: 0,
+ bg_g: 0,
+ bg_b: 0,
+ bg_a: 255,
+ has_seed: 1,
+ _pad: [0; 3],
+ seed: 1,
+ };
+ let mut session: *mut Session = ptr::null_mut();
+ let status = unsafe { omacy_session_create(&cfg, 20, 8, &mut session) };
+ if status == OmacyStatus::WrongThread {
+ return;
+ }
+ assert_eq!(status, OmacyStatus::Ok);
+ let status = unsafe { omacy_session_step(session, 1.0 / 60.0, ptr::null_mut()) };
+ assert_eq!(status, OmacyStatus::Null);
+ unsafe { omacy_session_destroy(session) };
+}
+
+#[test]
+fn error_message_null_session_any_thread() {
+ let mut buf = [0 as c_char; 64];
+ let status = unsafe { omacy_session_error_message(ptr::null(), buf.as_mut_ptr(), buf.len()) };
+ assert_eq!(status, OmacyStatus::Ok);
+}
+
+#[test]
+fn step_zeroes_out_on_invalid_elapsed() {
+ if !omacy_engine::ffi::is_main_thread() {
+ return;
+ }
+ let art = wordmark();
+ let effect = b"wipe";
+ let cfg = OmacySessionConfig {
+ config_dir: ptr::null(),
+ config_dir_len: 0,
+ ascii: art.as_ptr(),
+ ascii_len: art.len(),
+ effect: effect.as_ptr(),
+ effect_len: effect.len(),
+ bg_r: 0,
+ bg_g: 0,
+ bg_b: 0,
+ bg_a: 255,
+ has_seed: 1,
+ _pad: [0; 3],
+ seed: 1,
+ };
+ let mut session: *mut Session = ptr::null_mut();
+ let status = unsafe { omacy_session_create(&cfg, 20, 8, &mut session) };
+ if status != OmacyStatus::Ok {
+ return;
+ }
+ let mut out = OmacyStepResult::zeroed();
+ let status = unsafe { omacy_session_step(session, f64::NAN, &mut out) };
+ assert_eq!(status, OmacyStatus::InvalidArg);
+ assert!(out.frame.cells.is_null());
+ assert_eq!(out.needs_begin_next, 0);
+ unsafe { omacy_session_destroy(session) };
+}
+
+#[test]
+fn panic_invalidates_cells() {
+ if !omacy_engine::ffi::is_main_thread() {
+ return;
+ }
+ let art = wordmark();
+ let effect = b"wipe";
+ let cfg = OmacySessionConfig {
+ config_dir: ptr::null(),
+ config_dir_len: 0,
+ ascii: art.as_ptr(),
+ ascii_len: art.len(),
+ effect: effect.as_ptr(),
+ effect_len: effect.len(),
+ bg_r: 0,
+ bg_g: 0,
+ bg_b: 0,
+ bg_a: 255,
+ has_seed: 1,
+ _pad: [0; 3],
+ seed: 1,
+ };
+ let mut session: *mut Session = ptr::null_mut();
+ let status = unsafe { omacy_session_create(&cfg, 20, 8, &mut session) };
+ if status != OmacyStatus::Ok {
+ return;
+ }
+ let mut out = OmacyStepResult::zeroed();
+ let status = unsafe { omacy_session_step(session, 1.0 / 60.0, &mut out) };
+ assert_eq!(status, OmacyStatus::Ok);
+ assert!(!out.frame.cells.is_null());
+
+ let status = unsafe { debug_induce_panic(session) };
+ assert_eq!(status, OmacyStatus::Panic);
+
+ let mut after = OmacyStepResult::zeroed();
+ after.frame.cells = art.as_ptr() as *const _;
+ let status = unsafe { omacy_session_step(session, 1.0 / 60.0, &mut after) };
+ assert_eq!(status, OmacyStatus::Dead);
+ assert!(after.frame.cells.is_null());
+ assert_eq!(after.needs_begin_next, 0);
+ unsafe { omacy_session_destroy(session) };
+}
diff --git a/crates/omacy-engine/tests/oracle.rs b/crates/omacy-engine/tests/oracle.rs
new file mode 100644
index 0000000..a61910b
--- /dev/null
+++ b/crates/omacy-engine/tests/oracle.rs
@@ -0,0 +1,94 @@
+#[path = "sgr_decode.rs"]
+mod sgr_decode;
+
+use omacy_engine::abi::OmacyCell;
+use sgr_decode::{decode_ansi, occupancy};
+
+fn fixture(name: &str) -> String {
+ let path = format!(
+ "{}/../../assets/fixtures/ansi-oracle/{name}",
+ env!("CARGO_MANIFEST_DIR")
+ );
+ String::from_utf8(std::fs::read(path).expect("fixture")).expect("utf8")
+}
+
+fn cell_at(cells: &[OmacyCell], cols: u32, row: u32, col: u32) -> OmacyCell {
+ cells[(row * cols + col) as usize]
+}
+
+#[test]
+fn origin_asymmetric() {
+ let cells = decode_ansi(&fixture("origin-asymmetric.ans"), 2, 2, [0, 0, 0]);
+ let tr = cell_at(&cells, 2, 0, 1);
+ let bl = cell_at(&cells, 2, 1, 0);
+ let tl = cell_at(&cells, 2, 0, 0);
+ let br = cell_at(&cells, 2, 1, 1);
+ assert_eq!(occupancy(&tl), (false, false));
+ assert_eq!(occupancy(&br), (false, false));
+ assert_eq!(occupancy(&tr), (false, true));
+ assert_eq!(tr.glyph, u32::from('X'));
+ assert_eq!(occupancy(&bl), (true, false));
+ assert_ne!([bl.bg_r, bl.bg_g, bl.bg_b], [0, 0, 0]);
+ assert_eq!(tr.flags, 0);
+ assert_eq!(bl.flags, 0);
+}
+
+#[test]
+fn occupancy_four() {
+ let cells = decode_ansi(&fixture("occupancy-four.ans"), 2, 2, [0, 0, 0]);
+ assert_eq!(occupancy(&cell_at(&cells, 2, 0, 0)), (false, false));
+ assert_eq!(occupancy(&cell_at(&cells, 2, 0, 1)), (false, true));
+ assert_eq!(occupancy(&cell_at(&cells, 2, 1, 0)), (true, false));
+ assert_eq!(occupancy(&cell_at(&cells, 2, 1, 1)), (true, true));
+ assert_eq!(cell_at(&cells, 2, 0, 1).glyph, u32::from('A'));
+ assert_eq!(cell_at(&cells, 2, 1, 1).glyph, u32::from('B'));
+}
+
+#[test]
+fn sgr_reset_and_reverse() {
+ let reset = decode_ansi(&fixture("sgr-reset.ans"), 2, 1, [0, 0, 0]);
+ assert_eq!(occupancy(&reset[0]), (false, true));
+ assert_eq!(reset[0].glyph, u32::from('A'));
+ assert_eq!(occupancy(&reset[1]), (false, true));
+ assert_eq!(reset[1].glyph, u32::from('B'));
+ assert_eq!(reset[0].flags, 0);
+
+ let rev = decode_ansi(&fixture("sgr-reverse.ans"), 3, 1, [0, 0, 0]);
+ assert_eq!(occupancy(&rev[0]), (false, true));
+ assert_eq!(occupancy(&rev[1]), (true, true));
+ assert_eq!(occupancy(&rev[2]), (false, true));
+ assert_eq!(rev[1].bg_r, rev[0].fg_r);
+ assert_eq!([rev[1].fg_r, rev[1].fg_g, rev[1].fg_b], [0, 0, 0]);
+}
+
+#[test]
+fn sgr_truecolor_and_xterm() {
+ let tc = decode_ansi(&fixture("sgr-truecolor.ans"), 1, 1, [0, 0, 0]);
+ assert_eq!([tc[0].fg_r, tc[0].fg_g, tc[0].fg_b], [255, 128, 0]);
+ assert_eq!([tc[0].bg_r, tc[0].bg_g, tc[0].bg_b], [0, 0, 64]);
+ assert_eq!(occupancy(&tc[0]), (true, true));
+
+ let x = decode_ansi(&fixture("sgr-xterm256.ans"), 1, 1, [0, 0, 0]);
+ assert_eq!(occupancy(&x[0]), (true, true));
+ assert_eq!(x[0].glyph, u32::from('X'));
+}
+
+#[test]
+fn sgr_style_does_not_set_flags() {
+ let cells = decode_ansi(&fixture("sgr-style-ignored.ans"), 2, 1, [0, 0, 0]);
+ assert_eq!(cells[0].flags, 0);
+ assert_eq!(cells[1].flags, 0);
+ assert_eq!(cells[0].glyph, u32::from('X'));
+ assert_eq!(cells[1].glyph, u32::from('Y'));
+}
+
+#[test]
+fn sgr_ansi16_lengths() {
+ let fg = decode_ansi(&fixture("sgr-ansi16-fg.ans"), 16, 1, [0, 0, 0]);
+ assert_eq!(fg[0].glyph, u32::from('A'));
+ assert_eq!(fg[15].glyph, u32::from('P'));
+ assert!(fg.iter().all(|c| occupancy(c) == (false, true) && c.flags == 0));
+
+ let bg = decode_ansi(&fixture("sgr-ansi16-bg.ans"), 16, 1, [0, 0, 0]);
+ assert!(bg.iter().all(|c| occupancy(c) == (true, false) && c.flags == 0));
+}
diff --git a/crates/omacy-engine/tests/parity.rs b/crates/omacy-engine/tests/parity.rs
new file mode 100644
index 0000000..837fb30
--- /dev/null
+++ b/crates/omacy-engine/tests/parity.rs
@@ -0,0 +1,88 @@
+//! fill_grid vs ANSI oracle for the 37-effect matrix.
+
+use omacy_engine::abi::OmacyCell;
+use ttfx::effects::EffectCommand;
+use ttfx::engine::ctx::{Clock, EngineCtx};
+use ttfx::engine::terminal::TerminalConfig;
+use ttfx::utils::graphics::Color;
+use ttfx::utils::rng::Rng;
+
+#[path = "sgr_decode.rs"]
+mod sgr_decode;
+
+fn wordmark() -> String {
+ std::fs::read_to_string(format!(
+ "{}/../../assets/branding/screensaver.txt",
+ env!("CARGO_MANIFEST_DIR")
+ ))
+ .unwrap()
+}
+
+fn asymmetric() -> String {
+ std::fs::read_to_string(format!(
+ "{}/../../assets/fixtures/asymmetric.txt",
+ env!("CARGO_MANIFEST_DIR")
+ ))
+ .unwrap()
+}
+
+fn compare_frame(name: &str, packed: &[OmacyCell], ansi: &str, cols: u32, rows: u32) {
+ let oracle = sgr_decode::decode_ansi(ansi, cols, rows, [0, 0, 0]);
+ assert_eq!(packed.len(), oracle.len(), "{name} length");
+ for (i, (got, want)) in packed.iter().zip(oracle.iter()).enumerate() {
+ assert_eq!(got.occupancy, want.occupancy, "{name} occupancy {i}");
+ assert_eq!(got.glyph, want.glyph, "{name} glyph {i}");
+ assert_eq!(got.flags, 0, "{name} flags {i}");
+ assert_eq!(
+ [got.fg_r, got.fg_g, got.fg_b, got.fg_a],
+ [want.fg_r, want.fg_g, want.fg_b, want.fg_a],
+ "{name} fg {i}"
+ );
+ assert_eq!(
+ [got.bg_r, got.bg_g, got.bg_b, got.bg_a],
+ [want.bg_r, want.bg_g, want.bg_b, want.bg_a],
+ "{name} bg {i}"
+ );
+ }
+}
+
+fn run_effect(name: &str, input: &str, cols: i64, rows: i64, frames: u32) {
+ let mut effect = EffectCommand::from_name(name).unwrap_or_else(|| panic!("{name}"));
+ let config = TerminalConfig::gui(cols, rows, Color::from_hex("000000").unwrap());
+ let mut ctx =
+ EngineCtx::new(input, config, Rng::seeded(1), Clock::virtual_with_frame_rate(60))
+ .expect("ctx");
+ ctx.suppress_ansi = false;
+ effect.build(&mut ctx).expect("build");
+ let mut packed = vec![OmacyCell::default(); (cols * rows) as usize];
+ let mut last_ansi = String::new();
+ for _ in 0..frames {
+ match effect.next_frame(&mut ctx) {
+ Some(ansi) => {
+ ctx.terminal.fill_grid(&mut packed, [0, 0, 0]);
+ compare_frame(name, &packed, &ansi, cols as u32, rows as u32);
+ last_ansi = ansi;
+ }
+ None => {
+ if !last_ansi.is_empty() {
+ ctx.terminal.fill_grid(&mut packed, [0, 0, 0]);
+ compare_frame(name, &packed, &last_ansi, cols as u32, rows as u32);
+ }
+ return;
+ }
+ }
+ }
+}
+
+#[test]
+fn fill_grid_matches_oracle_for_all_effects() {
+ let inputs = [wordmark(), asymmetric()];
+ let canvases = [(80, 24), (160, 48)];
+ for name in EffectCommand::NAMES {
+ for input in &inputs {
+ for &(cols, rows) in &canvases {
+ run_effect(name, input, cols, rows, 180);
+ }
+ }
+ }
+}
diff --git a/crates/omacy-engine/tests/parity_debug.rs b/crates/omacy-engine/tests/parity_debug.rs
new file mode 100644
index 0000000..dcad178
--- /dev/null
+++ b/crates/omacy-engine/tests/parity_debug.rs
@@ -0,0 +1,48 @@
+//! Regression: effects that restore coordinates after ctx.frame() (unstable rumble)
+//! must still publish the displayed grid.
+
+use omacy_engine::abi::OmacyCell;
+use ttfx::effects::EffectCommand;
+use ttfx::engine::ctx::{Clock, EngineCtx};
+use ttfx::engine::effect::Effect;
+use ttfx::engine::terminal::TerminalConfig;
+use ttfx::utils::graphics::Color;
+use ttfx::utils::rng::Rng;
+
+#[path = "sgr_decode.rs"]
+mod sgr_decode;
+
+fn run(name: &str, input: &str, cols: i64, rows: i64, frames: u32) {
+ let mut effect = EffectCommand::from_name(name).unwrap();
+ let config = TerminalConfig::gui(cols, rows, Color::from_hex("000000").unwrap());
+ let mut ctx =
+ EngineCtx::new(input, config, Rng::seeded(1), Clock::virtual_with_frame_rate(60)).unwrap();
+ effect.build(&mut ctx).unwrap();
+ let mut packed = vec![OmacyCell::default(); (cols * rows) as usize];
+ for frame in 0..frames {
+ let Some(ansi) = effect.next_frame(&mut ctx) else {
+ break;
+ };
+ ctx.terminal.fill_grid(&mut packed, [0, 0, 0]);
+ let oracle = sgr_decode::decode_ansi(&ansi, cols as u32, rows as u32, [0, 0, 0]);
+ for (i, (got, want)) in packed.iter().zip(oracle.iter()).enumerate() {
+ assert_eq!(
+ (got.occupancy, got.glyph, got.fg_r, got.bg_r),
+ (want.occupancy, want.glyph, want.fg_r, want.bg_r),
+ "{name} frame={frame} cell={i} row={} col={}",
+ i / cols as usize,
+ i % cols as usize
+ );
+ }
+ }
+}
+
+#[test]
+fn unstable_rumble_fill_grid_matches_ansi() {
+ let input = std::fs::read_to_string(format!(
+ "{}/../../assets/branding/screensaver.txt",
+ env!("CARGO_MANIFEST_DIR")
+ ))
+ .unwrap();
+ run("unstable", &input, 80, 24, 180);
+}
diff --git a/crates/omacy-engine/tests/session.rs b/crates/omacy-engine/tests/session.rs
new file mode 100644
index 0000000..8f69da0
--- /dev/null
+++ b/crates/omacy-engine/tests/session.rs
@@ -0,0 +1,320 @@
+use omacy_engine::session::{ClockKind, Session};
+use omacy_engine::status::EngineError;
+
+fn wordmark() -> String {
+ std::fs::read_to_string(format!(
+ "{}/../../assets/branding/screensaver.txt",
+ env!("CARGO_MANIFEST_DIR")
+ ))
+ .unwrap()
+}
+
+fn session(effect: &str, cols: u32, rows: u32) -> Session {
+ Session::create(
+ wordmark(),
+ effect.into(),
+ [0, 0, 0, 255],
+ None,
+ Some(1),
+ cols,
+ rows,
+ ClockKind::Virtual60,
+ )
+ .expect("create")
+}
+
+#[test]
+fn create_and_step_publishes_grid() {
+ let mut s = session("beams", 80, 24);
+ let (frame, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(!waiting);
+ assert_eq!(frame.cols, 80);
+ assert_eq!(frame.rows, 24);
+ assert!(!frame.cells.is_null());
+ assert_eq!(frame.clear_a, 255);
+}
+
+#[test]
+fn running_resize_is_pending() {
+ let mut s = session("beams", 80, 24);
+ let (before, _) = s.step(1.0 / 60.0).unwrap();
+ let ptr = before.cells;
+ s.resize(100, 30).unwrap();
+ let (after, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(!waiting);
+ assert_eq!(after.cols, 80);
+ assert_eq!(after.rows, 24);
+ assert_eq!(after.cells, ptr);
+}
+
+#[test]
+fn invalid_elapsed_is_rejected() {
+ let mut s = session("wipe", 40, 12);
+ match s.step(f64::NAN) {
+ Err(EngineError::InvalidArg(_)) => {}
+ _ => panic!("expected invalid arg"),
+ }
+ match s.step(-0.1) {
+ Err(EngineError::InvalidArg(_)) => {}
+ _ => panic!("expected invalid arg"),
+ }
+}
+
+#[test]
+fn begin_next_rejected_while_running() {
+ let mut s = session("wipe", 40, 12);
+ match s.begin_next() {
+ Err(EngineError::InvalidArg(_)) => {}
+ _ => panic!("expected invalid arg"),
+ }
+}
+
+#[test]
+fn unknown_effect_is_invalid() {
+ let err = match Session::create(
+ wordmark(),
+ "not-an-effect".into(),
+ [0, 0, 0, 255],
+ None,
+ Some(1),
+ 40,
+ 12,
+ ClockKind::Virtual60,
+ ) {
+ Err(e) => e,
+ Ok(_) => panic!("expected error"),
+ };
+ assert!(matches!(err, EngineError::InvalidArg(_)));
+}
+
+#[test]
+fn geometry_cap() {
+ let err = match Session::create(
+ wordmark(),
+ "wipe".into(),
+ [0, 0, 0, 255],
+ None,
+ Some(1),
+ 513,
+ 1,
+ ClockKind::Virtual60,
+ ) {
+ Err(e) => e,
+ Ok(_) => panic!("expected error"),
+ };
+ assert!(matches!(err, EngineError::Limit(_)));
+}
+
+#[test]
+fn waiting_resize_applies_and_clears_cache() {
+ let mut s = session("wipe", 20, 8);
+ let mut waiting = false;
+ for _ in 0..10_000 {
+ let (_, w) = s.step(1.0 / 60.0).unwrap();
+ if w {
+ waiting = true;
+ break;
+ }
+ }
+ assert!(waiting, "wipe should complete on a tiny canvas");
+ s.resize(24, 10).unwrap();
+ let (frame, still) = s.step(1.0 / 60.0).unwrap();
+ assert!(still);
+ assert_eq!(frame.cols, 24);
+ assert_eq!(frame.rows, 10);
+ s.begin_next().unwrap();
+ let (frame, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(!waiting);
+ assert_eq!(frame.cols, 24);
+ assert_eq!(frame.rows, 10);
+ assert_eq!(s.generation(), 1);
+}
+
+#[test]
+fn ffi_create_off_main_fails() {
+ use omacy_engine::ffi::is_main_thread;
+ if is_main_thread() {
+ return;
+ }
+ let cfg = omacy_engine::abi::OmacySessionConfig {
+ config_dir: std::ptr::null(),
+ config_dir_len: 0,
+ ascii: b"A".as_ptr(),
+ ascii_len: 1,
+ effect: b"wipe".as_ptr(),
+ effect_len: 4,
+ bg_r: 0,
+ bg_g: 0,
+ bg_b: 0,
+ bg_a: 255,
+ has_seed: 1,
+ _pad: [0; 3],
+ seed: 1,
+ };
+ let mut out: *mut omacy_engine::session::Session = std::ptr::null_mut();
+ let status = unsafe {
+ omacy_engine::ffi::omacy_session_create(&cfg, 20, 8, &mut out)
+ };
+ assert_eq!(status, omacy_engine::OmacyStatus::WrongThread);
+ assert!(out.is_null());
+}
+
+#[test]
+fn pending_background_is_not_published_clear() {
+ let mut s = session("wipe", 20, 8);
+ s.set_pending(omacy_engine::session::ContentPacket {
+ art: None,
+ effect: "wipe".into(),
+ bg: [255, 0, 0, 255],
+ })
+ .unwrap();
+ let mut waiting = false;
+ let mut last_clear = [0u8; 4];
+ for _ in 0..10_000 {
+ let (frame, w) = s.step(1.0 / 60.0).unwrap();
+ last_clear = [frame.clear_r, frame.clear_g, frame.clear_b, frame.clear_a];
+ if w {
+ waiting = true;
+ break;
+ }
+ }
+ assert!(waiting);
+ assert_eq!(last_clear, [0, 0, 0, 255]);
+ s.begin_next().unwrap();
+ let (frame, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(!waiting);
+ assert_eq!(
+ [frame.clear_r, frame.clear_g, frame.clear_b, frame.clear_a],
+ [255, 0, 0, 255]
+ );
+}
+
+#[test]
+fn status_strings_are_nul_terminated() {
+ unsafe {
+ let p = omacy_engine::ffi::omacy_status_string(0);
+ assert!(!p.is_null());
+ let s = std::ffi::CStr::from_ptr(p).to_str().unwrap();
+ assert_eq!(s, "OMACY_OK");
+ }
+}
+
+#[test]
+fn mark_dead_clears_published_cells() {
+ let mut s = session("beams", 20, 8);
+ let (frame, _) = s.step(1.0 / 60.0).unwrap();
+ assert!(!frame.cells.is_null());
+ s.mark_dead("test".into());
+ assert!(s.is_dead());
+ let frame = s.published_c_frame();
+ assert!(frame.cells.is_null());
+}
+
+fn wait_for_end(s: &mut Session) {
+ for _ in 0..20_000 {
+ let (_, waiting) = s.step(1.0 / 60.0).unwrap();
+ if waiting {
+ return;
+ }
+ }
+ panic!("effect did not complete");
+}
+
+#[test]
+fn pending_queued_while_waiting_applies_at_following_boundary() {
+ let mut s = session("wipe", 20, 8);
+ wait_for_end(&mut s);
+ s.set_pending(omacy_engine::session::ContentPacket {
+ art: None,
+ effect: "beams".into(),
+ bg: [255, 0, 0, 255],
+ })
+ .unwrap();
+ s.begin_next().unwrap();
+ let (frame, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(!waiting);
+ assert_eq!(
+ [frame.clear_r, frame.clear_g, frame.clear_b, frame.clear_a],
+ [0, 0, 0, 255],
+ "packet queued in wait must not promote until the next boundary"
+ );
+ wait_for_end(&mut s);
+ s.begin_next().unwrap();
+ let (frame, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(!waiting);
+ assert_eq!(
+ [frame.clear_r, frame.clear_g, frame.clear_b, frame.clear_a],
+ [255, 0, 0, 255]
+ );
+}
+
+#[test]
+fn begin_next_consumes_running_pending_geometry() {
+ let mut s = session("wipe", 20, 8);
+ s.resize(30, 12).unwrap();
+ let (frame, _) = s.step(1.0 / 60.0).unwrap();
+ assert_eq!(frame.cols, 20);
+ assert_eq!(frame.rows, 8);
+ wait_for_end(&mut s);
+ let (frame, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(waiting);
+ assert_eq!(frame.cols, 20);
+ assert_eq!(frame.rows, 8);
+ s.begin_next().unwrap();
+ let (frame, waiting) = s.step(1.0 / 60.0).unwrap();
+ assert!(!waiting);
+ assert_eq!(frame.cols, 30);
+ assert_eq!(frame.rows, 12);
+}
+
+#[test]
+fn reentrant_step_is_invalid() {
+ let mut s = session("wipe", 20, 8);
+ match s.force_reentrant_step() {
+ Err(EngineError::InvalidArg(_)) => {}
+ other => panic!("expected invalid arg, got {other:?}"),
+ }
+ s.step(1.0 / 60.0).expect("session still live after re-entrant reject");
+}
+
+#[test]
+fn esc_in_art_is_invalid() {
+ let err = match Session::create(
+ "\u{1b}[31mX".into(),
+ "wipe".into(),
+ [0, 0, 0, 255],
+ None,
+ Some(1),
+ 20,
+ 8,
+ ClockKind::Virtual60,
+ ) {
+ Err(e) => e,
+ Ok(_) => panic!("expected error"),
+ };
+ assert!(matches!(err, EngineError::InvalidArg(_)));
+}
+
+#[test]
+fn ascii_line_cap() {
+ let art = (0..129).map(|_| "X").collect::>().join("\n");
+ let err = match Session::create(
+ art,
+ "wipe".into(),
+ [0, 0, 0, 255],
+ None,
+ Some(1),
+ 20,
+ 8,
+ ClockKind::Virtual60,
+ ) {
+ Err(e) => e,
+ Ok(_) => panic!("expected error"),
+ };
+ assert!(matches!(err, EngineError::Limit(_)));
+}
+
+#[test]
+fn effect_pool_is_thirty_seven() {
+ assert_eq!(ttfx::effects::EffectCommand::NAMES.len(), 37);
+}
diff --git a/crates/omacy-engine/tests/sgr_decode.rs b/crates/omacy-engine/tests/sgr_decode.rs
new file mode 100644
index 0000000..0330f9a
--- /dev/null
+++ b/crates/omacy-engine/tests/sgr_decode.rs
@@ -0,0 +1,188 @@
+//! Independent SGR decoder. fill_grid must not call this.
+
+use omacy_engine::abi::OmacyCell;
+use ttfx::engine::terminal::{CELL_HAS_BACKGROUND, CELL_HAS_GLYPH};
+use ttfx::utils::hexterm;
+
+#[derive(Clone, Copy)]
+struct Pen {
+ fg: Option<[u8; 3]>,
+ bg: Option<[u8; 3]>,
+ reverse: bool,
+}
+
+impl Default for Pen {
+ fn default() -> Self {
+ Self {
+ fg: None,
+ bg: None,
+ reverse: false,
+ }
+ }
+}
+
+pub fn decode_ansi(text: &str, cols: u32, rows: u32, term_bg: [u8; 3]) -> Vec {
+ let mut cells = vec![OmacyCell::default(); (cols * rows) as usize];
+ let mut pen = Pen::default();
+ let mut row = 0u32;
+ let mut col = 0u32;
+ let bytes = text.as_bytes();
+ let chars = text.char_indices().collect::>();
+ let mut ci = 0;
+ while ci < chars.len() {
+ let (byte_index, ch) = chars[ci];
+ if ch == '\u{1b}' {
+ if byte_index + 1 < bytes.len() && bytes[byte_index + 1] == b'[' {
+ if let Some((end, params)) = parse_sgr(&bytes[byte_index..]) {
+ apply_sgr(&mut pen, ¶ms);
+ let consumed = end;
+ while ci < chars.len() && chars[ci].0 < byte_index + consumed {
+ ci += 1;
+ }
+ continue;
+ }
+ }
+ }
+ if ch == '\n' {
+ row += 1;
+ col = 0;
+ ci += 1;
+ continue;
+ }
+ if row < rows && col < cols {
+ cells[(row * cols + col) as usize] = snapshot(ch, pen, term_bg);
+ }
+ col += 1;
+ ci += 1;
+ }
+ cells
+}
+
+fn parse_sgr(bytes: &[u8]) -> Option<(usize, Vec)> {
+ if bytes.len() < 3 || bytes[0] != 0x1B || bytes[1] != b'[' {
+ return None;
+ }
+ let mut params = Vec::new();
+ let mut n: Option = None;
+ for (idx, b) in bytes[2..].iter().enumerate() {
+ match *b {
+ b'0'..=b'9' => {
+ let d = (*b - b'0') as u16;
+ n = Some(n.unwrap_or(0).saturating_mul(10).saturating_add(d));
+ }
+ b';' => {
+ params.push(n.unwrap_or(0));
+ n = None;
+ }
+ b'm' => {
+ params.push(n.unwrap_or(0));
+ return Some((idx + 3, params));
+ }
+ _ => return None,
+ }
+ }
+ None
+}
+
+fn apply_sgr(pen: &mut Pen, params: &[u16]) {
+ let mut i = 0;
+ while i < params.len() {
+ match params[i] {
+ 0 => *pen = Pen::default(),
+ 1 | 22 | 3 | 23 | 4 | 24 => {}
+ 7 => pen.reverse = true,
+ 27 => pen.reverse = false,
+ 30..=37 => pen.fg = Some(ansi16((params[i] - 30) as u8)),
+ 90..=97 => pen.fg = Some(ansi16((params[i] - 90 + 8) as u8)),
+ 40..=47 => pen.bg = Some(ansi16((params[i] - 40) as u8)),
+ 100..=107 => pen.bg = Some(ansi16((params[i] - 100 + 8) as u8)),
+ 39 => pen.fg = None,
+ 49 => pen.bg = None,
+ 38 | 48 => {
+ let is_fg = params[i] == 38;
+ if i + 1 < params.len() && params[i + 1] == 5 && i + 2 < params.len() {
+ let rgb = xterm256(params[i + 2] as u8);
+ if is_fg {
+ pen.fg = Some(rgb);
+ } else {
+ pen.bg = Some(rgb);
+ }
+ i += 2;
+ } else if i + 1 < params.len() && params[i + 1] == 2 && i + 4 < params.len() {
+ let rgb = [
+ params[i + 2] as u8,
+ params[i + 3] as u8,
+ params[i + 4] as u8,
+ ];
+ if is_fg {
+ pen.fg = Some(rgb);
+ } else {
+ pen.bg = Some(rgb);
+ }
+ i += 4;
+ }
+ }
+ _ => {}
+ }
+ i += 1;
+ }
+}
+
+fn ansi16(code: u8) -> [u8; 3] {
+ xterm256(code)
+}
+
+fn xterm256(code: u8) -> [u8; 3] {
+ let hex = hexterm::xterm_to_hex(code);
+ let s = hex.trim_matches('#');
+ [
+ u8::from_str_radix(&s[0..2], 16).unwrap(),
+ u8::from_str_radix(&s[2..4], 16).unwrap(),
+ u8::from_str_radix(&s[4..6], 16).unwrap(),
+ ]
+}
+
+fn snapshot(ch: char, pen: Pen, term_bg: [u8; 3]) -> OmacyCell {
+ let mut cell = OmacyCell::default();
+ let ink = pen.fg.unwrap_or([255, 255, 255]);
+ let (fg, bg, has_background) = if pen.reverse {
+ (pen.bg.unwrap_or(term_bg), Some(ink), true)
+ } else {
+ (ink, pen.bg, pen.bg.is_some())
+ };
+ if has_background {
+ let [r, g, b] = bg.unwrap();
+ cell.occupancy |= CELL_HAS_BACKGROUND;
+ cell.bg_r = r;
+ cell.bg_g = g;
+ cell.bg_b = b;
+ cell.bg_a = 255;
+ }
+ if ch != ' ' && ch != '\0' {
+ cell.occupancy |= CELL_HAS_GLYPH;
+ cell.glyph = ch as u32;
+ cell.fg_r = fg[0];
+ cell.fg_g = fg[1];
+ cell.fg_b = fg[2];
+ cell.fg_a = 255;
+ }
+ cell
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn decoder_compiles() {
+ let cells = decode_ansi("A", 1, 1, [0, 0, 0]);
+ assert_eq!(cells[0].glyph, u32::from('A'));
+ }
+}
+
+pub fn occupancy(cell: &OmacyCell) -> (bool, bool) {
+ (
+ cell.occupancy & CELL_HAS_BACKGROUND != 0,
+ cell.occupancy & CELL_HAS_GLYPH != 0,
+ )
+}
diff --git a/crates/omacy-engine/tests/thumbnails.rs b/crates/omacy-engine/tests/thumbnails.rs
new file mode 100644
index 0000000..7c3ad4a
--- /dev/null
+++ b/crates/omacy-engine/tests/thumbnails.rs
@@ -0,0 +1,28 @@
+use std::collections::HashSet;
+
+fn imageset() -> std::path::PathBuf {
+ std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+ .join("../../apps/Omacy/OmacyScreensaver/Assets.xcassets/thumbnail.imageset")
+}
+
+#[test]
+fn screensaver_thumbnails_are_landscape_canary() {
+ let dir = imageset();
+ let one_x = image::open(dir.join("thumbnail.png")).expect("thumbnail.png");
+ let two_x = image::open(dir.join("thumbnail@2x.png")).expect("thumbnail@2x.png");
+ assert_eq!(one_x.width(), 107);
+ assert_eq!(one_x.height(), 65);
+ assert_eq!(two_x.width(), 214);
+ assert_eq!(two_x.height(), 65 * 2);
+
+ let rgb = one_x.to_rgb8();
+ let colors: HashSet<_> = rgb.pixels().map(|p| p.0).collect();
+ assert!(
+ colors.len() >= 3,
+ "thumbnail must show the canary (field + blank + glyph), got {} colors",
+ colors.len()
+ );
+ assert!(colors.contains(&[0, 0, 0]), "field is black");
+ assert!(colors.iter().any(|c| c[2] > 200 && c[0] < 80), "bottom-left blank is blue");
+ assert!(colors.contains(&[255, 255, 255]), "top-right glyph is white");
+}
diff --git a/docs/ffi.md b/docs/ffi.md
index 06a6d53..56b1a30 100644
--- a/docs/ffi.md
+++ b/docs/ffi.md
@@ -129,6 +129,9 @@ Layout is fixed-width, not a C `enum` type. The crate asserts `size_of` / `align
16 bytes, `#[repr(C)]`, little-endian.
```c
+#define OMACY_CELL_HAS_BACKGROUND 1 /* occupancy bit0 */
+#define OMACY_CELL_HAS_GLYPH 2 /* occupancy bit1 */
+
typedef struct {
uint32_t glyph; /* Unicode scalar. 0 if !has_glyph. Spaces never set has_glyph. */
uint8_t fg_r, fg_g, fg_b, fg_a;
diff --git a/docs/macos-gates.md b/docs/macos-gates.md
new file mode 100644
index 0000000..319659a
--- /dev/null
+++ b/docs/macos-gates.md
@@ -0,0 +1,23 @@
+# macOS canary and idle gates
+
+The engine is proven with `cargo test`. Host `.app` + screensaver `.appex` **compile** on Xcode 26.6 (this Mac, unsigned arm64 Release) and via GitHub Actions `macos.yml` on `macos-26`. Idle / System Settings listing remains a **signed-install Mac gate** and is not claimed by this change.
+
+Host sources include last-known-good App Group writes, stop-before-start lifecycle, Metal→CALayer canary fallback, occupancy constants, atlas white-pixel UVs, dead-session recreate, pending-config on save, uninstall “move Omacy to Trash” copy, About credit, and missing/unelected appex recovery. Those still need a signed run to execute in ScreenSaverEngine.
+
+| Check | Status here |
+|---|---|
+| Host + appex compile (Xcode, ad-hoc) | **Pass** — local Xcode 26.6 `xcodebuild` Release arm64 `BUILD SUCCEEDED`; nested `OmacyScreensaver.appex` (`be.zenjoy.omacy.screensaver`, `com.apple.screensaver`) |
+| Install: DMG → `/Applications` or Xcode DerivedData | Unverified |
+| Discover: listed with first-party savers in System Settings | Unverified |
+| Thumbnail 107×65 / 214×130 | Landscape canary fixture PNGs present; System Settings listing unverified |
+| Enable via PaperSaver `setScreensaverEverywhere` and Settings | Sources present; unverified |
+| Idle activation on macOS 26 | Unverified |
+| Multi-display paints the fixture / engine | Unverified |
+| Teardown: `willstop` / window-nil; no leak after Settings open/close | Unverified |
+| Uninstall: host unregisters; does not delete the bundle | Unverified |
+| Recovery: missing/unelected appex | Unverified |
+| macOS 15 repeat | Deferred until a box exists |
+
+If the canary does not appear in System Settings, activate on idle, and paint every display, stop putting the engine in the appex. The host preview remains the fallback product.
+
+Force the fixture grid (no engine) with UserDefaults key `omacy.forceCanary`.
diff --git a/fastlane/.env.example b/fastlane/.env.example
new file mode 100644
index 0000000..a7d2ea5
--- /dev/null
+++ b/fastlane/.env.example
@@ -0,0 +1,12 @@
+# Optional: same 1Password item Zentty uses.
+OP_RELEASE_ENV_VAULT=Engineering
+OP_RELEASE_ENV_ITEM=Zentty Release Environment
+
+# App Store Connect API Key for match + notarization
+# Generate at https://appstoreconnect.apple.com/access/integrations/api
+ASC_KEY_ID=
+ASC_ISSUER_ID=
+ASC_KEY_FILEPATH=
+
+# Match passphrase (same as Zentty — shared cert repo)
+MATCH_PASSWORD=
diff --git a/fastlane/Appfile b/fastlane/Appfile
new file mode 100644
index 0000000..ca9d9e7
--- /dev/null
+++ b/fastlane/Appfile
@@ -0,0 +1,2 @@
+app_identifier "be.zenjoy.omacy"
+team_id "25TVW8MSGJ"
diff --git a/fastlane/ExportOptions.plist b/fastlane/ExportOptions.plist
new file mode 100644
index 0000000..3f89231
--- /dev/null
+++ b/fastlane/ExportOptions.plist
@@ -0,0 +1,21 @@
+
+
+
+
+ method
+ developer-id
+ teamID
+ 25TVW8MSGJ
+ signingStyle
+ manual
+ signingCertificate
+ Developer ID Application
+ provisioningProfiles
+
+ be.zenjoy.omacy
+ match Direct be.zenjoy.omacy macos
+ be.zenjoy.omacy.screensaver
+ match Direct be.zenjoy.omacy.screensaver macos
+
+
+
diff --git a/fastlane/Fastfile b/fastlane/Fastfile
new file mode 100644
index 0000000..ceb7901
--- /dev/null
+++ b/fastlane/Fastfile
@@ -0,0 +1,129 @@
+require "json"
+require "open3"
+
+default_platform(:mac)
+
+APP_NAME = "Omacy"
+SCHEME = "Omacy"
+PROJECT = "apps/Omacy/Omacy.xcodeproj"
+BUILD_DIR = "build/release"
+APP_PATH = "#{BUILD_DIR}/#{APP_NAME}.app"
+PROJECT_ROOT = File.expand_path("..", __dir__)
+BUNDLE_IDS = [
+ "be.zenjoy.omacy",
+ "be.zenjoy.omacy.screensaver"
+].freeze
+
+def capture_command!(*args, chdir: PROJECT_ROOT, error_message: nil)
+ stdout, stderr, status = Open3.capture3(*args, chdir: chdir)
+ return stdout if status.success?
+
+ message = error_message || "Command failed: #{args.join(" ")}"
+ message += "\n#{stderr.strip}" unless stderr.strip.empty?
+ UI.user_error!(message)
+end
+
+def hydrate_release_env_from_one_password!
+ return if defined?(@release_env_loaded) && @release_env_loaded
+
+ @release_env_loaded = true
+ ENV["OP_RELEASE_ENV_ITEM"] = "Zentty Release Environment" if ENV["OP_RELEASE_ENV_ITEM"].to_s.strip.empty?
+ ENV["OP_RELEASE_ENV_VAULT"] = "Engineering" if ENV["OP_RELEASE_ENV_VAULT"].to_s.strip.empty?
+ item = ENV["OP_RELEASE_ENV_ITEM"].to_s.strip
+ return if item.empty?
+
+ args = ["op", "item", "get", item, "--format", "json", "--reveal"]
+ vault = ENV["OP_RELEASE_ENV_VAULT"].to_s.strip
+ args += ["--vault", vault] unless vault.empty?
+ payload = JSON.parse(capture_command!(*args, error_message: "Failed to read release env from 1Password"))
+
+ Array(payload["fields"]).each do |field|
+ next if field["purpose"] == "PASSWORD" || field["purpose"] == "NOTES"
+
+ key = field["label"] || field["id"]
+ env_key = key.to_s.strip.upcase.gsub(/[^A-Z0-9]+/, "_").gsub(/\A_+|_+\z/, "")
+ next if env_key.empty?
+
+ value = field["value"].to_s
+ next if value.empty?
+
+ ENV[env_key] = value if ENV[env_key].to_s.empty?
+ end
+end
+
+def required_env!(name)
+ hydrate_release_env_from_one_password!
+ value = ENV[name].to_s.strip
+ UI.user_error!("#{name} must be set") if value.empty?
+ value
+end
+
+def resolve_asc_key_filepath
+ path = required_env!("ASC_KEY_FILEPATH")
+ candidates = [
+ path,
+ File.expand_path(path, PROJECT_ROOT),
+ File.expand_path(path, File.join(PROJECT_ROOT, "fastlane")),
+ File.expand_path(File.join("..", "zentty", path), PROJECT_ROOT),
+ File.expand_path(File.join("..", "zentty", "fastlane", File.basename(path)), PROJECT_ROOT)
+ ]
+ hit = candidates.find { |candidate| File.file?(candidate) }
+ UI.user_error!("ASC_KEY_FILEPATH not found: #{path}") unless hit
+ hit
+end
+
+def load_api_key
+ app_store_connect_api_key(
+ key_id: required_env!("ASC_KEY_ID"),
+ issuer_id: required_env!("ASC_ISSUER_ID"),
+ key_filepath: resolve_asc_key_filepath
+ )
+end
+
+def sync_signing!(readonly:)
+ required_env!("MATCH_PASSWORD")
+ match(
+ type: "developer_id",
+ platform: "macos",
+ app_identifier: BUNDLE_IDS,
+ readonly: readonly,
+ api_key: load_api_key
+ )
+end
+
+platform :mac do
+ desc "Create or update Developer ID profiles in the shared match repo"
+ lane :generate_signing do
+ sync_signing!(readonly: false)
+ end
+
+ desc "Install Developer ID cert + profiles (readonly)"
+ lane :sync_signing do
+ sync_signing!(readonly: true)
+ end
+
+ desc "Archive and export with Developer ID signing"
+ lane :archive do
+ sync_signing!(readonly: true)
+ build_mac_app(
+ project: PROJECT,
+ scheme: SCHEME,
+ configuration: "Release",
+ clean: true,
+ output_directory: BUILD_DIR,
+ output_name: APP_NAME,
+ export_method: "developer-id",
+ export_options: "fastlane/ExportOptions.plist",
+ xcargs: "ARCHS=arm64 ONLY_ACTIVE_ARCH=YES EXCLUDED_ARCHS=x86_64"
+ )
+ end
+
+ desc "Notarize the exported .app"
+ lane :notarize_app do
+ notarize(
+ package: APP_PATH,
+ api_key: load_api_key,
+ print_log: true
+ )
+ end
+end
diff --git a/fastlane/Matchfile b/fastlane/Matchfile
new file mode 100644
index 0000000..c0972c0
--- /dev/null
+++ b/fastlane/Matchfile
@@ -0,0 +1,11 @@
+git_url "git@github.com:dedene/zentty-certificates.git"
+
+type "developer_id"
+platform "macos"
+app_identifier [
+ "be.zenjoy.omacy",
+ "be.zenjoy.omacy.screensaver"
+]
+team_id "25TVW8MSGJ"
+
+storage_mode "git"
diff --git a/rust-toolchain.toml b/rust-toolchain.toml
new file mode 100644
index 0000000..7855e6d
--- /dev/null
+++ b/rust-toolchain.toml
@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.88.0"
+components = ["rustfmt", "clippy"]
diff --git a/vendor/ttfx/.gitattributes b/vendor/ttfx/.gitattributes
new file mode 100644
index 0000000..f2b947a
--- /dev/null
+++ b/vendor/ttfx/.gitattributes
@@ -0,0 +1,2 @@
+tools/parity/cases.txt merge=union
+docs/ordering-inventory.md merge=union
diff --git a/vendor/ttfx/.github/workflows/ci.yml b/vendor/ttfx/.github/workflows/ci.yml
new file mode 100644
index 0000000..009a312
--- /dev/null
+++ b/vendor/ttfx/.github/workflows/ci.yml
@@ -0,0 +1,53 @@
+name: CI
+
+on:
+ push:
+ branches: [main, master]
+ pull_request:
+
+jobs:
+ test:
+ name: Tests + parity suite
+ # Parity CI is pinned to one platform/toolchain pair (plan.md §5.20):
+ # cross-platform builds are release targets, not parity targets.
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: dtolnay/rust-toolchain@stable
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - run: ./bin/test
+
+ test-macos:
+ name: Tests (macOS)
+ # bin/test skips the parity suites off Linux, so what's left here proves the
+ # port builds, tests green (with the boundary-tolerant easing assertion for
+ # Apple's libm), and honors the CLI and signal contracts on macOS.
+ runs-on: macos-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: dtolnay/rust-toolchain@stable
+ - uses: actions/setup-python@v5
+ with:
+ python-version: "3.12"
+ - run: ./bin/test
+ - uses: actions/upload-artifact@v4
+ with:
+ name: ttfx-aarch64-apple-darwin
+ path: target/release/ttfx
+
+ release-binary:
+ name: Static musl binary
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: dtolnay/rust-toolchain@stable
+ with:
+ targets: x86_64-unknown-linux-musl
+ - run: sudo apt-get update && sudo apt-get install -y musl-tools
+ - run: cargo build --release --target x86_64-unknown-linux-musl
+ - uses: actions/upload-artifact@v4
+ with:
+ name: ttfx-x86_64-unknown-linux-musl
+ path: target/x86_64-unknown-linux-musl/release/ttfx
diff --git a/vendor/ttfx/.gitignore b/vendor/ttfx/.gitignore
new file mode 100644
index 0000000..deba4cc
--- /dev/null
+++ b/vendor/ttfx/.gitignore
@@ -0,0 +1,5 @@
+/target
+/tools/parity/inputs/
+__pycache__/
+.claude/
+/reference/tte/
diff --git a/vendor/ttfx/Cargo.lock b/vendor/ttfx/Cargo.lock
new file mode 100644
index 0000000..aecf7ae
--- /dev/null
+++ b/vendor/ttfx/Cargo.lock
@@ -0,0 +1,248 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
+
+[[package]]
+name = "clap"
+version = "4.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_complete"
+version = "4.6.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3be2ad0423bdbbb0e25bc89add796f3559706d4a95e1bc98e4d9662a957b6a19"
+dependencies = [
+ "clap",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "syn"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "terminal_size"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "230a1b821ccbd75b185820a1f1ff7b14d21da1e442e22c0863ea5f08771a8874"
+dependencies = [
+ "rustix",
+ "windows-sys",
+]
+
+[[package]]
+name = "ttfx"
+version = "0.3.2"
+dependencies = [
+ "clap",
+ "clap_complete",
+ "terminal_size",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
diff --git a/vendor/ttfx/Cargo.toml b/vendor/ttfx/Cargo.toml
new file mode 100644
index 0000000..ab1b599
--- /dev/null
+++ b/vendor/ttfx/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+name = "ttfx"
+version = "0.3.2"
+edition = "2021"
+description = "Terminal text effects — a Rust port of terminaltexteffects (TTE)"
+license = "MIT"
+
+[dependencies]
+clap = { version = "4", features = ["derive"] }
+clap_complete = "4.6.9"
+terminal_size = "0.4"
+
+[profile.release]
+lto = true
+strip = true
+codegen-units = 1
+panic = "abort"
diff --git a/vendor/ttfx/LICENSE b/vendor/ttfx/LICENSE
new file mode 100644
index 0000000..3de7372
--- /dev/null
+++ b/vendor/ttfx/LICENSE
@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 37signals / omacom-io
+Copyright (c) 2023 ChrisBuilds (TerminalTextEffects, from which this is ported)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/vendor/ttfx/NOTICE b/vendor/ttfx/NOTICE
new file mode 100644
index 0000000..01f6cb3
--- /dev/null
+++ b/vendor/ttfx/NOTICE
@@ -0,0 +1,16 @@
+ttfx is a port of TerminalTextEffects (TTE).
+
+ TerminalTextEffects
+ https://github.com/ChrisBuilds/terminaltexteffects
+ MIT License, Copyright (c) 2023 ChrisBuilds
+
+Every effect in this program, the animation engine's architecture, and the
+command-line interface are that project's design. This port translates the
+work to Rust and reproduces its rendering exactly — frame for frame, byte for
+byte — but originates none of the art.
+
+The parity test suite compares against upstream at commit
+7a91dd9ca6ee0c4f4b1484efee0ecac1bb84104e (v0.15.0). That source is not
+vendored here; tools/parity/fetch_reference.sh clones it on demand.
+
+If you enjoy these effects, the credit belongs upstream.
diff --git a/vendor/ttfx/PIN b/vendor/ttfx/PIN
new file mode 100644
index 0000000..ac489c5
--- /dev/null
+++ b/vendor/ttfx/PIN
@@ -0,0 +1,9 @@
+7203e354498462064b7c0a89375051f65cf2ce99
+
+Patches (engine seams only; no effect-file forks):
+
+- Terminal::fill_grid + present-grid snapshot at frame()/ANSI emit
+- TerminalConfig::gui()
+- EngineCtx.suppress_ansi
+- Effect::advance default method
+- EffectCommand::from_name
diff --git a/vendor/ttfx/README.md b/vendor/ttfx/README.md
new file mode 100644
index 0000000..1472a73
--- /dev/null
+++ b/vendor/ttfx/README.md
@@ -0,0 +1,155 @@
+# ttfx
+
+Terminal text effects as a single static binary. Pipe text in, pick an effect:
+
+```sh
+ls -la | ttfx decrypt
+cat banner.txt | ttfx beams
+fortune | ttfx --random-effect
+git log --oneline -10 | ttfx matrix
+```
+
+
+
+## Credit where it's due
+
+**This is a port of [TerminalTextEffects](https://github.com/ChrisBuilds/terminaltexteffects)
+(TTE) by [ChrisBuilds](https://github.com/ChrisBuilds).** Every effect, the animation engine,
+and the command-line interface are their design — this project translates that work to Rust
+and adds nothing of its own to the art. If you like what you see here, star the original.
+
+TTE is MIT licensed and so is this port; the original copyright is preserved in
+[LICENSE](LICENSE) and [NOTICE](NOTICE). Please file *effect* ideas upstream, where they belong.
+
+## Why a port
+
+TTE is a Python package. That's the right call for a library, but for a shell toy that lives in
+your prompt pipeline it means an interpreter, an install step, and ~65 ms of import before the
+first frame. ttfx is one dependency-free binary that starts in half a millisecond.
+
+That difference is the whole reason this exists. On a fullscreen canvas the heavier effects run
+out of headroom under Python. Time to render a whole animation, pacing disabled so this measures
+throughput rather than `sleep()`:
+
+| At 200×50 cells | frames | ttfx | Python TTE | ttfx fps |
+|---|---|---|---|---|
+| slide | 375 | 76 ms | 2,203 ms | 4,930 |
+| beams | 732 | 181 ms | 5,564 ms | 4,050 |
+| rings | 1,566 | 521 ms | 10,439 ms | 3,004 |
+| waves | 633 | 374 ms | 8,745 ms | 1,693 |
+| startup | — | 0.5 ms | 64 ms | — |
+
+Across the 35 effects that aren't gated on wall-clock time, the median speedup is **27.5×**
+(range 17.1×–47.4×). The two that are gated — `matrix` and `thunderstorm` — spend most of their
+runtime in a fixed animation duration that no implementation can shorten, so they come in at
+1.9× and 1.3×; what ttfx buys there is a far higher frame rate inside that window, not a shorter
+one.
+
+Reproduce it with `python3 tools/tests/bench_full.py`, or set `TTFX_BENCH_COLS`, `TTFX_BENCH_LINES`
+and `TTFX_BENCH_FILL=1` for the fullscreen numbers above. Both sides run their real user-facing
+command, best of five.
+
+## The effects
+
+All 37, each animating the Omarchy logo. Every frame below came out of the Rust binary — and is
+byte-identical to what the Python original produces from the same input and seed.
+
+| | |
+|:---:|:---:|
+| beams
Create beams which travel over the canvas illuminating the characters behind them | binarypath
Binary representations of each character move towards the home coordinate of the character |
+| blackhole
Characters are consumed by a black hole and explode outwards | bouncyballs
Characters are bouncy balls falling from the top of the canvas |
+| bubbles
Characters are formed into bubbles that float down and pop | burn
Burns vertically in the canvas |
+| colorshift
Display a gradient that shifts colors across the terminal | crumble
Characters lose color and crumble into dust, vacuumed up, and reformed |
+| decrypt
Display a movie style decryption effect | errorcorrect
Some characters start in the wrong position and are corrected in sequence |
+| expand
Expands the text from a single point | fireworks
Characters launch and explode like fireworks and fall into place |
+| highlight
Run a specular highlight across the text | laseretch
A laser etches characters onto the terminal |
+| matrix
Matrix digital rain effect | middleout
Text expands in a single row or column in the middle of the canvas then out |
+| orbittingvolley
Four launchers orbit the canvas firing volleys of characters inward to build the input text from the center out | overflow
Input text overflows and scrolls the terminal in a random order until eventually appearing ordered |
+| pour
Pours the characters into position from the given direction | print
Lines are printed one at a time following a print head. Print head performs line feed, carriage return |
+| rain
Rain characters from the top of the canvas | randomsequence
Prints the input data in a random sequence |
+| rings
Characters are dispersed and form into spinning rings | scattered
Text is scattered across the canvas and moves into position |
+| slice
Slices the input in half and slides it into place from opposite directions | slide
Slide characters into view from outside the terminal |
+| smoke
Smoke floods the canvas colorizing any characters it crosses | spotlights
Spotlights search the text area, illuminating characters, before converging in the center and expanding |
+| spray
Draws the characters spawning at varying rates from a single point | swarm
Characters are grouped into swarms and move around the terminal before settling into position |
+| sweep
Sweep across the canvas to reveal uncolored text, reverse sweep to color the text | synthgrid
Create a grid which fills with characters dissolving into the final text |
+| thunderstorm
Create a thunderstorm in the terminal | unstable
Spawn characters jumbled, explode them to the edge of the canvas, then reassemble them in the correct layout |
+| vhstape
Lines of characters glitch left and right and lose detail like an old VHS tape | waves
Waves travel across the terminal leaving behind the characters |
+| wipe
Wipes the text across the terminal to reveal characters | |
+
+Every effect takes its own options — `ttfx --help`. A few of the GIFs above shorten a
+timed phase so the loop stays watchable (`matrix --rain-time 3`, `thunderstorm --storm-time 3`,
+`vhstape --total-glitch-time 250`, `spotlights --search-duration 80`, `errorcorrect
+--error-pairs 0.5`); everything else is stock.
+
+## Fidelity
+
+This is a *parity port*, not a reimplementation-in-spirit. Given the same input, config, and
+random draws, ttfx produces **byte-identical frames** to the Python original — verified
+mechanically in CI against a pinned upstream checkout (v0.15.0), not by eyeballing.
+
+| Suite | Checks | What it proves |
+|---|---|---|
+| `tools/parity/run_suite.sh` | 354 | every effect's frame stream, byte for byte, across configs and seeds |
+| `tools/parity/tty_compare.sh` | 41 | the full terminal byte stream — canvas prep, cursor moves, teardown |
+| `tools/tests/cli_corpus.sh` | 19 | exit codes and stdout/stderr routing |
+| `tools/tests/*_behavior.py` | pty | what only a real terminal shows: resize restarts, signal teardown |
+| `cargo test` | goldens + traces | easing/geometry/gradient values and engine state machines |
+
+`./bin/test` runs the lot, which is all CI does.
+
+Making that possible meant reproducing upstream's quirks deliberately, not "fixing" them:
+Python's banker's rounding, gradients built from integer floor division rather than float
+interpolation, a bezier arc-length approximation that drops its final segment, and looping
+scenes that report themselves complete on every tick. They're catalogued in
+[`plan.md`](plan.md); the places where Python's unordered iteration had to be pinned down are
+in [`docs/ordering-inventory.md`](docs/ordering-inventory.md).
+
+**Two deliberate differences.** Random number generation is not bit-compatible with CPython —
+ttfx uses xoshiro256++, so `--seed` is reproducible within ttfx but won't match Python's
+Mersenne Twister. (The parity harness swaps a shared PRNG into both sides, which is what makes
+frame comparison possible at all.) And Python plugin effects aren't supported, since there's
+no interpreter to load them.
+
+## Usage
+
+```
+ | ttfx [terminal options] [effect options]
+
+ttfx --help # all 37 effects and the terminal options
+ttfx --help # options for one effect
+ttfx --random-effect # surprise me (--include-effects / --exclude-effects to filter)
+ttfx --print-completion bash|zsh
+```
+
+Terminal options (canvas size and anchoring, color handling, frame rate, text wrapping) go
+before the effect name; effect options after it. Option names and defaults match `tte`, so
+existing invocations work with the binary name swapped.
+
+## Building
+
+```sh
+cargo build --release
+cargo build --release --target x86_64-unknown-linux-musl # static, ~3.3 MB
+```
+
+`./bin/test` runs every suite. It needs python3, and the parity half needs a copy of
+upstream, which it clones at the pinned commit on first run:
+
+```sh
+./tools/parity/fetch_reference.sh # what bin/test calls; safe to run by hand
+```
+
+Upstream is not vendored here — the harness fetches it, because it's their code.
+
+## Scope
+
+Linux and macOS. Built for [Omarchy](https://omarchy.org) originally; nothing targets a
+specific libc, and CI runs the tests and CLI corpus on both platforms. The byte-exact
+parity suites stay pinned to Linux/glibc — Apple's libm rounds a few transcendentals a
+last-ulp differently, which quantization hides in real frames but a bit-exact comparison
+would surface.
+
+## License
+
+MIT — see [LICENSE](LICENSE), which carries both this project's copyright and the original
+TerminalTextEffects copyright, and [NOTICE](NOTICE) for the attribution in full.
diff --git a/vendor/ttfx/bin/build b/vendor/ttfx/bin/build
new file mode 100755
index 0000000..1f699b3
--- /dev/null
+++ b/vendor/ttfx/bin/build
@@ -0,0 +1,14 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+
+if ! command -v cargo >/dev/null 2>&1; then
+ echo "cargo is required to build ttfx." >&2
+ exit 1
+fi
+
+cd "$ROOT"
+cargo build --release "$@"
+
+echo "Built $ROOT/target/release/ttfx"
diff --git a/vendor/ttfx/bin/release b/vendor/ttfx/bin/release
new file mode 100755
index 0000000..10c563d
--- /dev/null
+++ b/vendor/ttfx/bin/release
@@ -0,0 +1,194 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+PKGS="${OMARCHY_PKGS:-$HOME/Work/omacom/omarchy-pkgs}"
+SKIP_PKGS=0
+VERSION=""
+
+usage() {
+ cat <<'EOF'
+Usage: bin/release [version] [--skip-pkgs]
+
+Cuts a ttfx release: runs the tests, bumps Cargo.toml, tags and pushes, creates
+the GitHub release with generated notes, then points the omarchy-pkgs PKGBUILD
+at the new tarball.
+
+ version 0.4.0 or v0.4.0. Defaults to bumping the last tag's patch number.
+ --skip-pkgs Leave omarchy-pkgs alone. Implied when it isn't checked out.
+
+OMARCHY_PKGS overrides where omarchy-pkgs lives
+(default: $HOME/Work/omacom/omarchy-pkgs).
+EOF
+}
+
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --skip-pkgs) SKIP_PKGS=1 ;;
+ -h | --help)
+ usage
+ exit 0
+ ;;
+ -*)
+ echo "Unknown option: $1" >&2
+ usage >&2
+ exit 1
+ ;;
+ *)
+ if [ -n "$VERSION" ]; then
+ echo "Unexpected argument: $1" >&2
+ exit 1
+ fi
+ VERSION="$1"
+ ;;
+ esac
+ shift
+done
+
+for tool in cargo git gh curl sha256sum tar awk; do
+ if ! command -v "$tool" >/dev/null 2>&1; then
+ echo "$tool is required to release ttfx." >&2
+ exit 1
+ fi
+done
+
+cd "$ROOT"
+
+if [ -n "$(git status --porcelain)" ]; then
+ echo "Working tree is dirty; commit or stash before releasing." >&2
+ exit 1
+fi
+
+PREV="$(git describe --tags --abbrev=0 2>/dev/null || true)"
+
+if [ -z "$VERSION" ]; then
+ if [ -z "$PREV" ]; then
+ echo "No v* tag to bump from; pass a version explicitly." >&2
+ exit 1
+ fi
+ VERSION="$(echo "${PREV#v}" | awk -F. -v OFS=. '{ $NF += 1; print }')"
+fi
+
+VERSION="${VERSION#v}"
+TAG="v$VERSION"
+
+case "$VERSION" in
+[0-9]*.[0-9]*.[0-9]*) ;;
+*)
+ echo "Version must look like 0.4.0; got '$VERSION'." >&2
+ exit 1
+ ;;
+esac
+
+if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+ echo "Tag $TAG already exists." >&2
+ exit 1
+fi
+
+if [ -n "$(git ls-remote --tags origin "refs/tags/$TAG")" ]; then
+ echo "Tag $TAG already exists on origin." >&2
+ exit 1
+fi
+
+if ! gh auth status >/dev/null 2>&1; then
+ echo "gh is not authenticated; run: gh auth login" >&2
+ exit 1
+fi
+
+echo "Releasing ttfx $TAG (previous: ${PREV:-none})"
+
+"$ROOT/bin/test"
+
+# From here until the commit lands, put Cargo.toml back if anything fails.
+trap 'git -C "$ROOT" checkout -- Cargo.toml Cargo.lock 2>/dev/null || true' EXIT
+
+awk -v v="$VERSION" '
+ !bumped && /^version = "/ { sub(/"[^"]*"/, "\"" v "\""); bumped = 1 }
+ { print }
+' Cargo.toml >Cargo.toml.new && mv Cargo.toml.new Cargo.toml
+
+if ! grep -q "^version = \"$VERSION\"$" Cargo.toml; then
+ echo "Failed to set version in Cargo.toml." >&2
+ exit 1
+fi
+
+# Also refreshes Cargo.lock, so both go into the bump commit.
+"$ROOT/bin/build"
+
+BUILT="$("$ROOT/target/release/ttfx" --version)"
+if [ "$BUILT" != "ttfx $VERSION" ]; then
+ echo "Built binary reports '$BUILT', expected 'ttfx $VERSION'." >&2
+ exit 1
+fi
+
+git add Cargo.toml Cargo.lock
+git commit -m "Bump to $VERSION"
+trap - EXIT
+
+git push
+git tag "$TAG"
+git push origin "$TAG"
+
+RELEASE_URL="$(gh release create "$TAG" --title "$TAG" --generate-notes)"
+
+PKGBUILD="$PKGS/pkgbuilds/ttfx/PKGBUILD"
+SHA=""
+
+if [ "$SKIP_PKGS" -eq 1 ]; then
+ echo "Skipping omarchy-pkgs (--skip-pkgs)."
+elif [ ! -f "$PKGBUILD" ]; then
+ echo "Skipping omarchy-pkgs: no PKGBUILD at $PKGBUILD."
+else
+ TMP="$(mktemp -d)"
+ trap 'rm -rf "$TMP"' EXIT
+
+ TARBALL="$TMP/ttfx-$VERSION.tar.gz"
+ URL="https://github.com/omacom-io/ttfx/archive/refs/tags/$TAG.tar.gz"
+
+ # GitHub can lag a few seconds behind the tag push.
+ attempt=1
+ while ! curl -fsSL -o "$TARBALL" "$URL"; do
+ if [ "$attempt" -ge 5 ]; then
+ echo "Could not download $URL" >&2
+ exit 1
+ fi
+ echo " tarball not ready yet, retrying"
+ sleep 3
+ attempt=$((attempt + 1))
+ done
+
+ if ! tar tzf "$TARBALL" | grep -q "^ttfx-$VERSION/"; then
+ echo "Tarball doesn't contain ttfx-$VERSION/." >&2
+ exit 1
+ fi
+
+ SHA="$(sha256sum "$TARBALL" | cut -d' ' -f1)"
+
+ # Only the first sha256sums entry is the tarball; later ones are local files.
+ awk -v v="$VERSION" -v sha="$SHA" -v q="'" '
+ /^pkgver=/ { print "pkgver=" v; next }
+ /^pkgrel=/ { print "pkgrel=1"; next }
+ !hashed && /^sha256sums=/ { sub(q "[^" q "]*" q, q sha q); hashed = 1 }
+ { print }
+ ' "$PKGBUILD" >"$PKGBUILD.new" && mv "$PKGBUILD.new" "$PKGBUILD"
+
+ if ! grep -q "^pkgver=$VERSION$" "$PKGBUILD" || ! grep -q "$SHA" "$PKGBUILD"; then
+ echo "PKGBUILD was not updated as expected; leaving it for you to inspect." >&2
+ exit 1
+ fi
+
+ if command -v bash >/dev/null 2>&1; then
+ bash -n "$PKGBUILD"
+ fi
+
+ git -C "$PKGS" add pkgbuilds/ttfx
+ git -C "$PKGS" commit -m "Update ttfx to $TAG"
+ git -C "$PKGS" push
+fi
+
+echo
+echo "Released ttfx $TAG"
+echo " $RELEASE_URL"
+if [ -n "$SHA" ]; then
+ echo " omarchy-pkgs updated to $SHA"
+fi
diff --git a/vendor/ttfx/bin/test b/vendor/ttfx/bin/test
new file mode 100755
index 0000000..39dd719
--- /dev/null
+++ b/vendor/ttfx/bin/test
@@ -0,0 +1,31 @@
+#!/usr/bin/env sh
+# Everything CI runs, in one command. Nothing here is optional: if it passes
+# locally it passes on the runner, and the workflow is just a call to this.
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+
+for tool in cargo python3; do
+ if ! command -v "$tool" >/dev/null 2>&1; then
+ echo "$tool is required to run the ttfx tests." >&2
+ exit 1
+ fi
+done
+
+cd "$ROOT"
+
+cargo test --release
+"$ROOT/bin/build"
+./tools/tests/cli_corpus.sh
+python3 tools/tests/sigterm_behavior.py
+python3 tools/tests/terminal_close_behavior.py
+
+# Bit-exact parity is pinned to Linux/glibc (plan.md §5.20) — elsewhere the
+# reference was never promised to match. The resize suite goes with it: its
+# timings are calibrated on that runner, so a slower one would only flake.
+if [ "$(uname -s)" = "Linux" ]; then
+ ./tools/parity/fetch_reference.sh
+ ./tools/parity/run_suite.sh
+ ./tools/parity/tty_compare.sh
+ python3 tools/tests/resize_behavior.py
+fi
diff --git a/vendor/ttfx/docs/effects/beams.gif b/vendor/ttfx/docs/effects/beams.gif
new file mode 100644
index 0000000..12a67ed
Binary files /dev/null and b/vendor/ttfx/docs/effects/beams.gif differ
diff --git a/vendor/ttfx/docs/effects/binarypath.gif b/vendor/ttfx/docs/effects/binarypath.gif
new file mode 100644
index 0000000..0cef0fa
Binary files /dev/null and b/vendor/ttfx/docs/effects/binarypath.gif differ
diff --git a/vendor/ttfx/docs/effects/blackhole.gif b/vendor/ttfx/docs/effects/blackhole.gif
new file mode 100644
index 0000000..d7b536a
Binary files /dev/null and b/vendor/ttfx/docs/effects/blackhole.gif differ
diff --git a/vendor/ttfx/docs/effects/bouncyballs.gif b/vendor/ttfx/docs/effects/bouncyballs.gif
new file mode 100644
index 0000000..8743c95
Binary files /dev/null and b/vendor/ttfx/docs/effects/bouncyballs.gif differ
diff --git a/vendor/ttfx/docs/effects/bubbles.gif b/vendor/ttfx/docs/effects/bubbles.gif
new file mode 100644
index 0000000..7cc8698
Binary files /dev/null and b/vendor/ttfx/docs/effects/bubbles.gif differ
diff --git a/vendor/ttfx/docs/effects/burn.gif b/vendor/ttfx/docs/effects/burn.gif
new file mode 100644
index 0000000..6ae5cd0
Binary files /dev/null and b/vendor/ttfx/docs/effects/burn.gif differ
diff --git a/vendor/ttfx/docs/effects/colorshift.gif b/vendor/ttfx/docs/effects/colorshift.gif
new file mode 100644
index 0000000..7cd6ece
Binary files /dev/null and b/vendor/ttfx/docs/effects/colorshift.gif differ
diff --git a/vendor/ttfx/docs/effects/crumble.gif b/vendor/ttfx/docs/effects/crumble.gif
new file mode 100644
index 0000000..7f37f7a
Binary files /dev/null and b/vendor/ttfx/docs/effects/crumble.gif differ
diff --git a/vendor/ttfx/docs/effects/decrypt.gif b/vendor/ttfx/docs/effects/decrypt.gif
new file mode 100644
index 0000000..54834fb
Binary files /dev/null and b/vendor/ttfx/docs/effects/decrypt.gif differ
diff --git a/vendor/ttfx/docs/effects/errorcorrect.gif b/vendor/ttfx/docs/effects/errorcorrect.gif
new file mode 100644
index 0000000..26caba7
Binary files /dev/null and b/vendor/ttfx/docs/effects/errorcorrect.gif differ
diff --git a/vendor/ttfx/docs/effects/expand.gif b/vendor/ttfx/docs/effects/expand.gif
new file mode 100644
index 0000000..d772947
Binary files /dev/null and b/vendor/ttfx/docs/effects/expand.gif differ
diff --git a/vendor/ttfx/docs/effects/fireworks.gif b/vendor/ttfx/docs/effects/fireworks.gif
new file mode 100644
index 0000000..ddfc51a
Binary files /dev/null and b/vendor/ttfx/docs/effects/fireworks.gif differ
diff --git a/vendor/ttfx/docs/effects/highlight.gif b/vendor/ttfx/docs/effects/highlight.gif
new file mode 100644
index 0000000..056f03b
Binary files /dev/null and b/vendor/ttfx/docs/effects/highlight.gif differ
diff --git a/vendor/ttfx/docs/effects/laseretch.gif b/vendor/ttfx/docs/effects/laseretch.gif
new file mode 100644
index 0000000..ff010f3
Binary files /dev/null and b/vendor/ttfx/docs/effects/laseretch.gif differ
diff --git a/vendor/ttfx/docs/effects/matrix.gif b/vendor/ttfx/docs/effects/matrix.gif
new file mode 100644
index 0000000..a587e47
Binary files /dev/null and b/vendor/ttfx/docs/effects/matrix.gif differ
diff --git a/vendor/ttfx/docs/effects/middleout.gif b/vendor/ttfx/docs/effects/middleout.gif
new file mode 100644
index 0000000..d669b38
Binary files /dev/null and b/vendor/ttfx/docs/effects/middleout.gif differ
diff --git a/vendor/ttfx/docs/effects/orbittingvolley.gif b/vendor/ttfx/docs/effects/orbittingvolley.gif
new file mode 100644
index 0000000..36d6b58
Binary files /dev/null and b/vendor/ttfx/docs/effects/orbittingvolley.gif differ
diff --git a/vendor/ttfx/docs/effects/overflow.gif b/vendor/ttfx/docs/effects/overflow.gif
new file mode 100644
index 0000000..9bf67d5
Binary files /dev/null and b/vendor/ttfx/docs/effects/overflow.gif differ
diff --git a/vendor/ttfx/docs/effects/pour.gif b/vendor/ttfx/docs/effects/pour.gif
new file mode 100644
index 0000000..476859f
Binary files /dev/null and b/vendor/ttfx/docs/effects/pour.gif differ
diff --git a/vendor/ttfx/docs/effects/print.gif b/vendor/ttfx/docs/effects/print.gif
new file mode 100644
index 0000000..8f59c6f
Binary files /dev/null and b/vendor/ttfx/docs/effects/print.gif differ
diff --git a/vendor/ttfx/docs/effects/rain.gif b/vendor/ttfx/docs/effects/rain.gif
new file mode 100644
index 0000000..d659117
Binary files /dev/null and b/vendor/ttfx/docs/effects/rain.gif differ
diff --git a/vendor/ttfx/docs/effects/randomsequence.gif b/vendor/ttfx/docs/effects/randomsequence.gif
new file mode 100644
index 0000000..7f03ffb
Binary files /dev/null and b/vendor/ttfx/docs/effects/randomsequence.gif differ
diff --git a/vendor/ttfx/docs/effects/rings.gif b/vendor/ttfx/docs/effects/rings.gif
new file mode 100644
index 0000000..7337412
Binary files /dev/null and b/vendor/ttfx/docs/effects/rings.gif differ
diff --git a/vendor/ttfx/docs/effects/scattered.gif b/vendor/ttfx/docs/effects/scattered.gif
new file mode 100644
index 0000000..126424d
Binary files /dev/null and b/vendor/ttfx/docs/effects/scattered.gif differ
diff --git a/vendor/ttfx/docs/effects/slice.gif b/vendor/ttfx/docs/effects/slice.gif
new file mode 100644
index 0000000..49f0973
Binary files /dev/null and b/vendor/ttfx/docs/effects/slice.gif differ
diff --git a/vendor/ttfx/docs/effects/slide.gif b/vendor/ttfx/docs/effects/slide.gif
new file mode 100644
index 0000000..7ec164b
Binary files /dev/null and b/vendor/ttfx/docs/effects/slide.gif differ
diff --git a/vendor/ttfx/docs/effects/smoke.gif b/vendor/ttfx/docs/effects/smoke.gif
new file mode 100644
index 0000000..f7e27bb
Binary files /dev/null and b/vendor/ttfx/docs/effects/smoke.gif differ
diff --git a/vendor/ttfx/docs/effects/spotlights.gif b/vendor/ttfx/docs/effects/spotlights.gif
new file mode 100644
index 0000000..894e14f
Binary files /dev/null and b/vendor/ttfx/docs/effects/spotlights.gif differ
diff --git a/vendor/ttfx/docs/effects/spray.gif b/vendor/ttfx/docs/effects/spray.gif
new file mode 100644
index 0000000..85cc7da
Binary files /dev/null and b/vendor/ttfx/docs/effects/spray.gif differ
diff --git a/vendor/ttfx/docs/effects/swarm.gif b/vendor/ttfx/docs/effects/swarm.gif
new file mode 100644
index 0000000..696d20a
Binary files /dev/null and b/vendor/ttfx/docs/effects/swarm.gif differ
diff --git a/vendor/ttfx/docs/effects/sweep.gif b/vendor/ttfx/docs/effects/sweep.gif
new file mode 100644
index 0000000..52b9ea6
Binary files /dev/null and b/vendor/ttfx/docs/effects/sweep.gif differ
diff --git a/vendor/ttfx/docs/effects/synthgrid.gif b/vendor/ttfx/docs/effects/synthgrid.gif
new file mode 100644
index 0000000..3c9275e
Binary files /dev/null and b/vendor/ttfx/docs/effects/synthgrid.gif differ
diff --git a/vendor/ttfx/docs/effects/thunderstorm.gif b/vendor/ttfx/docs/effects/thunderstorm.gif
new file mode 100644
index 0000000..504d972
Binary files /dev/null and b/vendor/ttfx/docs/effects/thunderstorm.gif differ
diff --git a/vendor/ttfx/docs/effects/unstable.gif b/vendor/ttfx/docs/effects/unstable.gif
new file mode 100644
index 0000000..26e16ad
Binary files /dev/null and b/vendor/ttfx/docs/effects/unstable.gif differ
diff --git a/vendor/ttfx/docs/effects/vhstape.gif b/vendor/ttfx/docs/effects/vhstape.gif
new file mode 100644
index 0000000..4144bf1
Binary files /dev/null and b/vendor/ttfx/docs/effects/vhstape.gif differ
diff --git a/vendor/ttfx/docs/effects/waves.gif b/vendor/ttfx/docs/effects/waves.gif
new file mode 100644
index 0000000..903e750
Binary files /dev/null and b/vendor/ttfx/docs/effects/waves.gif differ
diff --git a/vendor/ttfx/docs/effects/wipe.gif b/vendor/ttfx/docs/effects/wipe.gif
new file mode 100644
index 0000000..dcfda31
Binary files /dev/null and b/vendor/ttfx/docs/effects/wipe.gif differ
diff --git a/vendor/ttfx/docs/ordering-inventory.md b/vendor/ttfx/docs/ordering-inventory.md
new file mode 100644
index 0000000..472171f
--- /dev/null
+++ b/vendor/ttfx/docs/ordering-inventory.md
@@ -0,0 +1,79 @@
+# Unordered-iteration inventory (plan.md §4.3)
+
+Every site where upstream TTE iterates an unordered container (set) or relies
+on dict insertion order, with the canonical deterministic order used by ttfx
+and matched by the parity shim. Extend this file as effect ports discover new
+sites — the parity harness surfaces them as first-divergence failures.
+
+## Engine (sets → canonical order)
+
+| Upstream site | Container | Canonical order | ttfx | shim patch |
+|---|---|---|---|---|
+| `BaseEffectIterator.update` (base_effect.py:92) | `active_characters` set | ascending `character_id` | `BTreeSet` | sort snapshot by id |
+| `Terminal._update_terminal_state` (terminal.py:1376) layer ties | `_visible_characters` set | `(layer, character_id)` | sort at render | sort key patched |
+| `EffectCharacter.links` iteration in `BreadthFirst.step` (breadthfirst.py:90) | `links` set | ascending `character_id` | id-sorted `Vec` | `sorted(links, key=id)` |
+
+## Effects (sets → canonical order)
+
+| Upstream site | Container | Canonical order | ttfx | shim patch |
+|---|---|---|---|---|
+| `MiddleOutIterator.__next__` full-phase activation loop (effect_middleout.py:229) | rebuilt `active_characters` set | ascending `character_id` | iterate `BTreeSet` | `MiddleOutIterator.__next__` sorts by id |
+| `UnstableIterator.__next__` explosion/reassembly tick loops (effect_unstable.py:332, :354) | `active_characters` set | ascending `character_id` | iterate `BTreeSet` snapshot | `UnstableIterator.__next__` sorts by id |
+
+## Engine (dict insertion order = behavior)
+
+| Upstream site | ttfx |
+|---|---|
+| `Motion.paths` / `Animation.scenes` values iteration (e.g. swarm chains `paths.values()`) | `OrderedMap` |
+| `Terminal._input_colors_frequency` (equal-count ties in `get_input_colors`) | insertion-ordered `ColorFrequency` |
+| `Gradient.build_coordinate_color_mapping` returned dict | `CoordColorMap` (insertion-ordered) |
+| `character.neighbors` (north, east, south, west) | fixed-field struct in that order |
+| `Scene.frame_index_map` | `Vec` tick map |
+| `PrimsWeighted._pending_weighted_links` (defaultdict; `min` over keys) | `BTreeMap` (order-independent result) |
+| distance buckets in `get_characters_grouped` CENTER/OUTSIDE | insertion-ordered vec of buckets |
+
+## Effect-level sets
+
+**Audit complete: all 37 effects reviewed.** Two needed canonical ordering and
+carry shim patches; the rest are documented below as order-unobservable.
+
+- middleout (effect_middleout.py:229) — set iteration — patched
+- unstable (effect_unstable.py:332, :354) — set iteration — patched
+
+Audited, no patch needed (set iteration present but order-unobservable):
+
+| Effect | Site | Why order-unobservable |
+|---|---|---|
+| slice | `for character in self.active_characters` at end of `build` (effect_slice.py) | only calls `set_character_visibility(True)`, a commutative per-character flag; render order is already canonicalized by the `_update_terminal_state` patch. ttfx iterates its `BTreeSet` (ascending id). |
+| decrypt | `for char in self.active_characters` at the typing→decrypting transition (effect_decrypt.py:263) | only calls `activate_scene("fast_decrypt")`, which mutates each character alone; no SCENE_ACTIVATED handlers registered, so order is unobservable. ttfx iterates its `BTreeSet` (ascending id). |
+| print, overflow | none | no set iteration or dict-order reliance beyond `active_characters` membership; ticking covered by the `BaseEffectIterator.update` patch, rows/lists are ordered Python lists. |
+| expand, scattered | none beyond `active_characters` membership | build loops iterate `get_characters()` lists; `active_characters` ticking covered by the `BaseEffectIterator.update` patch. |
+| colorshift, highlight, sweep, waves | none beyond `active_characters` membership (`add`/`update` only) | build loops iterate `get_characters()`/`get_characters_grouped()` lists; colorshift's `loop_tracker_map` dict is keyed access only (never iterated); ticking covered by the `BaseEffectIterator.update` patch. |
+| crumble | none beyond `active_characters` membership | falling/vacuuming pop from lists (`pending_chars`, `unvacuumed_chars`); resetting iterates `get_characters()`. |
+| blackhole | `all(character in self.blackhole_chars for ...)` over `active_characters` (effect_blackhole.py:372) | pure membership test (commutative); all activation loops iterate lists. |
+| swarm | `swarm_area_coordinate_map` is a dict (effect_swarm.py:218) | insertion-ordered dict with key-overwrite-in-place; ttfx uses an ordered `Vec<(Coord, Vec)>` with identical semantics. No set iteration. |
+| spotlights | `chars_in_range` / `illuminated_chars` set iteration in `illuminate_chars` (effect_spotlights.py:272,283) | per-character `set_appearance` only, disjoint targets, no RNG inside the loops — commutative. ttfx iterates `BTreeSet` (ascending id). |
+| burn, smoke, vhstape, synthgrid, matrix | none | no set iteration; ignition/flood/line/column/rain state is held in Python lists and dicts whose order ttfx mirrors. burn's ignition order comes from `PrimsSimple.char_link_order` (a list); smoke's flood order from `BreadthFirst.explored_last_step` (list, and its `links` iteration is already shimmed). |
+| laseretch | `color_shifted_chars: set[...]` declared at effect_laseretch.py:336 | dead code upstream — the set is never read, written, or iterated. `beam_chars` is a list. |
+| thunderstorm | none | `pending_strike_chars` / `active_strike_chars` / `pending_glow_chars` are all lists (effect_thunderstorm.py:194-198); particle pools iterate their own deques. |
+
+## lru_cache mutation quirk (plan §5 addendum)
+
+Plan.md's "Deliberate divergences" claims the geometry `lru_cache` layers are
+value-transparent. **False for swarm**: `SwarmIterator.build` calls
+`random.shuffle(...)` directly on the list returned by the cached
+`find_coords_on_circle`, mutating the cache entry in place. Later calls with
+the same focus coord return the *previously shuffled* list. ttfx reproduces
+this with an effect-local cache in `src/effects/swarm.rs` whose entries
+persist the shuffle mutation. Other ported call sites (blackhole, spotlights)
+only read the returned lists, so dropping the cache stays value-transparent
+there. Audit any future effect that mutates a geometry function's return
+value.
+| fireworks | `active_characters.add` in `__next__` (effect_fireworks.py) | membership only; shells are lists popped from the end. Ticking covered by the `BaseEffectIterator.update` patch. |
+| bubbles | `active_characters.union(bubble.characters)` in `__next__` (effect_bubbles.py) | membership only; bubbles and their character groups are lists, and `Bubble.move` steps animations in list order. Ticking covered by the `BaseEffectIterator.update` patch. |
+| beams | `active_characters.add` / `not self.active_characters` in `__next__` (effect_beams.py) | membership and emptiness only; pending/active groups and wipe groups are lists. Ticking covered by the `BaseEffectIterator.update` patch. |
+| rings | none beyond `active_characters` membership | `Ring.characters`, `pending_chars`, `non_ring_chars` are lists; `rings` dict iterated in insertion order (radius ascending, `Vec` in ttfx); RNG order fixed by list order. |
+| orbittingvolley | `any(launcher.magazine ...)` / `len(self.active_characters) > 1` | membership/length checks only; `_launchers` and magazines are lists; effect consumes no RNG. |
+| binarypath | none beyond `active_characters` membership | `pending_binary_representations`, `active_binary_reps`, `binary_characters`, `final_wipe_chars` are lists; the travel-phase `randrange` pops from a list, order preserved. |
+| laseretch | `active_chars` passed into ParticlePool; `color_shifted_chars` (effect_laseretch.py:336) | pool uses the set for membership add/discard only; `color_shifted_chars` is created but never read or iterated upstream (dead attribute, omitted in ttfx). Pool `available` is a deque, `pending_chars`/`beam_chars` are lists; RecursiveBacktracker only checks `links` for emptiness (no links iteration). Ticking covered by the `BaseEffectIterator.update` patch. |
+| synthgrid | none beyond `active_characters` membership | `pending_groups`, `grid_lines`, and each GridLine's character lists are Python lists; `group_tracker` dict is only summed over `.values()` (commutative count of nonzero entries, ttfx `Vec` indexed by group number); blocks look up `character_by_input_coord` by explicit coord list, no dict iteration. |
diff --git a/vendor/ttfx/packaging/PKGBUILD b/vendor/ttfx/packaging/PKGBUILD
new file mode 100644
index 0000000..d736817
--- /dev/null
+++ b/vendor/ttfx/packaging/PKGBUILD
@@ -0,0 +1,33 @@
+# Maintainer: David Heinemeier Hansson
+pkgname=ttfx
+pkgver=0.1.0
+pkgrel=1
+pkgdesc="Terminal text effects — single-binary Rust port of terminaltexteffects"
+arch=('x86_64')
+url="https://github.com/basecamp/ttfx"
+license=('MIT')
+depends=('gcc-libs')
+makedepends=('rust')
+source=("$pkgname-$pkgver.tar.gz::$url/archive/v$pkgver.tar.gz")
+sha256sums=('SKIP')
+
+build() {
+ cd "$pkgname-$pkgver"
+ export CARGO_TARGET_DIR=target
+ cargo build --release --locked
+}
+
+check() {
+ cd "$pkgname-$pkgver"
+ cargo test --release --locked
+}
+
+package() {
+ cd "$pkgname-$pkgver"
+ install -Dm755 "target/release/ttfx" "$pkgdir/usr/bin/ttfx"
+ install -Dm644 README.md "$pkgdir/usr/share/doc/$pkgname/README.md"
+ ./target/release/ttfx --print-completion bash \
+ | install -Dm644 /dev/stdin "$pkgdir/usr/share/bash-completion/completions/ttfx"
+ ./target/release/ttfx --print-completion zsh \
+ | install -Dm644 /dev/stdin "$pkgdir/usr/share/zsh/site-functions/_ttfx"
+}
diff --git a/vendor/ttfx/plan.md b/vendor/ttfx/plan.md
new file mode 100644
index 0000000..5980aab
--- /dev/null
+++ b/vendor/ttfx/plan.md
@@ -0,0 +1,483 @@
+# ttfx — Rust port of TerminalTextEffects
+
+> Name: `ttfx` (checked clean against Arch repos, AUR, and Debian; `ttx` was rejected —
+> taken by fonttools).
+
+A pixel-perfect reimplementation of [terminaltexteffects](https://github.com/ChrisBuilds/terminaltexteffects)
+(TTE) v0.15.0 (commit `7a91dd9`) in Rust, shipped as a single static binary with no runtime
+dependencies.
+
+## 1. Goals and non-goals
+
+**Goals**
+
+- Visual parity: given the same input, config, and random decisions, ttfx produces
+ byte-identical frames to Python TTE. "Pixel-perfect" is verified mechanically, not by eyeball
+ (see §7).
+- CLI compatibility: same effect names, option names, defaults, metavars, and choices as
+ `tte`, so existing invocations (`ls | tte decrypt --typing-speed 2`) work with `ttfx`
+ substituted.
+- Single static binary (musl), no runtime deps, fast startup.
+- All 37 effects.
+- Linux only, targeted exclusively at Omarchy (Arch). No macOS/Windows/BSD support.
+
+**Non-goals**
+
+- Bit-identical randomness with Python. TTE uses the module-global Mersenne Twister; we use our
+ own PRNG. `--seed` remains supported and is deterministic *within ttfx*.
+- The Python library API (embedding TTE in Python programs).
+- Python plugin effects (`~/.config/terminaltexteffects/effects/*.py`). Out of scope for v1;
+ the effect registry is static.
+- Wide-character correctness. TTE itself treats one codepoint as one cell (no wcwidth
+ anywhere); we reproduce that behavior for parity and document the limitation. Revisit later
+ behind a flag.
+
+## 2. Source of truth
+
+Pin the reference: TTE v0.15.0, commit `7a91dd9ca6ee0c4f4b1484efee0ecac1bb84104e`. Vendor a
+clone under `reference/tte/` (git submodule or plain checkout, excluded from the binary) so the
+parity harness and future upgrades diff against a fixed target.
+
+Scale of the port: ~22k lines of Python — engine ~3.5k, effects ~12.6k, utils ~3.3k. Expect
+roughly the same order of magnitude in Rust.
+
+## 3. Crate layout
+
+Single crate, lib + bin:
+
+```
+ttfx/
+ Cargo.toml
+ src/
+ main.rs # arg dispatch, stdin/file input, effect selection, run loop
+ cli.rs # clap root: global/terminal args, subcommand registry, completions
+ engine/
+ mod.rs
+ terminal.rs # Terminal: config, output, frame pacing, prep/restore
+ canvas.rs # Canvas: dims, anchoring, coord queries
+ input.rs # ANSI-aware input parser -> character grid (the mini terminal emulator)
+ character.rs # EffectCharacter storage (arena), visibility, neighbors/links
+ animation.rs # Scene, Frame, CharacterVisual, sync/eased stepping
+ motion.rs # Waypoint, Segment, Path, Motion
+ events.rs # EventHandler: Event, Action enums, dispatch
+ particles.rs # ParticlePool, ParticleReset
+ utils/
+ mod.rs
+ easing.rs # 31 named easings + cubic-bezier make_easing + EasingTracker/SequenceEaser
+ geometry.rs # Coord, circle/rect/bezier/line math
+ graphics.rs # Color, ColorPair, Gradient
+ hexterm.rs # xterm-256 <-> RGB table and nearest-match
+ ansi.rs # escape sequence constants + SGR builders (colorterm + ansitools)
+ pycompat.rs # Python-semantics helpers: round-half-even, floor_div, trunc — see §5
+ rng.rs # Rng trait + default PRNG + Python-shaped helpers (randint, choice, shuffle, ...)
+ spanning_tree.rs # PrimsSimple, PrimsWeighted, RecursiveBacktracker, BreadthFirst
+ effects/
+ mod.rs # static registry: name -> (build fn, clap command)
+ beams.rs ... wipe.rs # one file per effect, mirroring the Python effect files
+ tools/
+ parity/ # Python shim + differ (see §7)
+ reference/tte/ # pinned upstream checkout
+```
+
+**Dependencies** (kept deliberately short):
+
+- `clap` (derive) — CLI. Each effect's config is a struct with `#[arg(...)]` attributes,
+ the direct analog of TTE's `ArgSpec` dataclass-field trick.
+- `terminal_size` — terminal dimensions (replaces `shutil.get_terminal_size`, same
+ (80, 24) fallback on failure).
+- `getrandom` — OS entropy for unseeded runs; `signal-hook` (or a minimal self-pipe via
+ `libc`) — SIGINT handling. Statically linked crates are not runtime dependencies; the
+ single-binary goal doesn't require hand-rolling entropy or signal plumbing.
+- No rand crate: `rng.rs` implements xoshiro256++ plus Python-shaped helpers ourselves —
+ we need exact control over call semantics for the parity harness anyway (§7).
+- Dev-only: whatever the parity tooling needs (none in the binary).
+
+## 4. Core architecture decisions
+
+### 4.1 Arena + IDs instead of the Python object graph
+
+Python TTE is a web of back-references: character ⇄ animation/motion/event_handler, events
+holding Scene/Path/Waypoint objects, `links`/`neighbors` between characters, Paths mutated per
+activation. In Rust:
+
+- `Vec` arena owned by the Terminal, addressed by `CharacterId(u32)`
+ (TTE already has a monotonic `character_id` — reuse it as the index).
+- Scenes/Paths live in per-character maps addressed by `SceneId`/`PathId` (interned string or
+ small-index newtype). Waypoints by index within their Path.
+- `neighbors`/`links` store `CharacterId`s.
+- Event targets are IDs, so `EventHandler` tables are plain data:
+ `HashMap<(Event, CallerId), Vec<(Action, Target)>>` with insertion-order Vec for actions
+ (dispatch order matters).
+
+### 4.2 Ticking without aliasing — synchronous event dispatch
+
+`character.tick()` → motion first, then animation, and event callbacks fired mid-tick can
+mutate *other* characters, activate paths/scenes, and add/remove from `active_characters`
+(particles do this constantly). Crucially, Python executes actions **immediately at the
+emission point** (`_handle_event`, base_character.py:374): segment events fire in the *middle*
+of `Path.step` before the coordinate is computed, and `Motion.move` assigns the returned
+coordinate *after* callbacks ran — so e.g. a `SET_COORDINATE` action fired from a segment
+event is overwritten by the move's own assignment. A deferred queue drained after
+`step`/`move`/`tick` would change observable ordering and produce different frames even with
+identical RNG draws. Therefore: **no deferred queue.**
+
+Instead, all engine stepping functions are methods on `EngineCtx` (which owns the character
+arena, scenes, paths, events, RNG, clock) operating through IDs, never holding long-lived
+borrows of character internals. `EngineCtx::handle_event(caller, event)` is called inline at
+exactly the source's emission points, recursing depth-first just like Python's call stack.
+Where a step function needs local state across an emission point (e.g. `Path::step`'s segment
+walk), that state is plain locals (indices, distances) — not borrows — so the reentrant call
+is legal. Path/scene runtime state accessed both by the step and by reentrant actions is
+re-fetched by ID after each emission point rather than cached across it.
+
+Effect callbacks (`EventHandler.Callback` in Python — closures over iterator state, e.g.
+burn's `_emit_smoke`, and particle reclaim closures capturing the pool) cannot be boxed
+closures in the arena: they'd borrow the effect that transitively owns the arena. Instead an
+event action stores `Callback(CallbackId, Payload)` with an owned payload; the engine
+surfaces fired callbacks to the effect via `Effect::dispatch_callback(&mut self, ctx, character_id,
+callback_id, payload)`. Because Python callbacks can themselves trigger more engine work,
+`dispatch_callback` receives `&mut EngineCtx` and may recurse into engine calls — the effect
+struct and the engine context are separate ownership trees, so this borrows cleanly.
+`ParticlePool`s live in effect state and are addressed by `PoolId`; reclaim-on-event is a
+`Callback` carrying the pool id. No `Rc` anywhere.
+
+### 4.3 One Terminal, deterministic ordering
+
+Python constructs **two** Terminals per run (one owns the tty, one owns the simulation).
+Collapse to one `Terminal` (simulation + renderer) plus a thin `TtyWriter` (prep canvas,
+frame pacing, restore cursor — RAII `Drop` replaces the `@contextmanager`).
+
+**Ordering is behavior.** Python iterates unordered sets in several behaviorally relevant
+places — not just the two engine sites (`active_characters` ticking, render layer-ties) but
+also inside effects (middleout, unstable iterate sets directly) and `BreadthFirst`, which
+traverses the `links` *set*. And dict insertion order is load-bearing too: swarm chains
+`motion.paths.values()`, rings iterates `rings.values()`, and equal-frequency input-color
+sorting inherits dict insertion order. Rules:
+
+- **M1 deliverable: a complete inventory of every unordered iteration** (engine + all 37
+ effects + spanning trees), each assigned a canonical deterministic order (usually ascending
+ `CharacterId` or insertion order). The parity shim patches each Python site to the same
+ canonical order (§7).
+- Anywhere Python iterates a dict's values/items, Rust uses `Vec` + id→index lookup or an
+ insertion-ordered map — plain `HashMap` iteration is only allowed for lookup-only data.
+- Render: sort visible characters by `(layer, character_id)`; tick: snapshot
+ `active_characters` sorted by `CharacterId` (Python snapshots a tuple).
+
+**`character_id` is not a dense arena index.** Python allocates an id for *every* parsed
+character, including ones later overwritten by cursor-movement sequences, popped as trailing
+whitespace, or cropped by the canvas — so ids have gaps relative to surviving characters, and
+downstream id-ordered iteration depends on the original allocation order. The arena keeps
+slot index and `character_id` as separate values; the id counter consumes exactly as the
+Python parser does.
+
+### 4.4 Effects as a trait + static registry
+
+```rust
+pub trait Effect {
+ fn build(&mut self, ctx: &mut EngineCtx); // Python __init__/build()
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option; // __next__
+}
+```
+
+`effects/mod.rs` holds the static registry (name → clap `Command` + constructor), replacing
+`pkgutil` discovery. `--random-effect`/`--include-effects`/`--exclude-effects`/`--seed` work
+as upstream, including the quirk that a randomly selected effect runs with pure default config.
+
+### 4.5 Config system
+
+Terminal config: one clap struct with the 15 upstream options, same defaults
+(`--tab-width 4`, `--frame-rate 60`, `--canvas-width -1`, `--anchor-canvas sw`, ...), same
+value validation as `argutils` (PositiveInt, ratio ranges, hex-or-xterm ColorArg, etc. —
+implemented as clap value parsers in one module). Effect configs: one struct per effect with
+`#[arg]` attributes. The shared `final_gradient_*` args can't be a naively `#[flatten]`-ed
+struct because each effect overrides their defaults: parse them as `Option` in the shared
+struct and merge with the effect's own `Default` after parsing (or generate per-effect arg
+declarations with a small macro — decide at M0 with a two-effect spike). Help text copied
+from upstream so `--help` is familiar (exact help formatting parity is *not* a goal; option
+surface parity is). Usage errors exit 2 (clap's default, matching argparse); runtime errors
+exit 1 with upstream's stream choice — file errors print to *stdout*, unsupported-ANSI to
+*stderr* (yes, really).
+
+### 4.6 RNG
+
+`rng.rs` defines the engine RNG with Python-shaped methods matching every call TTE makes
+(counts from the survey): `randint(a,b)` (61 uses), `choice(&[T])` (54), `shuffle`
+(Fisher-Yates, 13), `randrange` (13), `uniform(a,b)` (12), `random()` (12). Backed by
+xoshiro256++; seeded from `--seed` or OS entropy (`getrandom` crate). The RNG lives on
+`EngineCtx` and is threaded explicitly — no globals — which is also what makes the parity
+harness possible (§7). Helper semantics are pinned exactly (e.g. `choice` =
+`seq[randbelow(len)]`, `uniform` = `a + (b-a)*random()`, Fisher-Yates in Python's order)
+because the Python shim mirrors them.
+
+### 4.7 Clock injection
+
+Two effects read wall/monotonic time directly: matrix (`time.time()` for rain-phase
+transitions) and thunderstorm (`time.monotonic()` for the storm budget). Real clocks would
+make parity depend on execution speed — with `frame_rate=0` a faster implementation produces
+more frames and consumes more RNG draws before a deadline. So `EngineCtx` carries a `Clock`
+(`now_wall()`, `now_monotonic()`): the production impl reads real time; the parity impl is
+virtual, advancing a fixed `1/frame_rate` per emitted frame. The Python shim monkeypatches
+`time.time` and `time.monotonic` with the same virtual clock (§7). This also bounds parity
+dump sizes for the time-budgeted effects.
+
+## 5. Fidelity traps (must-reproduce semantics)
+
+These are places where a natural Rust translation silently diverges from Python. All go
+through `pycompat.rs` helpers with tests pinned to Python-generated golden values.
+
+1. **`round()` is banker's rounding** (half-to-even). Used for every coordinate quantization,
+ `Path.max_steps`, animation frame indices, `adjust_color_brightness`. Rust's `f64::round`
+ is half-away-from-zero. → `pycompat::round_half_even(f64) -> i64` used everywhere Python
+ calls `round`.
+2. **Gradient channel deltas use integer floor division** (`(end - start) // steps`). Python
+ `//` floors; Rust `/` on integers truncates toward zero — they differ for negative deltas,
+ and gradients are *not* float lerp. → `pycompat::floor_div`, and `Gradient::generate`
+ transcribes the integer algorithm exactly (including appending the exact end stop per pair,
+ the shared-stop skip, and `loop` appending stop[0]).
+3. **Truncation vs rounding is inconsistent upstream and must stay that way**:
+ `shift_color_towards` uses `int(x*255)` (truncation); `adjust_color_brightness` uses
+ `round(x*255)` (half-to-even). Reproduce each as-is.
+4. **`find_length_of_bezier_curve` omits the final t=0.9→1.0 span** (10-sample loop bug).
+ Path lengths are systematically short; `max_steps` depends on it. Reproduce the bug.
+5. **Row deltas are doubled** in path distances (`double_row_diff=True`), circle x-offsets are
+ doubled, diagonal/radial gradient math doubles rows — the cell-aspect convention. Copy each
+ call site's choice exactly (`geometry::line_length(a, b, double_row: bool)` defaults off,
+ like upstream).
+6. **Unclamped eased `t`**: `Path.step` deliberately allows `t > 1`/`t < 0` for overshooting
+ easings (back/elastic) including traveling *past* the final waypoint via the for-else
+ overshoot re-add; `_step_eased_scene` clamps instead. Copy both behaviors.
+7. **`hex_to_xterm` metric** is minimum *mean absolute channel difference* via linear scan over
+ the 256-entry table (first minimum wins) — not Euclidean, not perceptual. Port the table and
+ scan order verbatim.
+8. **Looping-scene semantics**: `active_scene_is_complete()` returns true for looping scenes
+ (so loop-only characters get pruned from `active_characters`), and `SCENE_COMPLETE` fires
+ *every tick* for looping scenes. Effects depend on both quirks.
+9. **`activate_scene` does not reset playback** (resume semantics); `reset_scene` restores
+ played + remaining frames into the frame queue in original order, zeroes each frame's
+ `ticks_elapsed` and the easing step, and clears `played_frames`. Verify with
+ partial-playback tests.
+10. **Path re-activation mutates the path**: a synthetic origin segment from the current
+ coordinate is built, the *previous* origin segment's distance is subtracted and the new
+ one's added (rebase, not cumulative accumulation), segments[0] replaced or inserted,
+ `current_step`/`hold_time_remaining` reset, `max_steps` recomputed. Copy exactly.
+11. **Segment events key off the end Waypoint**, fire once per activation, and do not re-fire
+ on backwards easing motion. Copy the flag mechanics.
+12. **Synced-scene formulas** (`STEP`/`DISTANCE` with their `max(...,1)` guards and
+ `round()` indexing) transcribed exactly; missing active path → jump to last frame and
+ force-complete.
+13. **Input parsing**: the mini ANSI emulator (CSI-only, specific SGR subset, bold bumping a
+ pending standard fg by +8, `\t` → N space characters, cursor-movement sequences, the
+ unsupported-sequence error), trailing space/line trimming, plain uncolored spaces demoted
+ to fill characters, `"No Input."` fallback, empty-stdin-when-tty → `""`. Transcribe
+ directly with the same error taxonomy. Stateful quirks that must survive transcription:
+ *unsupported SGR parameter values are silently ignored* (the SGR loop has no error
+ fallback — only malformed/unsupported *sequences* raise), and `_input_colors_frequency`
+ increments at character-creation time, so colors of cells later overwritten by cursor
+ movement still count (affects `get_input_colors` and RNG ordering). Differential-test the
+ ugly corpus: cursor overwrites, trailing colored cells, ignored SGR params, private
+ modes, malformed CSI.
+14. **Canvas math**: center formulas (`top//2` + odd adjustment), anchor offset computation,
+ visible-bounds clamping, `outside_scope` random coords exactly one cell beyond an edge,
+ `-1`/`0` canvas sizing semantics, `--ignore-terminal-dimensions` overwriting terminal dims.
+15. **`get_characters` sort algorithms** including the destructive alternate-pop interleave for
+ outside/middle sorts (order matters, O(n²) is fine), and grouped variants' exact grouping
+ (diagonal bands by `row+column` / `column-row`, Manhattan-distance bucketing from
+ `text_center`).
+16. **CharacterVisual SGR order**: bold, italic, underline, blink, reverse, hidden, strike,
+ fg, bg, symbol, `\x1b[0m`; `dim` stored but never emitted; bare symbol when unformatted.
+ Frame string = rows joined `"\n"`, top row first. Row dimensions are **`visible_top` ×
+ `visible_right`** — absolute terminal-space extents after canvas anchoring and clipping —
+ *not* canvas width/height; non-southwest anchors produce leading blank rows/columns inside
+ every frame. Specify the renderer in `visible_*`/offset terms and golden-test all nine
+ anchors under both clipped and unclipped terminal sizes.
+17. **`existing_color_handling`** three modes including `"always"` overriding every
+ `add_frame`/`set_appearance` color and applying at parse time; `preexisting_colors_present`
+ scan. `Color` equality is on the *original argument* (`Color(255) != Color("ffffff")`) —
+ keep that for `input_colors_frequency` and any keying.
+18. **`find_normalized_distance_from_center` stays in [0,1]** for accepted coordinates (it
+ rejects out-of-rectangle coords with a `ValueError`, and the doubled-row diagonal bounds
+ the numerator); `Gradient::get_color_at_fraction` validates `0 <= f <= 1` and errors
+ otherwise. Reproduce both the rejection and the validation as errors (don't clamp), and
+ pin with exhaustive rectangle-lattice tests.
+19. **Frame pacing**: `1/frame_rate` delay, `monotonic` check, sleep remainder, timestamp
+ taken *after* sleep (drift accumulates), `frame_rate == 0` disables. Same ANSI prep/restore
+ dance: hide cursor, scroll-make-room (or `reuse_canvas` reposition), DEC save (`\x1b7`),
+ per-frame DEC restore/save + cursor-up, restore cursor + newline on exit (respecting
+ `--no-eol`/`--no-restore-cursor`), teardown running even on error/ctrl-C (RAII +
+ SIGINT handler; Python exits 1 silently on KeyboardInterrupt).
+20. **Float expression order**: transcribe arithmetic expressions in the same order/grouping as
+ Python — don't "simplify" math during port (easing functions, HSL round-trips, bezier De
+ Casteljau with float intermediates rounded only at the end). Caveat: identical expression
+ order guarantees identical results only for IEEE basic ops (+,-,*,/,sqrt). Transcendentals
+ (`sin`, `cos`, `pow`, `exp`) and `hypot` go through libm, and musl-Rust vs glibc-CPython
+ can differ by ulps. Mitigation: parity CI runs on one pinned platform/toolchain pair;
+ comparisons happen on *quantized* outputs (rounded coordinates, hex colors), which absorb
+ ulp noise except exactly at rounding boundaries; fine-grained easing/geometry goldens
+ flag any boundary case early, and such cases get boundary-tolerant assertions rather
+ than pretending bit-identity.
+
+**Deliberate divergences** (accepted, documented):
+
+- PRNG (xoshiro vs MT19937) and therefore any `--seed` output.
+- Set-iteration orderings replaced with `character_id` orderings (§4.3).
+- The `lru_cache` layers (geometry, `shift_color_towards`, `make_easing`) are dropped —
+ they're pure-function caches, so behavior is identical; Rust recomputation is cheaper than
+ Python cache hits. If profiling disagrees, memoize `make_easing`'s Newton–Raphson solve only.
+ **Addendum (found during the swarm port):** the value-transparency claim fails when an
+ effect MUTATES a cached return value — swarm `random.shuffle`s the list returned by the
+ cached `find_coords_on_circle`, so later same-argument calls observe the shuffled entry.
+ Such effects reproduce the cache at effect level (a persistent map whose entries carry the
+ mutation); audit any effect that writes to a geometry function's return value.
+- The `AldousBroder` spanning-tree generator is not ported: it exists upstream but no shipped
+ effect uses it (library-API surface, which is a non-goal).
+- No Python plugin loading.
+- Error-message *text* may differ; error *conditions* and exit codes match.
+
+## 6. Porting strategy
+
+Transcription, not reimagination: each Python file maps to one Rust file; functions keep their
+names and internal structure; comments reference upstream line numbers for anything subtle.
+The two survey documents (engine architecture + effect catalog) serve as the map; the pinned
+checkout is the letter.
+
+**Phase order** (each phase lands with its parity tests green):
+
+- **M0 — skeleton + input pipeline.** Cargo scaffold, CLI root with terminal config, stdin/file
+ input, the input parser (§5.13), Canvas + anchoring, fill characters, neighbors, renderer,
+ `TtyWriter`. Exit criterion: piping text through a no-op "effect" reproduces Python's
+ preprocessed first frame byte-for-byte across the anchor/canvas/wrap/tab/existing-color
+ option matrix.
+- **M1 — engine core.** easing (31 + `make_easing`), geometry, graphics, hexterm, animation,
+ motion, events, particles, spanning trees, `pycompat`, `rng`, clock. Exit criteria:
+ (a) golden-value tests for every pure function (inputs + expected outputs generated by a
+ Python script run against the pinned checkout, committed as fixtures); (b) the upstream
+ engine test suite (`tests/engine_tests/`) ported — it already covers multi-segment event
+ ordering, particle reclaim/reset, and scene lifecycle; (c) scripted state-trace tests for
+ the delicate machinery: nested/reentrant events, scene reactivation-resume, looping scenes,
+ path holds and loop-rebase, pool exhaustion/reuse; (d) the complete unordered-iteration
+ inventory (§4.3) written down with its canonical orders.
+- **M2 — parity harness** (§7). Exit criterion: harness runs end-to-end on a hand-written
+ trivial effect in both implementations with byte-identical frame streams.
+- **M3 — effects, wave 1 (motion + scenes basics):** randomsequence, wipe, expand, slice,
+ scattered, pour, slide, middleout, spray, rain, bouncyballs, errorcorrect. (~12 effects,
+ each small.)
+- **M4 — effects, wave 2 (gradients, sync, sequence easers, no-motion effects):** colorshift,
+ highlight, sweep, waves, decrypt, print, overflow, unstable, crumble, blackhole, swarm,
+ spotlights, fireworks, bubbles, beams, rings, orbittingvolley, binarypath.
+- **M5 — effects, wave 3 (heavy machinery):** burn + smoke (spanning trees), laseretch
+ (backtracker + particles + bezier), vhstape, synthgrid, matrix, thunderstorm. The top-5
+ hairiest land last, when the engine is fully proven.
+- **M6 — CLI completion + polish.** `--print-completion bash|zsh` (static generation from the
+ clap model, mirroring upstream's completion behavior), `--version`, `--random-effect`
+ filtering, error paths/exit codes, README.
+- **M7 — release engineering.** `x86_64-unknown-linux-musl` static build (add
+ `aarch64-unknown-linux-musl` only if Omarchy grows an ARM target), LTO + strip, CI running
+ the full parity suite against the pinned checkout, benchmark vs Python (startup + big-input
+ throughput), release artifacts + Arch packaging (PKGBUILD) for Omarchy.
+
+Each effect PR ships: the ported effect, its clap config struct, and its parity-suite entry.
+
+## 7. Parity verification (what makes "pixel-perfect" checkable)
+
+The problem: effects are random, so naive frame-diffing fails. The solution: make randomness a
+*shared injected dependency* during tests.
+
+**Deterministic RNG shim.** Implement one trivially-portable PRNG (xoshiro256++, fixed seed)
+identically in Rust (`rng.rs`, it's the real RNG) and in a small Python module
+(`tools/parity/shim.py`). The shim monkeypatches `random.randint/choice/shuffle/randrange/
+uniform/random` with the shared implementation before importing TTE. Both sides now draw
+identical random sequences — *provided the port makes RNG calls in the same order as Python*,
+which is exactly what faithful transcription gives us, and precisely what the harness verifies.
+
+**Determinism patches.** The shim also patches every site in the §4.3 inventory —
+`BaseEffectIterator.update`, render layer-tie ordering, effect-level set iterations
+(middleout, unstable, ...), `BreadthFirst`'s `links`-set traversal — to the same canonical
+orders as the Rust port. These patches pin *which* of Python's arbitrary orderings we compare
+against.
+
+**Clock patch.** The shim replaces `time.time`/`time.monotonic` with the virtual clock
+(§4.7), advancing `1/frame_rate` per frame, so matrix and thunderstorm are deterministic and
+their dumps bounded.
+
+**Shim audit.** Because the shim modifies the reference, we separately guard against "proving
+parity with a modified TTE": every deterministic (RNG-free, clock-free) effect and the whole
+M0 preprocessing matrix are *also* byte-compared against a completely unmodified pinned
+CPython run; and the shim's patches are limited by construction to ordering/RNG/clock
+substitution (a diff of shimmed-vs-unmodified TTE source is reviewed, small, and committed
+alongside the harness).
+
+**Frame capture.** Python side: shim iterates the effect with `frame_rate=0` and fixed canvas
+(`--canvas-width/height` explicit + `--ignore-terminal-dimensions`), writing each frame string
+to a length-prefixed dump. Rust side: hidden `--parity-dump ` flag does the same. A
+differ compares streams and reports first divergent frame/row/column with a decoded escape
+view.
+
+**Test matrix.** Per effect: 2–3 input texts (ASCII multiline, colored-ANSI input, ragged
+short input) × default config × 1–2 non-default configs exercising that effect's options.
+Plus the option-matrix suite for M0 preprocessing. All checked into CI; the suite regenerates
+Python dumps from `reference/tte/` on demand (dumps themselves can be cached by content hash).
+Parity CI runs on one pinned platform/toolchain pair (Arch x86_64, pinned CPython + rustc) —
+cross-platform builds are release targets, not parity targets (§5.20).
+
+**PTY byte-stream tests.** Frame dumps bypass the tty layer, so a separate small suite runs
+both implementations under a pseudo-terminal and byte-compares the *full* output stream:
+canvas prep (blank-row scroll, DEC save), per-frame restore/save/cursor-up preamble, and
+teardown (cursor show, EOL) — including the `--reuse-canvas`/`--no-eol`/`--no-restore-cursor`
+variants and the SIGINT path.
+
+**Fallback tier.** If an effect turns out to interleave RNG draws through a code path whose
+order can't reasonably be matched (none identified yet, but e.g. hash-order-dependent draw
+sequences inside an effect), it drops to tier-2 verification: structural frame comparison
+(non-random subsets byte-compared; random placements checked for distribution/bounds) plus
+manual visual sign-off against side-by-side recordings. Goal: zero tier-2 effects.
+
+**Unit goldens.** Independent of frame parity: fixtures generated from Python for easing curves
+(sampled at 1e-3 steps), all gradient constructions in the effect defaults, hexterm's full
+256-entry nearest-match on a color sweep, geometry functions on a coordinate lattice, and the
+input parser on an ANSI corpus.
+
+## 8. Runtime behavior details
+
+- **Input**: stdin (empty when tty), `--input-file`; empty/whitespace input → `NO INPUT.` on
+ stdout, exit 1. Decoding is **strict UTF-8** for both file and stdin — upstream file reads
+ are strict (decode failure → error message, exit 1) and stdin goes through Python's text
+ stream, strict UTF-8 in the environments we target. No lossy decoding; test the failure
+ path.
+- **Signals**: SIGINT is recorded via flag/self-pipe and *returns control to the main loop*,
+ which unwinds normally so the RAII teardown runs (`Drop` alone doesn't fire on a signal);
+ exit 1, no message (matches KeyboardInterrupt handling).
+- **Exit codes**: 0 success; 1 runtime errors — no-input, missing effect, file errors (message
+ on *stdout*, matching upstream), unsupported ANSI sequence (message on *stderr*); 2 usage
+ errors from argument parsing (argparse/clap convention). A CLI corpus test covers exit
+ codes, stream routing, root-option-before-subcommand placement, `nargs`-style multi-value
+ options, negative-looking values, include/exclude filtering, and decode failures.
+- **Performance target**: not a goal beyond "never the bottleneck" — full-canvas repaint at
+ 60fps on a 400×100 canvas is trivial in Rust; the O(n²) upstream algorithms (outside-in
+ sort, grouped scans) are kept for fidelity and are fine at terminal scale. Per-cell
+ `formatted_symbol` strings are precomputed on visual change exactly as upstream caches them
+ in `CharacterVisual`. Frame strings are freshly allocated `String`s at first (simple,
+ matches the `Option` iterator shape); buffer recycling only if profiling ever says
+ so.
+
+## 9. Risks
+
+| Risk | Mitigation |
+|---|---|
+| RNG call-order divergence in some effect makes frame parity unachievable there | Faithful transcription makes order match by construction; harness catches drift per-effect at port time, not at the end; tier-2 fallback exists |
+| Hidden reliance on Python set/hash/dict order beyond the M1 inventory | Parity harness surfaces it as a reproducible first-divergence; the site joins the inventory, the shim gains a patch, Rust matches it |
+| Float divergence (expression order or libm ulps) | §5.20: transcribe expression order, pin the parity platform, compare quantized outputs, fine-grained goldens catch boundary cases early |
+| Shim-validated parity diverges from *unmodified* TTE | Shim audit (§7): deterministic effects + preprocessing byte-compared against unpatched CPython; shim diff kept minimal and reviewed |
+| clap can't express an argparse corner (e.g. `nargs` tuple actions, dual-type parsers like laseretch's etch-pattern) | Custom value parsers; worst case a manual `TypedValueParser` per odd option — all identified odd options are enumerated in the survey |
+| Upstream moves on and the port targets a stale version | Pinned reference is explicit; upgrades are a diff of `reference/tte/` + re-run of parity suite |
+| Scope creep into "improving" TTE | §5 divergence list is the only allowed list; everything else is transcription |
+
+## 10. Open questions — all resolved
+
+1. Ship a `tte` alias/symlink in packaging? → **No.** It would collide with a real
+ `terminaltexteffects` install, and the whole point is that `ttfx` stands alone. Users who
+ want the alias can add a shell alias themselves.
+2. Vendor upstream as git submodule vs plain checked-in snapshot? → **Plain snapshot**
+ (`reference/tte/`, docs stripped, 2.4MB), simplest for CI and immune to upstream retagging.
+3. musl static build verified locally? → **CI-only.** This machine has system rust (gnu target
+ only, no rustup), so the musl job lives in `.github/workflows/ci.yml` and uploads the
+ artifact. Local `cargo build --release` links just libc/libm/libgcc.
diff --git a/vendor/ttfx/src/cli.rs b/vendor/ttfx/src/cli.rs
new file mode 100644
index 0000000..a29c4fe
--- /dev/null
+++ b/vendor/ttfx/src/cli.rs
@@ -0,0 +1,186 @@
+//! CLI root: the 15 TerminalConfig options (same names/defaults as upstream tte)
+//! plus global args. Effect subcommands land in M3+.
+
+use clap::Parser;
+
+use crate::engine::animation::ExistingColorHandling;
+use crate::engine::canvas::Anchor;
+use crate::engine::terminal::TerminalConfig;
+use crate::utils::graphics::Color;
+
+fn parse_positive_int(s: &str) -> Result {
+ let v: i64 = s.parse().map_err(|_| format!("invalid int value: '{s}'"))?;
+ if v > 0 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not > 0"))
+ }
+}
+
+fn parse_non_negative_int(s: &str) -> Result {
+ let v: i64 = s.parse().map_err(|_| format!("invalid int value: '{s}'"))?;
+ if v >= 0 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not >= 0"))
+ }
+}
+
+fn parse_canvas_dimension(s: &str) -> Result {
+ let v: i64 = s.parse().map_err(|_| format!("invalid int value: '{s}'"))?;
+ if v >= -1 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not >= -1"))
+ }
+}
+
+/// argutils.ColorArg: <=3 chars -> xterm int 0-255, else hex.
+pub fn parse_color(s: &str) -> Result {
+ if s.len() <= 3 {
+ let code: u8 = s.parse().map_err(|_| format!("invalid color value: '{s}'"))?;
+ Ok(Color::from_xterm(code))
+ } else {
+ Color::from_hex(s)
+ }
+}
+
+fn parse_anchor(s: &str) -> Result {
+ Anchor::parse(s).ok_or_else(|| format!("invalid anchor: '{s}'"))
+}
+
+fn parse_existing_color_handling(s: &str) -> Result {
+ match s {
+ "always" => Ok(ExistingColorHandling::Always),
+ "dynamic" => Ok(ExistingColorHandling::Dynamic),
+ "ignore" => Ok(ExistingColorHandling::Ignore),
+ _ => Err(format!("invalid choice: '{s}' (choose from 'always', 'dynamic', 'ignore')")),
+ }
+}
+
+#[derive(Parser, Debug)]
+#[command(
+ name = "ttfx",
+ version,
+ about = "Terminal text effects (Rust port of terminaltexteffects)",
+ // upstream tte exposes --version/-v, so replace clap's default -V flag
+ disable_version_flag = true
+)]
+pub struct Cli {
+ /// Print the version and exit
+ #[arg(short = 'v', long = "version", action = clap::ArgAction::Version)]
+ pub version: Option,
+
+ /// File to read input from
+ #[arg(short = 'i', long = "input-file")]
+ pub input_file: Option,
+
+ #[arg(long = "tab-width", default_value_t = 4, value_parser = parse_positive_int)]
+ pub tab_width: i64,
+
+ #[arg(long = "xterm-colors", default_value_t = false)]
+ pub xterm_colors: bool,
+
+ #[arg(long = "no-color", default_value_t = false)]
+ pub no_color: bool,
+
+ #[arg(long = "terminal-background-color", default_value = "#000000", value_parser = parse_color)]
+ pub terminal_background_color: Color,
+
+ #[arg(long = "existing-color-handling", default_value = "ignore", value_parser = parse_existing_color_handling)]
+ pub existing_color_handling: ExistingColorHandling,
+
+ #[arg(long = "wrap-text", default_value_t = false)]
+ pub wrap_text: bool,
+
+ #[arg(long = "frame-rate", default_value_t = 60, value_parser = parse_non_negative_int)]
+ pub frame_rate: i64,
+
+ #[arg(long = "canvas-width", default_value_t = -1, value_parser = parse_canvas_dimension, allow_negative_numbers = true)]
+ pub canvas_width: i64,
+
+ #[arg(long = "canvas-height", default_value_t = -1, value_parser = parse_canvas_dimension, allow_negative_numbers = true)]
+ pub canvas_height: i64,
+
+ #[arg(long = "anchor-canvas", default_value = "sw", value_parser = parse_anchor)]
+ pub anchor_canvas: Anchor,
+
+ #[arg(long = "anchor-text", default_value = "sw", value_parser = parse_anchor)]
+ pub anchor_text: Anchor,
+
+ #[arg(long = "ignore-terminal-dimensions", default_value_t = false)]
+ pub ignore_terminal_dimensions: bool,
+
+ #[arg(long = "reuse-canvas", default_value_t = false)]
+ pub reuse_canvas: bool,
+
+ #[arg(long = "no-eol", default_value_t = false)]
+ pub no_eol: bool,
+
+ #[arg(long = "no-restore-cursor", default_value_t = false)]
+ pub no_restore_cursor: bool,
+
+ /// Seed for the random number generator (deterministic within ttfx)
+ #[arg(long = "seed")]
+ pub seed: Option,
+
+ /// Print a shell completion script and exit
+ #[arg(long = "print-completion", value_name = "SHELL", value_parser = ["bash", "zsh"])]
+ pub print_completion: Option,
+
+ /// Run a random effect
+ #[arg(short = 'R', long = "random-effect", default_value_t = false)]
+ pub random_effect: bool,
+
+ /// Limit random-effect selection to these effects
+ #[arg(long = "include-effects", num_args = 1.., conflicts_with = "exclude_effects")]
+ pub include_effects: Vec,
+
+ /// Exclude these effects from random-effect selection
+ #[arg(long = "exclude-effects", num_args = 1..)]
+ pub exclude_effects: Vec,
+
+ /// M0 debug: make every canvas character visible and print the first frame
+ /// (used by the parity harness; hidden from help)
+ #[arg(long = "m0-dump", default_value_t = false, hide = true)]
+ pub m0_dump: bool,
+
+ /// Parity harness: dump length-prefixed frames deterministically (requires --seed)
+ #[arg(long = "parity-dump", default_value_t = false, hide = true)]
+ pub parity_dump: bool,
+
+ /// Parity harness: stop after N frames
+ #[arg(long = "max-frames", hide = true)]
+ pub max_frames: Option,
+
+ /// Parity harness: drive the clock virtually (1/frame_rate per frame) so
+ /// clock-dependent effects (matrix, thunderstorm) are reproducible on the
+ /// real tty output path. Implied by --parity-dump.
+ #[arg(long = "virtual-clock", default_value_t = false, hide = true)]
+ pub virtual_clock: bool,
+
+ #[command(subcommand)]
+ pub effect: Option,
+}
+
+impl Cli {
+ pub fn terminal_config(&self) -> TerminalConfig {
+ TerminalConfig {
+ tab_width: self.tab_width,
+ xterm_colors: self.xterm_colors,
+ no_color: self.no_color,
+ terminal_background_color: self.terminal_background_color.clone(),
+ existing_color_handling: self.existing_color_handling,
+ wrap_text: self.wrap_text,
+ frame_rate: self.frame_rate,
+ canvas_width: self.canvas_width,
+ canvas_height: self.canvas_height,
+ anchor_canvas: self.anchor_canvas,
+ anchor_text: self.anchor_text,
+ ignore_terminal_dimensions: self.ignore_terminal_dimensions,
+ reuse_canvas: self.reuse_canvas,
+ no_eol: self.no_eol,
+ no_restore_cursor: self.no_restore_cursor,
+ }
+ }
+}
diff --git a/vendor/ttfx/src/effects/beams.rs b/vendor/ttfx/src/effects/beams.rs
new file mode 100644
index 0000000..f7bf5a2
--- /dev/null
+++ b/vendor/ttfx/src/effects/beams.rs
@@ -0,0 +1,435 @@
+//! beams, ported from effects/effect_beams.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{
+ parse_gradient_direction, parse_gradient_steps, parse_positive_int, parse_positive_int_range, parse_symbol,
+};
+use crate::engine::animation::{Animation, ExistingColorHandling, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::EffectCallback;
+use crate::engine::terminal::{CharacterFilter, CharacterGroup, CharacterSort};
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct BeamsConfig {
+ /// Symbols to use for the beam effect when moving along a row. Strings will be used in sequence to create an animation.
+ #[arg(long = "beam-row-symbols", num_args = 1.., value_parser = parse_symbol,
+ default_values = ["▂", "▁", "_"])]
+ pub beam_row_symbols: Vec,
+
+ /// Symbols to use for the beam effect when moving along a column. Strings will be used in sequence to create an animation.
+ #[arg(long = "beam-column-symbols", num_args = 1.., value_parser = parse_symbol,
+ default_values = ["▌", "▍", "▎", "▏"])]
+ pub beam_column_symbols: Vec,
+
+ /// Number of frames to wait before adding the next group of beams. Beams are added in groups of size random(1, 5).
+ #[arg(long = "beam-delay", default_value_t = 6, value_parser = parse_positive_int)]
+ pub beam_delay: i64,
+
+ /// Speed range of the beam when moving along a row.
+ #[arg(long = "beam-row-speed-range", default_value = "15-60", value_parser = parse_positive_int_range)]
+ pub beam_row_speed_range: (i64, i64),
+
+ /// Speed range of the beam when moving along a column.
+ #[arg(long = "beam-column-speed-range", default_value = "9-15", value_parser = parse_positive_int_range)]
+ pub beam_column_speed_range: (i64, i64),
+
+ /// Space separated, unquoted, list of colors for the beam, a gradient will be created between the colors.
+ #[arg(long = "beam-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["ffffff", "00D1FF", "8A008A"])]
+ pub beam_gradient_stops: Vec,
+
+ /// Space separated, unquoted, numbers for the of gradient steps to use.
+ #[arg(long = "beam-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["2", "6"])]
+ pub beam_gradient_steps: Vec,
+
+ /// Number of frames to display each gradient step. Increase to slow down the gradient animation.
+ #[arg(long = "beam-gradient-frames", default_value_t = 2, value_parser = parse_positive_int)]
+ pub beam_gradient_frames: i64,
+
+ /// Space separated, unquoted, list of colors for the wipe gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["8A008A", "00D1FF", "ffffff"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Number of frames to display each gradient step. Increase to slow down the gradient animation.
+ #[arg(long = "final-gradient-frames", default_value_t = 4, value_parser = parse_positive_int)]
+ pub final_gradient_frames: i64,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "vertical", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+
+ /// Speed of the final wipe as measured in diagonal groups activated per frame.
+ #[arg(long = "final-wipe-speed", default_value_t = 3, value_parser = parse_positive_int)]
+ pub final_wipe_speed: i64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Direction {
+ Row,
+ Column,
+}
+
+/// BeamsIterator.Group state (get_next_character lives on Beams for hooks access).
+struct Group {
+ characters: Vec,
+ direction: Direction,
+ speed: f64,
+ next_character_counter: f64,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Phase {
+ Beams,
+ FinalWipe,
+ Complete,
+}
+
+pub struct Beams {
+ config: BeamsConfig,
+ pending_groups: Vec,
+ active_groups: Vec,
+ character_final_color_map: HashMap,
+ final_wipe_groups: Vec>,
+ delay: i64,
+ phase: Phase,
+}
+
+impl Beams {
+ pub fn new(config: BeamsConfig) -> Self {
+ Beams {
+ config,
+ pending_groups: Vec::new(),
+ active_groups: Vec::new(),
+ character_final_color_map: HashMap::new(),
+ final_wipe_groups: Vec::new(),
+ delay: 0,
+ phase: Phase::Beams,
+ }
+ }
+
+ /// Group.__init__.
+ fn make_group(&self, ctx: &mut EngineCtx, mut characters: Vec, direction: Direction) -> Group {
+ let speed_range = match direction {
+ Direction::Row => self.config.beam_row_speed_range,
+ Direction::Column => self.config.beam_column_speed_range,
+ };
+ let speed = ctx.rng.randint(speed_range.0, speed_range.1) as f64 * 0.1;
+ match direction {
+ Direction::Row => {
+ characters.sort_by_key(|&id| ctx.terminal.arena[id.0 as usize].input_coord.column);
+ }
+ Direction::Column => {
+ characters.sort_by_key(|&id| ctx.terminal.arena[id.0 as usize].input_coord.row);
+ }
+ }
+ if *ctx.rng.choice(&[true, false]) {
+ characters.reverse();
+ }
+ Group { characters, direction, speed, next_character_counter: 0.0 }
+ }
+
+ /// Group.get_next_character.
+ fn get_next_character(&mut self, ctx: &mut EngineCtx, group: &mut Group) -> Option {
+ group.next_character_counter -= 1.0;
+ let next_character = group.characters.remove(0);
+ let active_scene = ctx.terminal.arena[next_character.0 as usize].animation.active_scene.clone();
+ let return_value = if let Some(scene_id) = active_scene {
+ ctx.terminal.arena[next_character.0 as usize]
+ .animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .reset_scene();
+ None
+ } else {
+ ctx.terminal.set_character_visibility(next_character, true);
+ Some(next_character)
+ };
+ let scene_name = match group.direction {
+ Direction::Row => "beam_row",
+ Direction::Column => "beam_column",
+ };
+ ctx.activate_scene(self, next_character, scene_name);
+ return_value
+ }
+}
+
+impl EffectHooks for Beams {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for Beams {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ // __init__ precomputation (no RNG)
+ self.final_wipe_groups = ctx
+ .terminal
+ .get_characters_grouped(CharacterFilter::default(), CharacterGroup::DiagonalTopLeftToBottomRight);
+
+ let all_chars_filter = CharacterFilter {
+ input_chars: true,
+ inner_fill_chars: true,
+ outer_fill_chars: true,
+ added_chars: false,
+ };
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters =
+ ctx.terminal.get_characters(&mut ctx.rng, all_chars_filter, CharacterSort::TopToBottomLeftToRight);
+ for id in characters {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ if ch.is_fill_character {
+ self.character_final_color_map
+ .insert(id, ColorPair::new(Some(Color::from_hex("#000000").unwrap()), None));
+ continue;
+ }
+ let final_colors = if dynamic {
+ ColorPair::new(ch.animation.input_fg_color.clone(), ch.animation.input_bg_color.clone())
+ } else {
+ ColorPair::new(Some(final_gradient_mapping.get(&ch.input_coord).unwrap().clone()), None)
+ };
+ self.character_final_color_map.insert(id, final_colors);
+ }
+
+ let beam_gradient =
+ Gradient::new(&self.config.beam_gradient_stops, &self.config.beam_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let mut groups: Vec = Vec::new();
+ for row in ctx.terminal.get_characters_grouped(all_chars_filter, CharacterGroup::RowTopToBottom) {
+ groups.push(self.make_group(ctx, row, Direction::Row));
+ }
+ for column in ctx.terminal.get_characters_grouped(all_chars_filter, CharacterGroup::ColumnLeftToRight) {
+ groups.push(self.make_group(ctx, column, Direction::Column));
+ }
+ // Rows and columns contain the same characters; initialize each character's scenes only once.
+ for group in groups.iter().filter(|group| group.direction == Direction::Row) {
+ for &id in &group.characters {
+ let (input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.input_symbol.clone(), ch.uses_input_preexisting_colors)
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "beam_row", uses_pre);
+ ch.animation.new_scene(false, None, None, "beam_column", uses_pre);
+ ch.animation.new_scene(false, None, None, "brighten", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut("beam_row")
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &self.config.beam_row_symbols,
+ self.config.beam_gradient_frames,
+ Some(&beam_gradient),
+ None,
+ )
+ .map_err(EngineError::Other)?;
+ ch.animation
+ .scenes
+ .get_mut("beam_column")
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &self.config.beam_column_symbols,
+ self.config.beam_gradient_frames,
+ Some(&beam_gradient),
+ None,
+ )
+ .map_err(EngineError::Other)?;
+ }
+ let char_colors = self.character_final_color_map.get(&id).unwrap().clone();
+ let mut fg_fade_gradient: Option = None;
+ let mut bg_fade_gradient: Option = None;
+ let mut fg_brighten_gradient: Option = None;
+ let mut bg_brighten_gradient: Option = None;
+ if let Some(fg) = &char_colors.fg_color {
+ let faded_fg_color = Animation::adjust_color_brightness(fg, 0.3);
+ fg_fade_gradient = Some(
+ Gradient::with_steps(&[fg.clone(), faded_fg_color.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ );
+ fg_brighten_gradient = Some(
+ Gradient::with_steps(&[faded_fg_color, fg.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ );
+ }
+ if let Some(bg) = &char_colors.bg_color {
+ let faded_bg_color = Animation::adjust_color_brightness(bg, 0.3);
+ bg_fade_gradient = Some(
+ Gradient::with_steps(&[bg.clone(), faded_bg_color.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ );
+ bg_brighten_gradient = Some(
+ Gradient::with_steps(&[faded_bg_color, bg.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ );
+ }
+
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ if fg_fade_gradient.is_some() || bg_fade_gradient.is_some() {
+ ch.animation
+ .scenes
+ .get_mut("beam_row")
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 2,
+ fg_fade_gradient.as_ref(),
+ bg_fade_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ ch.animation
+ .scenes
+ .get_mut("beam_column")
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 2,
+ fg_fade_gradient.as_ref(),
+ bg_fade_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ ch.animation
+ .scenes
+ .get_mut("beam_row")
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ 2,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ ch.animation
+ .scenes
+ .get_mut("beam_column")
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ 2,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+
+ if fg_brighten_gradient.is_some() || bg_brighten_gradient.is_some() {
+ ch.animation
+ .scenes
+ .get_mut("brighten")
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ self.config.final_gradient_frames,
+ fg_brighten_gradient.as_ref(),
+ bg_brighten_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ ch.animation
+ .scenes
+ .get_mut("brighten")
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ self.config.final_gradient_frames,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ }
+
+ self.pending_groups = groups;
+ ctx.rng.shuffle(&mut self.pending_groups);
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if self.phase != Phase::Complete || !ctx.active_characters.is_empty() {
+ match self.phase {
+ Phase::Beams => {
+ if self.delay == 0 {
+ if !self.pending_groups.is_empty() {
+ for _ in 0..ctx.rng.randint(1, 5) {
+ if !self.pending_groups.is_empty() {
+ self.active_groups.push(self.pending_groups.remove(0));
+ }
+ }
+ }
+ self.delay = self.config.beam_delay;
+ } else {
+ self.delay -= 1;
+ }
+ let mut active_groups = std::mem::take(&mut self.active_groups);
+ for group in &mut active_groups {
+ group.next_character_counter += group.speed;
+ // int() truncation
+ let count = group.next_character_counter as i64;
+ if count > 1 {
+ for _ in 0..count {
+ if !group.characters.is_empty() {
+ if let Some(next_char) = self.get_next_character(ctx, group) {
+ ctx.active_characters.insert(next_char);
+ }
+ }
+ }
+ }
+ }
+ active_groups.retain(|group| !group.characters.is_empty());
+ self.active_groups = active_groups;
+ if self.pending_groups.is_empty()
+ && self.active_groups.is_empty()
+ && ctx.active_characters.is_empty()
+ {
+ self.phase = Phase::FinalWipe;
+ }
+ }
+ Phase::FinalWipe => {
+ if !self.final_wipe_groups.is_empty() {
+ for _ in 0..self.config.final_wipe_speed {
+ if self.final_wipe_groups.is_empty() {
+ break;
+ }
+ let next_group = self.final_wipe_groups.remove(0);
+ for id in next_group {
+ ctx.activate_scene(self, id, "brighten");
+ ctx.terminal.set_character_visibility(id, true);
+ ctx.active_characters.insert(id);
+ }
+ }
+ } else {
+ self.phase = Phase::Complete;
+ }
+ }
+ Phase::Complete => {}
+ }
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/binarypath.rs b/vendor/ttfx/src/effects/binarypath.rs
new file mode 100644
index 0000000..b3b8249
--- /dev/null
+++ b/vendor/ttfx/src/effects/binarypath.rs
@@ -0,0 +1,426 @@
+//! binarypath, ported from effects/effect_binarypath.py.
+//!
+//! The inner _BinaryRepresentation class is the `BinaryRepresentation` struct.
+//! No observable set iteration beyond the engine-canonical active_characters
+//! (docs/ordering-inventory.md).
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{
+ parse_gradient_direction, parse_gradient_steps, parse_non_negative_ratio, parse_positive_float,
+};
+use crate::engine::animation::{Animation, ExistingColorHandling, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::EffectCallback;
+use crate::engine::terminal::{CharacterFilter, CharacterGroup, CharacterSort};
+use crate::utils::easing::Easing;
+use crate::utils::geometry::Coord;
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct BinaryPathConfig {
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["00d500", "007500"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "radial", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+
+ /// Space separated, unquoted, list of colors for the binary characters. Character color is randomly assigned from this list.
+ #[arg(long = "binary-colors", num_args = 1.., value_parser = parse_color,
+ default_values = ["044E29", "157e38", "45bf55", "95ed87"])]
+ pub binary_colors: Vec,
+
+ /// Speed of the binary groups as they travel around the terminal.
+ #[arg(long = "movement-speed", default_value_t = 1.0, value_parser = parse_positive_float)]
+ pub movement_speed: f64,
+
+ /// Maximum number of binary groups that are active at any given time as a percentage of the total number of binary groups. Lower this to improve performance.
+ #[arg(long = "active-binary-groups", default_value_t = 0.08, value_parser = parse_non_negative_ratio)]
+ pub active_binary_groups: f64,
+}
+
+/// BinaryPathIterator._BinaryRepresentation.
+struct BinaryRepresentation {
+ character: CharId,
+ binary_characters: Vec,
+ pending_binary_characters: Vec,
+ input_coord: Coord,
+ is_active: bool,
+}
+
+impl BinaryRepresentation {
+ /// _BinaryRepresentation._travel_complete.
+ fn travel_complete(&self, ctx: &EngineCtx) -> bool {
+ self.binary_characters
+ .iter()
+ .all(|&bin_char| ctx.terminal.arena[bin_char.0 as usize].motion.current_coord == self.input_coord)
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Phase {
+ Travel,
+ Wipe,
+}
+
+/// typing.Literal["col", "row"].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Orientation {
+ Col,
+ Row,
+}
+
+pub struct BinaryPath {
+ config: BinaryPathConfig,
+ pending_binary_representations: Vec,
+ character_final_color_map: HashMap,
+ last_frame_provided: bool,
+ active_binary_reps: Vec,
+ complete: bool,
+ phase: Phase,
+ final_wipe_chars: Vec>,
+ max_active_binary_groups: i64,
+}
+
+impl BinaryPath {
+ pub fn new(config: BinaryPathConfig) -> Self {
+ BinaryPath {
+ config,
+ pending_binary_representations: Vec::new(),
+ character_final_color_map: HashMap::new(),
+ last_frame_provided: false,
+ active_binary_reps: Vec::new(),
+ complete: false,
+ phase: Phase::Travel,
+ final_wipe_chars: Vec::new(),
+ max_active_binary_groups: 0,
+ }
+ }
+}
+
+impl EffectHooks for BinaryPath {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for BinaryPath {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ // __init__: final_wipe_chars computed before build()
+ self.final_wipe_chars = ctx
+ .terminal
+ .get_characters_grouped(CharacterFilter::default(), CharacterGroup::DiagonalTopRightToBottomLeft);
+
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ let final_colors = if dynamic {
+ ColorPair::new(ch.animation.input_fg_color.clone(), ch.animation.input_bg_color.clone())
+ } else {
+ ColorPair::new(Some(final_gradient_mapping.get(&ch.input_coord).unwrap().clone()), None)
+ };
+ self.character_final_color_map.insert(id, final_colors);
+ }
+
+ for &id in &characters {
+ let (symbol, input_coord) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.animation.current_character_visual.symbol.clone(), ch.input_coord)
+ };
+ // format(ord(symbol), "08b")
+ let code_point = symbol.chars().next().expect("empty symbol") as u32;
+ let binary_string = format!("{code_point:08b}");
+ let mut bin_rep = BinaryRepresentation {
+ character: id,
+ binary_characters: Vec::new(),
+ pending_binary_characters: Vec::new(),
+ input_coord,
+ is_active: false,
+ };
+ for binary_char in binary_string.chars() {
+ let added = ctx.terminal.add_character(&binary_char.to_string(), Coord::new(0, 0));
+ bin_rep.binary_characters.push(added);
+ bin_rep.pending_binary_characters.push(added);
+ }
+ self.pending_binary_representations.push(bin_rep);
+ }
+
+ let mut pending_reps = std::mem::take(&mut self.pending_binary_representations);
+ for bin_rep in &pending_reps {
+ let mut path_coords: Vec = Vec::new();
+ let starting_coord = ctx.terminal.canvas.random_coord(&mut ctx.rng, true, false);
+ path_coords.push(starting_coord);
+ let mut last_orientation = *ctx.rng.choice(&[Orientation::Col, Orientation::Row]);
+ let mut next_coord = starting_coord; // will be rebound in the loop
+ let input_coord = bin_rep.input_coord;
+ while *path_coords.last().unwrap() != input_coord {
+ let last_coord = *path_coords.last().unwrap();
+ let column_direction = if last_coord.column > input_coord.column {
+ -1
+ } else if last_coord.column == input_coord.column {
+ 0
+ } else {
+ 1
+ };
+ let row_direction = if last_coord.row > input_coord.row {
+ -1
+ } else if last_coord.row == input_coord.row {
+ 0
+ } else {
+ 1
+ };
+ let max_column_distance = (last_coord.column - input_coord.column).abs();
+ let max_row_distance = (last_coord.row - input_coord.row).abs();
+ if last_orientation == Orientation::Col && max_row_distance > 0 {
+ // min(max_row_distance, max(10, int(canvas.right * 0.2))) — int() truncation
+ let limit = std::cmp::min(
+ max_row_distance,
+ std::cmp::max(10, (ctx.terminal.canvas.right as f64 * 0.2) as i64),
+ );
+ next_coord = Coord::new(
+ last_coord.column,
+ last_coord.row + ctx.rng.randint(1, limit) * row_direction,
+ );
+ last_orientation = Orientation::Row;
+ } else if last_orientation == Orientation::Row && max_column_distance > 0 {
+ next_coord = Coord::new(
+ last_coord.column + ctx.rng.randint(1, std::cmp::min(max_column_distance, 4)) * column_direction,
+ last_coord.row,
+ );
+ last_orientation = Orientation::Col;
+ } else {
+ next_coord = input_coord;
+ }
+
+ path_coords.push(next_coord);
+ }
+
+ path_coords.push(next_coord);
+ let final_coord = input_coord;
+ path_coords.push(final_coord);
+ for &bin_effectchar in &bin_rep.binary_characters {
+ let digital_path = {
+ let ch = &mut ctx.terminal.arena[bin_effectchar.0 as usize];
+ ch.motion.set_coordinate(path_coords[0]);
+ let path_id = ch
+ .motion
+ .new_path(self.config.movement_speed, None, None, 0, false, "")
+ .map_err(EngineError::Other)?;
+ let path = ch.motion.paths.get_mut(&path_id).unwrap();
+ for &coord in &path_coords {
+ path.new_waypoint(coord, None, "").map_err(EngineError::Other)?;
+ }
+ path_id
+ };
+ ctx.activate_path(self, bin_effectchar, &digital_path);
+ ctx.terminal.arena[bin_effectchar.0 as usize].layer = 1;
+ let color = ctx.rng.choice(&self.config.binary_colors).clone();
+ let color_scn = {
+ let ch = &mut ctx.terminal.arena[bin_effectchar.0 as usize];
+ let symbol = ch.animation.current_character_visual.symbol.clone();
+ let uses_pre = ch.uses_input_preexisting_colors;
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(
+ &symbol,
+ 1,
+ VisualParams { colors: Some(ColorPair::new(Some(color), None)), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ ctx.activate_scene(self, bin_effectchar, &color_scn);
+ }
+ }
+ self.pending_binary_representations = pending_reps.drain(..).collect();
+
+ for &id in &characters {
+ let (input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.input_symbol.clone(), ch.uses_input_preexisting_colors)
+ };
+ let final_colors = self.character_final_color_map.get(&id).unwrap().clone();
+ let final_fg_color = final_colors.fg_color.clone();
+ let final_bg_color = final_colors.bg_color.clone();
+ let dim_fg_color = final_fg_color.as_ref().map(|c| Animation::adjust_color_brightness(c, 0.5));
+ let dim_bg_color = final_bg_color.as_ref().map(|c| Animation::adjust_color_brightness(c, 0.5));
+ let collapse_fg_gradient = match &dim_fg_color {
+ Some(dim) => Some(
+ Gradient::with_steps(&[Color::from_hex("ffffff").unwrap(), dim.clone()], 7, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let collapse_bg_gradient = match &dim_bg_color {
+ Some(dim) => Some(
+ Gradient::with_steps(&[Color::from_hex("ffffff").unwrap(), dim.clone()], 7, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let collapse_scn = ch.animation.new_scene(false, None, Some(Easing::InQuad), "collapse_scn", uses_pre);
+ let scene = ch.animation.scenes.get_mut(&collapse_scn).unwrap();
+ if collapse_fg_gradient.is_some() || collapse_bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 3,
+ collapse_fg_gradient.as_ref(),
+ collapse_bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ 3,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+
+ let brighten_fg_gradient = match (&dim_fg_color, &final_fg_color) {
+ (Some(dim), Some(final_fg)) => Some(
+ Gradient::with_steps(&[dim.clone(), final_fg.clone()], 10, false).map_err(EngineError::Other)?,
+ ),
+ _ => None,
+ };
+ let brighten_bg_gradient = match (&dim_bg_color, &final_bg_color) {
+ (Some(dim), Some(final_bg)) => Some(
+ Gradient::with_steps(&[dim.clone(), final_bg.clone()], 10, false).map_err(EngineError::Other)?,
+ ),
+ _ => None,
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let brighten_scn = ch.animation.new_scene(false, None, None, "brighten_scn", uses_pre);
+ let scene = ch.animation.scenes.get_mut(&brighten_scn).unwrap();
+ if brighten_fg_gradient.is_some() || brighten_bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 2,
+ brighten_fg_gradient.as_ref(),
+ brighten_bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ 2,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ }
+ self.max_active_binary_groups = std::cmp::max(
+ 1,
+ (self.config.active_binary_groups * self.pending_binary_representations.len() as f64) as i64,
+ );
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !self.complete || !ctx.active_characters.is_empty() {
+ if self.phase == Phase::Travel {
+ while (self.active_binary_reps.len() as i64) < self.max_active_binary_groups
+ && !self.pending_binary_representations.is_empty()
+ {
+ let index =
+ ctx.rng.randrange(0, self.pending_binary_representations.len() as i64) as usize;
+ let mut next_binary_rep = self.pending_binary_representations.remove(index);
+ next_binary_rep.is_active = true;
+ self.active_binary_reps.push(next_binary_rep);
+ }
+
+ if !self.active_binary_reps.is_empty() {
+ let mut active_reps = std::mem::take(&mut self.active_binary_reps);
+ for active_rep in &mut active_reps {
+ if !active_rep.pending_binary_characters.is_empty() {
+ let next_char = active_rep.pending_binary_characters.remove(0);
+ ctx.active_characters.insert(next_char);
+ ctx.terminal.set_character_visibility(next_char, true);
+ } else if active_rep.travel_complete(ctx) {
+ // _deactivate
+ for &bin_char in &active_rep.binary_characters {
+ ctx.terminal.set_character_visibility(bin_char, false);
+ }
+ active_rep.is_active = false;
+ // _activate_source_character
+ ctx.terminal.set_character_visibility(active_rep.character, true);
+ ctx.activate_scene(self, active_rep.character, "collapse_scn");
+ ctx.active_characters.insert(active_rep.character);
+ }
+ }
+ active_reps.retain(|binary_rep| binary_rep.is_active);
+ self.active_binary_reps = active_reps;
+ }
+
+ if ctx.active_characters.is_empty() {
+ self.phase = Phase::Wipe;
+ }
+ }
+
+ if self.phase == Phase::Wipe {
+ for _ in 0..2 {
+ if !self.final_wipe_chars.is_empty() {
+ let next_group = self.final_wipe_chars.remove(0);
+ for character in next_group {
+ ctx.activate_scene(self, character, "brighten_scn");
+ ctx.terminal.set_character_visibility(character, true);
+ ctx.active_characters.insert(character);
+ }
+ } else {
+ self.complete = true;
+ }
+ }
+ }
+
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+
+ if !self.last_frame_provided {
+ self.last_frame_provided = true;
+ return Some(ctx.frame());
+ }
+
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/blackhole.rs b/vendor/ttfx/src/effects/blackhole.rs
new file mode 100644
index 0000000..9c680b6
--- /dev/null
+++ b/vendor/ttfx/src/effects/blackhole.rs
@@ -0,0 +1,616 @@
+//! blackhole, ported from effects/effect_blackhole.py.
+
+use std::collections::{HashMap, HashSet};
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{parse_gradient_direction, parse_gradient_steps};
+use crate::engine::animation::{ExistingColorHandling, SyncMetric, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::easing::Easing;
+use crate::utils::geometry;
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+use crate::utils::pycompat::{floor_div, round_half_even};
+
+#[derive(Args, Debug, Clone)]
+pub struct BlackholeConfig {
+ /// Color for the stars that comprise the blackhole border.
+ #[arg(long = "blackhole-color", default_value = "ffffff", value_parser = parse_color)]
+ pub blackhole_color: Color,
+
+ /// List of colors from which character colors will be chosen and applied after the explosion, but before the cooldown to final color.
+ #[arg(long = "star-colors", num_args = 1.., value_parser = parse_color,
+ default_values = ["ffcc0d", "ff7326", "ff194d", "bf2669", "702a8c", "049dbf"])]
+ pub star_colors: Vec,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["8A008A", "00D1FF", "ffffff"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["9"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "diagonal", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+enum Phase {
+ Forming,
+ Consuming,
+ Collapsing,
+ Exploding,
+ Complete,
+}
+
+pub struct Blackhole {
+ config: BlackholeConfig,
+ blackhole_chars: Vec,
+ awaiting_consumption_chars: Vec,
+ blackhole_radius: i64,
+ character_final_color_map: HashMap,
+ formation_delay: i64,
+ f_delay: i64,
+ phase: Phase,
+ awaiting_blackhole_chars: Vec,
+}
+
+impl Blackhole {
+ pub fn new(config: BlackholeConfig) -> Self {
+ Blackhole {
+ config,
+ blackhole_chars: Vec::new(),
+ awaiting_consumption_chars: Vec::new(),
+ blackhole_radius: 0,
+ character_final_color_map: HashMap::new(),
+ formation_delay: 0,
+ f_delay: 0,
+ phase: Phase::Forming,
+ awaiting_blackhole_chars: Vec::new(),
+ }
+ }
+
+ /// BlackholeIterator.prepare_blackhole.
+ fn prepare_blackhole(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let star_symbols = ["*", "'", "`", "¤", "•", "°", "·"];
+ let starfield_colors = Gradient::with_steps(
+ &[Color::from_hex("#4a4a4d").unwrap(), Color::from_hex("#ffffff").unwrap()],
+ 6,
+ false,
+ )
+ .map_err(EngineError::Other)?
+ .spectrum;
+ // gradient_map: dict keyed by starfield color, indexed here by spectrum position
+ let mut gradient_map: Vec = Vec::new();
+ for color in &starfield_colors {
+ gradient_map.push(
+ Gradient::with_steps(&[color.clone(), Color::from_hex("#000000").unwrap()], 10, false)
+ .map_err(EngineError::Other)?,
+ );
+ }
+ let mut available_chars: Vec = ctx.terminal.input_characters.clone();
+ while (self.blackhole_chars.len() as i64) < self.blackhole_radius * 3 && !available_chars.is_empty() {
+ let index = ctx.rng.randrange(0, available_chars.len() as i64) as usize;
+ self.blackhole_chars.push(available_chars.remove(index));
+ }
+ let black_hole_ring_positions = geometry::find_coords_on_circle(
+ ctx.terminal.canvas.center,
+ self.blackhole_radius,
+ self.blackhole_chars.len() as i64,
+ true,
+ );
+ for (position_index, &id) in self.blackhole_chars.iter().enumerate() {
+ let starting_pos = black_hole_ring_positions[position_index];
+ let blackhole_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let path_id = ch
+ .motion
+ .new_path(0.7, Some(Easing::InOutSine), None, 0, false, "blackhole")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(starting_pos, None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let uses_pre = ch.uses_input_preexisting_colors;
+ let blackhole_scn = ch.animation.new_scene(false, None, None, "blackhole", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&blackhole_scn)
+ .unwrap()
+ .add_frame(
+ "*",
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.blackhole_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ ctx.register_event(
+ id,
+ Event::PathActivated,
+ CallerKey::Path(blackhole_path),
+ EventAction::SetLayer(1),
+ )
+ .map_err(EngineError::Other)?;
+ // make rotation waypoints
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let rotation_path = ch
+ .motion
+ .new_path(0.45, None, None, 0, true, "blackhole_rotation")
+ .map_err(EngineError::Other)?;
+ let rotated: Vec<_> = black_hole_ring_positions[position_index..]
+ .iter()
+ .chain(black_hole_ring_positions[..position_index].iter())
+ .copied()
+ .collect();
+ for coord in rotated {
+ let path = ch.motion.paths.get_mut(&rotation_path).unwrap();
+ let waypoint_id = path.waypoints.len().to_string();
+ path.new_waypoint(coord, None, &waypoint_id).map_err(EngineError::Other)?;
+ }
+ }
+ }
+ let blackhole_set: HashSet = self.blackhole_chars.iter().copied().collect();
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ let canvas_center = ctx.terminal.canvas.center;
+ for &id in &characters {
+ ctx.terminal.set_character_visibility(id, true);
+ let star_symbol = *ctx.rng.choice(&star_symbols);
+ let star_color_index = {
+ // random.choice(starfield_colors)
+ let _ = &starfield_colors;
+ ctx.rng.choice_index(starfield_colors.len())
+ };
+ let star_color = starfield_colors[star_color_index].clone();
+ let starting_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let uses_pre = ch.uses_input_preexisting_colors;
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(
+ star_symbol,
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(star_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ ctx.activate_scene(self, id, &starting_scn);
+ if !blackhole_set.contains(&id) {
+ let starfield_coord = ctx.terminal.canvas.random_coord(&mut ctx.rng, false, false);
+ let speed = ctx.rng.uniform(0.17, 0.30);
+ let singularity_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.motion.set_coordinate(starfield_coord);
+ let path_id = ch
+ .motion
+ .new_path(speed, Some(Easing::InExpo), None, 0, false, "singularity")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(canvas_center, None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ let consumed_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let uses_pre = ch.uses_input_preexisting_colors;
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ let scene = ch.animation.scenes.get_mut(&scene_id).unwrap();
+ for color in &gradient_map[star_color_index].spectrum {
+ scene
+ .add_frame(
+ star_symbol,
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ scene.add_frame(" ", 1, VisualParams::default()).map_err(EngineError::Other)?;
+ scene.sync = Some(SyncMetric::Distance);
+ scene_id
+ };
+ ctx.register_event(
+ id,
+ Event::PathActivated,
+ CallerKey::Path(singularity_path.clone()),
+ EventAction::SetLayer(2),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::PathActivated,
+ CallerKey::Path(singularity_path),
+ EventAction::ActivateScene(consumed_scn),
+ )
+ .map_err(EngineError::Other)?;
+ self.awaiting_consumption_chars.push(id);
+ }
+ }
+ ctx.rng.shuffle(&mut self.awaiting_consumption_chars);
+ Ok(())
+ }
+
+ /// BlackholeIterator.rotate_blackhole.
+ fn rotate_blackhole(&mut self, ctx: &mut EngineCtx) {
+ for &id in &self.blackhole_chars.clone() {
+ ctx.activate_path(self, id, "blackhole_rotation");
+ ctx.active_characters.insert(id);
+ }
+ }
+
+ /// BlackholeIterator.collapse_blackhole.
+ fn collapse_blackhole(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let mut black_hole_ring_positions = geometry::find_coords_on_circle(
+ ctx.terminal.canvas.center,
+ self.blackhole_radius + 3,
+ self.blackhole_chars.len() as i64,
+ true,
+ );
+ let unstable_symbols = ["◦", "◎", "◉", "●", "◉", "◎", "◦"];
+ let mut point_char_made = false;
+ let canvas_center = ctx.terminal.canvas.center;
+ for &id in &self.blackhole_chars.clone() {
+ let next_pos = black_hole_ring_positions.remove(0);
+ let (expand_path, collapse_path) = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let expand_path =
+ ch.motion.new_path(0.2, Some(Easing::InExpo), None, 0, false, "").map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&expand_path)
+ .unwrap()
+ .new_waypoint(next_pos, None, "")
+ .map_err(EngineError::Other)?;
+ let collapse_path =
+ ch.motion.new_path(0.3, Some(Easing::InExpo), None, 0, false, "").map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&collapse_path)
+ .unwrap()
+ .new_waypoint(canvas_center, None, "")
+ .map_err(EngineError::Other)?;
+ (expand_path, collapse_path)
+ };
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(expand_path.clone()),
+ EventAction::ActivatePath(collapse_path.clone()),
+ )
+ .map_err(EngineError::Other)?;
+ if !point_char_made {
+ let point_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let uses_pre = ch.uses_input_preexisting_colors;
+ ch.animation.new_scene(false, None, None, "", uses_pre)
+ };
+ for _ in 0..3 {
+ for symbol in unstable_symbols {
+ let color = ctx.rng.choice(&self.config.star_colors).clone();
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut(&point_scn)
+ .unwrap()
+ .add_frame(
+ symbol,
+ 3,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(color), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(collapse_path.clone()),
+ EventAction::ActivateScene(point_scn),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(collapse_path),
+ EventAction::SetLayer(3),
+ )
+ .map_err(EngineError::Other)?;
+ point_char_made = true;
+ }
+
+ ctx.activate_path(self, id, &expand_path);
+ ctx.active_characters.insert(id);
+ }
+ Ok(())
+ }
+
+ /// BlackholeIterator.explode_singularity.
+ fn explode_singularity(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let star_colors = [
+ Color::from_hex("#ffcc0d").unwrap(),
+ Color::from_hex("#ff7326").unwrap(),
+ Color::from_hex("#ff194d").unwrap(),
+ Color::from_hex("#bf2669").unwrap(),
+ Color::from_hex("#702a8c").unwrap(),
+ Color::from_hex("#049dbf").unwrap(),
+ ];
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ let (input_coord, input_symbol, input_fg, input_bg, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.input_coord,
+ ch.input_symbol.clone(),
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ let circle_coords = geometry::find_coords_on_circle(input_coord, 3, 5, true);
+ let nearby_coord = circle_coords[ctx.rng.randrange(0, 5) as usize];
+ let nearby_speed = ctx.rng.randint(3, 4) as f64 / 10.0;
+ let nearby_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let path_id = ch
+ .motion
+ .new_path(nearby_speed, Some(Easing::OutExpo), None, 0, false, "")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(nearby_coord, None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ let input_speed = ctx.rng.randint(4, 6) as f64 / 100.0;
+ let input_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let path_id = ch
+ .motion
+ .new_path(input_speed, Some(Easing::InCubic), None, 0, false, "")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(input_coord, None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ let explode_star_color = ctx.rng.choice(&star_colors).clone();
+ let explode_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(explode_star_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ let cooling_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "", uses_pre)
+ };
+ if dynamic && ctx.preexisting_colors_present {
+ if input_fg.is_none() && input_bg.is_none() {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut(&cooling_scn)
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ 1,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ let cooling_gradient_fg = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[explode_star_color.clone(), fg.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let cooling_gradient_bg = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[explode_star_color.clone(), bg.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut(&cooling_scn)
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 20,
+ cooling_gradient_fg.as_ref(),
+ cooling_gradient_bg.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ }
+ } else {
+ let final_color = self.character_final_color_map.get(&id).unwrap().clone();
+ let cooling_gradient =
+ Gradient::with_steps(&[explode_star_color.clone(), final_color], 10, false)
+ .map_err(EngineError::Other)?;
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut(&cooling_scn)
+ .unwrap()
+ .apply_gradient_to_symbols(&[input_symbol.clone()], 20, Some(&cooling_gradient), None)
+ .map_err(EngineError::Other)?;
+ }
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(nearby_path.clone()),
+ EventAction::ActivatePath(input_path),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(nearby_path.clone()),
+ EventAction::ActivateScene(cooling_scn),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.activate_scene(self, id, &explode_scn);
+ ctx.activate_path(self, id, &nearby_path);
+ ctx.active_characters.insert(id);
+ }
+ Ok(())
+ }
+}
+
+impl EffectHooks for Blackhole {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for Blackhole {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ // BlackholeIterator.__init__
+ self.blackhole_radius = std::cmp::max(
+ std::cmp::min(
+ round_half_even(ctx.terminal.canvas.width as f64 * 0.3),
+ round_half_even(ctx.terminal.canvas.height as f64 * 0.20),
+ ),
+ 3,
+ );
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ let input_coord = ctx.terminal.arena[id.0 as usize].input_coord;
+ self.character_final_color_map
+ .insert(id, final_gradient_mapping.get(&input_coord).unwrap().clone());
+ }
+ self.prepare_blackhole(ctx)?;
+ self.formation_delay = std::cmp::max(floor_div(100, self.blackhole_chars.len() as i64), 6);
+ self.f_delay = self.formation_delay;
+ self.phase = Phase::Forming;
+ self.awaiting_blackhole_chars = self.blackhole_chars.clone();
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !ctx.active_characters.is_empty() || self.phase != Phase::Complete {
+ match self.phase {
+ Phase::Forming => {
+ if !self.awaiting_blackhole_chars.is_empty() {
+ if self.f_delay == 0 {
+ let next_char = self.awaiting_blackhole_chars.remove(0);
+ ctx.activate_path(self, next_char, "blackhole");
+ ctx.activate_scene(self, next_char, "blackhole");
+ ctx.active_characters.insert(next_char);
+ self.f_delay = self.formation_delay;
+ } else {
+ self.f_delay -= 1;
+ }
+ } else if ctx.active_characters.is_empty() {
+ self.rotate_blackhole(ctx);
+ self.phase = Phase::Consuming;
+ }
+ }
+ Phase::Consuming => {
+ if !self.awaiting_consumption_chars.is_empty() {
+ for &id in &self.awaiting_consumption_chars.clone() {
+ ctx.activate_path(self, id, "singularity");
+ ctx.active_characters.insert(id);
+ }
+ self.awaiting_consumption_chars.clear();
+ } else {
+ let blackhole_set: HashSet = self.blackhole_chars.iter().copied().collect();
+ if ctx.active_characters.iter().all(|id| blackhole_set.contains(&id)) {
+ self.phase = Phase::Collapsing;
+ }
+ }
+ }
+ Phase::Collapsing => {
+ self.collapse_blackhole(ctx).expect("collapse_blackhole failed");
+ self.phase = Phase::Exploding;
+ }
+ Phase::Exploding => {
+ if self.blackhole_chars.iter().all(|&id| {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ ch.motion.active_path.is_none() && ch.animation.active_scene.is_none()
+ }) {
+ self.explode_singularity(ctx).expect("explode_singularity failed");
+ self.phase = Phase::Complete;
+ }
+ }
+ Phase::Complete => {}
+ }
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/bouncyballs.rs b/vendor/ttfx/src/effects/bouncyballs.rs
new file mode 100644
index 0000000..994eec6
--- /dev/null
+++ b/vendor/ttfx/src/effects/bouncyballs.rs
@@ -0,0 +1,253 @@
+//! bouncyballs, ported from effects/effect_bouncyballs.py.
+
+use std::collections::{BTreeMap, HashMap};
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{
+ parse_easing, parse_gradient_direction, parse_gradient_steps, parse_non_negative_int, parse_positive_float,
+ parse_symbol,
+};
+use crate::engine::animation::{ExistingColorHandling, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::easing::Easing;
+use crate::utils::geometry::Coord;
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct BouncyBallsConfig {
+ /// Space separated list of colors from which ball colors will be randomly selected.
+ #[arg(long = "ball-colors", num_args = 1.., value_parser = parse_color,
+ default_values = ["d1f4a5", "96e2a4", "5acda9"])]
+ pub ball_colors: Vec,
+
+ /// Space separated list of symbols to use for the balls.
+ #[arg(long = "ball-symbols", num_args = 1.., value_parser = parse_symbol,
+ default_values = ["*", "o", "O", "0", "."])]
+ pub ball_symbols: Vec,
+
+ /// Number of frames between ball drops, increase to reduce ball drop rate.
+ #[arg(long = "ball-delay", default_value_t = 4, value_parser = parse_non_negative_int)]
+ pub ball_delay: i64,
+
+ /// Movement speed of the characters.
+ #[arg(long = "movement-speed", default_value_t = 0.45, value_parser = parse_positive_float)]
+ pub movement_speed: f64,
+
+ /// Easing function to use for character movement.
+ #[arg(long = "movement-easing", default_value = "out_bounce", value_parser = parse_easing)]
+ pub movement_easing: Easing,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["f8ffae", "43c6ac"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "diagonal", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+pub struct BouncyBalls {
+ config: BouncyBallsConfig,
+ pending_chars: Vec,
+ group_by_row: BTreeMap>,
+ character_final_color_map: HashMap,
+ ball_delay: i64,
+}
+
+impl BouncyBalls {
+ pub fn new(config: BouncyBallsConfig) -> Self {
+ BouncyBalls {
+ config,
+ pending_chars: Vec::new(),
+ group_by_row: BTreeMap::new(),
+ character_final_color_map: HashMap::new(),
+ ball_delay: 0,
+ }
+ }
+}
+
+impl EffectHooks for BouncyBalls {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for BouncyBalls {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ let canvas_top = ctx.terminal.canvas.top;
+ for id in characters {
+ let (input_coord, input_symbol, input_fg, input_bg, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.input_coord,
+ ch.input_symbol.clone(),
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ self.character_final_color_map
+ .insert(id, final_gradient_mapping.get(&input_coord).unwrap().clone());
+ let color = ctx.rng.choice(&self.config.ball_colors).clone();
+ let symbol = ctx.rng.choice(&self.config.ball_symbols).clone();
+ let ball_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(
+ &symbol,
+ 1,
+ VisualParams { colors: Some(ColorPair::new(Some(color.clone()), None)), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ let final_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "", uses_pre)
+ };
+ if dynamic {
+ let fg_gradient = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[color.clone(), fg.clone()], 10, false).map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let bg_gradient = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[color.clone(), bg.clone()], 10, false).map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut(&final_scene).unwrap();
+ if fg_gradient.is_some() || bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 6,
+ fg_gradient.as_ref(),
+ bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ 6,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ } else {
+ let final_color = self.character_final_color_map.get(&id).unwrap().clone();
+ let char_final_gradient =
+ Gradient::with_steps(&[color.clone(), final_color], 10, false).map_err(EngineError::Other)?;
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut(&final_scene)
+ .unwrap()
+ .apply_gradient_to_symbols(&[input_symbol.clone()], 6, Some(&char_final_gradient), None)
+ .map_err(EngineError::Other)?;
+ }
+ // Coord(input column, int(canvas.top * uniform(1.0, 1.5))) — int() truncation
+ let drop_row = (canvas_top as f64 * ctx.rng.uniform(1.0, 1.5)) as i64;
+ let input_coord_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.motion.set_coordinate(Coord::new(input_coord.column, drop_row));
+ let path_id = ch
+ .motion
+ .new_path(self.config.movement_speed, Some(self.config.movement_easing), None, 0, false, "")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(input_coord, None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ ctx.activate_path(self, id, &input_coord_path);
+ ctx.activate_scene(self, id, &ball_scene);
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(input_coord_path),
+ EventAction::ActivateScene(final_scene),
+ )
+ .map_err(EngineError::Other)?;
+ self.pending_chars.push(id);
+ }
+ let mut sorted_chars = self.pending_chars.clone();
+ sorted_chars.sort_by_key(|&id| ctx.terminal.arena[id.0 as usize].input_coord.row);
+ for id in sorted_chars {
+ let row = ctx.terminal.arena[id.0 as usize].input_coord.row;
+ self.group_by_row.entry(row).or_default().push(id);
+ }
+ self.pending_chars.clear();
+ self.ball_delay = 0;
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !self.group_by_row.is_empty() || !ctx.active_characters.is_empty() || !self.pending_chars.is_empty() {
+ if self.pending_chars.is_empty() && !self.group_by_row.is_empty() {
+ let min_row = *self.group_by_row.keys().next().unwrap();
+ let group = self.group_by_row.remove(&min_row).unwrap();
+ self.pending_chars.extend(group);
+ }
+ if !self.pending_chars.is_empty() {
+ if self.ball_delay == 0 {
+ for _ in 0..ctx.rng.randint(2, 6) {
+ if self.pending_chars.is_empty() {
+ break;
+ }
+ let index = ctx.rng.randint(0, self.pending_chars.len() as i64 - 1) as usize;
+ let next_character = self.pending_chars.remove(index);
+ ctx.terminal.set_character_visibility(next_character, true);
+ ctx.active_characters.insert(next_character);
+ }
+ self.ball_delay = self.config.ball_delay;
+ } else {
+ self.ball_delay -= 1;
+ }
+ }
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/bubbles.rs b/vendor/ttfx/src/effects/bubbles.rs
new file mode 100644
index 0000000..39b92ef
--- /dev/null
+++ b/vendor/ttfx/src/effects/bubbles.rs
@@ -0,0 +1,522 @@
+//! bubbles, ported from effects/effect_bubbles.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{
+ parse_easing, parse_gradient_direction, parse_gradient_steps, parse_positive_float, parse_positive_int,
+};
+use crate::engine::animation::{ExistingColorHandling, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterGroup, CharacterSort};
+use crate::utils::easing::Easing;
+use crate::utils::geometry::{self, Coord};
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+/// pop_condition choices.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PopCondition {
+ Row,
+ Bottom,
+ Anywhere,
+}
+
+fn parse_pop_condition(s: &str) -> Result {
+ Ok(match s {
+ "row" => PopCondition::Row,
+ "bottom" => PopCondition::Bottom,
+ "anywhere" => PopCondition::Anywhere,
+ _ => return Err(format!("invalid choice: '{s}' (choose from 'row', 'bottom', 'anywhere')")),
+ })
+}
+
+#[derive(Args, Debug, Clone)]
+pub struct BubblesConfig {
+ /// If set, the bubbles will be colored with a rotating rainbow gradient.
+ #[arg(long = "rainbow", default_value_t = false)]
+ pub rainbow: bool,
+
+ /// Space separated, unquoted, list of colors for the bubbles. Ignored if --no-rainbow is left as default False.
+ #[arg(long = "bubble-colors", num_args = 1.., value_parser = parse_color,
+ default_values = ["d33aff", "7395c4", "43c2a7", "02ff7f"])]
+ pub bubble_colors: Vec,
+
+ /// Color for the spray emitted when a bubble pops.
+ #[arg(long = "pop-color", default_value = "ffffff", value_parser = parse_color)]
+ pub pop_color: Color,
+
+ /// Speed of the floating bubbles.
+ #[arg(long = "bubble-speed", default_value_t = 0.5, value_parser = parse_positive_float)]
+ pub bubble_speed: f64,
+
+ /// Number of frames between bubbles.
+ #[arg(long = "bubble-delay", default_value_t = 20, value_parser = parse_positive_int)]
+ pub bubble_delay: i64,
+
+ /// Condition for a bubble to pop.
+ #[arg(long = "pop-condition", default_value = "row", value_parser = parse_pop_condition)]
+ pub pop_condition: PopCondition,
+
+ /// Easing function to use for character movement after a bubble pops.
+ #[arg(long = "movement-easing", default_value = "in_out_sine", value_parser = parse_easing)]
+ pub movement_easing: Easing,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["d33aff", "02ff7f"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "diagonal", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+/// BubblesIterator.Bubble state (methods live on Bubbles for hooks access).
+struct Bubble {
+ characters: Vec,
+ radius: i64,
+ anchor_char: CharId,
+ lowest_row: i64,
+ landed: bool,
+}
+
+pub struct Bubbles {
+ config: BubblesConfig,
+ bubbles: Vec,
+ animating_bubbles: Vec,
+ rainbow_gradient: Gradient,
+ character_final_color_map: HashMap,
+ steps_since_last_bubble: i64,
+}
+
+impl Bubbles {
+ pub fn new(config: BubblesConfig) -> Self {
+ let rainbow_stops = [
+ Color::from_hex("e81416").unwrap(), // red
+ Color::from_hex("ffa500").unwrap(), // orange
+ Color::from_hex("faeb36").unwrap(), // yellow
+ Color::from_hex("79c314").unwrap(), // green
+ Color::from_hex("487de7").unwrap(), // blue
+ Color::from_hex("4b369d").unwrap(), // indigo
+ Color::from_hex("70369d").unwrap(), // violet
+ ];
+ let rainbow_gradient = Gradient::with_steps(&rainbow_stops, 5, false).expect("rainbow gradient");
+ Bubbles {
+ config,
+ bubbles: Vec::new(),
+ animating_bubbles: Vec::new(),
+ rainbow_gradient,
+ character_final_color_map: HashMap::new(),
+ steps_since_last_bubble: 0,
+ }
+ }
+
+ /// Bubble.set_character_coordinates.
+ fn bubble_set_character_coordinates(&mut self, ctx: &mut EngineCtx, bubble: &mut Bubble) {
+ let anchor_coord = ctx.terminal.arena[bubble.anchor_char.0 as usize].motion.current_coord;
+ let points = geometry::find_coords_on_circle(
+ anchor_coord,
+ bubble.radius,
+ bubble.characters.len() as i64,
+ false,
+ );
+ for (i, &id) in bubble.characters.iter().enumerate() {
+ let point = points[i];
+ ctx.terminal.arena[id.0 as usize].motion.set_coordinate(point);
+ if point.row == bubble.lowest_row {
+ bubble.landed = true;
+ }
+ }
+ if self.config.pop_condition == PopCondition::Anywhere && ctx.rng.random() < 0.002 {
+ bubble.landed = true;
+ }
+ }
+
+ /// Bubble.__init__ (+ make_waypoints + make_gradients).
+ fn make_bubble(
+ &mut self,
+ ctx: &mut EngineCtx,
+ origin: Coord,
+ characters: Vec,
+ ) -> Result {
+ let radius = std::cmp::max(characters.len() as i64 / 5, 1);
+ let anchor_char = ctx.terminal.add_character(" ", origin);
+ let lowest_row = if self.config.pop_condition == PopCondition::Row {
+ characters.iter().map(|&id| ctx.terminal.arena[id.0 as usize].input_coord.row).min().unwrap()
+ } else {
+ ctx.terminal.canvas.bottom
+ };
+ let mut bubble = Bubble { characters, radius, anchor_char, lowest_row, landed: false };
+ self.bubble_set_character_coordinates(ctx, &mut bubble);
+ bubble.landed = false;
+ // make_waypoints
+ let waypoint_column = ctx.rng.randint(ctx.terminal.canvas.left, ctx.terminal.canvas.right);
+ let floor_path = {
+ let ch = &mut ctx.terminal.arena[bubble.anchor_char.0 as usize];
+ let path_id = ch
+ .motion
+ .new_path(self.config.bubble_speed, None, None, 0, false, "")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(Coord::new(waypoint_column, bubble.lowest_row), None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ ctx.activate_path(self, bubble.anchor_char, &floor_path);
+ // make_gradients
+ if self.config.rainbow {
+ let mut rainbow_gradient: Vec = self.rainbow_gradient.spectrum.clone();
+ let mut gradient_offset: usize = 0;
+ for &id in &bubble.characters {
+ let (input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.input_symbol.clone(), ch.uses_input_preexisting_colors)
+ };
+ let sheen_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ let scene = ch.animation.scenes.get_mut(&scene_id).unwrap();
+ for step in &rainbow_gradient {
+ scene
+ .add_frame(
+ &input_symbol,
+ 4,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(step.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ scene_id
+ };
+ gradient_offset += 2;
+ gradient_offset %= rainbow_gradient.len();
+ let mut rotated = rainbow_gradient[gradient_offset..].to_vec();
+ rotated.extend_from_slice(&rainbow_gradient[..gradient_offset]);
+ rainbow_gradient = rotated;
+ ctx.activate_scene(self, id, &sheen_scene);
+ let active_scene = ctx.terminal.arena[id.0 as usize].animation.active_scene.clone();
+ if let Some(scene_id) = active_scene {
+ ctx.terminal.arena[id.0 as usize]
+ .animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .is_looping = true;
+ }
+ }
+ } else {
+ let bubble_color = ctx.rng.choice(&self.config.bubble_colors).clone();
+ for &id in &bubble.characters {
+ let (input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.input_symbol.clone(), ch.uses_input_preexisting_colors)
+ };
+ let sheen_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(bubble_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ ctx.activate_scene(self, id, &sheen_scene);
+ }
+ }
+ Ok(bubble)
+ }
+
+ /// Bubble.pop.
+ fn bubble_pop(&mut self, ctx: &mut EngineCtx, bubble: &Bubble) {
+ let anchor_coord = ctx.terminal.arena[bubble.anchor_char.0 as usize].motion.current_coord;
+ let points = geometry::find_coords_on_circle(
+ anchor_coord,
+ bubble.radius + 3,
+ bubble.characters.len() as i64,
+ true,
+ );
+ // zip(characters, points) — truncates at the shorter sequence
+ for (&id, &point) in bubble.characters.iter().zip(points.iter()) {
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let pop_out_path = ch
+ .motion
+ .new_path(0.3, Some(Easing::OutExpo), None, 0, false, "pop_out")
+ .expect("pop_out path");
+ ch.motion
+ .paths
+ .get_mut(&pop_out_path)
+ .unwrap()
+ .new_waypoint(point, None, "")
+ .expect("pop_out waypoint");
+ }
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path("pop_out".to_string()),
+ EventAction::ActivatePath("final".to_string()),
+ )
+ .expect("pop_out event");
+ }
+ for &id in &bubble.characters {
+ ctx.activate_scene(self, id, "pop_1");
+ ctx.activate_path(self, id, "pop_out");
+ }
+ }
+
+ /// Bubble.move.
+ fn bubble_move(&mut self, ctx: &mut EngineCtx, bubble: &mut Bubble) {
+ ctx.motion_move(self, bubble.anchor_char);
+ self.bubble_set_character_coordinates(ctx, bubble);
+ for i in 0..bubble.characters.len() {
+ let id = bubble.characters[i];
+ ctx.step_animation(self, id);
+ }
+ }
+}
+
+impl EffectHooks for Bubbles {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for Bubbles {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for id in characters {
+ let (input_coord, input_symbol, input_fg, input_bg, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.input_coord,
+ ch.input_symbol.clone(),
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ self.character_final_color_map
+ .insert(id, final_gradient_mapping.get(&input_coord).unwrap().clone());
+ ctx.terminal.arena[id.0 as usize].layer = 1;
+ let (pop_1_scene, pop_2_scene) = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let pop_1 = ch.animation.new_scene(false, None, None, "pop_1", uses_pre);
+ let pop_2 = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&pop_1)
+ .unwrap()
+ .add_frame(
+ "*",
+ 9,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.pop_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ ch.animation
+ .scenes
+ .get_mut(&pop_2)
+ .unwrap()
+ .add_frame(
+ "'",
+ 9,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.pop_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ (pop_1, pop_2)
+ };
+ let final_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "", uses_pre)
+ };
+ if dynamic {
+ let fg_gradient = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[self.config.pop_color.clone(), fg.clone()], 8, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let bg_gradient = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[self.config.pop_color.clone(), bg.clone()], 8, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut(&final_scene).unwrap();
+ if fg_gradient.is_some() || bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 6,
+ fg_gradient.as_ref(),
+ bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ 6,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ } else {
+ let final_color = self.character_final_color_map.get(&id).unwrap().clone();
+ let char_final_gradient =
+ Gradient::with_steps(&[self.config.pop_color.clone(), final_color], 8, false)
+ .map_err(EngineError::Other)?;
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut(&final_scene)
+ .unwrap()
+ .apply_gradient_to_symbols(&[input_symbol.clone()], 6, Some(&char_final_gradient), None)
+ .map_err(EngineError::Other)?;
+ }
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(pop_1_scene),
+ EventAction::ActivateScene(pop_2_scene.clone()),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(pop_2_scene),
+ EventAction::ActivateScene(final_scene),
+ )
+ .map_err(EngineError::Other)?;
+ let final_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let path_id = ch
+ .motion
+ .new_path(0.3, Some(Easing::InOutExpo), None, 0, false, "final")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(input_coord, None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(final_path),
+ EventAction::SetLayer(0),
+ )
+ .map_err(EngineError::Other)?;
+ }
+
+ let mut unbubbled_chars: Vec = Vec::new();
+ for char_list in
+ ctx.terminal.get_characters_grouped(CharacterFilter::default(), CharacterGroup::RowBottomToTop)
+ {
+ unbubbled_chars.extend(char_list);
+ }
+ self.bubbles = Vec::new();
+ while !unbubbled_chars.is_empty() {
+ let mut bubble_group: Vec = Vec::new();
+ if unbubbled_chars.len() < 5 {
+ bubble_group.append(&mut unbubbled_chars);
+ } else {
+ let count = ctx.rng.randint(5, std::cmp::min(unbubbled_chars.len() as i64, 20));
+ for _ in 0..count {
+ bubble_group.push(unbubbled_chars.remove(0));
+ }
+ }
+ let bubble_origin = Coord::new(
+ ctx.rng.randint(ctx.terminal.canvas.left, ctx.terminal.canvas.right),
+ ctx.terminal.canvas.top + 10,
+ );
+ let new_bubble = self.make_bubble(ctx, bubble_origin, bubble_group)?;
+ self.bubbles.push(new_bubble);
+ }
+ self.animating_bubbles = Vec::new();
+ self.steps_since_last_bubble = 0;
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !self.animating_bubbles.is_empty() || !ctx.active_characters.is_empty() || !self.bubbles.is_empty() {
+ if !self.bubbles.is_empty() && self.steps_since_last_bubble >= self.config.bubble_delay {
+ let next_bubble = self.bubbles.remove(0);
+ for &id in &next_bubble.characters {
+ ctx.terminal.set_character_visibility(id, true);
+ }
+ self.animating_bubbles.push(next_bubble);
+ self.steps_since_last_bubble = 0;
+ }
+ self.steps_since_last_bubble += 1;
+
+ let mut animating = std::mem::take(&mut self.animating_bubbles);
+ for bubble in &animating {
+ if bubble.landed {
+ self.bubble_pop(ctx, bubble);
+ for &id in &bubble.characters {
+ ctx.active_characters.insert(id);
+ }
+ }
+ }
+ animating.retain(|bubble| !bubble.landed);
+ for bubble in &mut animating {
+ self.bubble_move(ctx, bubble);
+ }
+ self.animating_bubbles = animating;
+
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/burn.rs b/vendor/ttfx/src/effects/burn.rs
new file mode 100644
index 0000000..10c71c7
--- /dev/null
+++ b/vendor/ttfx/src/effects/burn.rs
@@ -0,0 +1,380 @@
+//! burn, ported from effects/effect_burn.py.
+//!
+//! RNG order mirrors BurnIterator.__init__: PrimsSimple construction (random
+//! starting coord) first, then the smoke ParticlePool preallocation (2000
+//! symbol choice() draws), then the build() body (algo run to completion),
+//! then per-frame randint(2, 4) + smoke emission draws.
+//!
+//! No new observable set iterations: char_link_order and the pool's available
+//! deque are ordered upstream lists; BreadthFirst is not used here
+//! (docs/ordering-inventory.md unchanged).
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{parse_gradient_direction, parse_gradient_steps, parse_non_negative_ratio};
+use crate::engine::animation::{ExistingColorHandling, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallbackValue, CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::particles::{ParticlePool, ParticleReset};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::geometry::Coord;
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+use crate::utils::spanning_tree::PrimsSimple;
+
+/// Callback id: EventHandler.Callback(lambda c: self._emit_smoke(c.input_coord, ...)).
+const CB_EMIT_SMOKE: u32 = 0;
+/// Callback id: ParticlePool.reclaim_on_event's reclaim closure.
+const CB_RECLAIM_SMOKE: u32 = 1;
+
+#[derive(Args, Debug, Clone)]
+pub struct BurnConfig {
+ /// Color of the characters before they start to burn.
+ #[arg(long = "starting-color", default_value = "837373", value_parser = parse_color)]
+ pub starting_color: Color,
+
+ /// Colors transitioned through as the characters burn.
+ #[arg(long = "burn-colors", num_args = 1.., value_parser = parse_color,
+ default_values = ["ffffff", "fff75d", "fe650d", "8A003C", "510100"])]
+ pub burn_colors: Vec,
+
+ /// Chance a given character will produce smoke while burning. Use 0 for no smoke.
+ #[arg(long = "smoke-chance", default_value_t = 0.5, value_parser = parse_non_negative_ratio)]
+ pub smoke_chance: f64,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["00c3ff", "ffff1c"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "vertical", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+const BURN_CHAR_ORDER: [&str; 9] = ["'", ".", "▖", "▙", "█", "▜", "▀", "▝", "."];
+const SMOKE_SYMBOLS: [&str; 6] = [".", ",", "'", "`", "#", "*"];
+
+pub struct Burn {
+ config: BurnConfig,
+ character_final_color_map: HashMap,
+ /// PrimsSimple.char_link_order, consumed FIFO in next_frame.
+ char_link_order: Vec,
+ /// Option so _emit_smoke can move the pool out of self while the on_emit
+ /// closure needs &mut self for event dispatch (see emit_smoke).
+ smoke_particles: Option,
+ /// Makes each reclaim Callback registration unique, mirroring Python's
+ /// fresh closure object per reclaim_on_event call (identity inequality
+ /// lets registrations accumulate upstream instead of raising
+ /// DuplicateEventRegistrationError; firing reclaim repeatedly is
+ /// idempotent, so behavior is identical).
+ emission_counter: i64,
+}
+
+impl Burn {
+ pub fn new(config: BurnConfig) -> Self {
+ Burn {
+ config,
+ character_final_color_map: HashMap::new(),
+ char_link_order: Vec::new(),
+ smoke_particles: None,
+ emission_counter: 0,
+ }
+ }
+
+ /// BurnIterator._has_input_colors.
+ fn has_input_colors(ctx: &EngineCtx, id: CharId) -> bool {
+ let anim = &ctx.terminal.arena[id.0 as usize].animation;
+ anim.input_fg_color.is_some() || anim.input_bg_color.is_some()
+ }
+
+ /// BurnIterator._is_burnable.
+ fn is_burnable(&self, ctx: &EngineCtx, id: CharId) -> bool {
+ ctx.terminal.arena[id.0 as usize].input_symbol != " "
+ || (ctx.terminal.config.existing_color_handling != ExistingColorHandling::Ignore
+ && Self::has_input_colors(ctx, id))
+ }
+
+ /// BurnIterator._make_smoke_pool's initialize_smoke: one reusable "smoke"
+ /// scene (10-frame 504F4F->C7C7C7 fade) and layer 2. Passed to every pool
+ /// call; runs only for newly created particles.
+ fn initialize_smoke(ctx: &mut EngineCtx, id: CharId) {
+ let (input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.input_symbol.clone(), ch.uses_input_preexisting_colors)
+ };
+ let gradient = Gradient::with_steps(
+ &[Color::from_hex("504F4F").unwrap(), Color::from_hex("C7C7C7").unwrap()],
+ 9,
+ false,
+ )
+ .expect("smoke gradient");
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let smoke_scn = ch.animation.new_scene(false, None, None, "smoke", uses_pre);
+ let scene = ch.animation.scenes.get_mut(&smoke_scn).unwrap();
+ for color in &gradient.spectrum {
+ scene
+ .add_frame(
+ &input_symbol,
+ 10,
+ VisualParams { colors: Some(ColorPair::new(Some(color.clone()), None)), ..Default::default() },
+ )
+ .expect("smoke frame");
+ }
+ ch.layer = 2;
+ }
+
+ /// BurnIterator._emit_smoke.
+ fn emit_smoke(&mut self, ctx: &mut EngineCtx, origin: Coord) {
+ if ctx.rng.random() > self.config.smoke_chance {
+ return;
+ }
+ // ParticleReset(clear_paths=True, deactivate_path=True,
+ // deactivate_scene=True) == the upstream defaults.
+ let reset = ParticleReset::default();
+ self.emission_counter += 1;
+ let emission_id = self.emission_counter;
+ // Move the pool out of self so the on_emit closure can borrow self as
+ // EffectHooks. Safe: on_emit only fires PATH_ACTIVATED/SCENE_ACTIVATED,
+ // for which smoke particles never register actions, so CB_RECLAIM_SMOKE
+ // cannot dispatch while the pool is out.
+ let mut pool = self.smoke_particles.take().expect("smoke pool");
+ pool.emit(ctx, origin, None, true, reset, Self::initialize_smoke, |ctx, next_particle| {
+ // on_emit_smoke
+ ctx.terminal.arena[next_particle.0 as usize]
+ .animation
+ .scenes
+ .get_mut("smoke")
+ .expect("smoke scene")
+ .reset_scene();
+ let smoke_path = ctx.terminal.arena[next_particle.0 as usize]
+ .motion
+ .new_path(0.5, None, None, 0, false, "")
+ .expect("smoke path");
+ let rise_target_coord = Coord::new(
+ ctx.rng.randint(origin.column - 4, origin.column + 4),
+ ctx.terminal.canvas.top + 1,
+ );
+ ctx.terminal.arena[next_particle.0 as usize]
+ .motion
+ .paths
+ .get_mut(&smoke_path)
+ .unwrap()
+ .new_waypoint(rise_target_coord, None, "")
+ .expect("smoke waypoint");
+ ctx.activate_path(self, next_particle, &smoke_path);
+ ctx.activate_scene(self, next_particle, "smoke");
+ // ParticlePool.reclaim_on_event(next_particle, caller="smoke")
+ ctx.register_event(
+ next_particle,
+ Event::SceneComplete,
+ CallerKey::Scene("smoke".to_string()),
+ EventAction::Callback(EffectCallback {
+ id: CB_RECLAIM_SMOKE,
+ args: vec![CallbackValue::Int(emission_id)],
+ }),
+ )
+ .expect("register reclaim");
+ });
+ self.smoke_particles = Some(pool);
+ }
+}
+
+impl EffectHooks for Burn {
+ fn dispatch_callback(&mut self, ctx: &mut EngineCtx, character: CharId, callback: &EffectCallback) {
+ match callback.id {
+ CB_EMIT_SMOKE => {
+ let origin = ctx.terminal.arena[character.0 as usize].input_coord;
+ self.emit_smoke(ctx, origin);
+ }
+ CB_RECLAIM_SMOKE => {
+ // reclaim(completed_character, hide=True, deactivate=True)
+ self.smoke_particles.as_mut().expect("smoke pool").reclaim(ctx, character, true, true);
+ }
+ _ => {}
+ }
+ }
+}
+
+impl Effect for Burn {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ // BurnIterator.__init__ order: PrimsSimple (random starting coord),
+ // then the pool preallocation (2000 choice() draws + initializer each).
+ let mut algo = PrimsSimple::new(ctx, None, true).map_err(EngineError::Other)?;
+ let mut pool =
+ ParticlePool::new(SMOKE_SYMBOLS.iter().map(|s| s.to_string()).collect(), Some(2000), None)
+ .map_err(EngineError::Other)?;
+ pool.preallocate(ctx, 2000, Self::initialize_smoke).map_err(EngineError::Other)?;
+ self.smoke_particles = Some(pool);
+
+ // BurnIterator.build()
+ let burn_char_order: Vec = BURN_CHAR_ORDER.iter().map(|s| s.to_string()).collect();
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ let coord = ctx.terminal.arena[id.0 as usize].input_coord;
+ self.character_final_color_map
+ .insert(id, final_gradient_mapping.get(&coord).expect("gradient mapping").clone());
+ }
+ let fire_gradient = Gradient::with_steps(&self.config.burn_colors, 10, false).map_err(EngineError::Other)?;
+
+ while !algo.complete {
+ algo.step(ctx);
+ }
+
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ ctx.terminal.set_character_visibility(id, true);
+ let (input_symbol, input_fg, input_bg, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.input_symbol.clone(),
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.set_appearance(
+ &input_symbol,
+ uses_pre,
+ Some(&input_symbol),
+ Some(ColorPair::new(Some(self.config.starting_color.clone()), None)),
+ );
+ }
+ let burn_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "burn", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .apply_gradient_to_symbols(&burn_char_order, 4, Some(&fire_gradient), None)
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ let final_color_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "", uses_pre)
+ };
+ let fire_last = fire_gradient.spectrum.last().expect("fire gradient spectrum").clone();
+ if dynamic {
+ let fg_gradient = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[fire_last.clone(), fg.clone()], 8, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let bg_gradient = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[fire_last.clone(), bg.clone()], 8, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut(&final_color_scn).unwrap();
+ if fg_gradient.is_some() || bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 4,
+ fg_gradient.as_ref(),
+ bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ 4,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ } else {
+ let final_color = self.character_final_color_map.get(&id).unwrap().clone();
+ let char_gradient =
+ Gradient::with_steps(&[fire_last, final_color], 8, false).map_err(EngineError::Other)?;
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut(&final_color_scn).unwrap();
+ for color in &char_gradient.spectrum {
+ scene
+ .add_frame(
+ &input_symbol,
+ 4,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(burn_scn.clone()),
+ EventAction::ActivateScene(final_color_scn),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(burn_scn),
+ EventAction::Callback(EffectCallback { id: CB_EMIT_SMOKE, args: Vec::new() }),
+ )
+ .map_err(EngineError::Other)?;
+ }
+ self.char_link_order = algo.char_link_order;
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !self.char_link_order.is_empty() || !ctx.active_characters.is_empty() {
+ for _ in 0..ctx.rng.randint(2, 4) {
+ if !self.char_link_order.is_empty() {
+ let next_char = self.char_link_order.remove(0);
+ if !self.is_burnable(ctx, next_char) {
+ continue;
+ }
+ ctx.activate_scene(self, next_char, "burn");
+ ctx.active_characters.insert(next_char);
+ }
+ }
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/colorshift.rs b/vendor/ttfx/src/effects/colorshift.rs
new file mode 100644
index 0000000..d53659d
--- /dev/null
+++ b/vendor/ttfx/src/effects/colorshift.rs
@@ -0,0 +1,275 @@
+//! colorshift, ported from effects/effect_colorshift.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{parse_gradient_direction, parse_gradient_steps, parse_positive_int};
+use crate::engine::animation::{ExistingColorHandling, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::geometry;
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct ColorShiftConfig {
+ /// Space separated, unquoted, list of colors for the gradient.
+ #[arg(long = "gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["e81416", "ffa500", "faeb36", "79c314", "487de7", "4b369d", "70369d"])]
+ pub gradient_stops: Vec,
+
+ /// Number of gradient steps to use. More steps will create a smoother gradient animation.
+ #[arg(long = "gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub gradient_steps: Vec,
+
+ /// Number of frames to display each gradient step. Increase to slow down the gradient animation.
+ #[arg(long = "gradient-frames", default_value_t = 2, value_parser = parse_positive_int)]
+ pub gradient_frames: i64,
+
+ /// Do not display the gradient as a wave.
+ #[arg(long = "no-travel")]
+ pub no_travel: bool,
+
+ /// Direction the gradient travels across the canvas.
+ #[arg(long = "travel-direction", default_value = "radial", value_parser = parse_gradient_direction)]
+ pub travel_direction: GradientDirection,
+
+ /// Reverse the gradient travel direction.
+ #[arg(long = "reverse-travel-direction")]
+ pub reverse_travel_direction: bool,
+
+ /// Do not loop the gradient.
+ #[arg(long = "no-loop")]
+ pub no_loop: bool,
+
+ /// Number of times to cycle the gradient.
+ #[arg(long = "cycles", default_value_t = 3, value_parser = parse_positive_int)]
+ pub cycles: i64,
+
+ /// Skip the final gradient.
+ #[arg(long = "skip-final-gradient")]
+ pub skip_final_gradient: bool,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["e81416", "ffa500", "faeb36", "79c314", "487de7", "4b369d", "70369d"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use for the final gradient.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "vertical", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+pub struct ColorShift {
+ config: ColorShiftConfig,
+ character_final_color_map: HashMap,
+ loop_tracker_map: HashMap,
+}
+
+impl ColorShift {
+ pub fn new(config: ColorShiftConfig) -> Self {
+ ColorShift { config, character_final_color_map: HashMap::new(), loop_tracker_map: HashMap::new() }
+ }
+}
+
+impl EffectHooks for ColorShift {
+ /// ColorShiftIterator.loop_tracker.
+ fn dispatch_callback(&mut self, ctx: &mut EngineCtx, character: CharId, _callback: &EffectCallback) {
+ let count = {
+ let entry = self.loop_tracker_map.entry(character).or_insert(0);
+ *entry += 1;
+ *entry
+ };
+ if self.config.cycles == 0 || count < self.config.cycles {
+ ctx.activate_scene(self, character, "gradient");
+ } else if !self.config.skip_final_gradient {
+ ctx.activate_scene(self, character, "final_gradient");
+ }
+ }
+}
+
+impl Effect for ColorShift {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ let input_coord = ctx.terminal.arena[id.0 as usize].input_coord;
+ self.character_final_color_map
+ .insert(id, final_gradient_mapping.get(&input_coord).unwrap().clone());
+ }
+ let gradient =
+ Gradient::new(&self.config.gradient_stops, &self.config.gradient_steps, false, !self.config.no_loop)
+ .map_err(EngineError::Other)?;
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for id in characters {
+ ctx.terminal.set_character_visibility(id, true);
+ let (input_fg, input_bg, input_coord, input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.input_coord,
+ ch.input_symbol.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ let colors: Vec = if self.config.no_travel {
+ gradient.spectrum.clone()
+ } else {
+ let direction_index = match self.config.travel_direction {
+ GradientDirection::Horizontal => {
+ input_coord.column as f64 / ctx.terminal.canvas.right as f64
+ }
+ GradientDirection::Vertical => input_coord.row as f64 / ctx.terminal.canvas.top as f64,
+ GradientDirection::Diagonal => {
+ (input_coord.row + input_coord.column) as f64
+ / (ctx.terminal.canvas.right + ctx.terminal.canvas.top) as f64
+ }
+ GradientDirection::Radial => geometry::find_normalized_distance_from_center(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ input_coord,
+ )
+ .map_err(EngineError::Other)?,
+ };
+ // int() truncation
+ let mut shift_distance = (gradient.spectrum.len() as f64 * direction_index) as i64;
+ if self.config.reverse_travel_direction {
+ shift_distance *= -1;
+ }
+ // Python slicing: spectrum[shift:] + spectrum[:shift], negative shifts wrap
+ let len = gradient.spectrum.len() as i64;
+ let k = if shift_distance < 0 {
+ (len + shift_distance).max(0) as usize
+ } else {
+ shift_distance.min(len) as usize
+ };
+ let mut rotated = gradient.spectrum[k..].to_vec();
+ rotated.extend_from_slice(&gradient.spectrum[..k]);
+ rotated
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "gradient", uses_pre);
+ let scene = ch.animation.scenes.get_mut("gradient").unwrap();
+ for color in &colors {
+ scene
+ .add_frame(
+ &input_symbol,
+ self.config.gradient_frames,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ ch.animation.new_scene(false, None, None, "final_gradient", uses_pre);
+ }
+ let last_color = colors.last().unwrap().clone();
+ if dynamic {
+ let fg_gradient = match &input_fg {
+ Some(c) => Some(
+ Gradient::with_steps(&[last_color.clone(), c.clone()], 8, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let bg_gradient = match &input_bg {
+ Some(c) => Some(
+ Gradient::with_steps(&[last_color.clone(), c.clone()], 8, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut("final_gradient").unwrap();
+ if fg_gradient.is_some() || bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ self.config.gradient_frames,
+ fg_gradient.as_ref(),
+ bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ self.config.gradient_frames,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ } else {
+ let final_color = self.character_final_color_map.get(&id).unwrap().clone();
+ let final_scene_gradient =
+ Gradient::with_steps(&[last_color, final_color], 8, false).map_err(EngineError::Other)?;
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut("final_gradient").unwrap();
+ for color in &final_scene_gradient.spectrum {
+ scene
+ .add_frame(
+ &input_symbol,
+ self.config.gradient_frames,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ ctx.activate_scene(self, id, "gradient");
+ ctx.active_characters.insert(id);
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene("gradient".to_string()),
+ EventAction::Callback(EffectCallback { id: 0, args: Vec::new() }),
+ )
+ .map_err(EngineError::Other)?;
+ }
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !ctx.active_characters.is_empty() {
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/common.rs b/vendor/ttfx/src/effects/common.rs
new file mode 100644
index 0000000..f50efff
--- /dev/null
+++ b/vendor/ttfx/src/effects/common.rs
@@ -0,0 +1,145 @@
+//! Shared clap value parsers for effect configs (argutils validators).
+
+use crate::utils::easing::Easing;
+use crate::utils::graphics::GradientDirection;
+
+pub fn parse_positive_float(s: &str) -> Result {
+ let v: f64 = s.parse().map_err(|_| format!("invalid float value: '{s}'"))?;
+ if v > 0.0 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not a valid value. Argument must be a float > 0."))
+ }
+}
+
+pub fn parse_non_negative_float(s: &str) -> Result {
+ let v: f64 = s.parse().map_err(|_| format!("invalid float value: '{s}'"))?;
+ if v >= 0.0 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not a valid value. Argument must be a float >= 0."))
+ }
+}
+
+/// argutils.PositiveInt for gradient steps (nargs +).
+pub fn parse_gradient_steps(s: &str) -> Result {
+ let v: i64 = s.parse().map_err(|_| format!("invalid int value: '{s}'"))?;
+ if v > 0 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not a valid value. Argument must be an int > 0."))
+ }
+}
+
+pub fn parse_positive_int(s: &str) -> Result {
+ parse_gradient_steps(s)
+}
+
+pub fn parse_non_negative_int(s: &str) -> Result {
+ let v: i64 = s.parse().map_err(|_| format!("invalid int value: '{s}'"))?;
+ if v >= 0 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not a valid value. Argument must be an int >= 0."))
+ }
+}
+
+/// argutils.NonNegativeRatio: 0 <= n <= 1.
+pub fn parse_non_negative_ratio(s: &str) -> Result {
+ let v: f64 = s.parse().map_err(|_| format!("invalid float value: '{s}'"))?;
+ if (0.0..=1.0).contains(&v) {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not a valid value. Argument must be a float 0 <= n <= 1."))
+ }
+}
+
+/// argutils.PositiveRatio: 0 < n <= 1.
+pub fn parse_positive_ratio(s: &str) -> Result {
+ let v: f64 = s.parse().map_err(|_| format!("invalid float value: '{s}'"))?;
+ if v > 0.0 && v <= 1.0 {
+ Ok(v)
+ } else {
+ Err(format!("{v} is not a valid value. Argument must be a float 0 < n <= 1."))
+ }
+}
+
+pub fn parse_gradient_direction(s: &str) -> Result {
+ match s {
+ "horizontal" => Ok(GradientDirection::Horizontal),
+ "vertical" => Ok(GradientDirection::Vertical),
+ "diagonal" => Ok(GradientDirection::Diagonal),
+ "radial" => Ok(GradientDirection::Radial),
+ _ => Err(format!("invalid gradient direction: '{s}'")),
+ }
+}
+
+pub fn parse_easing(s: &str) -> Result {
+ Easing::parse(s).ok_or_else(|| format!("invalid easing function: '{s}'"))
+}
+
+/// argutils.CharacterGroupArg: lowercased enum member names.
+pub fn parse_character_group(s: &str) -> Result {
+ use crate::engine::terminal::CharacterGroup::*;
+ Ok(match s {
+ "column_left_to_right" => ColumnLeftToRight,
+ "column_right_to_left" => ColumnRightToLeft,
+ "row_top_to_bottom" => RowTopToBottom,
+ "row_bottom_to_top" => RowBottomToTop,
+ "diagonal_top_left_to_bottom_right" => DiagonalTopLeftToBottomRight,
+ "diagonal_bottom_left_to_top_right" => DiagonalBottomLeftToTopRight,
+ "diagonal_top_right_to_bottom_left" => DiagonalTopRightToBottomLeft,
+ "diagonal_bottom_right_to_top_left" => DiagonalBottomRightToTopLeft,
+ "center_to_outside" => CenterToOutside,
+ "outside_to_center" => OutsideToCenter,
+ _ => return Err(format!("invalid character group: '{s}'")),
+ })
+}
+
+/// argutils.CharacterSortArg: lowercased enum member names.
+pub fn parse_character_sort(s: &str) -> Result {
+ use crate::engine::terminal::CharacterSort::*;
+ Ok(match s {
+ "random" => Random,
+ "top_to_bottom_left_to_right" => TopToBottomLeftToRight,
+ "top_to_bottom_right_to_left" => TopToBottomRightToLeft,
+ "bottom_to_top_left_to_right" => BottomToTopLeftToRight,
+ "bottom_to_top_right_to_left" => BottomToTopRightToLeft,
+ "outside_row_to_middle" => OutsideRowToMiddle,
+ "middle_row_to_outside" => MiddleRowToOutside,
+ _ => return Err(format!("invalid character sort: '{s}'")),
+ })
+}
+
+/// argutils.Symbol: single printable character.
+pub fn parse_symbol(s: &str) -> Result {
+ if s.chars().count() == 1 {
+ Ok(s.to_string())
+ } else {
+ Err(format!("invalid symbol: '{s}' argument must be a single character"))
+ }
+}
+
+/// argutils.PositiveIntRange: "1-10".
+pub fn parse_positive_int_range(s: &str) -> Result<(i64, i64), String> {
+ let (a, b) = s.split_once('-').ok_or_else(|| format!("invalid range: '{s}'"))?;
+ let a: i64 = a.parse().map_err(|_| format!("invalid range: '{s}'"))?;
+ let b: i64 = b.parse().map_err(|_| format!("invalid range: '{s}'"))?;
+ if a > 0 && a <= b {
+ Ok((a, b))
+ } else {
+ Err(format!("invalid range: '{s}'"))
+ }
+}
+
+/// argutils.PositiveFloatRange: "0.25-0.5".
+pub fn parse_positive_float_range(s: &str) -> Result<(f64, f64), String> {
+ let (a, b) = s.split_once('-').ok_or_else(|| format!("invalid range: '{s}'"))?;
+ let a: f64 = a.parse().map_err(|_| format!("invalid range: '{s}'"))?;
+ let b: f64 = b.parse().map_err(|_| format!("invalid range: '{s}'"))?;
+ if a > 0.0 && a <= b {
+ Ok((a, b))
+ } else {
+ Err(format!("invalid range: '{s}'"))
+ }
+}
diff --git a/vendor/ttfx/src/effects/crumble.rs b/vendor/ttfx/src/effects/crumble.rs
new file mode 100644
index 0000000..13bd5b5
--- /dev/null
+++ b/vendor/ttfx/src/effects/crumble.rs
@@ -0,0 +1,476 @@
+//! crumble, ported from effects/effect_crumble.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{parse_gradient_direction, parse_gradient_steps};
+use crate::engine::animation::{Animation, ExistingColorHandling, SyncMetric, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::easing::Easing;
+use crate::utils::geometry::Coord;
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct CrumbleConfig {
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["5CE1FF", "FF8C00"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "diagonal", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+enum Stage {
+ Falling,
+ Vacuuming,
+ Resetting,
+ Complete,
+}
+
+pub struct Crumble {
+ config: CrumbleConfig,
+ pending_chars: Vec,
+ character_final_color_map: HashMap,
+ fall_delay: i64,
+ max_fall_delay: i64,
+ min_fall_delay: i64,
+ reset: bool,
+ fall_group_maxsize: i64,
+ stage: Stage,
+ unvacuumed_chars: Vec,
+}
+
+impl Crumble {
+ pub fn new(config: CrumbleConfig) -> Self {
+ Crumble {
+ config,
+ pending_chars: Vec::new(),
+ character_final_color_map: HashMap::new(),
+ fall_delay: 0,
+ max_fall_delay: 0,
+ min_fall_delay: 0,
+ reset: false,
+ fall_group_maxsize: 1,
+ stage: Stage::Falling,
+ unvacuumed_chars: Vec::new(),
+ }
+ }
+}
+
+impl EffectHooks for Crumble {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for Crumble {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ // CrumbleIterator.DYNAMIC_NEUTRAL_GRAY
+ let dynamic_neutral_gray = Color::from_hex("#808080").unwrap();
+ let white = Color::from_hex("#ffffff").unwrap();
+
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ let canvas_bottom = ctx.terminal.canvas.bottom;
+ let canvas_top = ctx.terminal.canvas.top;
+ let canvas_center_column = ctx.terminal.canvas.center_column;
+ let canvas_center_row = ctx.terminal.canvas.center_row;
+ for &id in &characters {
+ let (input_coord, input_symbol, input_fg, input_bg, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.input_coord,
+ ch.input_symbol.clone(),
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ self.character_final_color_map
+ .insert(id, final_gradient_mapping.get(&input_coord).unwrap().clone());
+ let (
+ weak_fg_color,
+ weak_bg_color,
+ dust_fg_color,
+ dust_bg_color,
+ strengthen_flash_fg_gradient,
+ strengthen_flash_bg_gradient,
+ strengthen_fg_gradient,
+ strengthen_bg_gradient,
+ );
+ if dynamic {
+ let has_existing_colors = input_fg.is_some() || input_bg.is_some();
+ weak_fg_color = match &input_fg {
+ Some(fg) => Some(Animation::adjust_color_brightness(fg, 0.65)),
+ None => {
+ if input_bg.is_none() {
+ Some(Animation::adjust_color_brightness(&dynamic_neutral_gray, 0.65))
+ } else {
+ None
+ }
+ }
+ };
+ weak_bg_color = input_bg.as_ref().map(|bg| Animation::adjust_color_brightness(bg, 0.65));
+ dust_fg_color = match &input_fg {
+ Some(fg) => Some(Animation::adjust_color_brightness(fg, 0.55)),
+ None => {
+ if input_bg.is_none() {
+ Some(Animation::adjust_color_brightness(&dynamic_neutral_gray, 0.55))
+ } else {
+ None
+ }
+ }
+ };
+ dust_bg_color = input_bg.as_ref().map(|bg| Animation::adjust_color_brightness(bg, 0.55));
+ strengthen_flash_fg_gradient = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[fg.clone(), white.clone()], 6, false).map_err(EngineError::Other)?,
+ ),
+ None => {
+ if !has_existing_colors {
+ Some(
+ Gradient::with_steps(&[dynamic_neutral_gray.clone(), white.clone()], 6, false)
+ .map_err(EngineError::Other)?,
+ )
+ } else {
+ None
+ }
+ }
+ };
+ strengthen_flash_bg_gradient = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[bg.clone(), white.clone()], 6, false).map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ strengthen_fg_gradient = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[white.clone(), fg.clone()], 9, false).map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ strengthen_bg_gradient = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[white.clone(), bg.clone()], 9, false).map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ } else {
+ let final_color = self.character_final_color_map.get(&id).unwrap().clone();
+ weak_fg_color = Some(Animation::adjust_color_brightness(&final_color, 0.65));
+ weak_bg_color = None;
+ dust_fg_color = Some(Animation::adjust_color_brightness(&final_color, 0.55));
+ dust_bg_color = None;
+ strengthen_flash_fg_gradient = Some(
+ Gradient::with_steps(&[final_color.clone(), white.clone()], 6, false)
+ .map_err(EngineError::Other)?,
+ );
+ strengthen_flash_bg_gradient = None;
+ strengthen_fg_gradient = Some(
+ Gradient::with_steps(&[white.clone(), final_color.clone()], 9, false)
+ .map_err(EngineError::Other)?,
+ );
+ strengthen_bg_gradient = None;
+ }
+ let weaken_fg_gradient = match (&weak_fg_color, &dust_fg_color) {
+ (Some(weak), Some(dust)) => Some(
+ Gradient::with_steps(&[weak.clone(), dust.clone()], 9, false).map_err(EngineError::Other)?,
+ ),
+ _ => None,
+ };
+ let weaken_bg_gradient = match (&weak_bg_color, &dust_bg_color) {
+ (Some(weak), Some(dust)) => Some(
+ Gradient::with_steps(&[weak.clone(), dust.clone()], 9, false).map_err(EngineError::Other)?,
+ ),
+ _ => None,
+ };
+ ctx.terminal.set_character_visibility(id, true);
+ // set up initial and falling stage
+ let initial_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(weak_fg_color.clone(), weak_bg_color.clone())),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ ctx.activate_scene(self, id, &initial_scn);
+ let fall_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let path_id = ch
+ .motion
+ .new_path(0.65, Some(Easing::OutBounce), None, 0, false, "")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(Coord::new(input_coord.column, canvas_bottom), None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let weaken_scn = ch.animation.new_scene(false, None, None, "weaken", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&weaken_scn)
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 4,
+ weaken_fg_gradient.as_ref(),
+ weaken_bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ }
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let top_path = ch
+ .motion
+ .new_path(1.0, Some(Easing::OutQuint), None, 0, false, "top")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&top_path)
+ .unwrap()
+ .new_waypoint(
+ Coord::new(input_coord.column, canvas_top),
+ Some(vec![Coord::new(canvas_center_column, canvas_center_row)]),
+ "",
+ )
+ .map_err(EngineError::Other)?;
+ }
+ // set up reset stage
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let input_path = ch.motion.new_path(1.0, None, None, 0, false, "input").map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&input_path)
+ .unwrap()
+ .new_waypoint(input_coord, None, "")
+ .map_err(EngineError::Other)?;
+ }
+ let strengthen_flash_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 4,
+ strengthen_flash_fg_gradient.as_ref(),
+ strengthen_flash_bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ let strengthen_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ let scene = ch.animation.scenes.get_mut(&scene_id).unwrap();
+ if dynamic && input_fg.is_none() && input_bg.is_none() {
+ scene
+ .add_frame(
+ &input_symbol,
+ 4,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 4,
+ strengthen_fg_gradient.as_ref(),
+ strengthen_bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ }
+ scene_id
+ };
+ let dust_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, Some(SyncMetric::Distance), None, "", uses_pre)
+ };
+ let dust_symbols = ["*", ".", ","];
+ for _ in 0..5 {
+ let symbol = *ctx.rng.choice(&dust_symbols);
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut(&dust_scn)
+ .unwrap()
+ .add_frame(
+ symbol,
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(dust_fg_color.clone(), dust_bg_color.clone())),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene("weaken".to_string()),
+ EventAction::ActivatePath(fall_path),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene("weaken".to_string()),
+ EventAction::SetLayer(1),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene("weaken".to_string()),
+ EventAction::ActivateScene(dust_scn),
+ )
+ .map_err(EngineError::Other)?;
+
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path("input".to_string()),
+ EventAction::ActivateScene(strengthen_flash_scn.clone()),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(strengthen_flash_scn),
+ EventAction::ActivateScene(strengthen_scn),
+ )
+ .map_err(EngineError::Other)?;
+ self.pending_chars.push(id);
+ }
+ ctx.rng.shuffle(&mut self.pending_chars);
+ self.fall_delay = 12;
+ self.max_fall_delay = 12;
+ self.min_fall_delay = 9;
+ self.reset = false;
+ self.fall_group_maxsize = 1;
+ self.stage = Stage::Falling;
+ self.unvacuumed_chars = ctx.terminal.input_characters.clone();
+ ctx.rng.shuffle(&mut self.unvacuumed_chars);
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if self.stage != Stage::Complete {
+ match self.stage {
+ Stage::Falling => {
+ if !self.pending_chars.is_empty() {
+ if self.fall_delay == 0 {
+ // Determine the size of the next group of falling characters
+ let fall_group_size = ctx.rng.randint(1, self.fall_group_maxsize);
+ // Add the next group of falling characters to the animating characters list
+ for _ in 0..fall_group_size {
+ if !self.pending_chars.is_empty() {
+ let next_char = self.pending_chars.remove(0);
+ ctx.activate_scene(self, next_char, "weaken");
+ ctx.active_characters.insert(next_char);
+ }
+ }
+ // Reset the fall delay and adjust the fall group size and delay range
+ self.fall_delay = ctx.rng.randint(self.min_fall_delay, self.max_fall_delay);
+ if ctx.rng.randint(1, 10) > 4 {
+ // 60% chance to modify the fall delay and group size
+ self.fall_group_maxsize += 1;
+ self.min_fall_delay = std::cmp::max(0, self.min_fall_delay - 1);
+ self.max_fall_delay = std::cmp::max(0, self.max_fall_delay - 1);
+ }
+ } else {
+ self.fall_delay -= 1;
+ }
+ }
+ if self.pending_chars.is_empty() && ctx.active_characters.is_empty() {
+ self.stage = Stage::Vacuuming;
+ }
+ }
+ Stage::Vacuuming => {
+ if !self.unvacuumed_chars.is_empty() {
+ for _ in 0..ctx.rng.randint(3, 10) {
+ if !self.unvacuumed_chars.is_empty() {
+ let next_char = self.unvacuumed_chars.remove(0);
+ ctx.activate_path(self, next_char, "top");
+ ctx.active_characters.insert(next_char);
+ }
+ }
+ }
+ if ctx.active_characters.is_empty() {
+ self.stage = Stage::Resetting;
+ }
+ }
+ Stage::Resetting => {
+ if !self.reset {
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for id in characters {
+ ctx.activate_path(self, id, "input");
+ ctx.active_characters.insert(id);
+ }
+ self.reset = true;
+ }
+ if ctx.active_characters.is_empty() {
+ self.stage = Stage::Complete;
+ }
+ }
+ Stage::Complete => {}
+ }
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/decrypt.rs b/vendor/ttfx/src/effects/decrypt.rs
new file mode 100644
index 0000000..2eb1374
--- /dev/null
+++ b/vendor/ttfx/src/effects/decrypt.rs
@@ -0,0 +1,367 @@
+//! decrypt, ported from effects/effect_decrypt.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{parse_gradient_direction, parse_gradient_steps, parse_positive_int};
+use crate::engine::animation::{ExistingColorHandling, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct DecryptConfig {
+ /// Number of characters typed per keystroke.
+ #[arg(long = "typing-speed", default_value_t = 2, value_parser = parse_positive_int)]
+ pub typing_speed: i64,
+
+ /// Space separated, unquoted, list of colors for the ciphertext. Color will be randomly selected for each character.
+ #[arg(long = "ciphertext-colors", num_args = 1.., value_parser = parse_color,
+ default_values = ["008000", "00cb00", "00ff00"])]
+ pub ciphertext_colors: Vec,
+
+ /// Space separated, unquoted, list of colors for the character gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["eda000"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "vertical", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Phase {
+ Typing,
+ Decrypting,
+}
+
+pub struct Decrypt {
+ config: DecryptConfig,
+ typing_pending_chars: Vec,
+ /// Upstream is a set; membership only feeds `active_characters`, which is
+ /// canonically ordered, so insertion-ordered Vec is equivalent.
+ decrypting_pending_chars: Vec,
+ phase: Phase,
+ encrypted_symbols: Vec,
+ character_final_color_map: HashMap,
+}
+
+impl Decrypt {
+ pub fn new(config: DecryptConfig) -> Self {
+ let mut effect = Decrypt {
+ config,
+ typing_pending_chars: Vec::new(),
+ decrypting_pending_chars: Vec::new(),
+ phase: Phase::Typing,
+ encrypted_symbols: Vec::new(),
+ character_final_color_map: HashMap::new(),
+ };
+ effect.make_encrypted_symbols();
+ effect
+ }
+
+ /// DecryptIterator.make_encrypted_symbols (_DecryptChars ranges).
+ fn make_encrypted_symbols(&mut self) {
+ for n in 33u32..127 {
+ self.encrypted_symbols.push(char::from_u32(n).unwrap().to_string());
+ }
+ for n in 9608u32..9632 {
+ self.encrypted_symbols.push(char::from_u32(n).unwrap().to_string());
+ }
+ for n in 9472u32..9599 {
+ self.encrypted_symbols.push(char::from_u32(n).unwrap().to_string());
+ }
+ for n in 174u32..452 {
+ self.encrypted_symbols.push(char::from_u32(n).unwrap().to_string());
+ }
+ }
+
+ /// DecryptIterator.make_decrypting_animation_scenes.
+ fn make_decrypting_animation_scenes(&mut self, ctx: &mut EngineCtx, id: CharId) -> Result<(), EngineError> {
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let (input_symbol, input_fg, input_bg, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.input_symbol.clone(),
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "fast_decrypt", uses_pre);
+ }
+ let color = ctx.rng.choice(&self.config.ciphertext_colors).clone();
+ for _ in 0..80 {
+ let symbol = ctx.rng.choice(&self.encrypted_symbols).clone();
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut("fast_decrypt")
+ .unwrap()
+ .add_frame(
+ &symbol,
+ 2,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "slow_decrypt", uses_pre);
+ }
+ for _ in 0..ctx.rng.randint(1, 15) {
+ // 1-15 longer duration units
+ let symbol = ctx.rng.choice(&self.encrypted_symbols).clone();
+ // 30% chance of extra long duration
+ // wide duration range reduces 'waves' in the animation
+ // shorter duration creates flipping effect
+ let duration = if ctx.rng.randint(0, 100) <= 30 {
+ ctx.rng.randrange(35, 60)
+ } else {
+ ctx.rng.randrange(3, 6)
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut("slow_decrypt")
+ .unwrap()
+ .add_frame(
+ &symbol,
+ duration,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "discovered", uses_pre);
+ }
+ let white = Color::from_hex("ffffff").unwrap();
+ if dynamic {
+ let fg_gradient = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[white.clone(), fg.clone()], 10, false).map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let bg_gradient = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[white.clone(), bg.clone()], 10, false).map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut("discovered").unwrap();
+ if fg_gradient.is_some() || bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(
+ &[input_symbol.clone()],
+ 5,
+ fg_gradient.as_ref(),
+ bg_gradient.as_ref(),
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ 5,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ } else {
+ let final_fg = self
+ .character_final_color_map
+ .get(&id)
+ .unwrap()
+ .fg_color
+ .clone()
+ .expect("gradient mapping fg");
+ let discovered_gradient =
+ Gradient::with_steps(&[white, final_fg], 10, false).map_err(EngineError::Other)?;
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut("discovered")
+ .unwrap()
+ .apply_gradient_to_symbols(&[input_symbol.clone()], 5, Some(&discovered_gradient), None)
+ .map_err(EngineError::Other)?;
+ }
+ Ok(())
+ }
+
+ /// DecryptIterator.prepare_data_for_type_effect.
+ fn prepare_data_for_type_effect(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for id in characters {
+ let uses_pre = ctx.terminal.arena[id.0 as usize].uses_input_preexisting_colors;
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "typing", uses_pre);
+ }
+ for block_char in ["▉", "▓", "▒", "░"] {
+ let color = ctx.rng.choice(&self.config.ciphertext_colors).clone();
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut("typing")
+ .unwrap()
+ .add_frame(
+ block_char,
+ 2,
+ VisualParams { colors: Some(ColorPair::new(Some(color), None)), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ let symbol = ctx.rng.choice(&self.encrypted_symbols).clone();
+ let color = ctx.rng.choice(&self.config.ciphertext_colors).clone();
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation
+ .scenes
+ .get_mut("typing")
+ .unwrap()
+ .add_frame(
+ &symbol,
+ 1,
+ VisualParams { colors: Some(ColorPair::new(Some(color), None)), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ self.typing_pending_chars.push(id);
+ }
+ Ok(())
+ }
+
+ /// DecryptIterator.prepare_data_for_decrypt_effect.
+ fn prepare_data_for_decrypt_effect(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for id in characters {
+ self.make_decrypting_animation_scenes(ctx, id)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene("fast_decrypt".to_string()),
+ EventAction::ActivateScene("slow_decrypt".to_string()),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene("slow_decrypt".to_string()),
+ EventAction::ActivateScene("discovered".to_string()),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.activate_scene(self, id, "fast_decrypt");
+ self.decrypting_pending_chars.push(id);
+ }
+ Ok(())
+ }
+}
+
+impl EffectHooks for Decrypt {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for Decrypt {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ let final_colors = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ if dynamic {
+ ColorPair::new(ch.animation.input_fg_color.clone(), ch.animation.input_bg_color.clone())
+ } else {
+ ColorPair::new(Some(final_gradient_mapping.get(&ch.input_coord).unwrap().clone()), None)
+ }
+ };
+ self.character_final_color_map.insert(id, final_colors);
+ }
+ self.prepare_data_for_type_effect(ctx)?;
+ self.prepare_data_for_decrypt_effect(ctx)?;
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if self.phase == Phase::Typing {
+ if !self.typing_pending_chars.is_empty() || !ctx.active_characters.is_empty() {
+ if !self.typing_pending_chars.is_empty() && ctx.rng.randint(0, 100) <= 75 {
+ for _ in 0..self.config.typing_speed {
+ if !self.typing_pending_chars.is_empty() {
+ let next_character = self.typing_pending_chars.remove(0);
+ ctx.terminal.set_character_visibility(next_character, true);
+ ctx.activate_scene(self, next_character, "typing");
+ ctx.active_characters.insert(next_character);
+ }
+ }
+ }
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ // Upstream iterates the decrypting_pending_chars set here to
+ // activate "fast_decrypt" (effect_decrypt.py:263) — activation
+ // only mutates each character itself (no handlers registered for
+ // SCENE_ACTIVATED), so order is unobservable; ttfx iterates the
+ // canonical ascending-id order.
+ ctx.active_characters.clear();
+ ctx.active_characters.extend(self.decrypting_pending_chars.iter().copied());
+ let active: Vec = ctx.active_characters.iter().collect();
+ for id in active {
+ ctx.activate_scene(self, id, "fast_decrypt");
+ }
+ self.phase = Phase::Decrypting;
+ }
+
+ if self.phase == Phase::Decrypting {
+ if !ctx.active_characters.is_empty() {
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ return None;
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/errorcorrect.rs b/vendor/ttfx/src/effects/errorcorrect.rs
new file mode 100644
index 0000000..cee14b7
--- /dev/null
+++ b/vendor/ttfx/src/effects/errorcorrect.rs
@@ -0,0 +1,445 @@
+//! errorcorrect, ported from effects/effect_errorcorrect.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{
+ parse_gradient_direction, parse_gradient_steps, parse_positive_float, parse_positive_int,
+};
+use crate::engine::animation::{ExistingColorHandling, SyncMetric, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct ErrorCorrectConfig {
+ /// Percent of characters that are in the wrong position. This is a float between 0 and 1.0.
+ #[arg(long = "error-pairs", default_value_t = 0.1, value_parser = parse_positive_float)]
+ pub error_pairs: f64,
+
+ /// Number of frames between swaps.
+ #[arg(long = "swap-delay", default_value_t = 6, value_parser = parse_positive_int)]
+ pub swap_delay: i64,
+
+ /// Color for the characters that are in the wrong position.
+ #[arg(long = "error-color", default_value = "e74c3c", value_parser = parse_color)]
+ pub error_color: Color,
+
+ /// Color for the characters once corrected, this is a gradient from error-color and fades to final-color.
+ #[arg(long = "correct-color", default_value = "45bf55", value_parser = parse_color)]
+ pub correct_color: Color,
+
+ /// Speed of the characters while moving to the correct position.
+ #[arg(long = "movement-speed", default_value_t = 0.9, value_parser = parse_positive_float)]
+ pub movement_speed: f64,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["8A008A", "00D1FF", "FFFFFF"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "vertical", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+const BLOCK_WIPE_START: [&str; 8] = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+const BLOCK_WIPE_END: [&str; 7] = ["▇", "▆", "▅", "▄", "▃", "▂", "▁"];
+
+pub struct ErrorCorrect {
+ config: ErrorCorrectConfig,
+ swapped: Vec<(CharId, CharId)>,
+ swap_delay: i64,
+ character_final_color_map: HashMap,
+}
+
+impl ErrorCorrect {
+ pub fn new(config: ErrorCorrectConfig) -> Self {
+ ErrorCorrect { config, swapped: Vec::new(), swap_delay: 0, character_final_color_map: HashMap::new() }
+ }
+
+ /// ErrorCorrectIterator._get_dynamic_final_scene.
+ fn get_dynamic_final_scene(&self, ctx: &mut EngineCtx, id: CharId) -> Result {
+ let (input_symbol, input_fg, input_bg, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.input_symbol.clone(),
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ let final_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, None, None, "", uses_pre)
+ };
+ let fg_gradient = match &input_fg {
+ Some(fg) => Some(
+ Gradient::with_steps(&[self.config.correct_color.clone(), fg.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let bg_gradient = match &input_bg {
+ Some(bg) => Some(
+ Gradient::with_steps(&[self.config.correct_color.clone(), bg.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut(&final_scene).unwrap();
+ if fg_gradient.is_some() || bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(&[input_symbol.clone()], 3, fg_gradient.as_ref(), bg_gradient.as_ref())
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(&input_symbol, 3, VisualParams { colors: Some(ColorPair::default()), ..Default::default() })
+ .map_err(EngineError::Other)?;
+ }
+ Ok(final_scene)
+ }
+
+ /// ErrorCorrectIterator._configure_swapped_character.
+ fn configure_swapped_character(
+ &mut self,
+ ctx: &mut EngineCtx,
+ id: CharId,
+ correcting_gradient: &Gradient,
+ ) -> Result<(), EngineError> {
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let (input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.input_symbol.clone(), ch.uses_input_preexisting_colors)
+ };
+ let (first_block_wipe, last_block_wipe) = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let first = ch.animation.new_scene(false, None, None, "", uses_pre);
+ let last = ch.animation.new_scene(false, None, None, "", uses_pre);
+ (first, last)
+ };
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut(&first_block_wipe).unwrap();
+ for block in BLOCK_WIPE_START {
+ scene
+ .add_frame(
+ block,
+ 3,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.error_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ let final_colors = self.character_final_color_map.get(&id).unwrap().clone();
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene = ch.animation.scenes.get_mut(&last_block_wipe).unwrap();
+ if dynamic {
+ for block in &BLOCK_WIPE_END[..BLOCK_WIPE_END.len() - 1] {
+ scene
+ .add_frame(
+ block,
+ 3,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.correct_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ scene
+ .add_frame(
+ BLOCK_WIPE_END[BLOCK_WIPE_END.len() - 1],
+ 3,
+ VisualParams { colors: Some(final_colors), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ } else {
+ for block in BLOCK_WIPE_END {
+ scene
+ .add_frame(
+ block,
+ 3,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.correct_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ }
+ let initial_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(
+ &input_symbol,
+ 1,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.error_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ ctx.activate_scene(self, id, &initial_scene);
+ {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let error_scene = ch.animation.new_scene(false, None, None, "error", uses_pre);
+ let scene = ch.animation.scenes.get_mut(&error_scene).unwrap();
+ for _ in 0..10 {
+ scene
+ .add_frame(
+ "▓",
+ 3,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(self.config.error_color.clone()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ scene
+ .add_frame(
+ &input_symbol,
+ 3,
+ VisualParams {
+ colors: Some(ColorPair::new(Some(Color::from_hex("ffffff").unwrap()), None)),
+ ..Default::default()
+ },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ }
+ let correcting_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, Some(SyncMetric::Distance), None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .apply_gradient_to_symbols(&["█".to_string()], 3, Some(correcting_gradient), None)
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ let final_scene = if dynamic {
+ self.get_dynamic_final_scene(ctx, id)?
+ } else {
+ let final_fg = final_colors_fg(&self.character_final_color_map, id);
+ let char_final_gradient =
+ Gradient::with_steps(&[self.config.correct_color.clone(), final_fg], 10, false)
+ .map_err(EngineError::Other)?;
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .apply_gradient_to_symbols(&[input_symbol.clone()], 3, Some(&char_final_gradient), None)
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene("error".to_string()),
+ EventAction::ActivateScene(first_block_wipe.clone()),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(first_block_wipe.clone()),
+ EventAction::ActivateScene(correcting_scene),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(first_block_wipe),
+ EventAction::ActivatePath("input_coord".to_string()),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::PathActivated,
+ CallerKey::Path("input_coord".to_string()),
+ EventAction::SetLayer(1),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path("input_coord".to_string()),
+ EventAction::SetLayer(0),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path("input_coord".to_string()),
+ EventAction::ActivateScene(last_block_wipe.clone()),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::SceneComplete,
+ CallerKey::Scene(last_block_wipe),
+ EventAction::ActivateScene(final_scene),
+ )
+ .map_err(EngineError::Other)?;
+ Ok(())
+ }
+}
+
+fn final_colors_fg(map: &HashMap, id: CharId) -> Color {
+ map.get(&id).unwrap().fg_color.clone().expect("gradient mapping fg")
+}
+
+impl EffectHooks for ErrorCorrect {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for ErrorCorrect {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for &id in &characters {
+ let final_colors = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ if dynamic {
+ ColorPair::new(ch.animation.input_fg_color.clone(), ch.animation.input_bg_color.clone())
+ } else {
+ ColorPair::new(Some(final_gradient_mapping.get(&ch.input_coord).unwrap().clone()), None)
+ }
+ };
+ self.character_final_color_map.insert(id, final_colors);
+ }
+ for &id in &characters {
+ let spawn_colors = self.character_final_color_map.get(&id).unwrap().clone();
+ let spawn_scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ let uses_pre = ch.uses_input_preexisting_colors;
+ let input_symbol = ch.input_symbol.clone();
+ let scene_id = ch.animation.new_scene(false, None, None, "", uses_pre);
+ ch.animation
+ .scenes
+ .get_mut(&scene_id)
+ .unwrap()
+ .add_frame(&input_symbol, 1, VisualParams { colors: Some(spawn_colors), ..Default::default() })
+ .map_err(EngineError::Other)?;
+ scene_id
+ };
+ ctx.activate_scene(self, id, &spawn_scene);
+ ctx.terminal.set_character_visibility(id, true);
+ }
+
+ let mut all_characters: Vec = ctx.terminal.input_characters.clone();
+ let correcting_gradient = Gradient::with_steps(
+ &[self.config.error_color.clone(), self.config.correct_color.clone()],
+ 10,
+ false,
+ )
+ .map_err(EngineError::Other)?;
+
+ let pair_count = (self.config.error_pairs * characters.len() as f64) as i64;
+ for _ in 0..pair_count {
+ if all_characters.len() < 2 {
+ break;
+ }
+ let index1 = ctx.rng.randrange(0, all_characters.len() as i64) as usize;
+ let char1 = all_characters.remove(index1);
+ let index2 = ctx.rng.randrange(0, all_characters.len() as i64) as usize;
+ let char2 = all_characters.remove(index2);
+ let char1_input_coord = ctx.terminal.arena[char1.0 as usize].input_coord;
+ let char2_input_coord = ctx.terminal.arena[char2.0 as usize].input_coord;
+ {
+ let ch = &mut ctx.terminal.arena[char1.0 as usize];
+ ch.motion.set_coordinate(char2_input_coord);
+ let path_id = ch
+ .motion
+ .new_path(self.config.movement_speed, None, None, 0, false, "input_coord")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(char1_input_coord, None, "")
+ .map_err(EngineError::Other)?;
+ }
+ {
+ let ch = &mut ctx.terminal.arena[char2.0 as usize];
+ ch.motion.set_coordinate(char1_input_coord);
+ let path_id = ch
+ .motion
+ .new_path(self.config.movement_speed, None, None, 0, false, "input_coord")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(char2_input_coord, None, "")
+ .map_err(EngineError::Other)?;
+ }
+ self.swapped.push((char1, char2));
+ for id in [char1, char2] {
+ self.configure_swapped_character(ctx, id, &correcting_gradient)?;
+ }
+ }
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !self.swapped.is_empty() && self.swap_delay == 0 {
+ let (char1, char2) = self.swapped.remove(0);
+ for id in [char1, char2] {
+ ctx.activate_scene(self, id, "error");
+ ctx.active_characters.insert(id);
+ }
+ self.swap_delay = self.config.swap_delay;
+ } else if self.swap_delay != 0 {
+ self.swap_delay -= 1;
+ }
+ if !ctx.active_characters.is_empty() {
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/expand.rs b/vendor/ttfx/src/effects/expand.rs
new file mode 100644
index 0000000..a6d87c4
--- /dev/null
+++ b/vendor/ttfx/src/effects/expand.rs
@@ -0,0 +1,202 @@
+//! expand, ported from effects/effect_expand.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{parse_easing, parse_gradient_direction, parse_gradient_steps, parse_positive_float};
+use crate::engine::animation::{ExistingColorHandling, SyncMetric, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::easing::Easing;
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+
+#[derive(Args, Debug, Clone)]
+pub struct ExpandConfig {
+ /// Easing function to use for character movement.
+ #[arg(long = "expand-easing", default_value = "in_out_quart", value_parser = parse_easing)]
+ pub expand_easing: Easing,
+
+ /// Movement speed of the characters.
+ #[arg(long = "movement-speed", default_value_t = 0.35, value_parser = parse_positive_float)]
+ pub movement_speed: f64,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["8A008A", "00D1FF", "FFFFFF"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec,
+
+ /// Direction of the final gradient.
+ #[arg(long = "final-gradient-direction", default_value = "vertical", value_parser = parse_gradient_direction)]
+ pub final_gradient_direction: GradientDirection,
+}
+
+pub struct Expand {
+ config: ExpandConfig,
+ character_final_color_map: HashMap,
+}
+
+impl Expand {
+ pub fn new(config: ExpandConfig) -> Self {
+ Expand { config, character_final_color_map: HashMap::new() }
+ }
+}
+
+impl EffectHooks for Expand {
+ fn dispatch_callback(&mut self, _ctx: &mut EngineCtx, _character: CharId, _callback: &EffectCallback) {}
+}
+
+impl Effect for Expand {
+ fn build(&mut self, ctx: &mut EngineCtx) -> Result<(), EngineError> {
+ let final_gradient =
+ Gradient::new(&self.config.final_gradient_stops, &self.config.final_gradient_steps, false, false)
+ .map_err(EngineError::Other)?;
+ let final_gradient_mapping = final_gradient
+ .build_coordinate_color_mapping(
+ ctx.terminal.canvas.text_bottom,
+ ctx.terminal.canvas.text_top,
+ ctx.terminal.canvas.text_left,
+ ctx.terminal.canvas.text_right,
+ self.config.final_gradient_direction,
+ )
+ .map_err(EngineError::Other)?;
+
+ let dynamic = ctx.terminal.config.existing_color_handling == ExistingColorHandling::Dynamic;
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for id in characters {
+ let (input_fg, input_bg, input_coord) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (ch.animation.input_fg_color.clone(), ch.animation.input_bg_color.clone(), ch.input_coord)
+ };
+ let final_colors = if dynamic {
+ ColorPair::new(input_fg, input_bg)
+ } else {
+ ColorPair::new(Some(final_gradient_mapping.get(&input_coord).unwrap().clone()), None)
+ };
+ self.character_final_color_map.insert(id, final_colors);
+ }
+ let characters = {
+ let filter = CharacterFilter::default();
+ ctx.terminal.get_characters(&mut ctx.rng, filter, CharacterSort::TopToBottomLeftToRight)
+ };
+ for id in characters {
+ let (input_fg, input_bg, input_coord, input_symbol, uses_pre) = {
+ let ch = &ctx.terminal.arena[id.0 as usize];
+ (
+ ch.animation.input_fg_color.clone(),
+ ch.animation.input_bg_color.clone(),
+ ch.input_coord,
+ ch.input_symbol.clone(),
+ ch.uses_input_preexisting_colors,
+ )
+ };
+ let center = ctx.terminal.canvas.center;
+ let input_coord_path = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.motion.set_coordinate(center);
+ let path_id = ch
+ .motion
+ .new_path(self.config.movement_speed, Some(self.config.expand_easing), None, 0, false, "")
+ .map_err(EngineError::Other)?;
+ ch.motion
+ .paths
+ .get_mut(&path_id)
+ .unwrap()
+ .new_waypoint(input_coord, None, "")
+ .map_err(EngineError::Other)?;
+ path_id
+ };
+ ctx.terminal.set_character_visibility(id, true);
+ ctx.active_characters.insert(id);
+ ctx.register_event(
+ id,
+ Event::PathActivated,
+ CallerKey::Path(input_coord_path.clone()),
+ EventAction::SetLayer(1),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.register_event(
+ id,
+ Event::PathComplete,
+ CallerKey::Path(input_coord_path.clone()),
+ EventAction::SetLayer(0),
+ )
+ .map_err(EngineError::Other)?;
+ ctx.activate_path(self, id, &input_coord_path);
+ let gradient_scn = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.new_scene(false, Some(SyncMetric::Distance), None, "", uses_pre)
+ };
+ let symbols = vec![input_symbol.clone()];
+ {
+ let scene = {
+ let ch = &mut ctx.terminal.arena[id.0 as usize];
+ ch.animation.scenes.get_mut(&gradient_scn).unwrap()
+ };
+ if dynamic {
+ let fg_gradient = match &input_fg {
+ Some(c) => Some(
+ Gradient::with_steps(&[final_gradient.spectrum[0].clone(), c.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ let bg_gradient = match &input_bg {
+ Some(c) => Some(
+ Gradient::with_steps(&[final_gradient.spectrum[0].clone(), c.clone()], 10, false)
+ .map_err(EngineError::Other)?,
+ ),
+ None => None,
+ };
+ if fg_gradient.is_some() || bg_gradient.is_some() {
+ scene
+ .apply_gradient_to_symbols(&symbols, 1, fg_gradient.as_ref(), bg_gradient.as_ref())
+ .map_err(EngineError::Other)?;
+ } else {
+ scene
+ .add_frame(
+ &input_symbol,
+ 1,
+ VisualParams { colors: Some(ColorPair::default()), ..Default::default() },
+ )
+ .map_err(EngineError::Other)?;
+ }
+ } else {
+ let final_fg = self.character_final_color_map[&id]
+ .fg_color
+ .clone()
+ .expect("gradient mapping fg");
+ let gradient =
+ Gradient::with_steps(&[final_gradient.spectrum[0].clone(), final_fg], 10, false)
+ .map_err(EngineError::Other)?;
+ scene
+ .apply_gradient_to_symbols(&symbols, 5, Some(&gradient), None)
+ .map_err(EngineError::Other)?;
+ }
+ }
+ ctx.activate_scene(self, id, &gradient_scn);
+ }
+ Ok(())
+ }
+
+ fn next_frame(&mut self, ctx: &mut EngineCtx) -> Option {
+ if !ctx.active_characters.is_empty() {
+ ctx.update(self);
+ return Some(ctx.frame());
+ }
+ None
+ }
+}
diff --git a/vendor/ttfx/src/effects/fireworks.rs b/vendor/ttfx/src/effects/fireworks.rs
new file mode 100644
index 0000000..72cd4fa
--- /dev/null
+++ b/vendor/ttfx/src/effects/fireworks.rs
@@ -0,0 +1,421 @@
+//! fireworks, ported from effects/effect_fireworks.py.
+
+use std::collections::HashMap;
+
+use clap::Args;
+
+use crate::cli::parse_color;
+use crate::effects::common::{
+ parse_gradient_direction, parse_gradient_steps, parse_non_negative_int, parse_non_negative_ratio, parse_symbol,
+};
+use crate::engine::animation::{ExistingColorHandling, SyncMetric, VisualParams};
+use crate::engine::character::CharId;
+use crate::engine::ctx::{EffectHooks, EngineCtx};
+use crate::engine::effect::Effect;
+use crate::engine::error::EngineError;
+use crate::engine::events::{CallerKey, EffectCallback, Event, EventAction};
+use crate::engine::terminal::{CharacterFilter, CharacterSort};
+use crate::utils::easing::Easing;
+use crate::utils::geometry::{self, Coord};
+use crate::utils::graphics::{Color, ColorPair, Gradient, GradientDirection};
+use crate::utils::pycompat::{floor_div, round_half_even};
+
+#[derive(Args, Debug, Clone)]
+pub struct FireworksConfig {
+ /// If set, fireworks explode anywhere in the canvas. Otherwise, fireworks explode above highest settled row of text.
+ #[arg(long = "explode-anywhere", default_value_t = false)]
+ pub explode_anywhere: bool,
+
+ /// Space separated list of colors from which firework colors will be randomly selected.
+ #[arg(long = "firework-colors", num_args = 1.., value_parser = parse_color,
+ default_values = ["88F7E2", "44D492", "F5EB67", "FFA15C", "FA233E"])]
+ pub firework_colors: Vec,
+
+ /// Symbol to use for the firework shell.
+ #[arg(long = "firework-symbol", default_value = "o", value_parser = parse_symbol)]
+ pub firework_symbol: String,
+
+ /// Percent of total characters in each firework shell.
+ #[arg(long = "firework-volume", default_value_t = 0.05, value_parser = parse_non_negative_ratio)]
+ pub firework_volume: f64,
+
+ /// Number of frames to wait between launching each firework shell. +/- 0-50 percent randomness is applied to this value.
+ #[arg(long = "launch-delay", default_value_t = 45, value_parser = parse_non_negative_int)]
+ pub launch_delay: i64,
+
+ /// Maximum distance from the firework shell origin to the explode waypoint as a percentage of the total canvas width.
+ #[arg(long = "explode-distance", default_value_t = 0.2, value_parser = parse_non_negative_ratio)]
+ pub explode_distance: f64,
+
+ /// Space separated, unquoted, list of colors for the final color gradient.
+ #[arg(long = "final-gradient-stops", num_args = 1.., value_parser = parse_color,
+ default_values = ["8A008A", "00D1FF", "FFFFFF"])]
+ pub final_gradient_stops: Vec,
+
+ /// Number of gradient steps to use.
+ #[arg(long = "final-gradient-steps", num_args = 1.., value_parser = parse_gradient_steps,
+ default_values = ["12"])]
+ pub final_gradient_steps: Vec