Prepaint

Prepaint is the render layer of FirstTx.

• On user revisit, it restores the last screen from a DOM snapshot
• Reduces the visible blank interval while the React bundle and data are loading
• And when ViewTransition is available, it wraps the restore → real render handoff in a smooth animation.

1. Installation & basic integration

1-1. Install packages

In most cases, you’ll want to use all three layers together,

If you want to try Prepaint first, you can install it alone,

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

1-2. Vite plugin setup

Prepaint ships a Vite plugin that injects a boot script into your HTML. Currently, the Prepaint plugin is provided for Vite only.

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { firstTx } from "@firsttx/prepaint/plugin/vite";

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

• firstTx() bundles the boot script (using esbuild internally) and injects it as an IIFE into your HTML.

• Default behavior,

  • inline: true - bundle is inlined into the HTML (no extra network request)
  • minify is enabled only in production

• If you prefer a separate file, you can set inline: false and load it via <script src="/firsttx-boot.js">.

For static hosting, prefer an external boot asset or a CSP hash. A nonce passed to the Vite plugin is generated at build time, not once per HTTP response.

1-3. Entry point: createFirstTxRoot

// main.tsx
import { createFirstTxRoot } from "@firsttx/prepaint";
import { App } from "./App";

createFirstTxRoot(
  document.getElementById("root")!,
  <App />,
  { transition: true },
);

Instead of calling createRoot yourself, use createFirstTxRoot. It mounts React into an empty container and removes the visual overlay after the first commit.

2. Boot script & snapshot lifecycle

The core of Prepaint is the boot script injected into your HTML.

2-1. Snapshot storage spec

• IndexedDB DB name: firsttx-prepaint
• Object store: snapshots
• Key: route (route key)
• Snapshot format,

type Snapshot = {
  route: string;
  body: string;         // innerHTML of the first child of #root
  timestamp: number;    // when the snapshot was captured
  styles?: Array<
    | { type: "inline"; content: string }
    | { type: "external"; href: string; content?: string }
  >;
};

• Default max age: MAX_SNAPSHOT_AGE = 7 days

2-2. Boot flow

Roughly, the boot script does,

1. Compute route key

   • If window.FIRSTTX_ROUTE_KEY is set, use that.
   • Otherwise, fall back to location.pathname.

2. Read the snapshot for that key from the snapshots store in IndexedDB.

3. Validate snapshot shape and required fields.

   • If validation fails, delete the snapshot and fall back to a cold start.

4. Check TTL.

   • If the snapshot age exceeds 7 days, treat it as expired and do a cold start.

5. Restore visual cache

   • Render HTML and styles into a non-interactive Shadow DOM overlay.
   • Leave #root untouched for a clean React mount.
   • Set data-prepaint, data-prepaint-overlay, and data-prepaint-timestamp on the html root.

6. Emit a prepaint.restore event to DevTools, including the strategy ("has-prepaint" / "cold-start"), snapshot age, restore duration, etc.

// Conceptual example (the real implementation is more defensive)
async function boot() {
  const snapshot = await getSnapshotForRoute();
  if (!snapshot || isExpired(snapshot)) {
    emitRestore({ strategy: "cold-start" });
    return;
  }

  mountOverlay(snapshot.body, snapshot.styles);
  markAsPrepainted(snapshot.timestamp);

  emitRestore({
    strategy: "has-prepaint",
    age: Date.now() - snapshot.timestamp,
  });
}

3. Capture pipeline: what DOM is stored?

Right before the user leaves the page, Prepaint stores a snapshot of the first child of #root.

3-1. Capture triggers

setupCapture schedules a capture when the following events fire,

• visibilitychange (when document.visibilityState === "hidden")
• pagehide
• beforeunload

When these events occur, it queues the capture using queueMicrotask. To avoid capturing too frequently, it ignores redundant calls in a short time window in the same tab.

3-2. DOM serialization & scrubbing

During capture, Prepaint performs several cleanup steps,

• Target: only the first child node under #root is serialized.

• Security,

  • Remove all inline event handlers (onClick, onChange, etc.) to minimize XSS risk.

• Volatile values,

  • For elements with data-firsttx-volatile, clear their text/value.
  • This prevents always-changing values (timestamps, random IDs, counters) from appearing as stale visual cache.

• Sensitive data scrubbing,

  • Default selectors include input[type="password"], [data-firsttx-sensitive], etc.
  • You can provide additional selectors via window.FIRSTTX_SENSITIVE_SELECTORS.
  • For matching elements, values/text are removed from the snapshot.

3-3. Style collection

Styles are collected as,

• <style> tags

  • Their CSS text is stored inline.

• <link rel="stylesheet">

  • Same-origin + fetchable: CSS text is fetched and stored along with the href, for better offline restores.
  • Otherwise: only the href is stored (for a security/size trade-off).

This information becomes Snapshot.styles. On restore, style-utils turns them back into <style> / <link> elements.

4. Visual handoff

1. handoff() checks the data-prepaint marker to determine whether a snapshot was restored.
2. createFirstTxRoot() clears the container and always mounts React with createRoot().
3. The visual overlay and data-prepaint* markers remain until React's first commit.
4. After the first commit, Prepaint removes the overlay and markers. When ViewTransition is supported and transition: true, the removal is wrapped in a transition.

Cached client DOM is never reused as React input. There is no single-child root guard, so Fragments and multiple top-level React nodes are valid output.

5. DevTools & error model

5-1. DevTools events

Prepaint emits the following events to the DevTools bridge,

• capture - snapshot capture completed
• restore - snapshot restore completed (or cold start decided)
• handoff - control handed from Prepaint to React
• hydration.error - legacy event type retained for compatibility; not emitted by the current default path
• storage.error - IndexedDB read/write error

Each event has,

• category: "prepaint"
• id: a UUID
• timestamp: when it occurred
• priority: 0-2 (smooth flow / important events / errors)

Events are only emitted if window.__FIRSTTX_DEVTOOLS__?.emit is present.

5-2. Error hierarchy (overview)

Internally, Prepaint uses a small error hierarchy,

• PrepaintError (abstract)

  • getUserMessage()
  • getDebugInfo()
  • isRecoverable()

• BootError

  • For DB open, snapshot read, DOM restore, style injection, etc.
  • Usually recoverable (a retry can succeed).

• CaptureError

  • For DOM serialization, style collection, DB writes during capture.
  • Effect: “capture failed → Prepaint won’t be applied on next visit”, typically recoverable.

• HydrationError

  • Deprecated error type retained for legacy consumers.

• PrepaintStorageError

  • For IndexedDB issues like quota/permission/corruption.
  • PERMISSION_DENIED is treated as non-recoverable, others as recoverable.

You rarely need to catch these in app code directly, but they are useful when analyzing issues in DevTools or logs.

6. Synergy with Local-First / Tx

Prepaint works fine on its own, but the experience is best when combined with the other two layers.

Example revisit flow,

1. The user opens the same dashboard they were looking at yesterday.
2. Prepaint replays yesterday’s visual snapshot during boot.
3. React mounts and Local-First reads persisted state from IndexedDB.
4. If the TTL has expired, useSyncedModel runs a background server sync.
5. User actions (filter changes, form submissions, etc.) are handled by Tx as optimistic transactions, and rolled back cleanly—with ViewTransition—if needed.

7. Recommended settings & caveats

Based on the internal design and reference docs, here are some practical tips,

• Sensitive data

  • For passwords, tokens, personal information fields, mark them with data-firsttx-sensitive or register selectors in window.FIRSTTX_SENSITIVE_SELECTORS so their values are scrubbed.

• Frequently changing areas

  • Wrap clocks, counters, random badges, and A/B test placements with data-firsttx-volatile so stale text is not exposed in the visual cache.

• Style size

  • Storing same-origin CSS content improves offline restores, but in large apps it can consume noticeable IndexedDB space. If needed, structure your CSS so “critical styles” are same-origin (and stored), and heavy styles are externalized.

• Root structure

  • React Fragments and multiple top-level nodes are supported. Prepaint does not monitor or rewrite the committed React root.

With this setup, Prepaint can reduce the visible boot interval on revisit. Measure replay and handoff timing with the snapshot sizes, devices, and network profiles your app actually supports.