Cms Framework Laravel Package

Technical Evaluation

Architecture fit. artisanpack/cms-framework sits in the layer that emulates WordPress block-theme semantics inside a Laravel application: theme.json global styles, template part resolution, query loops, and block tree rendering. This patch release is almost entirely about fidelity to the editor contract rather than new architecture — QueryRuntime learning include/rand aliases and per-loop pagination, GlobalStylesEmitter matching WordPress's kebab-case preset class names and artisanpack/* fork selectors, and HasRenderedBlockContent running visual-editor's entity passes before rendering. That is the correct direction for a package whose value proposition is "content authored in a block editor renders correctly on the Laravel side," and it strengthens the fit for teams already running a WP-style editing experience.

Integration feasibility. Low-friction on paper: a patch-version bump with no removals, no signature changes to documented APIs, and no deprecations. The one genuinely new surface is QueryRuntime::resolveTrusted(), an additive opt-in. Two internal cache keys move (GlobalStylesEmitter to v12, then v13), which is self-managing but means the first request after deploy regenerates emitted CSS.

Technical risk. Concentrated in one behavioural change rather than the API: QueryRuntime::resolve() now defaults every post type — including pages and custom types — to published-only, and explicitly ignores a status block attribute. Hosts that relied on a loop surfacing drafts, pending, or private records via an attribute will silently see fewer rows after upgrade. That is a defensible hardening (block attributes are author-controlled, not a trusted authorization signal), but it is a silent content-visibility change, not a loud failure. Secondary risk is editor-parity drift: several fixes depend on visual-editor providing the entity passes and on its class-naming conventions; when those passes are absent or throw, the code deliberately degrades (renderContent() leaves the tree as it was), which converts integration gaps into blank output rather than exceptions.

Key questions.

• What Laravel/PHP versions does 2.15.3 declare, and is the project inside that matrix?
• Do any query loops on the site depend on a status attribute or on listing non-published pages/custom records? Those are the blast radius.
• Are there authorization-sensitive loops that should move to resolveTrusted()?
• Is visual-editor pinned to a version that supplies the entity passes, PostResolver::stampTree(), and BlockStyleCssCompiler parity this release assumes?
• Are parts/{slug}.html|blade.php theme-file parts in use, and do they declare area in theme.json?

Integration Approach

Stack fit. Assumes a standard Laravel app with the package's service provider, theme.json-driven styling, and visual-editor as the authoring surface. Nothing here imposes new infrastructure — no queue, no external service, no schema migration is mentioned. The main stack coupling is to visual-editor internals, so the two must be upgraded in a compatible pairing.

Migration path. Treat as a routine composer update plus a verification pass:

1. Update the package (and confirm visual-editor version alignment) in a staging environment.
2. Clear application and view caches; expect the global-styles emitter cache to rebuild once (v12/v13).
3. Audit QueryRuntime call sites and any block content containing query loops for reliance on status; replace with resolveTrusted() only where the host has already authorized the broader visibility.
4. Diff the rendered Site Editor canvas and front-end CSS for preset classes (h1–h6, gray900-style slugs) and for artisanpack/* forks of core blocks.
5. Spot-check a record's own content containing post-title/post-excerpt/post-terms and a related-posts loop.

Rollback is a composer revert; the only residue is regenerated cache entries, which are key-versioned and safe to discard.

Compatibility. No breaking changes declared. Behavioural compatibility is the caveat: published-only defaults for pages and custom types. Saved template parts keep their own area and still win over theme.json inference, so existing saved parts are unaffected. core/* and non-artisanpack namespaces emit unchanged selectors.

Sequencing. Land this before further theme/editor work rather than alongside it — the emitter cache-key and class-name fixes are prerequisites for trusting any visual QA of global styles. If a larger migration to resolveTrusted() is planned, do it as a separate follow-up change so the visibility shift is attributable.

Operational Impact

Maintenance. Low ongoing burden: patch release, no deprecations, no config changes mandated. The emitter cache key moving twice in one release suggests active churn in the global-styles subsystem; budget periodic visual regression review of the Site Editor canvas after package updates rather than assuming CSS parity holds.

Support. Expect two classes of report. First, "content disappeared from a listing" — almost certainly the published-only default; resolution is either publishing the records or an explicit resolveTrusted() call. Second, "styles don't apply" or "block renders empty" — usually visual-editor version mismatch or a missing pass, since the package now degrades silently by design. Support runbooks should name those two causes first.

Scaling. Per-loop pagination keyed on query-{queryId}-page removes a real correctness bug for multi-loop pages, and reading include/rand reduces reliance on custom resolver code. Note that resolve() filtering is a query-level change likely to reduce rows returned, which is neutral-to-positive for load. No new scaling concerns are introduced; the emitter remains a cache-backed compile step.

Failure modes.

• Silent content narrowing on query loops (published-only, status ignored).
• Empty wrappers for post-* blocks if visual-editor's entity passes are unavailable — no exception raised.
• Preset/block styles absent in the canvas if the emitter cache is stale or the visual-editor class conventions diverge.
• Theme-shipped template parts falling back to slug-guessed areas when theme.json lacks a matching templateParts entry, so a navigation-overlay part may not render as an overlay.
• Recursion is explicitly guarded (a post-content block inside its own record renders empty; an already-rendering record is not re-rendered), so self-referential loops fail closed rather than hanging — acceptable, but worth documenting for editors.

Ramp-up. Minimal for developers already familiar with block themes; the concepts (theme.json presets, template part areas, query loops) are WordPress-native and transferable. The learning cost is in the trust boundary: teams must internalize that block attributes are not an authorization mechanism and that visibility decisions belong in resolveTrusted() at the host layer. Editors need a short note that styling in the Site Editor may now differ from what they previously saw — in most cases because it is now correct.