amjadiqbal/laravel-rough-notation
A Laravel package that wraps Rough Notation, making it easy to add hand-drawn style annotations such as underlines, boxes, circles, highlights, brackets, and strike-throughs to text using Blade directives and PHP helpers with configurable animation.
Package shape. A Blade-facing wrapper around Rough Notation, the client-side library that draws hand-drawn SVG annotations over DOM elements. The public surface visible in these release notes is narrow: a @roughNotationScripts directive for injecting the JS, and a data-rough-options attribute on annotated elements that carries per-element JSON configuration. There is no evident persistence, queue, event, or container-binding surface — this is a presentation-layer package.
Architecture fit. Good fit for a standard Laravel app: it defers all rendering work to the browser, composes with the existing Blade + Vite asset pipeline, and has a blast radius measured in "an annotation fails to draw." Nothing here couples to domain logic, so it can be adopted by a single team and removed by deleting one layout line and a set of HTML attributes.
Integration feasibility. Low effort. Composer install, publish assets, add one directive to the base layout, then sprinkle data attributes onto elements you want annotated. Reasonable estimate: half a day for a spike, one to two days to apply consistently across a design system and verify.
Technical risk — governance, not code. The dominant signal in these notes is not the two bug fixes, it's the framing around them. The package shipped on Packagist from February 2026 with no version tag, meaning every consumer has been tracking dev-main — no reproducibility, no semver contract, no changelog discipline. That is now remedied, but adoption should be sized accordingly. The second signal is that the Pest suite already existed and had simply never been run; both defects were caught by executing tests that were sitting there. That tells you the shipped happy path was not exercised end-to-end before release.
The fixes are behavioral changes, not cosmetic ones. (1) data-rough-options was over-escaped, so the attribute read back as HTML entities rather than valid JSON — any consumer for whom this "worked" must have introduced a workaround (pre-escaped JSON, or unescaped Blade output) that will now double-encode or break. (2) @roughNotationScripts failed to compile at all, so the documented usage path was throwing a PHP parse error in any view that used it. A consumer who hit that would have stopped using the directive rather than fixed it — meaning existing installs may have a locally invented alternative in place.
Key questions before adoption.
<script>? If so, what's the CSP story, and is there a nonce/integrity option?aria-hidden, and is there a prefers-reduced-motion path?Stack fit. Sits alongside the existing front-end toolchain without competing with it. It should not be routed through Vite (the directive owns script injection), which means asset fingerprinting, cache busting, and SRI are the package's responsibility rather than your build's — worth confirming, as that's the one place it diverges from house convention.
Compatibility. Verify the claimed Laravel/PHP range against your floor before committing; the package is small enough that an incompatibility is a fork-and-patch afternoon rather than a blocker. No database, no config file beyond asset publishing, no migration.
Migration path for existing dev-main consumers.
composer.lock — that is your only baseline, and it is about to be replaced by a tag.roughNotationScripts and data-rough-options, and specifically audit for workarounds: pre-escaped entities in the attribute, {!! !!} unescaped output, hand-rolled script includes that bypass the directive, or a locally written replacement for the broken directive.^1.0.0, run your own test suite, then visually diff every annotated page side by side against the pre-upgrade build.@roughNotationScripts and a data-rough-options attribute, then asserts the attribute value decodes as JSON. That is precisely the pair of failures their suite missed, and it costs an hour.Fresh adoption path. composer require, publish assets, place the directive near the end of the layout after your script stack, annotate elements, verify options JSON in the browser inspector, confirm annotations draw and survive a client-side navigation.
Sequencing. Because the package is decorative and degrades silently, it does not need a change-freeze slot. Bundle it with a routine front-end release rather than making it its own deployment. Isolate the directive in a single layout partial so removal is one commit, and ship it behind a config flag for the first release cycle so rollback doesn't require a redeploy of templates.
Maintenance. Very low steady state. No server-side runtime, no scheduled work, no migrations, no storage growth. The recurring cost is two things: upstream Rough Notation releases (the JS library's own evolution) and Laravel major-version bumps, both of which are infrequent and cheap to validate given the small surface.
Support. Single maintainer with community contributions. The 1.0.0 tag signals intent to stabilize; the unrun test suite signals the process is still thin. Treat this as a package you should be willing to fork. The scope is small enough that a fork is an afternoon's work, which materially caps the support risk — but decide that deliberately rather than discovering it when a Laravel major lands and the package lags.
Scaling. Effectively zero server-side impact — one static asset and per-element attributes. Client-side, watch the annotated-node count: each annotation instantiates SVG overlays and observers, so pages with hundreds of annotated elements benefit from lazy initialization on visibility or intersection. Serve the asset compressed from your own origin if the package permits, for cache-control and SRI reasons.
Failure modes, roughly in order of severity.
data-rough-options fails to parse, or the script doesn't load, and annotations simply don't draw. Lowest severity, hardest to notice in review.Ramp-up. Hours for any competent Laravel developer — the directive goes in the layout, the attributes go on elements. The only non-obvious knowledge is the options JSON contract and the escaping semantics of the attribute, and the latter is precisely what just changed, so document it in your own onboarding notes rather than pointing people at the README.
Recommendation. Adopt, pinned at ^1.0.0, with low ceremony and a one-commit rollback path. Do not read v1.0.0 as a maturity signal — read it as "the first release that was actually executed." The corrective action isn't to distrust the package, it's to add the compile-and-parse smoke test on your side that would have caught both defects, because your CI is now the only thing standing between a directive regression and a broken page.
How can I help you explore Laravel packages today?