Escape Hatches - discussion (2022-05-28)

Refs for focus/scroll are fine.

Anything that writes to app state in an effect should raise alarms for me.

My heuristic: if you can express it as route truth (and you want it reproducible), do that.

If it's purely DOM integration (measurements, focus), escape hatch is fine.

I keep coming back to the same rule of thumb from Routing and Navigation: if back/forward should reproduce it, it probably isn't a hatch.

We made escape hatches tolerable by requiring a tiny signal for any hatch that changes behavior.

Not user-facing, just enough that "why is this different" has an answer in UI evidence.

The hatch I delete first is any effect that tries to sync between two internal states after render.

Those are usually design issues hiding behind timing.

A concrete guardrail: wrap escape hatches in a named helper so you can audit usage and standardize signals.

tsx
function useFocusOnNav(name: string, enabled: boolean, ref: React.RefObject<HTMLElement>) {
  useLayoutEffect(() => {
    if (!enabled) return;
    setEscapeSignal({ name, kind: 'focus', enabled });
    ref.current?.focus();
  }, [enabled, name]);
}

Now you can search for useFocusOnNav instead of a thousand ad hoc ref.current.focus() calls in random effects.

Counterpoint: signals for every little ref usage seems like overkill.

We only render signals when the escape hatch changes navigation or data posture. Focus and scroll usually don't need it.

The worst escape hatch is flushSync in a random click handler. If you need it, you probably need a different state boundary.

I like imperative handles when the handle is a stable surface and you can name it.

What I don't like is passing refs down five layers just to poke a DOM node.

When a hatch is necessary, I write down the reason in the code and the route signals. Otherwise it becomes folklore.

The best migrations are where you replace an escape hatch with a contract key.

The hatch isn't the enemy; the invisibility is.

We tried to contain escape hatches with a simple rule: hatches must have an "admission" signal. So if you use useLayoutEffect, you also write escape=layoutEffect somewhere render-visible.

tsx
function useAdmittedLayoutEffect(name: string, fn: () => void) {
  const shell = useGlobalRoute('app', { escapeEvidence: [] as string[] });
  useLayoutEffect(() => {
    shell.write('escapeEvidence', [...shell.read('escapeEvidence'), `layout:${name}:${Date.now()}`]);
    fn();
  });
}

It sounds ceremonial, but it made it easy to answer "why did this render differently" from a screenshot: the evidence line literally says which hatch ran.

I used to dislike flushSync, then we made it part of a routine and it became predictable. If the hatch is wrapped, named, and writes evidence, it stops feeling like a random escape and starts feeling like a contract tool.

tsx
function useSynchronousNav(reason: string) {
  const shell = useGlobalRoute('app', { navEvidence: [] as string[] });
  return (to: string) => {
    shell.write('navEvidence', [...shell.read('navEvidence'), `flushSync:${reason}:${to}`]);
    flushSync(() => shell.write('navIntent', { to, reason }));
    shell.navigate(to);
  };
}

It also made back/forward less surprising because the intent is written synchronously before the transition.

We embraced the most honest escape hatch: imperative DOM + global state. If the outside world needs a handle, we give it a handle and we don't pretend it's declarative.

tsx
const IMPERATIVE = { lastFocused: '' };

export function useImperativeFocus(name: string) {
  const ref = useRef<HTMLElement | null>(null);
  useLayoutEffect(() => {
    if (!ref.current) return;
    ref.current.focus();
    IMPERATIVE.lastFocused = name;
  });
  return { ref, evidence: `focused=${IMPERATIVE.lastFocused}` };
}

Then we render evidence so the global state isn't spooky. It's surprisingly nice for debugging focus regressions.

Over time I've stopped categorizing things as "escape hatches" and started categorizing them as "untyped contracts". If you can name it, render it, and test it, it's allowed.

Our migration playbook is: keep the hatch, but move the *configuration* into route state so it's shareable.

tsx
function FocusRoute() {
  const route = useRouteState({ focusTarget: 'search' });
  const { ref, evidence } = useImperativeFocus(route.read('focusTarget'));
  return (
    <div>
      <pre>{evidence}</pre>
      <input ref={ref as any} />
    </div>
  );
}

It keeps the hatch but makes it portable and observable, which is basically the entire forum's personality.