← All libraries

Own your own Scanner instance — no global Manager wiring required. Wrap rendered chunks with invisible Unicode-sentinel markers, scan to discover bounding boxes, then hit-test mouse events. ZoneClickTracker deduplicates Press/Release pairs so each logical click emits once.

Install

composer require sugarcraft/candy-mouse

Quickstart

use SugarCraft\Mouse\Mark;
use SugarCraft\Mouse\Scanner;
use SugarCraft\Mouse\ZoneClickTracker;
use SugarCraft\Mouse\MouseEvent;

// 1. Wrap interactive content with invisible zone markers.
$rendered = Mark::zone('btn-ok', '  OK  ')
              . Mark::zone('btn-cancel', 'Cancel');

// 2. Scan after rendering to populate the zone registry.
$scanner = Scanner::new()->scan($rendered);

// 3. Reverse-lookup on mouse events.
$zone = $scanner->hit($mouseX, $mouseY); // ?Zone

// 4. Deduplicate clicks so each press+release pair emits one click.
$tracker = new ZoneClickTracker();
$result = $tracker->track(new MouseEvent(5, 1, 0, MouseAction::Release));
if ($result !== null) {
    echo "Clicked zone: " . $result->zone->id;
}

What's in the box

Source & demos

• Source on GitHub
• Full README
• Runnable examples
• Inspired by bubblezone (Go upstream)
• bubblezone issue #10 — ZoneClickTracker addresses this gap

Try the quickstart →

API

Class	Method	Description
Mark	::zone(id, content)	Wrap content with invisible sentinel markers
Scanner	::new()	Create empty scanner
Scanner	->scan(rendered)	Parse sentinels, build zone registry
Scanner	->get(id)	Get Zone by id
Scanner	->hit(col, row)	Reverse-lookup Zone at coordinates
Zone	$id	Zone identifier
Zone	$startCol / $startRow / $endCol / $endRow	1-based bounding box
MouseEvent	::press(x, y, button)	Factory for press event
MouseEvent	::release(x, y, button)	Factory for release event
MouseAction	Press / Release / Drag / Scroll	Mouse action enum
ZoneClickTracker	->track(MouseEvent)	Feed event, receive ClickResult or null
ZoneClickTracker	->setPressZone(Zone)	Set zone for pending press (call after track(Press))
ClickResult	$zone / $button	Completed click result

Demos.

VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.