README

Ghostwire

Automatic runtime skeleton loaders for Livewire — synthesized from your live DOM, zero markup.

📘 Documentation: https://matheusmarnt.github.io/ghostwire/ · 🇧🇷 Português · 🇪🇸 Español

Add wire:ghost to any element (or #[Ghost] to a component class, with zero view changes) and Ghostwire synthesizes a matching skeleton from the live DOM the instant a Livewire request starts — no hand-written placeholder markup, no layout shift, and it works identically whether your app runs Livewire 3.6+ or 4.x.

Features

Zero-markup synthesis — walks the live DOM, classifies text/heading/media/control/container nodes, and emits a matching Bone Tree, all in one batched read pass (no forced reflow)
Dual Livewire bridge — Livewire 3.6+ and 4.x supported from the same package, selected by runtime feature detection (never a version-string check)
Morph-safe — the Ghost Layer mounts outside Livewire's reconciled tree; concealment uses only visibility/opacity/pointer-events, never a structural DOM change
freeze mode — dims and disables the live host in place, for layouts synthesis can't safely cover
#[Ghost] attribute — class- or method-level, a 7-level precedence cascade (directive modifier → directive expression → method → class → inherited → config → package default), zero view changes required
Silence by default — sync-only and polling messages never trigger a ghost, so background updates stay invisible
Repeat-sibling sampling, scrollable clipping, sticky/fixed geometry — real layouts (paginated tables, kanban boards, scrollable panels) synthesize correctly, not just simple cards
Theming — shimmer/pulse/wave animations, automatic dark mode, prefers-reduced-motion support, all pure CSS behind data/CSS-variable tokens
Accessibility — aria-busy, focus preservation across the ghost window, a shared live region announcing loading/idle state; axe-core clean at the strictest level
CSP-safe — runs under a strict Content-Security-Policy (no inline scripts, no eval); stylesheet nonce support built in
php artisan ghost:inspect — see exactly which precedence level decided each component's configuration
Learning — remembers a component's synthesized skeleton locally (opt-in, refused in production) so a lazy-loaded component's first paint on a later visit already has a matching placeholder — export it with php artisan ghost:export as a static Blade @placeholder

Requirements & compatibility

	Supported
PHP	8.2, 8.3, 8.4
Laravel	12.x, 13.x
Livewire	3.6+, 4.x

Tier matrix (FR-81)

Bridge selection is runtime feature detection, never a version string. Everything below is verified on both lines in CI.

Tier	Capabilities
A — identical	Directive + every modifier except `.island` · `#[Ghost]` in full (class, method, inheritance, precedence) · synthesis · `freeze` · timing (delay/hold/timeout) · sync silence · theme & tokens · accessibility · morph coexistence
B — degraded on 3.x	Post-paint removal (emulated via double `requestAnimationFrame`) · finalization (composed from multiple hooks) · cancellation (resolved as finalization) · poll detection (origin heuristic) · per-action interception (bridge-level filter — same observable behavior)
C — 4.x only	Island scoping (`.island`) · message-skip handling

Full detail: /docs/compat.

Installation

composer require matheusmarnt/ghostwire

<div wire:ghost>
    {{-- your existing Livewire markup, unchanged --}}
</div>

See /docs/install for the full first-effect walkthrough, and /playground to try synthesis on your own markup without installing anything.

Learning

Ghostwire can remember a component's synthesized skeleton locally in the browser and reuse it the next time that component is about to lazy-load — so a later visit's first lazy paint already has a matching skeleton, not a blank placeholder. Off by default, and refused server-side in production regardless of config.

GHOSTWIRE_LEARNING=true

#[Ghost(lazy: true)]
class OrdersTable extends Component
{
    // ...
}

Ghostwire.exportLearned()      // in the browser: downloads ghostwire-learned.json
php artisan ghost:export --component=orders-table --breakpoint=lg --from=~/Downloads/ghostwire-learned.json

Full walkthrough, storage/privacy details, and the export command's security posture: /docs/learning.

Documentation

Full docs, live playground, and gallery: https://matheusmarnt.github.io/ghostwire/

/docs/wire-ghost — directive & modifiers
/docs/ghost-attribute — #[Ghost] attribute & precedence
/docs/learning — local persistence, lazy skeletons, ghost:export
/docs/choosing — directive vs. attribute
/docs/compat — Livewire 3/4 tier matrix
/docs/theming — tokens, dark mode, animation
/docs/how-it-works — the synthesis algorithm
/docs/security — CSP, transport, supply chain
/docs/testing — Pest helpers & browser tests
/docs/interop — @placeholder, Wirebones, Flux, livecharts, scoutify

Security

See SECURITY.md and /docs/security. No DOM data ever leaves the browser; learning is local-only; zero telemetry (FR-93).

matheusmarnt / ghostwire

Package info

Security

Statistics

README

Ghostwire

Features

Requirements & compatibility

Tier matrix (FR-81)

Installation

Learning

Documentation

Security

Other packages by the author

License