@firsttx/prepaint

Instant replay for CSR apps — ~0ms blank screen on revisit

Restores your app's last visual state from IndexedDB before JavaScript loads. No blank screens. Automatic React hydration with graceful fallback.

❌ Before prepaint	✅ After prepaint
Slow 4G: Blank screen exposed	Slow 4G: Instant restore

``bash
npm install @firsttx/prepaint
`

![npm version](https://www.npmjs.com/package/@firsttx/prepaint)
![License](LICENSE)

> Module format: ESM-only. CommonJS users should use import() (dynamic import).

---

Why Prepaint?

The only solution that restores UI before JavaScript loads.

- No SSR/SSG infrastructure needed
- Works with any existing CSR React app
- Automatic React hydration with graceful fallback
- Native ViewTransition support

$3

`
Traditional CSR on revisit:
User clicks → Blank screen (2000ms) → Content appears

With Prepaint:
User clicks → Last snapshot (~0ms) → React hydrates → Fresh data
`

Prepaint captures DOM snapshots per route and replays them instantly on the next visit.

---

Quick Start

$3

Prepaint currently provides a Vite plugin only.

`ts
// vite.config.ts
import { firstTx } from '@firsttx/prepaint/plugin/vite';

export default defineConfig({
plugins: [firstTx()],
});
`

$3

`tsx
// main.tsx
import { createFirstTxRoot } from '@firsttx/prepaint';

createFirstTxRoot(document.getElementById('root')!, );
`

Done. Prepaint now:

- Captures snapshots on page hide/unload
- Restores them in ~0ms on revisit
- Hydrates with React (or falls back gracefully)

---

How It Works

$3

`
┌─────────────────────────────────┐
│ 1) Capture (on page leave) │
│ - beforeunload/pagehide/ │
│ visibilitychange │
│ - Saves DOM + styles to │
│ IndexedDB │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ 2) Boot (~0ms on revisit) │
│ - Inline script runs │
│ - Reads snapshot from IndexedDB│
│ - Injects into #root │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ 3) Handoff (~500ms) │
│ - Main bundle loads │
│ - Hydrates or client-renders │
│ - Cleans up prepaint artifacts │
└─────────────────────────────────┘
`

Storage

- DB: firsttx-prepaint
- Store: snapshots
- Key: route pathname
- TTL: 7 days

---

API

$3

`typescript
createFirstTxRoot(
container: HTMLElement,
element: ReactElement,
options?: {
transition?: boolean; // ViewTransition (default: true)
onCapture?: (snapshot: Snapshot) => void;
onHandoff?: (strategy: 'has-prepaint' | 'cold-start') => void;
onHydrationError?: (error: Error) => void;
}
);
`

Behavior

- If snapshot exists + #root has 1 child → hydrateRoot()
- Otherwise → createRoot() fresh render
- On hydration error → fallback to clean render (with ViewTransition)

$3

`typescript
firstTx({
inline?: boolean, // Inline boot script (default: true)
minify?: boolean, // Minify boot script (default: !isDev)
injectTo?: 'head-prepend' | 'head' | 'body-prepend' | 'body',
nonce?: string | (() => string),
overlay?: boolean, // Enable overlay mode globally
overlayRoutes?: string[], // Overlay for specific routes
})
`

---

Overlay Mode

Problem Direct injection into #root can race with routers, causing duplicate DOM.

Solution Overlay mode paints the snapshot above your app in Shadow DOM, then fades out after hydration.

$3

`js
// Option 1: Global flag
window.__FIRSTTX_OVERLAY__ = true;

// Option 2: localStorage (persists)
localStorage.setItem('firsttx:overlay', '1');

// Option 3: Specific routes
localStorage.setItem('firsttx:overlayRoutes', '/prepaint,/dashboard');

// Option 4: Vite plugin
firstTx({ overlay: true });
`

$3

`js
delete window.__FIRSTTX_OVERLAY__;
localStorage.removeItem('firsttx:overlay');
localStorage.removeItem('firsttx:overlayRoutes');
`

---

Real-World Patterns

$3

`tsx
import { useModel } from '@firsttx/local-first';

function ProductsPage() {
const [products] = useModel(ProductsModel);

// Prepaint shows last snapshot
// useModel provides instant data from IndexedDB
if (!products) return ;

return ;
}
`

$3

`tsx
// These change on every render → exclude from snapshot
{Date.now()}




`

$3

`tsx
createFirstTxRoot(root, , {
onCapture: (snapshot) => console.log('Captured:', snapshot.route),
onHandoff: (strategy) => console.log('Strategy:', strategy),
onHydrationError: (err) => console.error('Hydration failed:', err),
});
`

---

Hydration & Fallback

$3

Prepaint only attempts hydration if #root has exactly 1 child. Otherwise → fresh render.

$3

After mount, a MutationObserver watches #root:

- Detects extra children (e.g., router appending siblings)
- Unmounts → clears → re-renders cleanly
- Prevents "double UI" issues

$3

Post-mount:

- Removes
- Removes style[data-firsttx-prepaint]
- Removes overlay host #__firsttx_prepaint__

---

Best Practices

$3

✅ Use ViewTransition (default)

`tsx
createFirstTxRoot(root, , { transition: true });
`

✅ Mark volatile content

`html
{timestamp}
`

✅ Combine with Local-First

`tsx
const [data] = useModel(Model);
// Instant data from IndexedDB while network refreshes
`

$3

❌ Don't expect instant availability on first visit

`tsx
// First visit: snapshot doesn't exist yet
// Only kicks in on second+ visits
`

❌ Don't capture sensitive data

`tsx
// Snapshots are plain HTML in IndexedDB
// Avoid capturing auth tokens, PII, etc.
`

---

Security

$3

Prepaint sanitizes all restored HTML to prevent XSS attacks:

- Removes dangerous tags: