Filament Rich Editor Toolkit Laravel Package

Technical Evaluation

What this release actually is: v1.1.0 changes rendered output, not just internals. A patch-level-safe upgrade silently alters the HTML produced from already-stored content, with no application code change required. For a TPM that is the headline: this is a content-contract change dressed as a feature release.

Architecture fit

• The package sits in the Filament rich-text editing path: editor-side plugins (authoring) and renderer-side plugins (presentation) must agree. v1.1.0 turns on LinkOptionsPlugin and ImagePropertiesPlugin on both sides by default, which is architecturally coherent (a saved caption would otherwise vanish at render time) but means defaults are now coupled across two call sites plus config.
• <figure>/<figcaption> → <span class="asignua-rte-figure">/<span class="asignua-rte-caption"> swaps semantic HTML for class-based markup. That is a deliberate trade for styling control, but it moves the burden of accessibility and structured-data semantics onto the consuming theme.
• rel token filtering plus forced noopener noreferrer on _blank is a sensible hardening default, but it places link policy inside a vendor package rather than in your own sanitization/SEO layer.

Integration feasibility

• Low code effort: upgrade, run php artisan filament:assets, optionally set config. No database migration.
• The opt-out surface is threefold — renderer($html, links: false, images: false), plugins(links: false, images: false), and renderer.link_options / renderer.image_properties config. Three ways to express one intent is a configuration-drift risk: editor-side and renderer-side flags must be flipped together or captions are editable but invisible.
• Critically, "keep the 1.0 output" is not a true compatibility mode: disabling image properties at render means any caption an editor saves disappears from the published page. Opting out is safe only until the first editor uses the new affordance.

Technical risk (ranked)

1. Silent content fidelity loss. Figcaption inner markup is flattened on re-render. Bold, links, or emphasis inside an existing caption are destroyed the first time the page renders, and re-saving makes it permanent. No migration step, no warning.
2. Downstream consumer breakage. Anything parsing rendered HTML — CSS selectors targeting figure/figcaption, RSS/email/AMP exports, PDF or search indexing pipelines, Open Graph extractors, e2e snapshot tests, CSP/rel-dependent affiliate logic — sees different markup or stripped rel tokens (sponsored, nofollow, ugc may not survive unless they are in link_options.rel_tokens).
3. Forced _blank on links conflicts with accessibility guidance (WCAG 3.2.5 / "warn before new window" conventions) and with any product rule that keeps internal links in-tab. Confirm whether the rule applies to external links only.
4. Google Docs image import changed four ways at once: authenticated user now required (guest authoring breaks unless paste_clean.remote_image_guests or authorizeRemoteImages() is set), no outbound proxy, no decompression, and wildcard allow-list entries over public suffixes (*.co.uk) no longer match. Each is defensible hardening; together they are four silent failure paths in a feature that is off by default — hence high blast radius if you already turned it on.
5. Deploy-step dependency. Forgetting php artisan filament:assets leaves changed and new modules unpublished; symptom is a broken or stale editor, not an obvious error.
6. Minor-version behavior change. Semver expectations are violated in spirit; teams pinning by caret range get new output on next install.

Key questions for the maintainer

• Is there a content migration or an audit command for existing <figure>/<figcaption> content, or is flattening accepted as lossy?
• What are the default link_options.rel_tokens? Are sponsored, nofollow, ugc preserved for SEO/compliance?
• Does _blank apply to internal/relative links, or external only? Is it configurable per-link?
• What are the defaults for renderer.link_options and renderer.image_properties in the published config, and can editor-side and renderer-side be set from a single switch?
• Exactly how does the public-suffix change behave — silently blocked, or logged? Is there a validation/warning at config load?
• For remote image import: is there a timeout, size cap, or queue path now that there is no proxy and no decompression step?
• Is the span-based figure markup documented for CSS authors, with an accessible-name strategy (caption not exposed as a caption to assistive tech)?

Integration Approach

Stack fit

• Confirm Filament major version and Laravel/PHP constraints before anything else; run filament:assets in the deploy pipeline as a mandatory, verified step (fail the build if assets are missing).
• Treat the package as presentation-layer infrastructure: it owns HTML output, so it should be covered by rendering snapshot tests in your repo, not assumed correct from the vendor's tests.

Migration path

1. Pin the current version. Do not let a caret range pull v1.1.0 into production unattended.
2. Inventory existing content: count posts containing <figure>, <figcaption>, target=, and non-empty captions with inline markup. This sizes the flattening risk.
3. Decide the link policy first — it is a product/legal decision, not a technical one. Then record it in link_options.rel_tokens and document it.
4. Add golden-file rendering tests: render a fixture set of stored HTML on old and new versions, diff the output, and sign off on each difference class (figure/span, target, rel, alt="").
5. Update theme CSS to target .asignua-rte-figure / .asignua-rte-caption before deploy, keeping the old figure/figcaption selectors during the transition.
6. Upgrade in staging, then a canary panel or internal-editor cohort, then full rollout.
7. Only after the rendering diff is accepted should editors be given access to caption entry — the moment captions are authorable, opt-out stops being viable.

Compatibility

• Keep editor-side and renderer-side flags locked together. Express the choice once (config) and derive both call sites, or encapsulate in your own toolkit wrapper so no caller can half-configure it.
• Decide explicitly whether alt="" retention and caption support are additive (yes) or substitute (no) for real alt text; add authoring guidance that captions are not alt text.
• Audit any server-side HTML sanitizer or rel rewriter that runs after the package renderer — double-filtering can strip noopener noreferrer or re-add target.

Sequencing

• Week 1: pin + inventory + link policy decision.
• Week 2: snapshot diff harness, CSS update, sanitizer audit.
• Week 3: staging upgrade, filament:assets in CI, internal cohort.
• Week 4: full rollout; then, separately and only if needed, revisit guest Google Docs imports with paste_clean.remote_image_guests deliberately scoped rather than broadly enabled.

Operational Impact

Maintenance

• Minor upgrades now require a rendering diff review, not just a changelog read. Budget a recurring "HTML output contract" check in the upgrade runbook.
• Configuration lives in three places for two features; document the intended combination and add a startup assertion or test that flags mismatched editor/renderer settings.
• The span-based figure markup is now your styling contract; changes to it in future releases are effectively breaking for your theme.

Support

• Expect two tickets: "my link opens in a new tab" and "my image caption lost its bold/link." The second is unrecoverable once re-saved — prepare a support script that stops editors from re-saving affected content until triage.
• Guest-authored Google Docs imports will fail with an auth error that looks like a permissions bug. Name the config keys in the support runbook.
• Wildcard allow-list entries over public suffixes will silently stop importing. Provide a log line or health check.

Scaling

• Remote image fetch now egresses directly from your application servers with no proxy. Consider an egress policy (NAT/firewall allow-list) and move imports to a queue with timeouts — a synchronous fetch of a large Google Docs image ties up a PHP worker.
• No decompression step means no decompression-bomb risk, but also no size normalization; enforce file-size and dimension limits yourself and expect larger stored blobs.
• Figure→span output is more markup per image; negligible for page weight, but check list/index rendering paths that were trimming HTML.

Failure modes

• Silent HTML change on deploy (highest likelihood, highest invisibility).
• Caption inline markup flattened and lost permanently on re-save.
• Theme CSS broken because selectors no longer match.
• rel tokens stripped → affiliate/sponsored linking non-compliant.
• Guest image import blocked; wildcard domain imports blocked.
• Stale editor assets because filament:assets was skipped.
• Half-configured flags: captions editable but invisible on the public page.

Ramp-up

• Small, bounded effort overall — days, not sprints — but it needs four reviewers: frontend/CSS, accessibility/content, security (image fetch + rel policy), and whoever owns SEO/links. Skipping the CSS and security reviews is how this release turns into an incident.
• Verdict: ready to adopt, but not as a routine bump. Treat v1.1.0 as a content-contract release requiring a rendering diff sign-off, a link-policy decision, and a deploy-runbook update before it reaches production.