ruelluna/canvas-pointer
A Laravel package that adds an interactive canvas pointer field to forms, letting users click an image to select and store X/Y coordinates. Ideal for image hotspots, annotations, and coordinate pickers.
Architecture fit. This is a Filament form field, not a general-purpose package. Its usefulness is entirely gated on the host application running Filament (v3 or v4) on Laravel with Livewire and Alpine. Where that gate is met, the fit is clean by construction: it participates in the standard form schema lifecycle, hydrates and dehydrates through Livewire state like any other field, and requires no new service, queue worker, or external API. There is no server-side compute, no third-party data processor, and no data egress — the annotation happens in the browser and the result is persisted to a model column. The real architectural question is domain fit: whether the product genuinely needs spatial annotation on a 2D image (floor plans, site surveys, damage/defect marking, photo hotspot tagging, equipment callouts) or whether a simpler structured list of labels would satisfy the requirement at a fraction of the accessibility and maintenance cost.
Integration feasibility. Mechanically straightforward: a Composer require, asset publication (or a registered asset bundle, depending on how the package ships its JS/CSS), and a field declaration in the form schema. The persistence layer is a JSON or text column holding a collection of points, ideally with an Eloquent array cast. A competent Filament developer can produce a working spike in well under a day. The unknowns are all in packaging details rather than architecture: whether prebuilt assets ship with the release or require a Node build, and whether asset registration collides with the host panel's Vite pipeline under Filament v4.
Technical risk. The dominant risk is not technical, it is supply-chain. Twenty-three stars and a single maintainer means a bus factor of one, no backport guarantees, and a realistic chance the package goes stale at the next Filament major. Filament has a history of breaking changes between majors that ripple through custom fields, and a one-person package is the least likely to absorb that quickly. Secondary risks: unknown coordinate semantics (percentage-relative versus absolute pixels, which determines whether data survives responsive rendering and image replacement), unknown test coverage, unverified touch handling on mobile and tablet, and accessibility — a click-to-place-on-image interaction is inherently pointer-only and will not pass WCAG 2.1 keyboard-operability without a fallback input. None of these are blockers; all of them need verification before commitment.
Key questions.
composer.json?Stack fit. Laravel + Filament + Livewire + Alpine + Tailwind. The field adds no runtime dependency beyond what a Filament panel already ships. Image delivery should route through Laravel's storage abstraction so the same code path works on local disk in development and S3 in production; if the package expects a plain public URL, that assumption will need a wrapper to keep signed URLs from expiring mid-session.
Migration path. Add a nullable JSON column for the marker payload and cast it to an array or collection on the model. If a legacy free-text or comma-separated location field exists, run both in parallel for one release: render the new field, backfill from the old format where parseable, and keep the old column read-only until the new field is validated in production. Persist normalized coordinates from day one, even if the package stores pixels — normalize in the model accessor/mutator so a later swap of image resolution or of the field package itself does not invalidate historical data.
Compatibility. Pin the Filament major version in composer.json and confirm the package's declared constraint matches. Verify the PHP and Livewire versions align. Test explicitly against the panel's asset pipeline. If the package requires publishing assets into public/vendor, confirm that survives your deploy strategy (some deployments symlink or prune public/).
Sequencing. (1) Timeboxed spike in a throwaway branch: render the field, place markers, save, reload, confirm hydration. (2) Wrap it in an internal field class that owns the storage format and validation, so the third-party dependency is confined to one file and swappable. (3) Pilot on one low-risk resource with a small group of internal users. (4) Collect mobile and accessibility feedback before broader rollout. (5) Only then deprecate the legacy field. The wrapper in step 2 is the single most valuable piece of engineering here — it converts an abandonment risk into a contained, replaceable detail.
Maintenance. The code surface we own is tiny, which is the package's main operational virtue. The dependency surface we do not own is a single-maintainer project with no release cadence guarantee. Treat it as a tier-3 dependency: track it in the dependency register, subscribe to releases, and budget a small allowance each Filament upgrade cycle to either patch, fork, or absorb the field. Because the scope is a few hundred lines of Alpine and a Blade view, absorbing it internally is a credible exit strategy — that is the mitigation that makes the rest of the risk acceptable.
Support. Community-only: GitHub issues, no SLA, no vendor to escalate to. Name an internal owner for the field. Document the storage format and the wrapper's contract so any team member can debug or replace it without reverse-engineering the package.
Scaling. Server-side cost is effectively zero — annotation is client-only and the payload is a few kilobytes of JSON. The scaling concern is image delivery: large source images served full-size will dominate bandwidth and hurt mobile experience. Plan for a downscaled display image with the original retained separately, served through a CDN. Watch payload growth if marker counts run into the hundreds and the field re-renders on every Livewire round trip.
Failure modes. Coordinate drift when the underlying image is replaced or re-cropped at a different aspect ratio. Silent data loss if the field dehydrates empty on a modal or wizard step transition. Broken rendering after a Filament upgrade or an asset-publish step missed in deployment. Expired S3 URLs breaking the preview mid-edit. Touch events landing between markers on small screens. Complete inaccessibility for keyboard and screen-reader users, which is a compliance issue wherever WCAG or Section 508 obligations apply. Every one of these is detectable with a targeted test or a manual QA script; none require novel mitigation.
Ramp-up. Low for developers already fluent in Filament — an hour to read the wrapper and the package source. Content editors need a short written guide and a note on the image-replacement caveat. The only non-trivial ramp is accessibility: if the product has compliance obligations, plan and budget for a fallback input (a structured list of points with numeric fields) alongside the visual field, and do not treat it as a later enhancement.
How can I help you explore Laravel packages today?