DEV Community: Het Dave

How We Built Perceive: Web Content Extraction for RAG Pipelines

Het Dave — Sat, 05 Sep 2026 12:53:36 +0000

A browser and a language model can look at the same URL and effectively see two different things.

A browser sees a rendered interface: navigation, cookie banners, buttons, ads, sidebars, images, scripts, interactive components, and eventually the text a human came to read. A language model sees whatever representation we decide to give it.

That distinction matters when the URL is going into a RAG pipeline.
Open the developer tools on any major news or documentation site and look at the raw HTML. A typical article page runs between 300KB and 800KB of markup. The article text itself is usually between 2KB and 10KB. The ratio of markup to content is consistently between 10:1 and 40:1 depending on how heavily templated the site is. When you pass raw HTML to a language model, you are passing all of it, and most pipelines treat this as an acceptable default.

Perceive is the endpoint we built to fix that. You give it a URL. It returns clean Markdown. This post is about what happens in between and why we made the engineering decisions we did.

Why raw HTML is a poor RAG input

The token waste is real but it is not the worst problem. Three failure modes compound each other.

Token waste. A blog post with 800 words of real content can run to 6,000–12,000 tokens as raw HTML once you include navigation, scripts, inline styles, and layout markup. The same content in Markdown is often 900–1,200 tokens. That is not just a cost issue. It is context window space that cannot go to content.

Embedding contamination. Embedding models are trained predominantly on natural language. When you embed a chunk containing <div class="sidebar-widget__title">Related Articles</div> alongside the article content, the vector is pulled toward the markup semantics rather than the content

semantics. The embedding does not cleanly represent the article; it represents a mixture of the article and the site's component naming conventions. Retrieval degrades as a result: chunks that should be semantically similar rank below chunks that happen to share markup patterns.

Chunking breakdown. Standard splitters are designed around prose or structured Markdown. HTML does not have semantic boundaries at the text level. A </div> tag is not a paragraph break. Splitting HTML by character count produces chunks with no meaningful coherence. The wrong content gets embedded together and the right content gets split apart.

The Perceive pipeline

Perceive processes every URL through four discrete stages.
Fetch. An HTTP request with appropriate headers, redirect handling, timeout management, and response validation. Non-200 responses are surfaced as errors rather than silently returning empty content. This stage handles rate limiting and robots.txt compliance.

Render. For JavaScript-rendered pages (SPAs, documentation sites built on frameworks like Docusaurus or GitBook, any page where content is injected into the DOM after initial load) a real browser render runs before extraction. The render uses a multi-engine fallback: a fast TLS fingerprint pass first, escalating to headless Chrome when the page needs JavaScript, and once more to a stealth-hardened render when anti-bot protection is detected. Cookie banners are dismissed, the page is scrolled to trigger lazy-loaded content, and images are given time to load.

One detail worth noting: the render step waits for network idle rather than just DOM ready. Modern SPAs often make secondary API calls after the initial render to populate content. Waiting for DOM ready captures the shell. Waiting for network idle captures the content. The cost is latency. The trade-off is necessary.

Extract. This is the hardest stage. The system needs to identify what is content and what is chrome. Navigation is not a semantic HTML tag; sites implement it with <nav>, <header>, <div class="nav-wrapper">, <ul class="menu">, and dozens of other patterns. The extraction layer uses a combination of element position in the DOM, text-to-link ratio within elements, text density relative to the page body, and known structural patterns to infer content boundaries. It is heuristic, not rule-based, which means it fails in specific ways rather than universally.

Structure. Extracted content is converted to Markdown. Headings map to ATX heading levels based on their HTML hierarchy. Lists preserve nesting. Tables become Markdown tables. Code blocks retain language hints where the site uses syntax highlighting. Inline links are preserved. Images become alt text references where available.

The only_main_content parameter

Passing only_main_content: true runs an additional stripping pass. The conceptual goal is to answer one question: if a human came to this URL to read the page, what information would they actually care about?

What gets removed: navigation elements, site headers and footers, cookie consent banners, sidebar content, related article blocks, and social sharing widgets.

What stays: the page title, the main content body, all heading structure within that body, lists, tables, code blocks, and inline links that appear within the content.

The engineering challenge is that the boundary between content and chrome is not always clear. An article with a "Further reading" section at the bottom is content. A dynamically injected related articles widget is chrome. The system uses element injection patterns and DOM position relative to the identified content body to distinguish between the two. On well-structured sites it works cleanly. On unusual layouts it occasionally over-strips and when stripping would remove too much real content, the full page is returned instead with a warning. That is why only_main_content is optional.

Why Markdown

Plain text loses structure. If a documentation page has four heading levels, three nested lists, and two tables, flattening it to plain text collapses the hierarchy that makes chunking semantically coherent.

Consider the difference in chunking behaviour. A RecursiveCharacterTextSplitter splitting on \n## produces chunks that correspond to sections. The same splitter on plain text produces chunks that correspond to character counts. Those are very different things to embed and retrieve against.

JSON requires an upfront schema decision and adds parsing overhead for the consumer. For a RAG pipeline where content goes directly into an embedding call or a LangChain Document, that parsing step is overhead without benefit.

Markdown preserves heading hierarchy, list nesting, table structure, and code block language identifiers. It is readable without a parser. It chunks predictably. Embedding models handle it better than raw HTML because it reads closer to natural language with light structural annotation.

One production detail that matters: we enforce consistent Markdown flavour across all output. ATX headings with a space after the hash. Fenced code blocks with language identifiers. GFM-style tables. If your chunking strategy relies on splitting at heading boundaries, inconsistency in heading format breaks it silently. Consistent output means your downstream logic behaves the same regardless of which site the content came from.

Edge cases

JavaScript-heavy SPAs. The multi-engine render handles the majority of these. The failure case is client-side routing where navigating to a URL does not trigger a full page load, only a state change. Some SPAs require specific interaction patterns to surface content that Perceive does not replicate.

Paywalled content. Perceive fetches what is publicly accessible. If a page returns a login wall or a metered paywall modal, that is what extraction runs on. The output is the paywall content, not the article behind it. There is no mechanism to bypass authentication and there should not be.

Scroll-triggered and lazy-loaded content. Content that only enters the DOM on user scroll or interaction is frequently not captured. Infinite scroll feeds, image galleries that load on demand, and content inside collapsed accordions that require a click to expand all fall into this category.

Inconsistent site structures. The failure mode that comes up most in practice is heavily templated pages where the main content column is structurally indistinguishable from the sidebar. Sites that use the same component markup for editorial content and promotional content are the hardest case. The heuristics fail here more than anywhere else.

A real request
Using curl:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": ["markdown"],
    "only_main_content": true
  }'

The response is a JSON envelope. The Markdown comes back as a pre-signed URL that expires after 15 minutes, alongside the signals worth checking before trusting the content:

{
  "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
  "status": "completed",
  "url": "https://example.com/blog/post",
  "url_final": "https://example.com/blog/post",
  "content_hash": "9f2b8c1a...d4e5",
  "render_quality": 0.93,
  "cache_hit": false,
  "outputs": {
    "markdown": {
      "url": "https://spaces.example.com/...signed...",
      "object_key": "env/files/4127/v2-perceive/per_3f9a..._markdown.md",
      "size_bytes": 8421,
      "content_type": "text/markdown; charset=utf-8",
      "expires_in": 900
    }
  },
  "extraction_tier": "heuristic",
  "duration_ms": 6230,
  "warnings": []
}

Or in Python, fetching the Markdown from its signed URL and passing it into a LangChain Document:

import requests
from langchain_core.documents import Document
from langchain_text_splitters import RecursiveCharacterTextSplitter

BASE = "https://api.enconvert.com"
HEADERS = {"X-API-Key": "sk_your_private_key"}

result = requests.post(
    f"{BASE}/v2/perceive",
    headers=HEADERS,
    json={
        "url": "https://example.com/blog/post",
        "outputs": ["markdown"],
        "only_main_content": True,
    },
    timeout=120,
).json()

// Below 0.40 means a failed render: anti-bot page, login wall, soft 404, empty shell.
if result["render_quality"] < 0.40:
    raise RuntimeError(f"unreliable render for {result['url_final']}")

// The signed URL is good for 15 minutes.
markdown = requests.get(result["outputs"]["markdown"]["url"], timeout=60).text

doc = Document(
    page_content=markdown,
    metadata={
        "source": result["url_final"],
        "content_hash": result["content_hash"],
        "render_quality": result["render_quality"],
    },
)

// Heading-aware chunks, which is the whole reason for asking for Markdown.
splitter = RecursiveCharacterTextSplitter(
    separators=["\n## ", "\n### ", "\n\n", "\n", " "],
    chunk_size=1500,
    chunk_overlap=150,
)
chunks = splitter.split_documents([doc])

If you want to skip the signed URL step and receive the Markdown bytes directly in the response body, add "direct_download": true to the request. The response will be the raw Markdown file rather than a JSON envelope:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": ["markdown"],
    "direct_download": true
  }' \
  -o post.md

The metadata that would have been in the envelope rides in response headers instead: X-Operation-Id, X-Render-Quality, X-Content-Hash, X-Cache-Hit, X-Source-Status-Code, and X-Warnings-Count. The response structure is consistent across Perceive, Ingest, and Convert. Error handling and retry logic transfer without modification across all three endpoints.

One honest limitation

Content boundary detection fails on sites that do not have a clear content region. If a page is built as a grid of equally weighted content blocks with no structural differentiation between editorial content and navigational content, the extraction heuristics make a guess. Sometimes that guess is wrong. The output contains more chrome than it should, or misses content that sits in a region the system classified as navigation.

There is no clean fix at the extraction layer without site-specific rules, which do not scale. The current workaround is to check the render_quality score returned in the response. Scores below 0.40 indicate a failed or unreliable render: an anti-bot page, a login wall, or an empty shell. For sources you know are structurally ambiguous, a post-extraction review pass or a second model call to strip non-content is more reliable than trusting the heuristic output.

We are looking at surfacing a confidence signal more explicitly in a future response version.

Free tier is 500 ops per month, no credit card required. If you are building RAG pipelines and the ingestion layer is where you are losing time, try it here and let us know what breaks. Feedback from engineers running this at scale is the most useful input we have.

Your game HUD is just React: overlay UI over a CarverJS game canvas

Het Dave — Mon, 04 May 2026 11:07:28 +0000

Most browser game setups separate game rendering from UI rendering. The game owns the canvas; HTML elements layer over it with careful z-index management. State crossing that boundary usually means event emitters, global flags, or a separate state system. In some frameworks, the game objects are their own DOM abstraction. In raw canvas work, the DOM overlay is entirely your problem.

CarverJS takes a different position: the game is a React subtree. The HUD is another React subtree positioned next to it. No second renderer, no event bus. Just JSX.

The structure

<Game> owns the canvas, the game loop, and the audio context. From React's perspective it is still JSX — which means you wrap it, position siblings over it with CSS, and pass state up and down through normal React patterns.

function GameScreen() {
  const [score, setScore] = useState(0);

  return (
    <div style={{ position: 'relative', width: 800, height: 600 }}>
      <Game width={800} height={600}>
        <Arena onScore={() => setScore((s) => s + 1)} />
      </Game>

      {/* HUD — absolute div over the canvas */}
      <div
        style={{
          position: 'absolute',
          top: 16,
          left: 16,
          color: 'white',
          fontFamily: 'monospace',
          pointerEvents: 'none',
        }}
      >
        Score: {score}
      </div>
    </div>
  );
}

The score display is a position: absolute div. React renders both the canvas and the HUD. There is no second rendering pass, no HUD texture atlas, no DOM-over-canvas bridge.

Wiring game events to HUD state

Game events happen inside hooks that run within <Game>'s React context. To expose them outside that boundary, lift shared state into an external store.

Zustand works cleanly here:

// store.ts
import { create } from 'zustand';

interface GameState {
  score: number;
  hp: number;
  addScore: (n: number) => void;
  takeDamage: (n: number) => void;
}

export const useGameStore = create<GameState>((set) => ({
  score: 0,
  hp: 100,
  addScore: (n) => set((s) => ({ score: s.score + n })),
  takeDamage: (n) => set((s) => ({ hp: Math.max(0, s.hp - n) })),
}));

Inside the game, actor hooks write to the store on collision:

// Player.tsx
function Player() {
  const playerRef = useRef(null);
  const addScore = useGameStore((s) => s.addScore);
  const takeDamage = useGameStore((s) => s.takeDamage);

  const coinHit = useCollision(playerRef, ['coin']);
  const enemyHit = useCollision(playerRef, ['enemy']);

  useEffect(() => {
    if (coinHit) addScore(1);
  }, [coinHit]);

  useEffect(() => {
    if (enemyHit) takeDamage(10);
  }, [enemyHit]);

  return <Actor ref={playerRef} tags={['player']} />;
}

The HUD subscribes from outside <Game>:

// HUD.tsx
function HUD() {
  const score = useGameStore((s) => s.score);
  const hp = useGameStore((s) => s.hp);

  return (
    <div style={{ position: 'absolute', inset: 0, pointerEvents: 'none' }}>
      <div style={{ position: 'absolute', top: 16, left: 16, color: 'white' }}>
        <div>HP: {hp} / 100</div>
        <div>Score: {score}</div>
      </div>
    </div>
  );
}

No prop drilling. No event emitters. Standard Zustand subscriptions.

A health bar

Once hp is in the store, the health bar is a styled div:

function HealthBar({ hp, max }: { hp: number; max: number }) {
  const pct = Math.round((hp / max) * 100);
  return (
    <div
      style={{
        width: 200,
        height: 12,
        background: '#333',
        borderRadius: 4,
        overflow: 'hidden',
      }}
    >
      <div
        style={{
          width: `${pct}%`,
          height: '100%',
          background: hp < 30 ? '#e53e3e' : '#48bb78',
          borderRadius: 4,
          transition: 'width 120ms linear',
        }}
      />
    </div>
  );
}

The width transition is CSS. React's reconciler handles updates. No animation library required.

Debug overlays during development

Because the HUD is React, a debug overlay is a conditional render:

{process.env.NODE_ENV === 'development' && (
  <div
    style={{
      position: 'absolute',
      bottom: 8,
      right: 8,
      color: 'lime',
      fontSize: 11,
      fontFamily: 'monospace',
      pointerEvents: 'none',
    }}
  >
    HP: {hp} | Score: {score}
  </div>
)}

Same component, same store, stripped in the production build by your bundler. No debug-mode game loop variant.

The full GameScreen

function GameScreen() {
  return (
    <div style={{ position: 'relative', width: 800, height: 600 }}>
      <Game width={800} height={600}>
        <Player />
        <EnemySpawner />
        <CoinField />
      </Game>
      <HUD />
    </div>
  );
}

Three layers, one component tree:

Canvas — CarverJS actors, game loop, AABB collision detection
HUD — React divs with score, health bar, any overlay widget
Overlays — pause screen, inventory, settings as conditional JSX

State flows through Zustand subscriptions. Components re-render when the store updates.

What this means

The HUD can use any React-ecosystem library your app already uses. React Query, Framer Motion, a CSS-in-JS system — none of that requires special integration because the HUD is just a React component tree over a canvas.

That is the design bet CarverJS makes: the game is a feature of the React app, not a runtime hosted by it.

@carverjs/core on npm, MIT licensed. v0.0.1, beta — APIs will move before 1.0.

Build a playable 2D game in React — from zero to ~40 lines with CarverJS

Het Dave — Tue, 28 Apr 2026 07:03:50 +0000

Most game tutorials for web developers start with "install Unity" or "set up a canvas context." Both paths lead somewhere real — but if your game lives inside a React app, you want your game loop to compose with React state the same way everything else does.

CarverJS is a React game engine built for that case. v0.0.1, APIs will move. But the core hooks are stable enough to build with today.

Here is what a complete playable 2D game looks like from scratch.

What you'll build

A player square that moves with WASD. Bounces off the viewport edges. The whole thing is around 40 lines. No canvas setup, no manual requestAnimationFrame, no cleanup in useEffect.

Install

npm install carverjs

The core bundle is under 200 KB. Three.js and react-three-fiber are peer dependencies — CarverJS lazy-loads them so they don't land in your main bundle if you're not already using R3F.

The game loop

useGameLoop is the spine of CarverJS. It runs your callback in the ordered update pipeline — earlyUpdate → fixedUpdate → update → lateUpdate. The delta value (time since last frame, in seconds) is max-delta-capped: if the tab slows down, delta won't compound into a physics spiral.

import { useRef } from 'react';
import { useGameLoop } from 'carverjs';

function Player() {
  const pos = useRef({ x: 200, y: 200 });
  const vel = useRef({ x: 120, y: 90 });

  useGameLoop(({ delta }) => {
    pos.current.x += vel.current.x * delta;
    pos.current.y += vel.current.y * delta;
  });
}

Default slot is update. Pass 'fixedUpdate' as a second argument when you need deterministic timing — physics, multiplayer state sync.

Input

useInput watches keyboard state reactively. No event listeners to register or clean up.

import { useRef } from 'react';
import { useGameLoop, useInput } from 'carverjs';

function Player() {
  const pos = useRef({ x: 200, y: 200 });
  const vel = useRef({ x: 0, y: 0 });
  const SPEED = 200; // px/s

  const input = useInput();

  useGameLoop(({ delta }) => {
    if (input.keys['KeyW']) vel.current.y = -SPEED;
    if (input.keys['KeyS']) vel.current.y =  SPEED;
    if (input.keys['KeyA']) vel.current.x = -SPEED;
    if (input.keys['KeyD']) vel.current.x =  SPEED;

    pos.current.x += vel.current.x * delta;
    pos.current.y += vel.current.y * delta;
  });
}

Wall bounds

Check position against viewport size in the same update callback. Invert velocity on overshoot.

useGameLoop(({ delta }) => {
  // ... input handling above
  pos.current.x += vel.current.x * delta;
  pos.current.y += vel.current.y * delta;

  if (pos.current.x < 0 || pos.current.x > window.innerWidth - 32)
    vel.current.x *= -1;
  if (pos.current.y < 0 || pos.current.y > window.innerHeight - 32)
    vel.current.y *= -1;
});

Mount the scene

<Game> and <Scene> are the wrappers. The mode prop is a discriminated union ("2d" | "3d") — TypeScript narrows the rendering pipeline at compile time.

import { Game, Scene } from 'carverjs';

export default function App() {
  return (
    <Game>
      <Scene mode="2d">
        <Player />
      </Scene>
    </Game>
  );
}

Mount the component, the loop starts. Unmount it, the loop stops. No globals to clean up.

The full game (~40 lines)

import { useRef } from 'react';
import { Game, Scene, useGameLoop, useInput } from 'carverjs';

function Player() {
  const pos = useRef({ x: 200, y: 200 });
  const vel = useRef({ x: 120, y: 90 });
  const SPEED = 200;
  const input = useInput();

  useGameLoop(({ delta }) => {
    if (input.keys['KeyW']) vel.current.y = -SPEED;
    if (input.keys['KeyS']) vel.current.y =  SPEED;
    if (input.keys['KeyA']) vel.current.x = -SPEED;
    if (input.keys['KeyD']) vel.current.x =  SPEED;

    pos.current.x += vel.current.x * delta;
    pos.current.y += vel.current.y * delta;

    if (pos.current.x < 0 || pos.current.x > window.innerWidth - 32)
      vel.current.x *= -1;
    if (pos.current.y < 0 || pos.current.y > window.innerHeight - 32)
      vel.current.y *= -1;
  });

  return (
    <div style={{
      position: 'absolute',
      left: pos.current.x,
      top: pos.current.y,
      width: 32,
      height: 32,
      background: '#4ade80',
    }} />
  );
}

export default function App() {
  return (
    <Game>
      <Scene mode="2d">
        <Player />
      </Scene>
    </Game>
  );
}

WASD movement, velocity, wall bounce. Runs in a browser tab inside your React app. Composes with the rest of your component tree like any other component.

What this doesn't cover

Collision between actors: that's useCollision — AABB only, two registered refs, returns a boolean in reactive state.
Audio: useAudio with 6 independent volume channels. Not needed here.
Multiplayer: P2P for 2–16 players. A topic on its own.

CarverJS is v0.0.1. APIs will move before 1.0. If the hook doesn't fit your use case, open an issue. If something breaks, same place.

Docs: docs.carverjs.dev

Introducing CarverJS

Het Dave — Mon, 27 Apr 2026 06:53:18 +0000

Here is a complete 2D game written in React. Move with WASD. Renders in a browser. The whole thing is around 40 lines.

import { useRef, useEffect } from "react";
import { Game, World, Actor } from "@carverjs/core/components";
import { useGameLoop, useInput } from "@carverjs/core/hooks";
import { useGameStore } from "@carverjs/core/store";
import type { Group } from "@carverjs/core/types";

function Player() {
  const ref = useRef<Group>(null);
  const setPhase = useGameStore((s) => s.setPhase);
  const { getAxis } = useInput();

  useEffect(() => {
    setPhase("playing");
  }, [setPhase]);

  useGameLoop((dt) => {
    if (!ref.current) return;
    ref.current.position.x += getAxis("KeyA", "KeyD") * 5 * dt;
    ref.current.position.y += getAxis("KeyS", "KeyW") * 5 * dt;
  });

  return (
    <Actor
      ref={ref}
      type="primitive"
      shape="circle"
      color="royalblue"
      geometryArgs={[0.5, 24]}
    />
  );
}

export default function App() {
  return (
    <Game mode="2d">
      <World>
        <Player />
      </World>
    </Game>
  );
}

That is CarverJS. It is a React game engine I just published to npm in early beta. Free, MIT, version 0.0.1 at the time of this post, with two packages: @carverjs/core and @carverjs/multiplayer. The API will move before it hits 1.0.

This post is the long version of why I built it, what it actually does, and what is still half-finished. If you have ever closed a game-dev tutorial because step one was "install Unity," this one is for you.

Why I built it

The honest answer: I needed it for my own product.

I run a small edtech company. We are building game-based learning for K-12 students. Two products: a B2B platform for schools (admin dashboards, teacher tooling, student experience) and a B2C marketplace. Every product surface eventually renders a game. The games are short, social, browser-based, often multiplayer.

I am a React developer. The rest of my team are React developers. Our admin portal, teacher app, marketing site, internal tools — every product surface is React, all the way down. The natural question was: can the games also be React?

The non-React paths I evaluated:

Unity WebGL. Exports run 10-50 MB on average, multi-second cold loads, doesn't compose with React UI. Great engine for the wrong runtime.
Phaser. Mature, deep 2D feature set, but you are back to imperative game loops. State lives outside React.
Godot HTML5. Smaller than Unity, same composition problem. GDScript or C#, neither of which is the language we ship in.
Raw Three.js / R3F. Excellent for 3D scenes. No game abstractions. You build your own input system, collision system, audio manager, scene manager, asset loader, and multiplayer layer.

Each option meant either learning a separate engine or rebuilding a stack of plumbing. I started writing the plumbing once, then twice, then realized I was writing a game engine. So I made it deliberate, pulled it out of the company monorepo, and open-sourced it.

That engine is CarverJS.

The mental model

CarverJS is built on top of React Three Fiber and Three.js, but in normal use you do not import from either. Every component, hook, type, and store you need ships from @carverjs/core and @carverjs/multiplayer. If you already know R3F, the API shape will feel familiar. If you do not, you can ship a game without ever learning what an <Object3D> is.

Components describe the world:

<Game mode="3d">
  <World physics={{ gravity: [0, -9.81, 0] }}>
    <Actor type="primitive" shape="box" position={[0, 0, 0]} />
    <Actor type="model" src="/hero.glb" animationName="run" position={[1, 0, 0]} />
    <Actor type="sprite" src="/coin.png" billboard position={[3, 0, 0]} />
  </World>
</Game>

Hooks drive behavior:

import { useRef } from "react";
import { Actor } from "@carverjs/core/components";
import { useGameLoop, useInput, useAudio } from "@carverjs/core/hooks";
import type { Group } from "@carverjs/core/types";

function Player() {
  const ref = useRef<Group>(null);
  const { isPressed, getAxis } = useInput({
    actions: { jump: ["Space"], shoot: ["KeyJ"] },
  });
  const { play } = useAudio({
    sounds: {
      jump: { src: "/jump.wav", channel: "sfx" },
      hit:  { src: "/hit.wav",  channel: "sfx" },
    },
  });

  useGameLoop((dt) => {
    if (!ref.current) return;
    ref.current.position.x += getAxis("KeyA", "KeyD") * 5 * dt;
    if (isPressed("Space")) play("jump");
  });

  return <Actor ref={ref} type="primitive" shape="capsule" />;
}

The components are not thin wrappers. <Game> mounts the entire game stack on the way in: WebGL renderer, lighting presets, audio system, input manager, collision manager, and a game loop with phase tracking (loading, playing, paused, gameover). <World> groups actors, sets up a default camera per mode, and optionally enables Rapier physics as a lazy-loaded peer dependency. <Actor> is a discriminated union over three rendering modes — 3D models (.glb/.gltf), sprites (with optional grid- or atlas-based animation), and code-generated primitives — sharing a common base of transform, event, and physics props.

Hooks then read from the singleton systems <Game> set up. useGameLoop is useFrame with phase awareness, fixed-timestep mode, four staged update slots (earlyUpdate, fixedUpdate, update, lateUpdate), and a max-delta cap so a backgrounded tab doesn't spiral the simulation. useInput reads from a centralized InputManager with action mapping. useCollision registers AABB / sphere / circle colliders without dragging in a physics engine. useAudio registers sounds, supports spatial audio, music crossfades, six volume channels, and audio sprites.

The thing I was hunting for, that no lower-level library gave me cleanly, was this: a place to write game logic that looks and feels like React component logic. No imperative boot file. No animation loop wired by hand. No scene-graph state living outside React. Mount a component, the game starts. Unmount it, it cleans itself up.

2D and 3D in the same engine

You change one prop:

<Game mode="2d">  // OrthographicCamera, no shadows, no environment, brighter ambient
<Game mode="3d">  // PerspectiveCamera, shadows, sky, environment, OrbitControls

The same <Actor> components work in both. A sprite in 3D mode billboards at the camera by default; in 2D mode it sits flat. Primitives become <mesh>es with the appropriate material. Models work in either mode, though most 2D games will not need them. Physics is mode-aware: in 2D, Z translation and X/Y rotation are auto-locked per actor so things stay on the plane.

This matters because most game projects do not get to pick "2D or 3D" cleanly. You build a 2D game and then realize the menu wants a parallax background with depth. You build a 3D game and then realize the HUD needs 2D widgets in world space. CarverJS gives you both in the same scene, with a <Camera> component that can override the defaults if you want full control of FOV, near/far, follow targets, or controls (orbit, map, pointerlock, none).

Multiplayer without a game server

This was the part I expected to be the hardest, and it turned out to be the part I am most glad to have built.

Multiplayer in CarverJS is peer-to-peer. One player is the host, all others are clients, and game traffic flows over WebRTC data channels. There is no game server in the architectural sense. The host is the server.

import { MultiplayerProvider } from "@carverjs/multiplayer";

<MultiplayerProvider appId="my-game">
  <Game mode="2d">
    <World>
      <Actor type="primitive" shape="circle" networked />
    </World>
  </Game>
</MultiplayerProvider>

That networked prop is the entire opt-in. The actor's transform now syncs to every connected peer at 20 Hz, with delta compression. Only changed properties go on the wire.

Peer discovery is serverless too. You bring your own signaling network:

MQTT — default, free, zero-config. Uses public MQTT brokers. Good enough for prototyping and small games.
Firebase RTDB — bring your own Firebase project for production. More reliable, more isolated, easy rules.
Cloudflare TURN (or any TURN provider) — optional, for NAT traversal when peers behind restrictive networks cannot connect directly.

After signaling, all data flows directly between peers. No room state lives on a server you have to operate.

Sync modes are layered. You pick the one that fits the actor:

Mode	Latency Feel	Bandwidth	Best for
Events	discrete	very low	turn-based games, chat, infrequent triggers
Snapshot (default)	smoothed	moderate	RPGs, casual co-op, strategy
Prediction	instant	higher	FPS, racing, fighting, fast platformers

Different actors in the same game can use different modes. The player character can use prediction; the chest they are walking towards can use events; the moving platform under their feet can use snapshots. You configure it inline:

<Actor
  type="model"
  src="/player.glb"
  networked={{ sync: "prediction", owner: myPeerId, priority: 2 }}
/>

Host migration is handled. If the host disconnects, peers sort by ID and the lowest ID becomes the new host. State is preserved through the migration — clients hit a brief migrating connection state and resume.

There is a working multiplayer demo in the repo — examples/multiplayer-2d, a small game called Coin Chase. Two players on different machines, collecting coins in real time, using Firebase RTDB for signaling and Cloudflare TURN for NAT traversal. Clone the repo and run it locally with two browser windows pointed at it.

I want to be clear about scope: this is not trying to be Photon or Colyseus. It is a peer-to-peer layer that fits inside React, designed for small to medium multiplayer games — roughly 2 to 16 players, browser-based. The trade-off is that the host has to stay online for the game to continue smoothly. Migration helps but is not a replacement for an authoritative server when you actually need one.

For MoneyTales — small classroom games, friends playing quick rounds — this is exactly the right shape. For your shooter MMO, it is not.

What is in the box right now

@carverjs/core ships:

<Game>, <World>, <Actor>, <Camera>, <AudioListener>
<SceneManager> and <Scene> for stack-based scene navigation with fade and custom-shader transitions, lazy-loaded scenes via Suspense, and per-scene error boundaries
<AssetLoader> and <LoadingScreen> for declarative asset preloading with retry, priority, progress, and groups
<ParticleEmitter> with presets (fire, smoke, explosion, sparks, rain, snow, magic, confetti)
useGameLoop, useInput, useCamera, useAnimation, useScene, useAssets, useTween, useParticles
useCollision (AABB / sphere / circle, layer-based filtering, sensors, no physics engine required)
useGridCollision (tile-based, O(1) lookups — perfect for Snake, tile RPGs, puzzles)
usePhysics (Rapier, lazy-loaded peer dependency)
useAudio (Web Audio with HTML5 fallback, spatial 3D audio, six volume channels, music crossfade, audio sprites, automatic AudioContext unlock)

@carverjs/multiplayer ships:

<MultiplayerProvider>, <MultiplayerBridge> (the R3F context bridge, since <Canvas> runs its own reconciler)
useMultiplayer, useLobby, useRoom, usePlayers, useHost
WebRTC transport with reconnection, host migration, interest management, and network simulation tools (latency, jitter, drop) for testing

The whole thing is TypeScript-first. Every hook and component has full type definitions. The core bundle is under 200KB before your assets, which is the whole point — a Unity WebGL export of an equivalently small game starts in the tens of megabytes.

Three demo games are open-source in the repo:

basic-2d — a minimal 2D scene with input
basic-3d — a minimal 3D scene with a model and orbit controls
multiplayer-2d — Coin Chase, the multiplayer demo above

You can run any of them with pnpm install && pnpm --filter @carverjs/example-basic-2d dev.

What CarverJS is not

This is a beta. Things will move before 1.0, and I want to be specific about scope.

It is not Unity. Do not bring AAA pipelines, baked global illumination, complex animation graphs, or 50-MB asset budgets here. The engine is designed for browser-shaped games.
It is not Phaser. Phaser is older, more battle-tested, and has a deeper 2D feature set, particularly for tile-based platformers. If you want a pure 2D engine that does not care about React, use Phaser. CarverJS is for the case where the game lives in a React app.
It is not a managed multiplayer backend. No matchmaking service, no analytics, no auth, no "studio plan." Bring your own Firebase or any signaling network. Bring your own TURN if you need NAT traversal.
The API will break. Minor versions will break things until 1.0. Pin your version. Read the changelog.

What CarverJS actually competes with is the version of "I will write my own game stack on top of R3F" that lives in your head when you start a side project. If that was the alternative, CarverJS will save you a lot of glue code.

What is next

The 1.0 milestone is roughly six months out. Between now and then:

Stabilize the core hooks and prop shapes (no big API churn after 1.0)
More multiplayer transports and a proper interest-management profile
A managed signaling service for teams who do not want to operate their own — paid, optional, the engine itself stays free and MIT
An asset marketplace for sprites, models, and audio packs, with most of the revenue going to creators
More examples — a multiplayer platformer, a tile-based puzzle, a 3D space shooter

The signaling service and the marketplace are how the project funds itself. The engine is free and stays free.

Try it

pnpm add @carverjs/core
# or
npm install @carverjs/core

Clone the repo and play with the demo games:

git clone https://github.com/moneytales/carverjs.git
cd carverjs
pnpm install
pnpm build
pnpm --filter @carverjs/example-basic-2d dev

Docs: docs.carverjs.dev
GitHub: github.com/moneytales/carverjs
Discord: discord.gg/5ymwfD4hYE
npm: @carverjs/core, @carverjs/multiplayer

If you build something with it, send it to me — I want to see what you make. If something is broken, GitHub Issues is the right place. If something is rough, Discord is where the rough things get tracked.

Most game engines were built by C++ programmers for C++ programmers, with a web export bolted on later. CarverJS was built backwards: web first, React first, game logic written the way component logic is written. It is an opinion as much as a tool. If the opinion fits, you will like the tool.