DEV Community: KernelX

KaTeX + html-to-image Outputs a Blank White Image — Here's Why and How to Fix It

KernelX — Mon, 09 Mar 2026 03:33:19 +0000

You render a beautiful math equation with KaTeX. You export it to PNG with html-to-image. You open the file — blank white rectangle.

This is what happened to me while building BlockTeXu, a block-based visual LaTeX editor. The layout was correct (fraction bars, integral positions), but the characters had vanished.

The Naive Approach

import { toPng } from 'html-to-image';

const dataUrl = await toPng(element);

Simple enough. But with KaTeX, this reliably produces a blank image.

Why It Happens: SVG foreignObject + Web Fonts

html-to-image serializes the DOM to an SVG <foreignObject>, draws it to a Canvas, then exports the Canvas as PNG.

The problem: @font-face web fonts do not load reliably inside SVG <foreignObject>.

KaTeX uses custom fonts for math rendering (KaTeX_Main, KaTeX_Math, etc.), all defined via @font-face. In a normal HTML document, these load fine. But when the DOM is serialized into an SVG blob, the browser treats it as a separate document — and the fonts fail to resolve before the canvas capture happens.

The result: font glyphs are invisible, leaving only the structural elements (lines, positioning) visible. Equations look like they're rendered with invisible ink.

What Doesn't Work: `document.fonts.ready`

The natural first attempt:

await document.fonts.ready;
const dataUrl = await toPng(element);

document.fonts.ready resolves when the HTML document's fonts are loaded. But it says nothing about fonts inside an SVG <foreignObject>. The capture still runs before the SVG has resolved its fonts internally.

What Works: Call `toPng` Twice

await document.fonts.ready;

// First call: triggers font embedding into the SVG blob
await toPng(element, options);
// Second call: fonts are now cached/embedded — capture is clean
const dataUrl = await toPng(element, options);

The first toPng call forces html-to-image to attempt to embed the fonts into the SVG. This populates an internal cache. The second call finds the fonts already embedded and renders correctly.

It's unintuitive, but it's documented in html-to-image issues as a standard workaround. The library itself doesn't expose a "wait for fonts" hook, so the double-call is the practical solution.

The Full Implementation

import { toPng } from 'html-to-image';

const PNG_OPTIONS = {
  backgroundColor: '#ffffff',
  pixelRatio: 3, // retina-quality output
};

export async function exportElementToPng(
  element: HTMLElement,
  filename: string
): Promise<void> {
  await document.fonts.ready;

  // First call primes the font cache
  await toPng(element, PNG_OPTIONS);
  // Second call is the real capture
  const dataUrl = await toPng(element, PNG_OPTIONS);

  const link = document.createElement('a');
  link.download = `${filename}.png`;
  link.href = dataUrl;
  link.click();
}

pixelRatio: 3 produces 3× resolution output. Without it, images look blurry on retina displays.

Capturing a Dynamically Created DOM Node

BlockTeXu also has a "save all stock items as one image" feature. For this, I can't capture an existing element — I need to create a temporary DOM node, render KaTeX into it, capture it, then clean up.

export async function renderLatexToImage(
  latex: string,
  filename: string
): Promise<void> {
  // Create a container positioned off-screen
  const container = document.createElement('div');
  container.style.position = 'absolute';
  container.style.left = '-9999px';
  container.style.padding = '40px';
  container.style.fontSize = '24px';
  container.style.background = '#ffffff';
  document.body.appendChild(container);

  // Render math into the container
  const { default: katex } = await import('katex');
  katex.render(latex, container, {
    throwOnError: false,
    displayMode: true,
  });

  try {
    await exportElementToPng(container, filename);
  } finally {
    // Guaranteed cleanup — even if export throws
    document.body.removeChild(container);
  }
}

Two things worth noting:

left: '-9999px' — positions the container off-screen so the user never sees it flash. display: none or visibility: hidden would make it invisible but would also break html-to-image's ability to measure and capture the layout.

try...finally — ensures the off-screen container is always removed, regardless of whether the export succeeds or throws. Without this, failed exports would silently accumulate invisible DOM nodes.

Should You Switch to html2canvas?

html2canvas renders directly from the DOM to Canvas without going through SVG <foreignObject>, so the font issue doesn't apply in the same way.

I considered switching but didn't:

The double-call fix worked immediately with no configuration
html2canvas has its own quirks with KaTeX's complex CSS
Switching libraries for a workaround that's already solved felt like unnecessary risk

If you're starting fresh and need high compatibility across more environments, it might be worth benchmarking html2canvas against html-to-image with your specific KaTeX output.

Summary

Approach	Result
`toPng(element)`	Blank image — fonts not embedded
`await document.fonts.ready` then `toPng`	Still blank — fonts.ready doesn't cover SVG
`toPng` twice	Works — first call primes font cache
Off-screen DOM + `try...finally`	Works — cleans up even on failure

If you're combining KaTeX with html-to-image, the double-call is essentially mandatory. Save yourself the debugging time.

Next post: Building a drag-and-drop block editor with HTML5 DnD API — palette drops, workspace reordering, and nested slot drops all in one system without any external library.

Try BlockTeXu at blocktexu.com/en

Why Your React Keyboard Handler Always Reads Old State

KernelX — Fri, 20 Feb 2026 14:14:46 +0000

You add a keyboard shortcut with useEffect. It works — until it doesn't. After a few state updates, the handler starts behaving as if nothing changed. Values are stale. Actions fire on outdated data.

This is the stale closure problem, and it bit me hard while building BlockTeXu, a block-based visual LaTeX editor.

The Setup: A Global Keyboard Handler

BlockTeXu has keyboard shortcuts throughout: Ctrl+Z for undo, Delete to remove blocks, Enter to confirm dialogs. The natural way to add these is:

useEffect(() => {
  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.key === 'Delete') {
      deleteSelectedBlock(selectedBlockId);  // ← uses state
    }
    if (e.ctrlKey && e.key === 'z') {
      undo();
    }
  };

  window.addEventListener('keydown', handleKeyDown);
  return () => window.removeEventListener('keydown', handleKeyDown);
}, []);  // ← empty dependency array

This seems fine. But there's a subtle bug hiding here.

The Problem: Closures Capture Values, Not References

When handleKeyDown is created inside useEffect, it closes over the current value of selectedBlockId. With an empty dependency array [], the effect runs only once — on mount. The event listener is registered once and never re-registered.

Here's what that means:

Mount:  selectedBlockId = null  → handler captures null
User clicks block A:  selectedBlockId = 'block-A'
User presses Delete:  handler still sees null  ← stale!

The function you passed to addEventListener is frozen in time. It will always read the value that existed when it was first created.

Key Insight: This isn't a React bug or an event listener quirk — it's how JavaScript closures work. The function literally holds a reference to the scope that existed at creation time, not a live pointer to current state.

Attempted Fix: Add Everything to the Dependency Array

The obvious fix:

useEffect(() => {
  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.key === 'Delete') {
      deleteSelectedBlock(selectedBlockId);
    }
  };

  window.addEventListener('keydown', handleKeyDown);
  return () => window.removeEventListener('keydown', handleKeyDown);
}, [selectedBlockId, deleteSelectedBlock, undo, /* ... */]);

This works, but has a cost: the listener is removed and re-added every time any dependency changes. With many state values in the dependency array, you get constant register/unregister cycles. For a global keyboard handler that touches most of the app's state, this becomes impractical.

You'd also need to be careful about referential stability of the callbacks (useCallback on everything they depend on), which adds more boilerplate and more opportunities to miss a dependency.

The Solution: useRef as a Stable Bridge

The cleanest fix uses useRef to bridge between the stable event listener and the current state:

// 1. Keep a ref that always points to the latest handler
const handlerRef = useRef<(e: KeyboardEvent) => void>(() => {});

// 2. Update the ref on every render — this is intentional
useEffect(() => {
  handlerRef.current = (e: KeyboardEvent) => {
    if (e.key === 'Delete') {
      deleteSelectedBlock(selectedBlockId);
    }
    if (e.ctrlKey && e.key === 'z') {
      undo();
    }
    // ... all your keyboard logic
  };
});  // no dependency array — runs every render

// 3. Register a stable listener that calls through the ref
useEffect(() => {
  const stable = (e: KeyboardEvent) => handlerRef.current(e);
  window.addEventListener('keydown', stable);
  return () => window.removeEventListener('keydown', stable);
}, []);  // runs only once

Why this works:

The stable listener (stable) is registered once and never removed until unmount
stable always calls handlerRef.current — a ref lookup, not a closure capture
The ref's value is updated on every render with a fresh function that closes over current state
When the user presses a key, stable fires, reads handlerRef.current, and gets the latest handler

The ref acts as a mutable variable that the stable function can "look through" at runtime.

Mount:       stable = (e) => handlerRef.current(e)   ← registered once
Render 1:    handlerRef.current = fn that sees selectedBlockId = null
User clicks: selectedBlockId = 'block-A'
Render 2:    handlerRef.current = fn that sees selectedBlockId = 'block-A'
Key press:   stable() → handlerRef.current() → sees 'block-A' ✅

The Complete Pattern

Here's the full implementation in BlockTeXu:

function useKeyboardHandler(
  blocks: PlacedBlock[],
  selectedId: number | null,
  onDelete: (id: number) => void,
  onUndo: () => void,
  onRedo: () => void,
) {
  const handlerRef = useRef<(e: KeyboardEvent) => void>(() => {});

  // Update ref every render
  useEffect(() => {
    handlerRef.current = (e: KeyboardEvent) => {
      // Ignore if focus is inside an input/textarea
      const target = e.target as HTMLElement;
      if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA') return;

      if (e.key === 'Delete' && selectedId !== null) {
        e.preventDefault();
        onDelete(selectedId);
      }
      if (e.ctrlKey && e.key === 'z') {
        e.preventDefault();
        onUndo();
      }
      if (e.ctrlKey && e.key === 'y') {
        e.preventDefault();
        onRedo();
      }
    };
  });

  // Register stable listener once
  useEffect(() => {
    const handler = (e: KeyboardEvent) => handlerRef.current(e);
    window.addEventListener('keydown', handler);
    return () => window.removeEventListener('keydown', handler);
  }, []);
}

One important detail: if target is INPUT/TEXTAREA, return early. Without this, pressing Delete while typing in an input field would trigger your delete shortcut. Always guard global key handlers against active form elements.

React 19.2 Update: useEffectEvent

After publishing the Japanese version of this article on Zenn, a reader pointed out that React 19.2 (released as stable) ships useEffectEvent — an official solution to exactly this problem.

import { useEffectEvent } from 'react';

function useKeyboardHandler(selectedId: number | null, onDelete: ...) {
  const handleKeyDown = useEffectEvent((e: KeyboardEvent) => {
    if (e.key === 'Delete' && selectedId !== null) {
      onDelete(selectedId);
    }
  });

  useEffect(() => {
    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, []);  // no need to list selectedId in deps
}

useEffectEvent creates a function that:

Always reads the latest values (like our useRef approach)
Has a stable identity (like a ref wrapper)
Is excluded from dependency lint rules (React knows it's always fresh)

The useRef pattern we built manually is essentially what useEffectEvent does under the hood. The hook makes the intent explicit and removes the boilerplate.

As of React 19.2, useEffectEvent is the canonical solution. If you're on React 19.2+, use it directly. For earlier versions, the useRef bridge pattern is the way to go.

Comparison

Approach	Pros	Cons
Empty deps `[]`	Simple	Always reads stale state
Full deps array	Correct	Re-registers on every change, dependency hell
`useRef` bridge	Correct, registers once	Two `useEffect` calls, manual boilerplate
`useEffectEvent`	Correct, clean	Requires React 19.2+

Key Takeaways

Stale closures happen when an event listener captures state from a specific render and never updates
useRef bridge pattern: update a ref every render, register one stable listener that reads through the ref
useEffectEvent (React 19.2+) is the official replacement — same semantics, no boilerplate
Always guard global key handlers against INPUT/TEXTAREA focus

The useRef bridge isn't React-specific. The same pattern applies whenever you need a stable function reference that always reads current values — WebSocket message handlers, requestAnimationFrame callbacks, timer callbacks, and more.

Next post: How KaTeX + html-to-image produced blank white images — the SVG foreignObject font-loading problem and the two-call workaround.

Try BlockTeXu at blocktexu.com/en

How I Built Recursive UI for a Visual Math Editor in React

KernelX — Wed, 18 Feb 2026 11:06:51 +0000

Tree-structured UIs are everywhere — file explorers, comment threads, org charts. They all share the same challenge: a component that renders itself recursively. Getting this right in React is trickier than it looks.

While building BlockTeXu, a block-based visual LaTeX editor, I had to design a recursive component that could represent arbitrarily nested math expressions. Here's what I learned.

Representing Math as a Tree

First, let's look at the data structure. A math expression is a tree where each node is a "block":

interface PlacedBlock {
  id: number;
  definition: BlockDefinition;  // block type (fraction, integral, etc.)
  children: PlacedBlock[][];    // 2D array: [slot index][blocks in that slot]
  rawValues: string[];          // text typed into empty slots
}

Key design choice: children is a 2D array. A fraction block has two slots (numerator and denominator), and each slot can hold multiple blocks side by side:

Fraction block
  children[0] → [block, block, ...]   // slot 0: numerator
  children[1] → [block, ...]          // slot 1: denominator

This lets you express deeply nested structures like $\frac{x + 1}{\int_0^1 f(t) \, dt}$ naturally.

The Recursive Component Design

Two-Component Pattern

I split the UI into two components that call each other:

Component	Role
`PlacedBlock`	Renders one block. If it has input slots, calls `BlockSlot`
`BlockSlot`	Renders one input slot. If it has content, calls `PlacedBlock`

PlacedBlock (Fraction)
  ├── BlockSlot[0] (Numerator)
  │     └── PlacedBlock (Integral)
  │           ├── BlockSlot[0] (Lower bound)
  │           └── BlockSlot[1] (Upper bound)
  └── BlockSlot[1] (Denominator)
        └── PlacedBlock (Variable y)

PlacedBlock: Rendering a Single Block

function PlacedBlock({ block, depth = 0, onAddBlockToSlot, ... }) {
  const hasInputs = block.definition.inputs > 0;

  return (
    <span
      className={`placed-block ${depth > 0 ? 'nested' : ''}`}
      draggable={depth === 0}  // only top-level blocks are draggable
    >
      {hasInputs ? (
        // structural block: render slots recursively
        <span className="placed-block-structure">
          {block.children.map((slotBlocks, slotIdx) => (
            <BlockSlot
              key={slotIdx}
              slotBlocks={slotBlocks}
              depth={depth}
              parentBlock={block}
              slotIndex={slotIdx}
              onAddBlockToSlot={onAddBlockToSlot}
            />
          ))}
        </span>
      ) : (
        // leaf block: render math with KaTeX
        <span ref={katexRef} className="placed-block-katex" />
      )}
    </span>
  );
}

The key branch:

Structural blocks (fraction, integral, etc.) → render child slots recursively
Leaf blocks (variables, operators, etc.) → render directly with KaTeX

BlockSlot: Rendering an Input Slot

function BlockSlot({ slotBlocks, depth, parentBlock, slotIndex, ... }) {
  const hasBlocks = slotBlocks.length > 0;

  return (
    <span className="block-slot">
      {hasBlocks && slotBlocks.map((childBlock) => (
        <PlacedBlock
          key={childBlock.id}
          block={childBlock}
          depth={depth + 1}    // ← increment depth here
          onAddBlockToSlot={onAddBlockToSlot}
        />
      ))}
      {hasBlocks ? (
        <span className="slot-add-zone">+</span>
      ) : (
        <input
          type="text"
          placeholder="?"
          value={rawValue}
          onChange={(e) => onUpdateRawValue(parentBlock.id, slotIndex, e.target.value)}
        />
      )}
    </span>
  );
}

Key Insight: depth + 1 is incremented in BlockSlot, not in PlacedBlock. This means depth always reflects the nesting level of the current block, not the slot. Empty slots show a text input; slots with blocks show the blocks plus an add button.

Controlling Behavior with `depth`

The depth prop does two important things:

1. Drag & Drop Control

draggable={depth === 0}

Only top-level blocks are draggable for reordering. If nested blocks were also draggable, dragging them would conflict with the parent block's drag handler — you'd get both moving at once.

2. Visual Scaling via CSS

Without size reduction at each nesting level, deeply nested math would expand the UI horizontally until it overflows.

.placed-block {
  padding: 6px 10px;
  font-size: 0.95rem;
  background: #1a365d;
}

.placed-block.nested {
  padding: 3px 6px;
  font-size: 0.85rem;
  background: #2a4a7f;
  box-shadow: none;
}

For finer-grained control, you could pass depth as a CSS custom property:

// potential future approach
<span style={{ '--depth': depth } as React.CSSProperties}>

Immutable Tree Updates

Rendering the recursive tree is the easy part. Updating it is where things get tricky.

When a user drops a block into a deeply nested slot, you need to update a node at an arbitrary depth — while keeping React's immutability guarantees. No array.push(), no direct mutation.

`updateBlockInTree`

function updateBlockInTree(
  blocks: PlacedBlock[],
  id: number,
  updater: (b: PlacedBlock) => PlacedBlock
): PlacedBlock[] {
  return blocks.map(block => {
    // found the target: apply the update
    if (block.id === id) {
      return updater(block);
    }

    // recursively search children
    const newChildren = block.children.map(slot =>
      updateBlockInTree(slot, id, updater)
    );

    // only create a new object if something actually changed
    if (newChildren.some((slot, i) => slot !== block.children[i])) {
      return { ...block, children: newChildren };
    }

    // no change: return the original reference
    return block;
  });
}

Three things worth noting:

1. Preserve reference identity

return block;  // same reference = React skips re-rendering this subtree

Unchanged subtrees return their original object reference. React's reconciler uses Object.is comparison, so unchanged parts skip re-rendering automatically.

2. Separate traversal from update logic

// add a block to a slot
updateBlockInTree(blocks, parentId, parent => {
  const newChildren = [...parent.children];
  newChildren[slotIndex] = [...newChildren[slotIndex], newBlock];
  return { ...parent, children: newChildren };
});

// update a raw text value
updateBlockInTree(blocks, blockId, block => {
  const newRawValues = [...block.rawValues];
  newRawValues[slotIndex] = value;
  return { ...block, rawValues: newRawValues };
});

The updater callback keeps tree traversal logic separate from what you're actually doing. Add, remove, update text — all use the same traversal function.

3. 2D array immutable update requires two spreads

// ❌ mutates in place
parent.children[slotIndex].push(newBlock);

// ✅ creates new arrays at both levels
const newChildren = [...parent.children];
newChildren[slotIndex] = [...newChildren[slotIndex], newBlock];
return { ...parent, children: newChildren };

Since children is PlacedBlock[][], you need to spread both the outer array (slot list) and the inner array (blocks within a slot).

Undo/Redo with a History Stack

Immutable state makes Undo/Redo almost embarrassingly simple:

const [state, setState] = useState<WorkspaceState>({ blocks: [] });
const [history, setHistory] = useState<WorkspaceState[]>([]);
const [future, setFuture] = useState<WorkspaceState[]>([]);

On every state change: push to history

function pushHistory(prev: WorkspaceState) {
  setHistory(h => [...h, prev]);
  setFuture([]);  // clear redo stack on new action
}

const addBlock = (def: BlockDefinition) => {
  pushHistory(state);
  setState(prev => ({ blocks: [...prev.blocks, createBlock(def)] }));
};

Undo: pop history, push current to future

const undo = useCallback(() => {
  if (history.length === 0) return;
  const prev = history[history.length - 1];
  setHistory(h => h.slice(0, -1));
  setFuture(f => [...f, state]);
  setState(prev);
}, [history, state]);

Redo: pop future, push current to history

const redo = useCallback(() => {
  if (future.length === 0) return;
  const next = future[future.length - 1];
  setFuture(f => f.slice(0, -1));
  setHistory(h => [...h, state]);
  setState(next);
}, [future, state]);

Because state snapshots are immutable, the objects stored in history are never accidentally modified. If you used array.push() to mutate state directly, your history would contain references to objects that have since changed — and Undo would restore the wrong values.

LaTeX Generation: Another Recursive Pass

There's a second recursion running over the same tree: generating the LaTeX string.

function generateBlockLatex(block: PlacedBlock): string {
  let latex = block.definition.latex;  // e.g., "\\frac{□}{□}"

  for (let i = 0; i < block.definition.inputs; i++) {
    const slotBlocks = block.children[i] || [];
    const slotLatex = slotBlocks.length > 0
      ? slotBlocks.map(b => generateBlockLatex(b)).join(' ')
      : block.rawValues[i] || '\\square';

    latex = latex.replace('□', slotLatex);
  }

  return latex;
}

Each block's definition.latex is a template (e.g., \frac{□}{□}). The placeholder □ gets replaced sequentially with the results from child nodes. Because the templates guarantee syntactic correctness, users can never produce a LaTeX syntax error by combining blocks.

The same tree data drives two separate recursive processes: UI rendering and LaTeX generation.

Design Decisions Summary

Element	Decision	Reason
Component split	`PlacedBlock` + `BlockSlot` as two layers	Slots serve as the natural recursion boundary
Depth tracking	Integer prop passed down	Controls drag behavior and CSS scaling
Children structure	`PlacedBlock[][]` (2D array)	Multiple slots × multiple blocks per slot
State updates	`updateBlockInTree` recursive walk	Immutable update while preserving reference identity
Undo/Redo	`history` / `future` arrays	Free snapshot storage from immutable state

The hardest part of recursive components isn't the rendering — it's immutable updates at arbitrary depth. The updateBlockInTree pattern here applies to any recursive structure: file trees, comment threads, nested forms.

Wrapping Up

If you're building any tree-structured UI in React, the pattern covered here — two mutually-recursive components, depth-based behavior control, and updateBlockInTree for immutable updates — gives you a solid foundation.

I'd love to hear how you've handled recursive UIs in your own projects. Drop a comment below!

Next post: The stale closure problem in keyboard handlers — why useEffect + addEventListener reads stale state, and how useRef fixes it.

Try BlockTeXu at blocktexu.com/en

8 Challenges I Faced Building a Complex Visual Editor in React

KernelX — Mon, 16 Feb 2026 15:06:17 +0000

Editing LaTeX as raw strings is a nightmare for beginners. That's why I built BlockTeXu — a block-based visual LaTeX equation editor where you snap together math symbols like LEGO blocks, and it generates valid LaTeX automatically.

Along the way, I ran into a number of challenges that are broadly useful in React development: recursive components, immutable tree operations, Drag & Drop, and more.

This article gives an overview of the 8 technical challenges I faced and how I approached them. I'll dive deeper into each topic in upcoming posts.

LaTeX Generation: Template Substitution

The core mechanism generates LaTeX from a tree of PlacedBlock nodes. Here's the implementation:

function generateBlockLatex(block: PlacedBlock): string {
  let latex = block.definition.latex;

  for (let i = 0; i < block.definition.inputs; i++) {
    const slotBlocks = block.children[i] || [];
    let slotLatex: string;

    if (slotBlocks.length > 0) {
      slotLatex = slotBlocks.map(b => generateBlockLatex(b)).join(' ');
    } else {
      slotLatex = block.rawValues[i] || '\\square';
    }

    latex = latex.replace('□', slotLatex);
  }

  return latex;
}

Each block's definition.latex holds a template (e.g., \frac{□}{□}), and the placeholders □ are replaced sequentially with the results from child nodes. Because templates guarantee correct syntax, this approach structurally prevents LaTeX syntax errors.

The mechanism is simple, but implementing the actual UI, interactions, and output revealed several React-specific challenges.

Challenge 1: Recursive Component Design

Problem: How do you represent a tree-structured UI with React components?

In BlockTeXu, the UI is essentially a visual representation of an Abstract Syntax Tree (AST). I implemented this using a recursive pattern: PlacedBlock → BlockSlot → PlacedBlock.

PlacedBlock (Fraction)
  ├── BlockSlot[0] (Numerator)
  │     └── PlacedBlock (Integral)
  │           ├── BlockSlot[0] (Lower bound)
  │           └── BlockSlot[1] (Upper bound)
  └── BlockSlot[1] (Denominator)
        └── PlacedBlock (Variable y)

Key Insight: To prevent infinite UI scaling issues, I used a depth prop to dynamically adjust CSS scales and font sizes. Managing Drag & Drop across these nested boundaries was one of the trickiest parts of the project.

→ Next post: "Designing Recursive Components in React — Implementing Nested Math Structures"

Challenge 2: Immutable Tree Updates

Problem: How do you update a node at an arbitrary depth while preserving React's immutability?

When a user adds a block to a slot, we need to update a node at any depth in the tree. A recursive function called updateBlockInTree creates new objects only along the path to the target node, keeping all other references unchanged.

Undo/Redo relies on this immutability — it's implemented simply by storing the state history as an array.

→ Next post: Covered in detail in the recursive components article

Challenge 3: Keyboard Shortcuts and the Stale Closure Problem

Problem: Keyboard handlers inside useEffect can't read the latest state

When registering a handler with window.addEventListener('keydown', handler) inside useEffect, the state referenced in the handler gets trapped in the closure from the time it was registered (stale closure).

In BlockTeXu, I changed pendingAction (a pending state for two-step shortcuts) and selectedStockIndex (stock selection) from useState to useRef, so the handler can always read the latest values synchronously.

→ Next post: "Solving the Stale Closure Problem in Keyboard Handlers with useRef"

Challenge 4: Image Export with KaTeX × html-to-image

Problem: When converting KaTeX-rendered equations to images, the text doesn't appear

html-to-image uses SVG foreignObject to convert DOM to images, but KaTeX's web fonts (@font-face) aren't embedded correctly, resulting in blank white images.

I tried multiple approaches: waiting with document.fonts.ready, calling toPng twice (the first call primes the font cache), and considering a switch to html2canvas.

→ Next post: "The Web Font Problem When Exporting KaTeX Equations as Images"

Challenge 5: Block Operations with HTML5 Drag & Drop

Problem: How do you support both adding from a palette and reordering within the workspace?

The design stores block definition JSON in the dataTransfer of the HTML5 Drag & Drop API, which is then parsed at the drop target.

To distinguish between adding new blocks (palette → workspace) and reordering (within workspace), the data includes a { reorder: true, index } flag, and the drop handler branches accordingly. Drops into nested slots are also supported, making event bubbling control (stopPropagation) essential.

→ Next post: "Design Patterns for Building a Block Editor with HTML5 Drag & Drop"

Challenge 6: Search Feature Design

Problem: How do you quickly find the right block among 216 options?

The implementation uses useMemo to control recalculation and separates category selection state from search state. During a search, all blocks across every category are included in the results. When the search is cleared, the display returns to category-based browsing.

Challenge 7: Vercel Deployment Pitfalls

Problem: It works locally, but the Vercel build fails

I ran into multiple obstacles before a successful deploy: Vite build failures caused by non-ASCII characters in Windows file paths (OneDrive/Desktop), and Linux file permission errors from committing node_modules to Git.

→ Next post: "Pitfalls When Deploying a Vite + React App to Vercel"

Challenge 8: SEO for a Single-Page Application

Problem: A React SPA's HTML is just <div id="root"></div>. Will search engines index it correctly?

I embedded meta descriptions, OGP tags, Twitter Cards, JSON-LD structured data, sitemap.xml, and robots.txt in the static HTML, then manually requested indexing via Google Search Console. Googlebot can execute JavaScript, so SPAs can be indexed — but including information in the initial HTML improves reliability.

→ Next post: "A Complete Guide to SEO for a Personal Dev Tool SPA"

Upcoming Posts

#	Topic	Summary
3	Recursive component design	PlacedBlock→BlockSlot recursion, depth management, immutable tree updates
4	Stale closure in keyboard handlers	useRef synchronization pattern, pendingAction design
5	KaTeX image export font issues	How html-to-image works, double rendering, html2canvas comparison
6	Block editor with Drag & Drop	dataTransfer design, nested drops, bubbling control
7	Vercel deployment pitfalls	Non-ASCII path issues, node_modules permission errors, build commands
8	SEO for SPAs	Complete setup of meta/OGP/JSON-LD/Search Console

Wrapping Up

Recursive components, immutable tree operations, Drag & Drop, web font image rendering — building a single editor touched on a surprisingly wide range of React topics.

I'll be sharing implementation code and lessons learned for each topic in upcoming posts.

If you're interested in recursive UI or tree operation design, I'd love to hear your thoughts in the comments. And if you'd like to try BlockTeXu yourself, check it out at blocktexu.com/en!

DEV Community: KernelX

KaTeX + html-to-image Outputs a Blank White Image — Here's Why and How to Fix It

The Naive Approach

Why It Happens: SVG foreignObject + Web Fonts

What Doesn't Work: document.fonts.ready

What Works: Call toPng Twice

The Full Implementation

Capturing a Dynamically Created DOM Node

Should You Switch to html2canvas?

Summary

Why Your React Keyboard Handler Always Reads Old State

The Setup: A Global Keyboard Handler

The Problem: Closures Capture Values, Not References

Attempted Fix: Add Everything to the Dependency Array

The Solution: useRef as a Stable Bridge

The Complete Pattern

React 19.2 Update: useEffectEvent

Comparison

Key Takeaways

How I Built Recursive UI for a Visual Math Editor in React

Representing Math as a Tree

The Recursive Component Design

Two-Component Pattern

PlacedBlock: Rendering a Single Block

BlockSlot: Rendering an Input Slot

Controlling Behavior with depth

1. Drag & Drop Control

2. Visual Scaling via CSS

Immutable Tree Updates

updateBlockInTree

Undo/Redo with a History Stack

On every state change: push to history

Undo: pop history, push current to future

Redo: pop future, push current to history

LaTeX Generation: Another Recursive Pass

Design Decisions Summary

Wrapping Up

8 Challenges I Faced Building a Complex Visual Editor in React

LaTeX Generation: Template Substitution

Challenge 1: Recursive Component Design

Challenge 2: Immutable Tree Updates

Challenge 3: Keyboard Shortcuts and the Stale Closure Problem

Challenge 4: Image Export with KaTeX × html-to-image

Challenge 5: Block Operations with HTML5 Drag & Drop

Challenge 6: Search Feature Design

Challenge 7: Vercel Deployment Pitfalls

Challenge 8: SEO for a Single-Page Application

Upcoming Posts

Wrapping Up

What Doesn't Work: `document.fonts.ready`

What Works: Call `toPng` Twice

Controlling Behavior with `depth`

`updateBlockInTree`