Mason Laravel Package

Technical Evaluation

Architecture fit. Mason is an admin-surface dependency, not a platform dependency. It registers as a Filament form field: a Livewire drag-and-drop editor, a sandboxed preview iframe coordinated over postMessage, a PHP brick registry, and a Blade render path driven by @masonStyles / @masonEntryStyles. It owns no models, queues, jobs, APIs, or auth. That yields a clean blast-radius statement for a change board: the integration is confined to Filament panels and to the public Blade templates that render Mason entries. Content persists as structured JSON in an existing column, so backups, replication, and data-tier risk are unchanged — there is no schema migration in this release.

Verification task before any estimate is socialized. The supplied description describes a responsive masonry CSS/Blade layout component — columns, breakpoints, gaps, "no frontend dependencies" — while the release notes and prior assessments describe a block-based page/document builder field for Filament with bricks, previews, and an iframe. Same repository, materially different products and effort profiles. Compounding this, the "last release" field is dated in the future and reads as metadata noise. Treat every package fact as unconfirmed until we have reproduced it against an installed 3.6.0 artifact: a Mason::make('content') field rendering in a Filament form, one brick class registered, and one entry rendered front-end. That is a two-hour spike and the highest-leverage risk reduction in the plan. Commit no estimate before it closes.

Integration feasibility. Low engineering lift assuming a Filament codebase: Composer constraint bump, service provider and panel plugin registration, asset publish. The API surface is additive — no removals, no config churn, no transitive dependency surprises. The honest sizing is half a day of engineering plus a change-management exercise; engineering is not the critical path. The deployment steps and the brick audit are.

Technical risk, ranked for the register.

Key questions to force decisions.

• Which Filament major are we on, and does Mason's 3.x constraint actually resolve against it in composer why-not?
• Does our deploy pipeline demonstrably run php artisan filament:assets, and can we produce the log line on demand?
• Do we have any brick (or any planned brick) that uses $data === null as an editor sentinel? If unknown, assume yes.
• What is our raw-HTML policy for bricks, and who signs off on sanitization?
• Is the near-term need structured repeatable blocks or simple rich text? A Tiptap/ProseMirror field is cheaper if it is the latter.
• Are we willing to own the content API, search indexing, and multi-channel delivery ourselves? Mason is server-rendered Blade-oriented; it is not headless.
• Who is the named internal owner of this dependency for the next four quarters?

Integration Approach

Stack fit. Non-negotiable: Laravel + Filament + Livewire with an existing admin panel. Mason is a Filament form component; outside Filament it is not the package. Adjacent requirements are modest — a Blade front-end for published output, Tailwind-friendly styling, and a build step we already own. The buy case is strongest where content is structured and repeatable (heroes, CTAs, media galleries, testimonial rows, product detail sections, help-center documents) rather than free-form prose.

Migration path. Two distinct paths, and the plan should separate them.

1. Greenfield fields — attach the field to a new JSON column and ship. Near-zero data risk, fastest value, recommended for the first production field.
2. Existing content — moving current rich-text or HTML blobs into bricks is a content migration with a mapping decision, not a package concern. Scope it separately, behind the greenfield success, and estimate it as its own work item. Do not let it ride along on the dependency upgrade; conflating the two is how a half-day change becomes a quarter.

Compatibility. Pin to a Filament major explicitly. Mason is community-maintained: no vendor SLA, no guaranteed backports of security fixes to older minors. Adopt a standing policy of staying on the newest 3.x minor rather than freezing a version, because the security remediation path is forward. Track that previewData() is opt-in per field and fields without it behave exactly as before — this is what makes incremental adoption safe.

Sequencing — gates, in order, each with an exit criterion.

1. Artifact verification spike (2h). Exit: field renders, brick registers, entry renders front-end on 3.6.0.
2. Pipeline proof (half day, staging). Exit: filament:assets evidenced in build log; a deliberately stale asset is demonstrably replaced.
3. Dependency bump + release (half day). Composer bump → filament:assets → view:clear, in that order. No feature flag required; ship with the next regular deploy. Exit: spot-check one multi-brick page preview and published entry styles on staging.
4. Brick audit (per-brick, parallel). Exit: written confirmation that no brick depends on the $data === null sentinel.
5. previewData() enablement (incremental). Start with one field whose preview is visibly wrong today — the locale case is the reference implementation — sourced from the saved record, allow-listed fields only.

Steps 1–3 are the release. Steps 4–5 are a capability rollout and should be tracked as a separate workstream with its own owner.

Operational Impact

Maintenance. Single maintainer, MIT, modest star count, zero dependent packages — the ecosystem signal is thin. Nothing here disqualifies adoption on an admin surface, but it does mean we carry the relationship: assign a named owner, pin the Filament major, review release notes on every 3.x minor, and budget a recurring allowance (a few hours per quarter) for upgrade-and-verify. The upside is real: the @masonStyles / @masonEntryStyles render-time fix in #74 permanently retires the "clear your view cache after a Mason upgrade" ticket class, which on a portfolio of Filament apps is a genuine recurring support cost removed.

Support. Expect the internal support burden to land on brick authoring, not on the package. Tier 1 is our own team: the security page is now citable as the normative trust-boundary document ("Mason trusts its signed render context and its own configuration; brick authors must treat brick configuration as untrusted input"), so the answer to "who sanitizes this?" is a documented policy rather than an escalation. Every roadmap item that lets a non-engineer author block settings, embed URLs, or raw HTML must carry a sanitization acceptance criterion — write that into the definition of done now, not after the first incident.

Scaling. Server-side rendering of published entries is Blade and scales like any other Blade template; no new runtime infrastructure. The scaling question lives in the editor: Livewire round-trips, preview iframe rendering, and JSON payload size as a page accumulates bricks. Instrument one realistically large page (say 30+ bricks) in staging and record editor responsiveness before declaring the field production-ready. previewData() payloads should stay small — they ride in the signed render context to the browser.

Failure modes to pre-write runbook entries for.

• Patched backend, vulnerable browser bundle — Composer shows the fix, the vulnerability is live. Detection: build-log check for filament:assets. This is the one that fails silently and misleads a security review.
• Stale compiled views — styles do not update post-deploy. Remedy: one-time artisan view:clear.
• Silent preview misrender — a brick's null-sentinel logic misfires once previewData() is enabled. No exception, no log. Detection: only the brick audit and visual QA of representative pages.
• Data over-sharing — an engineer passes model attributes into previewData() and exposes fields to anyone reaching the editor. Detection: code review against an allow-list.
• Upstream abandonment — no backports, no SLA. Mitigation: fork readiness is credible here because bricks are our PHP and our Blade views; the vendor-code surface we would inherit is the editor component and the render path. Note that as a risk-acceptance rationale, not a plan.

Ramp-up. Engineer-facing package; bricks are code. Budget roughly one day of onboarding per engineer who will author bricks — a typed brick class plus a Blade view is learnable quickly. The two rules to teach on day one: treat brick configuration as untrusted input (escape and sanitize in your view), and never use a null check to detect editor context once previewData() is in play. Product and content stakeholders need no Mason training; they need a fixed menu of block types and a content-design conversation about which blocks exist, which is our work. The ramp-up line item most likely to be underestimated is not engineering hours — it is the editorial change-management of moving authors from free-form fields to a block menu.