Visual Laravel Package

Product Decisions This Supports

• Build vs. buy for merchant-facing page composition. The real decision is whether visual page editing is a differentiator worth owning or table stakes you shouldn't be building. If merchants repeatedly ask to rearrange category pages, stand up campaign landing pages, or swap promo blocks, this is a credible alternative to a bespoke builder or an external CMS — and the buy case is strongest exactly where homegrown builders decay: the block registry, the preview path, and the cache interaction.

• Feature: self-serve merchandising. Editable layouts assembled from reusable components map directly to a roadmap line like "marketing publishes a campaign page without an engineering ticket." The reusable-component model is the product-significant part — it's what keeps a merchant-editable storefront from becoming a thousand bespoke pages with no design system behind them. Keep the registry in config so merchants choose from an approved list rather than an open canvas, and version blocks rather than mutating props, because saved layouts will reference the old shape.

• Feature: review-and-approve workflow. The alpha.31 change rendering draft preview without the editor client is the highest-leverage item in this release for a PM. It converts preview from "a mode inside the authoring tool" into "a rendered URL anyone can open," unlocking approvals by non-technical stakeholders, shareable proof links, QA sign-off against real rendering, and review in channels that never load the editor. The preview URL becomes the hand-off artifact and screenshot-in-Slack review can be retired.

• Sequencing: preview fidelity before anything clever. The middleware-order-independent full-page cache bypass is a product risk fix, not an infra nicety. Every roadmap item that depends on reviewers trusting what they see — scheduled campaigns, gated launches, A/B variants, seasonal takeovers — should be sequenced after preview correctness is verified against your own middleware, reverse proxy, and CDN. Ship preview trust first; ship preview-dependent features second.

• Platform direction: a typed commerce event contract. Wishlist and compare storefront events shipping with a TypeScript mirror moves the package from "renders pages" to "emits a typed event vocabulary shared across PHP and TypeScript." That is an enabler for analytics parity, experimentation hooks, personalization triggers, and abandoned-interest signals without per-feature instrumentation. Adopting it is a decision to own that contract as a versioned interface rather than treat it as a byproduct — and one parity assertion is needed so the two definitions can't drift silently, since the failure symptom is missing analytics weeks later, not an error.

• Consolidation play. One event vocabulary across backend and frontend removes duplicated definitions in two languages. If you already maintain parallel PHP and TS analytics schemas, this argues for convergence.

• Delivery risk as an explicit product input. This is 2.0.0-alpha.31 — the 31st alpha of a major line — with zero dependents and modest adoption signals. Any decision to build a merchant-facing workflow on it must be paired with a named owner, a pinned exact version, and a written exit plan. That governance call belongs to the PM, not to engineering by default.

When to Consider This Package

Consider it when:

• You run a Laravel storefront — strongest fit on Bagisto, where it is native rather than bolted on — and page composition is a recurring merchant need, not a one-off request.
• Non-technical users need to change storefront presentation — campaign pages, category layouts, promo blocks — and that work currently lands on engineering as tickets.
• You need a review/approval step before publish, and the current process is "a developer stages it and sends screenshots." Editor-client-free draft preview is a direct upgrade to that loop.
• You plan to build analytics, experimentation, or personalization on storefront intent signals and want one PHP/TypeScript event contract instead of two divergent schemas.
• You have in-house Laravel depth to read the source, pin versions, absorb alpha churn, and own the integration — accepting pre-stable APIs deliberately rather than by accident.
• Preview correctness is verifiable in your stack. You can assert preview ≠ published across your real middleware, response cache, reverse proxy, and CDN, and re-run that matrix on every bump.
• Content is data, not deploy. Composed layouts will outlive any version of this package, so you're prepared to keep a rollback path that doesn't require redeploying merchant content.
• You can carry the support burden. MIT, no visible commercial support path, zero dependents: fork or vendor into a private mirror and keep patches small and rebasable so a blocked storefront isn't waiting on upstream.

Look elsewhere when:

• You are not on Bagisto, or your storefront is a decoupled SPA/headless front end. The value collapses outside server-rendered Blade themes; the block registry and preview path assume a Blade rendering layer.
• The need is one-off. A single promo block or a one-time landing page is a template, not a framework. The cost of an alpha dependency is only justified by recurring composition demand.
• Preview or editor routes touch revenue-critical paths and you have not characterised a few upgrade diffs. Budget a re-validation pass per bump; if the cadence costs more than the content tickets it saves, that is a valid reason to stop.
• You need guaranteed support SLAs, stable APIs, or vendor accountability. This is a pre-1.0-equivalent surface with a fast release train and no upstream support organisation — you are it.
• Preview security cannot be threat-modelled by you. Something now decides who may render unpublished content, and the release notes don't describe it: is the URL signed, does it expire, is it scoped per-user or per-tenant, can a forwarded link be replayed? Until you answer those, exposing preview links broadly is not a supported use.
• Your CDN is the fidelity problem. The package fixes Laravel-level caching only; if Cloudflare or a reverse proxy is what serves stale pages, this package doesn't reach it.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version. This package is a credible buy option for merchant self-service page composition on a Laravel/Bagisto storefront, and the decision in front of us is whether visual merchandising is table stakes we should stop building in-house. The strongest capability in the current release is editor-free draft preview: an approvable URL of an unpublished edit that anyone can open. That converts content review from a developer-mediated, screenshot-based process into a shareable link — a measurable reduction in engineering tickets and approval latency. The counterweight is maturity: this is the 31st alpha of a major line with no dependents and no commercial support path. The recommendation is a time-boxed, canary-gated pilot on non-revenue pages with a pinned version, a named internal owner, and a written exit plan — not a platform commitment.

For engineering — what we're actually signing up for. Pin the literal alpha version, no caret, commit the lockfile, and record the pin plus rationale in an ADR. Read source before prose: service provider, config registry, routes, and above all the design/preview mode middleware — the highest-risk code in the package. Start with one promo block end to end: register it, render it on a non-critical page, open a draft preview URL with no editor session, and confirm it renders edited-not-published content. Then encode the parts the changelog doesn't promise: a cache matrix test across {no cache, response cache} × {middleware orderings} × {guest, editor, preview}, a behavioural assertion that preview ≠ published, and a response header or log line telling you which mode rendered a given response. Keep blocks dumb and the registry authoritative, route every composed layout through a single renderer so editor, preview, and published paths are byte-identical by construction, and assert query counts on the composed page, not individual blocks. Gate editor routes behind an env flag and an allowlist, roll out to one content type and one editor group, and vendor a forkable mirror so we can patch without waiting on upstream.

What we are explicitly not claiming. That this is production-stable, that preview authorization is documented (it isn't — we threat-model it), or that it fixes CDN-level staleness. Alpha churn is the recurring cost, not the install; we budget a re-validation pass per bump and keep the package off revenue-critical paths until we've characterised a few upgrade diffs. If the upgrade cadence outruns the content tickets it saves, stopping is a legitimate outcome — and the composed layouts are data, so they survive that decision.