Block Library Laravel Package

Technical Evaluation

Architecture fit: capell-app/block-library is not a standalone utility — it is the content vocabulary layer of the Capell suite. It ships typed block primitives (Hero, Features, Pricing, FAQ, Accordion, CTA, Comparison, Counter, Divider, Content, Logos, Stats) as Filament Builder classes, Data objects, Actions, and Blade catalog views, declared explicitly as a no-schema-impact package. That last property is the single most important fact for a TPM: the package defines shape and rendering of blocks but delegates persistence to a host package (the docs list this as an acknowledged documentation gap and point to Content Sections and Foundation Theme as siblings). Practically, this means block-library is a contract package, not a storage package. Architectural fit is strong only if we are already committed to Capell + Filament for authoring; it is a poor fit as an isolated "reusable blocks" library in an application with a different admin stack, because the Filament Builder classes and the RegisterBlockDefinitionProviderAction/ResolveBlockDefinitionAction registry are only meaningful inside Capell's builder lifecycle.

Leverage (what a TPM actually gets): three concrete wins, and they should be framed as such in any business case. (1) Build-vs-buy on block components — roughly 12–20 catalog blocks with editor forms, screenshots, and frontend Blade already written, removing a meaningful chunk of bespoke CMS component work from the roadmap. (2) A frozen design-system contract — BlockDefinitionData, BlockVariantData, BlockContentContractData, BlockAccessibilityContractData, and ListBlockDefinitionsAction give us a machine-readable answer to "what blocks exist and what do they accept," which is exactly what a design system needs to stay coherent. (3) Testability hooks — ValidateDefaultBlockCatalogAction, BlockFixtureData, BlockScreenshotData, and BlockLibraryHealthCheck give us an automated gate for catalog integrity and screenshot contract drift. Those three are the reasons the opportunity score exists; the 0 stars / 0 dependents are not.

Integration feasibility: Low mechanical difficulty for a Laravel team already on the Capell foundation bundle: composer require, provider registration, cache clear, verify the admin surface appears. No migrations, no permissions, no routes, no settings, no commands, no queues — an unusually small blast radius for an admin-facing package. The residual cost is content governance, not engineering: which blocks are enabled in the picker, who owns screenshots and accessibility contracts, and who signs off on changes to public Blade output.

Technical risk:

• Maturity/ecosystem risk (high visibility, moderate actual risk): 0 stars, 0 dependents, and a composite score of ~27.9 means there is no external validation signal — no third party has been broken by this package's releases. Our assurance must come from vendor-suite vetting and our own staging render-diff, not from adoption.
• Release-legibility risk (the top operational risk): releases in the provided list are changelog stubs — link only, no described fixes, deprecations, or migration notes. For a package that defines a shared contract consumed by other packages, an undocumented patch bump is an unassessed change, not a low-risk one. The last release date (2026-10-28) also needs confirming against our sourcing pipeline; a future-dated artifact in our inventory is a data-integrity item before it is a dependency item.
• Coupling risk: the registry Actions and AbstractCatalogBuilderBlock base class create compile-time-ish coupling to Capell core and Filament version floors. A floor bump in composer.json is our most likely "routine upgrade" failure.
• Authoring-boundary risk: the package's own pitfalls section flags authoring-markers/model IDs/editor URLs leaking into public Blade and cached HTML. That is a security-relevant regression class, and it is precisely the class that patch notes would normally tell us about.

Key questions:

• Does a sibling package (Content Sections) own block persistence? If not, what writes block content, and who owns that data if we ever leave Capell?
• What are the exact Capell core / Filament / Laravel / PHP constraints, and does adopting this narrow our supported matrix?
• Who internally owns "the block catalog" — product, design, or platform engineering — and is that a named role or an aspiration?
• Which of the 12–20 catalog blocks do we actually enable at launch, and who arbitrates additions?
• Do we have a vendor support commitment and an escalation path for a 0-star, single-vendor package with stub release notes?
• Is the block-library cache tag wired into our invalidation runbook, or is it a surprise at first content change?

Integration Approach

Stack fit: Laravel + Filament + Capell core, on the foundation bundle with Content Sections and Foundation Theme. Verify the PHP/Laravel/Filament floors in the package composer.json against our runtime before anything else — this is the most frequent failure mode on a first install and costs minutes to check. If we are not on Filament, stop: the value collapses to a set of Blade partials and we would be adopting surface area we cannot use.

Migration path: Greenfield is the recommended entry — install, publish config, curate the enabled block set, seed templates, then build pages. Brownfield content migration (existing pages re-expressed in catalog blocks) is a separate, design-led workstream and must not share a change window with the package install. Because the package has no schema impact, the rollback story is clean at the package layer; the risk lives entirely in rendered content fidelity, which is where the render-diff step below earns its keep.

Compatibility: Pin an exact patch version rather than a caret range while release notes remain stubs. This is a deliberate, documented trade: we accept manual bump toil in exchange for not absorbing unreviewed contract changes during a composer update. Revisit the pin after two or three consecutive releases with legible notes, and record that decision so it is not relitigated every quarter. Also pin the sibling packages (Content Sections, Foundation Theme) in lockstep — a split version set across a shared block contract is the failure mode to design out.

Sequencing:

1. Confirm the package artifact and its release date are real and sourced correctly; capture the diff between the current and prior release and classify it (contract change / view change / metadata only).
2. Diff composer.json constraints against our lockfile; escalate any floor change to the platform owner as a gating decision.
3. Install in a staging environment with the sibling packages; register the provider; clear config/route caches; confirm the admin surface and the three documented admin screenshots reproduce.
4. Run a render-diff snapshot across a representative page sample (top-traffic plus one page per block type) and a screenshot-contract check.
5. Exercise the authoring UX — insert, reorder, save, republish — since catalog-block regressions typically surface only through the editor.
6. Ship in a normal release window behind a feature flag limiting the enabled block set; widen the catalog after one clean cycle.

Operational Impact

Maintenance: Low code maintenance, non-trivial review maintenance. Every release requires an engineer to reconstruct intent from a link-only changelog — budget 30–60 minutes per bump plus a staging render pass, and schedule it as a recurring, owned task rather than an ad-hoc one. The catalog itself is the recurring cost: each new block or variant added by the vendor is a design and QA decision (screenshot contract, accessibility contract, public presentation) that lands on our backlog whether we ask for it or not.

Support: Single-vendor, foundation-tier, free package with no visible external user base. Do not plan on community answers for defects; plan on (a) a written vendor escalation contact, (b) our own ability to fork or pin-out the package if it stalls, and (c) an internal owner of record for the block catalog. The absence of community support is acceptable only because the package is a leaf dependency with no schema footprint — the exit cost is low, but that only holds if we never let block content become unexportable.

Scaling: Rendering cost is per-page composition, not per-tenant; the block catalog is static configuration, so admin-side scaling is negligible. The real scaling levers are (1) the block-library cache tag — establish invalidation discipline before traffic, because stale or over-invalidated block caches look like content bugs; and (2) public-output discipline — no lazy queries or model IDs inside catalog Blade, enforced by the package's public-output tests in CI. If we run multi-site or per-brand variants, decide early whether variation is expressed as block variants (BlockVariantKey) or as separate page instances; retrofitting that later is expensive.

Failure modes (ranked, with mitigations):

1. Silent contract change on a patch bump → exact pin, staged render-diff, diff review before every bump.
2. Authoring data leaking into public output → run package public-output tests in CI; review any Blade diff touching resources/views/blocks/catalog/.
3. Dependency floor drift breaking a routine upgrade → constraint diff gate in the upgrade checklist.
4. Catalog sprawl — too many enabled blocks degrading editor usability and QA coverage → a curated allow-list owned by design, reviewed quarterly.
5. Vendor abandonment → because there is no schema impact, the hedge is to keep page content expressible in a portable form and keep the pin current enough that a fork is a patch, not a rewrite.
6. Health check blindness — BlockLibraryHealthCheck exists but is worthless unmonitored; wire it into the same alerting as the rest of the platform or delete it from the runbook.

Ramp-up: One Laravel/Filament engineer can complete install, catalog curation, and first page authoring within a sprint; the longer tail is content/design ramp — editors need a short enablement session on block selection heuristics (when Features vs. Comparison, when Content vs. CTA) or the catalog will be used inconsistently from day one. Budget roughly half a sprint of engineering plus a half-day of editor training, and set one success metric up front — e.g., percentage of new pages built from catalog blocks without custom template work — so the leverage claim is measured rather than assumed.