MFCMouseEffect makes mouse input visible and lets WASM plugins draw it

Five effect channels rather than a cursor skin

The README makes a point of the distinction that the effects are not a reskin. There are five independent effect channels, and they are click, trail, scroll, hold and hover. Each of those is a separate capability with its own settings rather than a variation on one visual.

In practice that means a click ripple, a particle trail behind the pointer, feedback when the wheel turns, a charging effect during a long press, and a glow on hover. Each is separately configurable, and the settings live in a web interface that the README describes as shared across platforms, with a unified configuration path, state synchronisation, and settings that can be adjusted and rolled back.

The audience is stated in the README as creators making recordings, tutorials or live demonstrations, and also as developers who want to bring WASM extension into a C++ host. That second group is the more unusual one, and the design decisions that follow from it are the ones worth understanding before you install anything.

The project is a C++ application with a Svelte based web settings interface, published under the MIT licence, and it describes itself as extensible and plugin driven with WASM support. There is also a mouse companion feature, a desktop pet that follows the cursor, which the README presents as a plugin-first direction rather than a finished feature.

The host owns the rendering, the plugin owns the logic

The architecture section of the README states the rule plainly: the host controls the rendering boundary, plugins only do logic computation, and the host owns render execution, budget validation, fallback and resource control.

That division is the whole design. A plugin never draws. It receives input state, decides what should appear, and emits commands, and the host decides whether to execute them, whether the frame budget allows them, and what to fall back to when something goes wrong. The README lists the module layering as Core, Platform, Server, WebUI, Tools and Docs, each with its own responsibility, and describes extension as progressive, with built-in effects working, WASM plugins layered on top, and a native fallback underneath.

The WASM surface has two kinds of plugin, `effects` and `indicator`, and the runtime handles manifest loading, reloading, importing and exporting. It also does budget control, command validation, error codes and stage diagnostics, and it distinguishes transient from retained rendering semantics, which is the difference between something that appears and disappears and something that stays.

The command vocabulary is concrete enough to be useful, with primitives for spawning text, images, pulses, polylines, ribbon strips and batches of glow. A plugin template ships in the examples directory, and the README links both a route document for custom effects and an ABI design document for version 3 of the plugin interface.

The separation matters for a specific reason. Because the host validates and budgets, a plugin cannot be the reason the application stutters, and a plugin that throws produces a diagnostic rather than a frozen UI. That is a better contract than handing a scripting runtime the whole screen.

Indicators and automation mapping turn visuals into input

The keyboard and mouse indicator is the feature that goes beyond decoration, and the README describes it in a way that explains the design.

The indicator shows mouse clicks, scroll direction and keyboard combinations together, so that information like a repeated left click, a key plus a triple click, or a command tab shortcut becomes visible at a glance. The README's argument is that in a recording or a demonstration the audience can then see not just where the pointer is but what was pressed, what was switched, and what was triggered.

The automation mapping is the second half, and it is where input feedback stops being a display layer. The current support covers mapping mouse actions, the wheel and gestures onto hotkeys, delays, URLs and application launch actions. The README is explicit that fuller scripting, profiles and advanced action chains are on the roadmap rather than shipped, and the contributing table points at a separate automation notes document for that direction.

So the current state is a real mapping engine with a bounded action set, and an explicit plan to widen it. That distinction matters when you are deciding whether a workflow you have in mind is possible now or only later.

The indicator itself is also a plugin surface. The contributing table lists visualisation, layout and WASM indicator work under the same heading as the effects, which means the overlay system and the effect system share the host, the budget model and the plugin ABI.

The build is platform owned, and the Makefile says so

There is no single cross-platform build command, and the Makefile is explicit about that. The build target dispatches on the operating system name, sending a Darwin host to the macOS build, and a MinGW, MSYS or Cygwin host to the Windows build, and failing with a message that build is supported on macOS or Windows and that make test or make check should be used on other hosts.

The targets themselves are thin wrappers around scripts in the tools directory.

.PHONY: help build build-macos build-windows test test-webui check check-docs package package-macos package-windows audit

build-macos:
	@bash ./tools/platform/build/build-macos-project.sh $(ARGS)

build-windows:
	@bash ./tools/platform/build/build-windows-project.sh $(ARGS)

There is a `make test` for the canonical POSIX regression suite, a `make test-webui` for the WebUI model and dev-contract tests, a `make check` that runs the documentation checks, the WebUI tests and the POSIX regression together, and a `make audit` for non-mutating repository audit prerequisites. Options are passed through with `ARGS`, and the README's own example for the macOS build shows the same mechanism with a flag to skip rebuilding the web interface.

The Windows path is different again, and the README recommends opening the solution file in a recent Visual Studio and building the Release x64 configuration, with a command script offered as the alternative for a build, a shipping build and a packaging run. The `mfx` script on the macOS side offers the same verbs, including a run that skips the build and one that exits automatically after a fixed number of seconds for a quick check.

The project root carries both `mfx` and `mfx.cmd` wrappers, a `build.bat`, an `Install/` directory and a `Makefile`, which is what a three platform project with two native toolchains looks like in practice.

Windows stable, macOS in development, Linux following

The platform status table in the README is the clearest statement of where the project actually stands, and it is not a list of equal support.

Windows 10 and later is the stable main line with the most complete set of capabilities and a compatibility regression suite. macOS is the primary development line and the current priority for investment. Linux follows, with compile gating and contract regression.

The README states the current rhythm as macOS mainline first, while requiring that Windows behaviour does not regress. So a change that fixes something on macOS is expected to keep the Windows path working, which is a stricter requirement than it sounds when the two platforms have different input capture models and different overlay mechanisms.

That has a direct consequence for the macOS user, and the README flags it: macOS requires Accessibility and Input Monitoring permissions to capture global input. Those are the two system permissions macOS gates synthetic input and global event capture behind, and a user who has not granted them gets an application that appears to do nothing.

The privacy angle is handled with some care for a program that watches every mouse and keyboard event. The repository carries both an English and a Chinese privacy policy at the top level, and the README links the Chinese one in its navigation. For an application that sits in the input path of every machine it is installed on, that document is part of the product, not an afterthought.

A 1.x project where the newest release is older than the last commit

The maintenance picture is the last thing to weigh.

The recent releases are v1.2.2 on 2026-02-08, v1.3.0 on 2026-02-14 and v1.3.1 on 2026-03-20, with the release notes describing the work in each. The macOS support, the plugin support for effects, the keyboard and mouse indicator and the gesture to hotkey mapping all appear in the v1.3.x notes, and v1.3.0 also added GPU support through a cross platform graphics layer, fixed a trail latency problem, added a text size setting, fixed a DPI misalignment bug and addressed effects stopping inside virtual machines.

Those release notes are unusually specific for a 1.x project, and they read like the log of someone fixing the things that break on a second platform. The DPI fix and the virtual machine fix are the kind of bugs that only appear once an effect is drawn on a scaled display or inside a guest system.

The last push was on 2026-07-26, so work continued after the last published tag, and the repository is not archived. The gap between the newest release and the last push is the thing to keep in mind: the release page is where you get a build, and the main branch is where the work is, and for a project whose development focus is macOS those two can differ for months.

The licence is MIT, the primary language is C++, and the contributing table is unusually well organised for a project this size, with separate entries for mouse effects, automation mapping, the indicator, the mouse companion, WASM plugins, the web settings, cross platform alignment between Windows and macOS, and documentation and testing. The recommended flow is to open an issue first, discuss the direction, then submit a pull request, with an email contact for large or architectural changes.

Editorial conclusion

MFCMouseEffect fits a creator who records or presents and wants the audience to see clicks, scroll direction and key combinations, and a C++ developer who wants a documented WASM plugin surface rather than a closed effect system. Skip it if you only want a cursor highlighter on one platform, since the build is not a single cross-platform command, or if you cannot grant macOS accessibility permissions. Verify first which host platform you are on and which release line you need, since the newest published release is older than the last push, and read the ABI document before writing a plugin.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sqmw/MFCMouseEffect on GitHub