Tether

Tether is a cross-platform desktop physics toy that turns your desktop into a playground for a tethered, throwable physics object.

Grab it. Throw it. Swing it from its rope, snap it loose, reattach it, or launch it through hoops. Tether runs directly on the desktop rather than inside a conventional game window.

Public demo media is coming soon. The repository intentionally contains no screenshots or recordings from private development sessions; see media/.

What it does

• A simulated object suspended from a physical rope
• Global desktop grabbing and throwing
• Rope snapping and interactive reattachment
• Click and held-click Shockwaves
• Configurable wall, ceiling, and floor collision boundaries
• Multiple object shapes and color schemes
• A rotating wireframe tesseract
• Hoops, scoring, and lifetime statistics
• Persistent physics and appearance settings
• An optional Anti-touch safety mode with explicit emergency exits

Platforms

	Linux / GNOME	Windows
Runtime	GNOME Shell 50 extension on Wayland	.NET 8 WPF desktop application
Rendering	Shell chrome actors using St, Clutter, and Cairo	Transparent always-on-top WPF overlay
Input	GNOME Shell stage events and pointer polling	Win32 low-level mouse hook, global hotkey, and cursor polling
Settings	GSettings	Versioned JSON in %APPDATA%\Tether
Physics	Original v17 implementation	Behavioral port of the v17 model

The implementations intentionally share behavior rather than source code. Windows separates the portable simulation (Tether.Core) from Win32 integration (Tether.Interop) and the WPF host (Tether.App). Linux executes as shell chrome inside GNOME Shell.

Tether
├── linux/                 GNOME Shell extension and semantic verifier
└── windows/
    ├── Tether.Core/       Simulation, state, scoring, and settings model
    ├── Tether.Interop/    Win32 hooks, hotkeys, monitors, and window styles
    ├── Tether.App/        WPF rendering, lifecycle, tray, and persistence
    └── Tether.Tests/      Deterministic unit and behavioral tests

Controls and safety

On both platforms, primary-button activity produces Shockwaves and secondary-button dragging grabs or throws the object. The anchor can be moved along the top edge, and a detached object can be dragged into the reattachment area.

Anti-touch is deliberately platform-specific:

• Linux: a GNOME Shell shield blocks the pointer/touch events delivered through its active Clutter capture path. Its emergency shortcut and visible exit control are established before the shield.
• Windows: blocks relevant mouse-button and wheel interactions while intentionally permitting cursor movement. Freezing WM_MOUSEMOVE would freeze the Windows system cursor and obstruct the visible exit surface. Direct touch and pen blocking are not claimed. Keyboard input is not generally hooked; the registered emergency hotkey is Ctrl+Alt+Shift+Escape.

Anti-touch should be tested from source or deterministic test seams unless you deliberately intend to exercise global input blocking. Elevated Windows surfaces, secure desktop, and device input below the low-level mouse-hook layer remain platform limitations.

Linux / GNOME

Requirements include GNOME Shell 50, GJS, glib-compile-schemas, Node.js for semantic tests, and standard ZIP tooling.

cd linux
./verify.sh
./install.sh

The installer deploys the extension under its established UUID, tether@natebuildsai.com. On Wayland, log out and back in if GNOME Shell retains an older imported module. Do not use the X11-only Alt+F2, r restart path.

To create a deterministic extension package:

cd linux
./package.sh

The package is written to linux/dist/ and includes Tether's root GPL license.

Windows

Building requires the .NET 8 SDK on Windows.

cd windows
dotnet build Tether.sln -c Release
dotnet test Tether.Tests -c Release
dotnet run --project Tether.App -c Release

Create the supported self-contained, single-file win-x64 distribution with:

dotnet publish Tether.App/Tether.App.csproj -c Release -p:PublishProfile=win-x64 -o publish

Distribute these files together:

• Tether.App.exe
• LICENSE-TETHER.txt
• LICENSE-DOTNET.txt
• THIRD-PARTY-NOTICES-DOTNET.txt

See windows/README.md for component and persistence details.

Verification status

The sanitized public source was verified during repository construction:

• Windows: Release build passed; 143 of 143 tests passed; a fresh self-contained win-x64 single-file publish was verified; the existing non-hook state-dump smoke path exited successfully from an isolated temporary directory.
• Linux: verify.sh passed its semantic and static checks; the Anti-touch teardown fault-injection regression is present; two fresh packages were byte-identical.

The accepted Linux Repair 1 source has not yet been deployed or live-accepted in GNOME Shell. The verification above is source-level and non-disruptive; it is not a claim of post-repair live-desktop acceptance.

License and provenance

Copyright (C) 2026 NateBuildsAI.

Tether is free software licensed under the GNU General Public License, version 3 or later (GPL-3.0-or-later). See LICENSE. Third-party dependencies retain their own licenses; distribution notes are summarized in THIRD_PARTY.md.

See PROVENANCE.md for the origin of this sanitized public source release.