Braid Laravel Package

Getting Started

This assessment reflects v0.1.1. The release is additive — a new moving-ruler UI affordance, a "note presence" filter, and Shiki optimisations — so there is no migration work if you are already on 0.1.0. If you are adopting now, start on ^0.1.1 and lock the minor: this is a pre-1.0 package and the surface area is still moving.

Minimal steps:

1. composer require <vendor>/<package>:^0.1.1 and commit the lock file.
2. Publish config and front-end assets: php artisan vendor:publish --tag=<package>-config and the matching assets tag. Shiki output is generated/pre-rendered, so assets must be re-published after every upgrade — not just on first install.
3. Run php artisan config:clear (and view:clear) immediately after publishing. Stale cached config is the single most common "the new option does nothing" cause.
4. Read, in this order: the published config file (highlighter theme, ruler defaults), the package's Blade component / view namespace, and any migrations if notes are persisted rather than passed inline.

First use case worth building: a documentation or onboarding page where a code sample is rendered through the package with per-line notes, and the surrounding list is filtered to only examples that actually carry notes. That exercises highlighting, annotations, and the new filter in one screen — and it is the shape most teams ship first.

Implementation Patterns

Annotated code samples. Keep notes as data (array keyed by line number, a translatable file, or a related model), not as hand-written HTML. The package renders the code; you own the source of truth for the annotations. This keeps the sample copy-pasteable — readers can lift the raw snippet without dragging comment noise along.

Filter by note presence. Use this to build "annotated examples only" views, coverage dashboards, or to gate a docs index. Push it into the query layer rather than filtering a hydrated collection in PHP:

$examples = Example::query()
    ->withNotes()          // or ->whereHas('notes')
    ->latest()
    ->paginate(20);

If the package exposes it as a scope, prefer the scope over hand-rolled whereHas — the definition of "has a note" (published? visible? non-empty body?) belongs to the package, not to your controller.

Pre-render Shiki, don't highlight per request. v0.1.1 optimises the Shiki integration, which is a hint about where the cost lives: highlighting is a build/deploy-time concern. Render to cached HTML (a code_html column, a cache key, or a build step) and echo it. Per-request highlighting on a docs index with 30 snippets will show up in your TTFB.

Moving ruler as a presentational contract. Treat the ruler as a display guide for the reader, configured once at the component or config level. If you actually care about line length, enforce it in CI with Pint/PHPCS or a formatter — the ruler is a hint, not a validator.

Integration workflow. Author in Markdown or a model, sync notes in a seeder/import command, assert rendering in a feature test that snapshots the generated HTML. A tiny snapshot test catches almost all Shiki and view-override regressions on upgrade.

Gotchas and Tips

• Pre-1.0 churn. At 0.1.x, a patch bump can rename an option. Read the diff of the published config on every upgrade (git diff against your committed copy), not just the release notes.
• Shiki upgrades invalidate rendered output. The optimised highlighter in 0.1.1 can change generated markup — class names, inline styles, wrapper elements. If you cache highlighted HTML, bust it as part of the deploy, and if you snapshot-test it, expect to re-approve snapshots once. Do not assume your CSS survived.
• Re-publish assets after upgrade. Upgrading the composer package alone leaves the old Shiki bundle in public/. Re-run the publish command, then hard-refresh when checking locally.
• "Note presence" semantics. Confirm whether the filter counts all notes or only visible/published ones before you build a public index on it — an empty-note record can flip an example into the filtered set unexpectedly. Write one test asserting the boundary case.
• N+1 on notes. Eager-load notes whenever you render a list with annotations. The filter makes it easy to build a query that returns the right rows but lazy-loads a relation per item in the view.
• Ruler is client-side only. It does nothing for stored content, API responses, or PDF/email output. Don't build validation around it.
• Debugging order. Config cache → published assets → rendered HTML (dump() the component output before the Blade layout mangles it) → package version in composer.lock. Skipping straight to the package source is usually wasted effort at 0.1.x.
• Extension points worth knowing now. Custom Shiki themes, view overrides via the package's namespace, and the note renderer. Overriding views is fine; patching the package in vendor/ is not — it will be overwritten by the next 0.1.x release, and there will be a next one soon.