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).