Five core interaction lanes are available:

• click
• trail
• scroll
• hold
• hover

Why it matters:

• these are separate capability lanes, not just cosmetic variants of one effect
• type normalization and config mapping are continuously aligned across Windows and macOS
• settings, tuning, and diagnostics are exposed through WebSettings
• parts of the effect stack can be handed off to WASM plugins

The project also has a dedicated cursor-decoration layer:

• built-in ring / orb decoration
• additive lane independent from the five main effect lanes
• can run as native fallback or a dedicated cursor_decoration WASM lane
• integrated with blacklist policy, fallback control, and plugin state

Input indicator support includes:

• mouse left / right / middle click feedback
• wheel direction and streak labels such as W+ x2
• keyboard labels and combos such as Cmd+Tab
• relative / absolute positioning
• multi-monitor targeting and offsets
• native fallback and WASM indicator routing

Automation mapping is a real product surface, not a side feature:

• mouse button and wheel mappings to shortcuts
• drag gesture recognition with direction chains such as up_right
• configurable trigger button, sample step, stroke threshold, and max segments
• app-scope matching and deterministic priority behavior
• draw-and-save gesture flow plus self-check and regression coverage

This is one of the strongest differentiators of the project:

• separate effects and indicator surfaces
• manifest load, reload, import, and export flows
• budget control, command validation, fallback, and machine-readable diagnostics
• transient and retained rendering semantics
• ABI documentation and a bundled plugin template

Current command coverage already includes high-value primitives such as:

• spawn_text
• spawn_image
• spawn_pulse
• spawn_polyline
• spawn_path_stroke
• spawn_path_fill
• spawn_ribbon_strip
• spawn_glow_batch
• spawn_sprite_batch
• spawn_quad_batch
• retained emitter / trail / quad-field / group primitives

The repo already has a dedicated plugin-management surface:

• unified Plugin Management section
• policy binding for effect lanes, indicator lanes, and cursor-decoration lanes
• manifest path, enabled-state, failure-state, and fallback visibility
• apply flow reflects real backend state instead of only mutating a form

Plugins are a first-class feature. Start here:

• Template: examples/wasm-plugin-template/README.md
• Core doc: docs/architecture/custom-effects-wasm-route.md
• ABI spec: docs/architecture/wasm-plugin-abi-v3-design.md
• Load path: WebSettings Plugin Management -> choose manifest -> Apply

Mouse Companion is one of the most visible active feature directions:

• plugin-first route for long-term extensibility
• macOS currently has a Phase1 visual host
• Windows is on Phase1.5 with renderer seams and runtime diagnostics
• the goal is a sustainable companion architecture, not a one-off pet demo

The current settings UI is organized around focused product areas:

• General
• Mouse Companion
• Cursor Effects
• Input Indicator
• Automation Mapping
• Plugin Management

Benefits:

• cleaner capability boundaries
• backend-state-driven apply behavior
• easier platform reuse, debugging, and future expansion

The structure below is ready for later screenshot replacement.

Module	Preview	Module	Preview
Settings page		Click effect
Trail effect		Scroll effect
Hold effect		Hover effect

More Detail Images (placeholders, expandable)

Scene	Detail Image	Scene	Detail Image
Input Indicator		Automation Mapping
WASM Runtime		Plugin Management
Cursor Decoration		Mouse Companion

This section is intentionally front-loaded to reduce install and first-run friction.

Check system permissions first:

• Accessibility
• Input Monitoring

The macOS runtime depends on those permissions for global input capture.
When permissions are missing, the runtime can degrade gracefully and recover after the permissions are restored.

That is an intentional project policy:

• default is --no-gpu
• it is more stable for the common path
• it avoids extra runtime payload by default
• use ./mfx build --gpu only when you explicitly want that route

Shipping keeps the main runtime and WebUI, but trims deep testing and heavy diagnostics:

• no full /api/test deep test surface
• better for delivery
• not the best target for deepest runtime proof workflows

Not yet.

Linux currently follows the project mainly through:

• compile success
• contract coverage
• structural alignment with the mainline architecture

For the best experience, prefer Windows or macOS.

Many settings are backend-state-driven.
If the backend binding did not actually succeed, the UI will reconcile back to the real runtime state instead of pretending the apply succeeded.

Typical things to check:

• manifest path validity
• whether the target lane is enabled
• platform support for that route
• fallback state and plugin load failures

No.

This is one of the core architecture boundaries:

• plugins compute logic
• the host owns rendering execution, budget checks, fallback, and resources

That constraint is deliberate and central to the project's long-term design.

Yes:

• current macOS packages are unsigned
• Gatekeeper may block first launch
• users may need Finder Open on first run
• notarization is not part of the current packaging path yet

MFCMouseEffect/
├── MFCMouseEffect/
│   ├── MouseFx/                 # Core engine: effects, automation, wasm, diagnostics, server
│   ├── Platform/                # Windows / macOS / Linux implementations
│   ├── WebUIWorkspace/          # Svelte settings UI source
│   ├── Runtime/                 # Runtime resources and dependencies
│   ├── Assets/                  # Companion and visual assets
│   └── WasmRuntimeBridge/       # WASM runtime bridge layer
├── tools/
│   ├── platform/regression/     # Regression scripts
│   ├── platform/manual/         # Manual and self-check helpers
│   └── docs/                    # Doc routing and doc-governance scripts
├── docs/                        # Architecture, roadmap, workflow, issue docs
├── examples/                    # Examples and templates
└── mfx / mfx.cmd                # Preferred command entrypoints

• MouseFx/Core owns semantics and reusable capability contracts
• Platform/windows, Platform/macos, and Platform/linux keep platform code separated
• MouseFx/Server plus WebUIWorkspace form a clear settings-server boundary
• tools/platform/regression and tools/platform/manual make the project verifiable
• docs are maintained as part of the engineering system, not as an afterthought

• Docs overview: docs/README.md
• Chinese docs index: docs/README.zh-CN.md
• Current active context: docs/agent-context/current.md
• macOS mainline snapshot: docs/refactoring/phase-roadmap-macos-m1-status.md
• P2 capability router: docs/agent-context/p2-capability-index.md

Issues, ideas, suggestions, and pull requests are all welcome.

For larger features, architecture changes, or behavior changes across platforms, it is best to align first before implementation so work does not split across conflicting directions.

Recommended flow:

• open an Issue
• discuss the change briefly
• then send a PR
• for larger collaboration or architecture topics, email first

Contact:

• [email protected]

Good contribution areas:

• new visual effects and styles
• WebSettings UX improvements
• WASM plugin samples and tooling
• Windows and macOS behavior alignment
• docs, testing, self-checks, and regression tooling