Mason Laravel Package

Product Decisions This Supports

• Build vs. buy on the authoring surface. Mason provides the block editor inside a Filament panel — drag-and-drop canvas, per-brick config forms, sandboxed preview iframe, and server-side Blade rendering for published output. That is the expensive half of a page-builder build, replaced by an MIT Composer dependency. The decision is really "who owns the block menu and the brick views" and the answer stays with us: bricks are typed PHP classes with our Blade templates, not a vendor's proprietary format.
• Roadmap: localized and tenant-scoped content. previewData() (3.6.0) lets a field hand each brick JSON context during editing — the reference case being the edited record's locale so locale-dependent bricks preview correctly. That converts "localized landing pages," "per-tenant blocks," and "campaign defaults" from a bespoke preview build into a field configuration line. This is the single most roadmap-relevant item in the release.
• Feature sizing: preview fidelity is now a config change, not a sprint. Bricks previously got null in preview toHtml(). Any preview-accuracy work that was descoped or estimated as engineering can be re-estimated as a one-line change per field. Worth revisiting the backlog for items that were parked for this reason alone.
• Security posture as a scoping input, not a closing checklist. The new security page defines the trust boundary normatively: Mason trusts its signed render context and its own config; brick authors must treat brick configuration as untrusted input. Every roadmap item that lets non-engineers set embed URLs, raw HTML, or arbitrary links inherits an obligation that lands on our code. Put sanitization in the story's acceptance criteria, not in the retro.
• Unblocking share and reviewer surfaces. The iframe message-origin fix closes a cross-window command path into the editor. If the roadmap has reviewer previews, share links, or "open preview in a new tab," that path is now safe to pursue rather than blocked behind a security review.
• Platform cost across a portfolio of Filament apps. Render-time style resolution for @masonStyles / @masonEntryStyles removes the recurring "clear your view cache after upgrading Mason" support ticket — small per instance, real at portfolio scale.
• Representative use cases: marketing landing pages, CMS articles with mixed media, help-center documents, product-detail sections — anything composed from a fixed, curated menu of block types. Not an open canvas for arbitrary layout.
• One decision-blocking caveat: the one-line repository description reads as a CSS masonry-grid layout component; the package and release notes describe a block-based page/document builder. Those are different products with different effort profiles. Confirm against the installed artifact — a Mason::make('content') field rendering in a Filament form, a brick registered, an entry rendered front-end — before any estimate goes to a steering committee. This is a two-hour spike and the cheapest risk reduction available.

When to Consider This Package

Adopt when:

• We are on Laravel + Filament + Livewire with an existing admin panel. Mason is a Filament form field; outside Filament this is not the product.
• Content is structured and per-record, and we want each block type to be first-class PHP owned by our team — a brick class plus our Blade view — rather than a serialized HTML blob or a closed vendor format.
• Previews need record context (locale, tenant, campaign) to be credible to editors, which previewData() now supplies.
• We accept that brick configuration is untrusted input and will own escaping, sanitization, and raw-HTML policy in our own brick views.
• The deploy pipeline reliably runs php artisan filament:assets (typically via filament:upgrade in Composer's post-autoload-dump) and can run php artisan view:clear once. Verify this empirically against a staging artifact — do not infer from the Dockerfile.

Look elsewhere when:

• The requirement is a SaaS page builder for non-technical marketers — stock templates, A/B testing, hosted previews. Mason is developer-facing; every new block is a code change and a deploy.
• We are not on Filament, or are pinned to an older Filament major.
• Content is simple rich text. A Tiptap/ProseMirror field is cheaper to build, cheaper to maintain, and less to explain to editors than a block system.
• The target is headless, API-first delivery with strict schema contracts. Mason is oriented around server-rendered Blade; a content API would have to be built around it, not by it.
• We require a vendor SLA or guaranteed backports of security fixes to older minors. MIT, ~249 stars, zero dependents, single maintainer — acceptable for an admin-surface dependency with a pinning policy, not acceptable as a platform dependency. Budget for reading changelogs and tracking security pages ourselves.
• The organization has deliberately kept the admin thin and does not want a full editor UI in scope.

How to Pitch It (Stakeholders)

To executives: Mason is our content-editing layer — the drag-and-drop block builder plus the server-side rendering of published pages. Buying it instead of building avoids roughly an engineering quarter and gives us a maintained editor rather than an internal one we staff indefinitely. v3.6.0 is additive: no breaking API changes, no schema or data migration, two artisan commands at deploy. It ships a genuine security remediation and, for the first time, published security documentation — which materially shortens a security review. It also unlocks localized and per-tenant previews that were previously a bespoke build. The trade is a small, single-maintainer community dependency on the admin surface only; it does not touch data models, APIs, auth, or the storage tier, so blast radius is confined to Filament panels and our own templates.

To engineering: Small upgrade with one non-negotiable step. Bump the Composer constraint, run php artisan filament:assets — mandatory, because the cross-window message-origin fix ships in the browser bundle, so skipping it leaves the vulnerability live while the lockfile says "patched" — then php artisan view:clear once so compiled views pick up render-time style resolution. New capability is opt-in per field: previewData(fn (?Model $record) => [...]) passes JSON-serializable context into brick previews. Two rules: source it from the saved record, not a live form field (the editor reads it once, so unstable payloads produce confusing previews), and never put secrets in it — it travels in the signed render context to the browser. One behavioral caveat: bricks that detected "am I in the editor?" via $data === null must switch to inspecting the data once their field supplies previewData(). That is a silent rendering bug, not a compile error. Audit bricks before enabling the feature; fields without previewData() behave exactly as before. Treat a missing filament:assets in the deploy log as a failed release.

To security and compliance: The editor and its preview iframe now accept messages only from each other, closing a cross-window command path present through 3.5.3. The new security page defines the trust boundary normatively — Mason trusts its signed render context and its own configuration; brick authors must treat brick configuration as untrusted input. Cite that page in the threat model, and confirm our custom bricks sanitize and escape their output: that obligation is ours, not the package's. Note that the mitigation only reaches users after the asset republish — verify the build artifact, not just the Composer lockfile.

Rollout recommendation: No feature flag required. Ship with the next regular deploy in this order — Composer bump → filament:assets → view:clear — with the asset step verified in the build log. Spot-check one multi-brick page preview and published entry styles. Adopt previewData() incrementally afterward, starting with a field whose preview is visibly wrong today (the locale case is the reference implementation), once we have confirmed no bricks depend on the $data === null sentinel.