DOMolition

"Because sometimes the only valid response to centering a div is blowing up the entire UI."

DOMolition is a React-based physics engine wrapper that converts standard DOM elements into interactive, rigid-body physics simulations. It is designed to provide highly satisfying "rage quit" UI mechanisms by capturing the visual state of a component tree and destroying it dynamically on an HTML5 canvas.

Architecture

The underlying system operates in three distinct phases:

1. Capture Phase: Utilizes html-to-image (specifically toCanvas) to perform a high-fidelity capture of the target DOM node, resolving computed styles while supporting modern CSS features better than older rasterization libraries.
2. Kinematic Phase: Integrates matter-js to compute rigid body dynamics. Depending on the selected "engine" (e.g., Grid, Glass, Implode), the source bitmap is algorithmically subdivided—either into a discrete Cartesian grid or via Voronoi tessellations using d3-delaunay. Each subdivision becomes a physical body with calculated mass, restitution, and friction. Specific force vectors are applied based on the engine's explosive profile.
3. Render Pipeline: The original DOM element is visually hidden, and a full-viewport canvas is injected. A synchronized requestAnimationFrame loop paints the bitmap slices—using complex world-space clipping masks—according to the translation and rotation matrices calculated by the physics engine. The loop self-terminates when all rigid bodies reach a sleeping state.

Installation

Install the package via npm:

npm install domolition

Note: Ensure react and react-dom (v18.0.0 or higher) are installed in your project.

Usage

The library exposes the primary RageQuitWrapper component. The physics simulation is typically controlled imperatively via a React Ref, allowing you to trigger the effect from external buttons.

import React, { useRef, useState } from 'react';
import { RageQuitWrapper, RageQuitRef } from 'domolition';

export const Application = () => {
  const shatterRef = useRef<RageQuitRef>(null);

  return (
    <main style={{ padding: '2rem' }}>
      <button onClick={() => shatterRef.current?.triggerShatter()}>
        Initiate Destruction
      </button>

      <RageQuitWrapper ref="{shatterRef}" effect="glass" shardCount="{150}" onShatterComplete="{()"> console.log('Simulation terminated.')}
      >
        <section style={{ padding: '2rem', border: '1px solid #ccc', background: '#fff' }}>
          <h1>System Dashboard</h1>
          <p>This interface remains fully functional until the sequence is triggered.</p>
        </section>
      </RageQuitWrapper>
    </main>
  );
};

Physics Engines (Effects)

DOMolition supports multiple destruction engines, selected via the effect prop.

1. The Glass Engine (effect="glass")

Simulates brittle fracture. The UI cracks first (Pre-Fracture Phase), holding tension for 250ms, before shattering into jagged, realistic glass shards using Voronoi tessellation and a deterministic jitter-grid for performance. Usage:

<RageQuitWrapper effect="glass" shardCount="{200}" // Controls the number of jagged pieces>
  <YourComponent/>
</RageQuitWrapper>

2. The Implode Engine (effect="implode")

A high-energy inward collapse. The UI is broken into a grid, and forces pull all pieces toward the center of mass before they drop. Usage:

<RageQuitWrapper effect="implode" rows="{25}" // Horizontal grid subdivisions cols="{20}" Vertical>
  <YourComponent/>
</RageQuitWrapper>

3. The Grid Engine (effect="grid")

The classic blocky explosion. The UI splits into a clean grid of rectangles that explode outward uniformly. Usage:

<RageQuitWrapper effect="grid" rows="{12}" cols="{10}">
  <YourComponent/>
</RageQuitWrapper>

API Reference

RageQuitWrapperProps

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | children | React.ReactNode | required | The DOM sub-tree to be captured and simulated. | | effect | 'grid' \| 'glass' \| 'implode' | 'glass' | The physics engine to use for destruction. | | isShattered | boolean | false | A declarative fallback prop to trigger the shatter effect. | | shardCount | number | 150 | The number of shards generated by the glass engine. | | rows | number | 10 | The horizontal subdivisions for the grid and implode engines. | | cols | number | 8 | The vertical subdivisions for the grid and implode engines. | | onShatterComplete | () => void | undefined | Callback invoked when all rigid bodies stop moving. |

RageQuitRef (Imperative API)

| Method | Signature | Description | | :--- | :--- | :--- | | triggerShatter | () => void | Imperatively triggers the capture and subsequent physics simulation. |

Core Dependencies

• matter-js: Resolves 2D rigid body collisions, tunneling prevention, and kinematics.
• d3-delaunay: Powers the Voronoi tessellation math for realistic glass fractures.
• html-to-image: Executes the target DOM rasterization (replacing older html2canvas setups).