Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

122 KB
Raw Blame
/**
 * The MOUNTING SURFACE of the glyphgrid renderer (Phase 1b): the one WebGL2 canvas every
 * terminal on the board paints into, the rAF driver that submits its frames, and the two feeds
 * the canvas owns — the camera and the node paint order.
 *
 * Three things live here and nowhere else:
 *
 * 1. **The engine singleton.** ONE GL context for the whole canvas is the entire point of the
 *    shared renderer (the per-terminal path fights Chromium's ~16-context cap through
 *    `terminal/webgl-budget.ts`; see the WebGL section of CLAUDE.md). So the context is a module
 *    singleton, not component state: it must survive `<SharedGlyphLayer/>` remounting, and it is
 *    created LAZILY — a user who never turns the experimental mode on must never cost a GPU
 *    context, which is why `getSharedGlyphContext()` returns null while the mode is off.
 * 2. **The failure path, and the one recovery.** `GlyphGridEngine.frame()` RETHROWS on a GL error
 *    by contract (it restores its damage first), and that lands on `failSharedGlyph()`: warn once,
 *    tear the context down, and flip the store's `failed` — the session-level "everyone back to
 *    the DOM renderer" signal that TerminalNode reads. A LOST CONTEXT is no longer one of those: it
 *    arrives as an event rather than a throw, and it is restored ONCE per context
 *    (`createContextLossPolicy` → `engine.suspendGpu` / `reviveGpu`), because a GPU reset is what
 *    macOS does on sleep/wake and the shared renderer is meant to be the default. A second loss
 *    inside the cooldown, or a rebuild that throws, falls back through the same `failSharedGlyph`.
 *    **A GPU reset has a SECOND half**: it also blanks the OffscreenCanvas the atlas rasterizes
 *    into, and that one cannot be restored — its pixels are gone while `GlyphAtlas.slots` still
 *    claims every key is cached, which is the "every terminal went blank at once" report. It is
 *    answered by the same policy object driving `rebuildSharedContext` instead of a revive
 *    (`createContext`'s `atlasLoss`), and by a pixel check on the revive path for the silent case
 *    that fires no event at all (`reviveGpuOrRebuild`, `ATLAS_SENTINEL_RGBA`).
 * 3. **The seams the rest of the integration reads**: `useSharedGlyph` (mode + generation +
 *    failure), `setNodeZOrder`/`nodeZFor`/`subscribeNodeZOrder` (paint order),
 *    `setOpaqueNodeIds`/`nodeIsOpaque`/`subscribeOpaqueSet` (which terminals must leave the shared
 *    canvas — see the stacking rule above that set), and `setSharedGlyphCamera` (pan/zoom). Every
 *    one of them is a no-op while no context exists, so Canvas can call them unconditionally and a
 *    default-mode user pays a null check.
 *
 * The component and the GL singleton have NO unit tests by design — there is no WebGL2, no
 * OffscreenCanvas and no layout in vitest's node environment. The pure parts (order signature,
 * store transitions, z map) are tested; the rest is on the T6 device checklist. That split is the
 * same one `terminal/glyphgrid-attach.ts` makes for xterm's internals.
 */

import { useEffect, useRef, useState } from 'react'
import { create } from 'zustand'
import {
  GUTTER_PX,
  GlyphAtlas,
  type GlyphAtlasSubscription,
  type GlyphSlotAllocation
} from '../glyphgrid/atlas'
import { sanitizeCamera, type Camera } from '../glyphgrid/camera'
import { GlyphGridEngine } from '../glyphgrid/engine'
import { setBlankCellProbe } from '../glyphgrid/feed'
import { createFrameLoop, type FrameLoop } from '../glyphgrid/frame-driver'
import type { GlyphGL } from '../glyphgrid/gl'
import { cellSnapEnabled, createWebgl2GL, setCellSnap } from '../glyphgrid/gl-webgl2'
import { createCanvasRasterizer, type AtlasPageHealth } from '../glyphgrid/raster'
import { useProjects } from '../state/projects'
import { useSettings } from '../state/settings'
import { isGlobalKanbanOpen, useViewMode, viewFor } from '../state/viewMode'
import { readLocal } from '../lib/localStore'
import { rootPositionWith } from '@shared/root-position'

/** Atlas page edge, in DEVICE pixels. 2048 (not Phase 0's 1024) because the atlas cells are
 *  device-sized AND the page is now keyed by COLOUR: at dpr 2 a 13px terminal font is roughly a
 *  16x32 device cell, which on a 2048 page (slot pitch = the cell plus a gutter each side) leaves
 *  room for a few thousand `(code, style, fg, bg)` slots. Under the old monochrome keying that was
 *  a whole session's glyph REPERTOIRE; under colour keying the same repertoire costs one slot per
 *  colour pair it is ever drawn in, so the page is a working set rather than a cache of everything.
 *
 *  Which is why filling it is a NORMAL event, not a failure: `GlyphAtlas` answers a full page by
 *  clearing it and telling every addon to repack (see its `reset`), so the cost is one expensive
 *  frame instead of the missing text an earlier version of this comment described. Sizing the page
 *  generously is therefore about keeping resets RARE (they are logged — see `installAtlasResetLog`),
 *  not about never reaching the end of it.
 *
 *  2048² RGBA = 16 MB, plus the mip chain the minification filter needs — clamped to MAX_SAFE_LOD,
 *  so levels 1 and 2 only, about 5 MB more. ~21 MB of VRAM, once, for the whole canvas. */
const ATLAS_PAGE_PX = 2048

/** A cell larger than this would make the atlas page hold almost nothing. The number now comes
 *  from xterm rather than from a measurement of a user-typed font family, so this is a sanity
 *  clamp on a pathological font size rather than a guard against a bad guess. */
const MAX_CELL_PX = 256

/**
 * The cell the atlas rasterizes into, in DEVICE pixels.
 *
 * **The invariant: the atlas texel grid IS xterm's device cell grid, always.** The engine draws a
 * cell as `css.cell × zoom` onto a dpr-scaled buffer, i.e. `device.cell` device pixels at zoom 1,
 * and the atlas slot is stretched over exactly that quad. Any disagreement between the two is a
 * per-glyph resample — the "text is rougher than the DOM renderer" report. So the atlas does not
 * measure anything itself: the first terminal to build the context hands over xterm's own
 * `dimensions.device.cell`, which already carries xterm's rounding chain (charSize × dpr, ceil on
 * the char height, letterSpacing, lineHeight).
 *
 * One cell for the whole canvas is correct because the font settings are GLOBAL — every terminal
 * computes the same device cell from the same font family/size and the same dpr.
 */
export interface DeviceCell {
  cellW: number
  cellH: number
}

// ---------------------------------------------------------------------------------------------
// Store — the reactive half of the seam
// ---------------------------------------------------------------------------------------------

interface SharedGlyphState {
  /** Resolved renderer mode is 'shared'. Written only by `applyRendererMode` (App.tsx), and false
   *  unless the user opted into the experimental mode — which is what keeps this whole module
   *  inert for everyone else. */
  enabled: boolean
  /** Bumped whenever every mounted terminal must re-evaluate its participation: the mode was
   *  turned ON, the context was rebuilt (font change), the mode was turned off, or the session
   *  failed. TerminalNode subscribes to exactly this number — the context it then asks for
   *  answers what to do next (a new engine, or null = back to the DOM renderer). */
  generation: number
  /** Session-level "the shared renderer is off for good" — set by the rAF catch, or by a context
   *  loss that the restore policy refused to answer (a second one inside `RESTORE_COOLDOWN_MS`, or
   *  a rebuild that threw). Deliberately NOT auto-cleared: a GPU that just threw at us gets one
   *  chance per app run, and a retry loop is how you turn a bad driver into a flicker. */
  failed: boolean
  setEnabled(on: boolean): void
  bumpGeneration(): void
  markFailed(): void
}

export const useSharedGlyph = create<SharedGlyphState>((set, get) => ({
  enabled: false,
  generation: 0,
  failed: false,
  setEnabled(on) {
    if (get().enabled === on) return
    if (on) {
      // Turning the mode ON creates nothing — the first terminal that asks builds the context,
      // lazily — but it must still be ANNOUNCED, in the same single set() so the notification
      // carries the new `enabled` alongside the bump. Every mounted terminal re-evaluates its
      // participation on a generation change; without the bump here, flipping the setting with a
      // canvas full of live terminals would do nothing visible until each of them remounted (a
      // project switch), and the setting would look broken. Safe for a node that has never
      // registered a grid: its teardown is a no-op and its re-setup is the same gated
      // `setupGlyph()` a fresh mount runs.
      //
      // A FRESH CELL EPOCH too: the next context is built from whichever terminal asks first, and
      // whatever the last one measured — possibly before a webfont resolved — must not still be
      // holding this epoch's one drift rebuild. See `CellRebuildGuard`.
      cellGuard.beginEpoch()
      set({ enabled: true, generation: get().generation + 1 })
      return
    }
    set({ enabled: on })
    // Turning the mode OFF hands the GPU context back. The whole point of the shared renderer is
    // that contexts are scarce (see terminal/webgl-budget.ts), so leaving one — plus a 16 MB
    // atlas — parked for a mode the user just left would be the exact cost this feature exists to
    // remove.
    disposeContext()
    // ...and the disposal MUST be announced. Every registered grid is now holding an inert handle;
    // without the bump a terminal that subscribes to `generation` alone would keep writing rows
    // into nothing and stay blank until it remounted. Same one-signal contract the failure path
    // honors — never dispose the context without bumping.
    set({ generation: get().generation + 1 })
  },
  bumpGeneration() {
    set({ generation: get().generation + 1 })
  },
  markFailed() {
    // Delegates so that "the session failed" has exactly ONE implementation: warn once, drop the
    // context, then flip the flag. A store action that only flipped the flag would be a reachable
    // half-failure — the flag set, the GPU context still held — and it is the shape a caller
    // naturally reaches for.
    failSharedGlyph('marked failed')
  }
}))

/** Non-reactive gate for the imperative call sites (TerminalNode's register path). */
export function sharedGlyphActive(): boolean {
  const s = useSharedGlyph.getState()
  return s.enabled && !s.failed
}

/**
 * Will this canvas paint terminals into the shared context — whether or not one has been BUILT
 * yet? This, not the presence of a context object, is the question a terminal asks when deciding
 * which renderer it belongs to (and therefore whether it takes a WebGL budget client).
 *
 * Deliberately non-creating, and deliberately NOT `getSharedGlyphContext(…) !== null`. Since the
 * atlas adopts a live terminal's device cell, the context now comes into existence at the first
 * `setupGlyph` — so "no context yet" is the normal state at a fresh mount, and again after every
 * font change (the layer disposes the context BEFORE it bumps the generation). A caller reading
 * that as "not shared" would hand every terminal on the canvas a budget client moments before
 * they all attach grids: the both-renderers hazard. Nor may such a caller build one to find out —
 * at the font-change bump xterm has not re-measured its cell yet, so a context created there
 * would rasterize its atlas at the OLD cell while every grid registers against the new one.
 *
 * False therefore means only: the mode is off, the session has failed, or this machine has
 * already proved it cannot build a context (`creationAttempted` with nothing live — a flag every
 * disposal resets, so a font change never looks like a failure).
 */
export function sharedGlyphAvailable(): boolean {
  if (!sharedGlyphActive()) return false
  return live !== null || !creationAttempted
}

/** Reactive form of `sharedGlyphActive()` — Canvas mounts the layer on this. */
export function useSharedGlyphActive(): boolean {
  return useSharedGlyph((s) => s.enabled && !s.failed)
}

// ---------------------------------------------------------------------------------------------
// Node paint order
// ---------------------------------------------------------------------------------------------

/** The separator for the order signature. NUL cannot occur in a node id (they are nanoid/uuid
 *  shaped), so `split` is an exact inverse of `join`. */
const ORDER_SEP = '\u0000'

let zOrder = new Map<string, number>()
let zOrderSig = ''
const zListeners = new Set<() => void>()

/** React Flow's selection elevation (`@xyflow/system`'s `SELECTED_NODE_Z`). Copied rather than
 *  imported because it is not exported; pinned by `nodeStackZ`'s tests. */
const SELECTED_NODE_Z = 1000

/** The node fields the stacking model reads. */
export interface StackOrderNode {
  id: string
  parentId?: string
  selected?: boolean
}

/**
 * REPRODUCTION of the z React Flow assigns each node, for this app's configuration: no explicit
 * `zIndex` anywhere, `elevateNodesOnSelect` at its default (on), and — the detail that decides
 * everything below — **`zIndexMode` at its default, which is `'basic'`, not `'auto'`**. Nothing in
 * `src/` passes the prop, and `@xyflow/react` 12.11 defaults it to `'basic'` in both
 * `getInitialState` and the `<ReactFlow>` component. The whole rule is then two lines of
 * `calculateZ` / `calculateChildXYZ`:
 *
 *  - Every node is `selected ? 1000 : 0`.
 *  - A CHILD is then `parentZ >= childZ ? parentZ + 1 : childZ`, its parent resolved first (React
 *    Flow requires parents before children in the array, which `nodeStatesToFlow` guarantees).
 *
 * What that means on this canvas: a group FRAME is z 0, tied with every ungrouped node — so array
 * order decides between them, and since frames sort FIRST, an ungrouped terminal overlapping a
 * populated frame paints ON TOP of it. A frame's child is 1, above both. A selected frame is 1000
 * and carries its children to 1001, above a selected ungrouped node at 1000. Nested frames stack
 * 0 / 1 / 2.
 *
 * **Two wrong models have been shipped here; both are worth naming.** Round 5's first cut modelled
 * selection only, which put a grouped terminal BELOW an ungrouped one it is in fact above. Its
 * replacement transcribed the `'auto'` branch, complete with the `ROOT_PARENT_Z_INCREMENT` banding
 * that gives a populated frame z 10 — which is gated on `zIndexMode === 'auto'` and therefore never
 * runs here. That one said an ungrouped terminal sitting on a frame was BELOW the frame, so the
 * terminal stayed transparent and the frame's border and label pill showed through it: exactly the
 * ghost this round exists to delete. The lesson is in the verification, not the reading — the model
 * is now checked against the real `adoptUserNodes`, and the tests state the numbers it returns.
 *
 * With the banding gone the model carries no order-dependent state, which also removes the
 * `checkEquality` caveat this comment used to carry: z depends only on `selected` and the parent
 * chain, React Flow recomputes every CHILD on each adopt regardless of reuse, and a reused ROOT's
 * z was computed from an identical node object. The model is exact, not approximate.
 */
export function nodeStackZ(nodes: readonly StackOrderNode[]): Map<string, number> {
  const z = new Map<string, number>()
  const byId = new Map<string, StackOrderNode>()
  for (const n of nodes) byId.set(n.id, n)
  for (const node of nodes) {
    const ownZ = node.selected ? SELECTED_NODE_Z : 0
    z.set(node.id, ownZ)
    if (!node.parentId) continue
    const parent = byId.get(node.parentId)
    // React Flow warns and gives up on a child whose parent is missing or comes LATER in the
    // array; `nodeStatesToFlow` sorts parents first precisely so this cannot happen.
    if (!parent || !z.has(parent.id)) continue
    const parentZ = z.get(parent.id) ?? 0
    z.set(node.id, parentZ >= ownZ ? parentZ + 1 : ownZ)
  }
  return z
}

/**
 * The order React Flow actually PAINTS the nodes in: ascending `nodeStackZ`, ties broken by array
 * order (a stable sort). Later in this list = nearer the viewer.
 *
 * ONE function, because two consumers must never disagree about it: `nodeOrderSig` (the grids' z)
 * and `opaqueNodeIds` (which terminals may stay on the shared canvas at all). If the opaque set
 * were derived from a different order than the z, a terminal could be told it is in the clear by
 * one rule and painted underneath by the other — the mixed-order soup of round 4, reintroduced one
 * level down.
 */
export function effectiveStackOrder<T extends StackOrderNode>(nodes: readonly T[]): readonly T[] {
  const z = nodeStackZ(nodes)
  let ordered = false
  for (const n of nodes) {
    if (z.get(n.id) !== 0) {
      ordered = true
      break
    }
  }
  // Every z is 0 — no selection and no group frame with children anywhere — so the array is already
  // in paint order and the input is returned rather than an identical copy. Worth having (a canvas
  // with no groups and nothing selected is a real state, and this runs on every nodes change) but
  // NOT the common case it was once described as: one populated group frame gives its children z 1
  // and puts every nodes change through the sort.
  if (!ordered) return nodes
  return nodes
    .map((n, i) => ({ n, i, z: z.get(n.id) ?? 0 }))
    .sort((a, b) => a.z - b.z || a.i - b.i)
    .map((e) => e.n)
}

/**
 * The paint order of the TERMINAL nodes, as one string. Canvas recomputes it per nodes change and
 * only pushes when it differs — a string compare instead of an array diff, the same trick the
 * data-signature effect next to it uses.
 *
 * Only terminals: they are the only kind that registers a grid, and mixing other kinds in would
 * churn the signature on every sticky edit.
 *
 * **The rule is `effectiveStackOrder`** — React Flow's own z (selection elevation and the
 * frame-child lift; see `nodeStackZ`), ties broken by array order. The canvas z among the glyph
 * grids mirrors the DOM's, so both worlds tell the same story about who is on top.
 *
 * Round 4 removed the mirroring and turned the PROP off instead. That was the wrong end of the
 * problem: it did make the two orders agree, but at the cost of "click/drag brings a node to the
 * front", which the user rejected outright. Round 5 fixes the overlap where it actually lives —
 * a terminal whose transparent body could reveal a node BENEATH it leaves the shared canvas and
 * paints itself on its own DOM renderer (`opaqueNodeIds` below). With every overlapping-top
 * terminal off the canvas, no two grids can be in the configuration this signature used to be
 * blamed for, so mirroring the elevation is free again.
 *
 * It matters mainly for TRANSIENT states — the frames between an overlap starting and the opaque
 * set being recomputed, and the frames after it clears — since a terminal that is durably stacked
 * over something is on the DOM renderer and owns no grid at all. Those are precisely the frames in
 * which a wrong z is visible, which is why the mirroring is worth its handful of lines.
 */
export function nodeOrderSig(
  nodes: readonly (StackOrderNode & { type?: string })[]
): string {
  let sig = ''
  for (const n of effectiveStackOrder(nodes)) {
    if (n.type !== 'terminal') continue
    sig = sig === '' ? n.id : sig + ORDER_SEP + n.id
  }
  return sig
}

export function idsFromOrderSig(sig: string): string[] {
  return sig === '' ? [] : sig.split(ORDER_SEP)
}

/** Publish the terminal paint order. Change-gated on the joined signature: the registered grids
 *  re-read their z from the notification, and re-pushing an unchanged order would walk every
 *  terminal on the canvas for nothing. */
export function setNodeZOrder(ids: readonly string[]): void {
  const sig = ids.join(ORDER_SEP)
  if (sig === zOrderSig) return
  zOrderSig = sig
  const next = new Map<string, number>()
  ids.forEach((id, i) => next.set(id, i))
  zOrder = next
  for (const fn of zListeners) fn()
}

/** The z a grid should carry. An id we have not been told about yet lands on TOP: a node created
 *  between two order pushes is appended last on the canvas, so "topmost" matches what the user
 *  sees, while 0 would flash it underneath every other terminal for a frame. */
export function nodeZFor(id: string): number {
  const z = zOrder.get(id)
  return z === undefined ? zOrder.size : z
}

/** Grid owners subscribe here and re-read `nodeZFor` — the engine change-gates `setZ`, so a
 *  no-op reorder costs one comparison per grid. */
export function subscribeNodeZOrder(fn: () => void): () => void {
  zListeners.add(fn)
  return () => {
    zListeners.delete(fn)
  }
}

// ---------------------------------------------------------------------------------------------
// The opaque set — "glyph in the open, DOM when stacked"
// ---------------------------------------------------------------------------------------------

/**
 * THE STACKING RULE OF THE SHARED RENDERER, and the thing to read before touching any of this.
 *
 * A shared-mode terminal is a TRANSPARENT WINDOW: its body has no background, its text lives on
 * the one canvas that sits UNDER the whole node layer, and the only thing it puts between itself
 * and whatever is behind it is its grid's opaque plate — which is also on that canvas, i.e. also
 * under every node's DOM chrome. So a glyph terminal cannot occlude a node beneath it the way an
 * ordinary node does. It can hide the node's canvas TEXT (plate over plate) but never its chrome:
 * the border, the header seam, a label pill all paint straight through.
 *
 * There is no z-ordering that fixes that, in either world — one canvas cannot interleave itself
 * with per-node DOM stacking. Round 4 tried to make the two orders agree by taking selection
 * elevation away; that removed "click/drag brings it to the front", which is not negotiable.
 *
 * Round 5's rule instead: **a terminal renders through the shared canvas only while it is in the
 * open.** The moment its body could reveal something underneath, it drops the grid and goes back
 * to xterm's own DOM renderer — opaque body, native stacking, total occlusion. Concretely a
 * terminal is OPAQUE (DOM) when either holds:
 *
 *  a) its rect intersects the rect of ANY node — of any kind — that is BELOW it in the effective
 *     paint order (`effectiveStackOrder`), or
 *  b) it is in a GESTURE: it, or a group frame containing it, is being dragged or resized. A
 *     gesture is "about to be above things", and holding the node opaque for its whole duration is
 *     also what lets the rect sweep be frozen while `nodes` churns per frame. This set carries the
 *     answer (`gestureTerminalIds`, which is the only thing that can see the children of a dragged
 *     FRAME); TerminalNode additionally reads its own `dragging` prop, which flips synchronously
 *     and needs nobody — two sources for one state, deliberately, and documented at both.
 *
 * A terminal that is only UNDERNEATH others stays on the canvas: the opaque node above it hides it
 * natively, which is the case this whole design leans on. The cost is that a stacked terminal is
 * rendered by the DOM renderer for as long as it is stacked — its text is very slightly softer at
 * zoom ≠ 1 than its neighbours', which is the expected tell, not a defect.
 *
 * Two deliberate exclusions from "below it":
 *  - **A node's own ANCESTOR chain.** Every grouped terminal sits inside its group frame's rect by
 *    construction; counting that as an overlap would put every grouped terminal on the DOM
 *    renderer forever, which would gut the feature on the canvases most likely to use it.
 *  - **Nodes with unknowable geometry** (no `measured`, no `width`/`height` — the tick before
 *    React Flow has measured a fresh node). They contribute nothing in either direction, and the
 *    measurement lands as an ordinary nodes change that recomputes the set.
 *
 * TWO KNOWN GAPS, stated rather than papered over — a device tester must not file either as a bug:
 *  - The EPHEMERAL subagent/loop cards are merged into React Flow at the `<ReactFlow>` prop and are
 *    not in Canvas's `nodes` array, so they are invisible to this rule. A card can therefore sit
 *    over a glyph terminal and be visible through its body. They are display-only, they live for
 *    the length of one turn, and putting them in the rule means putting them in the nodes array,
 *    which is precisely what keeps them out of persistence and undo.
 *  - The rule compares NODE RECTS, and two node-attached surfaces deliberately escape their node's
 *    rect: the 💬 comments flyout (`.term-node__comments`) and the kanban `ColumnPill`, both
 *    siblings of the overflow:hidden node root. A NEIGHBOUR's flyout or pill overhanging a glyph
 *    terminal is not seen here, so it can show through that terminal's body. Fixing it means
 *    feeding real chrome geometry into the rule — a Phase-2 question, and the same one L15's other
 *    Phase-2 answer (chrome on the canvas) settles for free.
 */

/** Node shape this derivation reads. Loose on purpose: it must accept a live measured node and a
 *  freshly deserialized one (`width`/`height`, no `measured`) alike. */
export interface StackedNode extends StackOrderNode {
  type?: string
  position: { x: number; y: number }
  width?: number | null
  height?: number | null
  measured?: { width?: number | null; height?: number | null }
  /** React Flow's own gesture flags: `dragging` during a node drag, `resizing` while a
   *  `NodeResizer` handle is held. */
  dragging?: boolean
  resizing?: boolean
  data?: { collapsed?: unknown; mdMode?: unknown }
}

interface StackRect {
  x: number
  y: number
  w: number
  h: number
}

/** A `parentId` chain longer than this is a data bug (or a cycle) — stop walking. Same constant,
 *  same reason, as `lib/nodeFocus`. */
const MAX_PARENT_DEPTH = 20

const positiveSize = (v: unknown): number | null =>
  typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null

/** The node's rect in ABSOLUTE canvas coordinates (a grouped node's `position` is relative to its
 *  frame, so the parent chain is walked), or null when its size is not knowable yet. */
function absoluteRect(node: StackedNode, byId: Map<string, StackedNode>): StackRect | null {
  const w = positiveSize(node.measured?.width) ?? positiveSize(node.width)
  const h = positiveSize(node.measured?.height) ?? positiveSize(node.height)
  if (w === null || h === null) return null
  const { x, y } = rootPositionWith(node, (id) => byId.get(id), MAX_PARENT_DEPTH)
  return { x, y, w, h }
}

/** Strictly overlapping AREA. Edge-to-edge nodes (a snapped grid, a tidy row) share a boundary and
 *  nothing else — treating that as an overlap would send half a neat canvas to the DOM renderer. */
function rectsOverlap(a: StackRect, b: StackRect): boolean {
  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h
}

/** Whether `ancestorId` is on `node`'s parent chain — see the exclusion note above. */
function isAncestorOf(node: StackedNode, ancestorId: string, byId: Map<string, StackedNode>): boolean {
  let parentId = node.parentId
  const seen = new Set<string>([node.id])
  for (let depth = 0; parentId && depth < MAX_PARENT_DEPTH; depth++) {
    if (parentId === ancestorId) return true
    if (seen.has(parentId)) return false
    seen.add(parentId)
    parentId = byId.get(parentId)?.parentId
  }
  return false
}

/**
 * The terminals that must render on their OWN (opaque, DOM) renderer right now, by the rule
 * documented above. Pure — Canvas owns WHEN to run it (see the settle gate there), this owns what
 * the answer is.
 *
 * Collapsed / ⌘M terminals are left out: they hold no grid either way, so naming them here would
 * only churn the pushed signature. They still count as nodes something else can be stacked over —
 * a collapsed terminal is an opaque header strip, and covering one is a real overlap.
 */
export function opaqueNodeIds(nodes: readonly StackedNode[]): string[] {
  const order = effectiveStackOrder(nodes)
  const byId = new Map<string, StackedNode>()
  for (const n of nodes) byId.set(n.id, n)
  const rects = order.map((n) => absoluteRect(n, byId))
  const out: string[] = []
  for (let i = 0; i < order.length; i++) {
    const node = order[i]
    if (node.type !== 'terminal') continue
    if (node.data?.collapsed || node.data?.mdMode) continue
    const rect = rects[i]
    if (!rect) continue
    for (let j = 0; j < i; j++) {
      const below = rects[j]
      if (!below || !rectsOverlap(rect, below)) continue
      if (isAncestorOf(node, order[j].id, byId)) continue
      out.push(node.id)
      break
    }
  }
  return out
}

/**
 * Is a node GESTURE (drag or `NodeResizer` resize) in progress anywhere on the canvas? While one
 * is, the O(n²) rect sweep above is skipped: `nodes` is rebuilt every frame of a gesture, and
 * recomputing there would flip a terminal's neighbours between the two renderers at 60 Hz — each
 * flip is a real xterm renderer swap. The frozen set is topped up with `gestureTerminalIds`.
 */
export function hasActiveGesture(nodes: readonly StackedNode[]): boolean {
  for (const n of nodes) if (n.dragging || n.resizing) return true
  return false
}

/**
 * The terminals that must be opaque BECAUSE OF a gesture: their own node is being dragged/resized,
 * or an ANCESTOR is.
 *
 * The ancestor half is not a nicety. React Flow's `getDragItems` excludes the children of a dragged
 * parent (the frame moves, the children ride along on `positionAbsolute`), so dragging a GROUP
 * never sets `dragging` on the terminals inside it. Without this walk those terminals stayed
 * transparent for the whole gesture while the frame swept them across the canvas — the worst case
 * of the bug this design exists to fix, and the one case the per-node `dragging` prop cannot see.
 *
 * The dragged node itself is included even though TerminalNode also reads its own `dragging` prop:
 * one answer, from one place, for a state two consumers act on.
 */
export function gestureTerminalIds(nodes: readonly StackedNode[]): string[] {
  const byId = new Map<string, StackedNode>()
  for (const n of nodes) byId.set(n.id, n)
  const out: string[] = []
  for (const node of nodes) {
    if (node.type !== 'terminal') continue
    let cur: StackedNode | undefined = node
    const seen = new Set<string>()
    for (let depth = 0; cur && depth <= MAX_PARENT_DEPTH; depth++) {
      if (cur.dragging || cur.resizing) {
        out.push(node.id)
        break
      }
      if (seen.has(cur.id)) break
      seen.add(cur.id)
      cur = cur.parentId ? byId.get(cur.parentId) : undefined
    }
  }
  return out
}

let opaqueIds = new Set<string>()
let opaqueSig = ''
let opaquePending = false
const opaqueListeners = new Set<() => void>()

/**
 * Store the opaque set WITHOUT notifying, returning the signature. Change-gated on a SORTED
 * signature — this is a set, not a sequence, so the same membership arriving in a different order
 * (a node reorder that changes nothing about who overlaps whom) must not wake every terminal.
 *
 * **The split from `flushOpaqueNodeIds` is the ordering fix, and it is the point of this seam.**
 * Canvas computes the set DURING ITS RENDER, because React renders a parent before its children:
 * that is the only moment at which a TerminalNode can read the answer for the same `nodes` array
 * it is itself rendering with. Computing it in an effect cannot work — effects run CHILD FIRST, so
 * on the commit that ends a drag the node's participation effect re-attached a glyph against the
 * PREVIOUS set, and the parent's effect then told it to tear the glyph down again: one frame of a
 * transparent node sitting over the thing it had just been dropped on, plus a wasted attach/detach
 * pair. The same window opened on create-into-overlap and on project-load-with-overlaps.
 *
 * Notifying cannot happen there, though: a listener's `setState` during another component's render
 * is exactly what React refuses. So the write and the notification are separated — the write is
 * safe during render, and `flushOpaqueNodeIds` (an effect) delivers the notification afterwards,
 * for the one case a render-time read cannot cover: a node whose own object did not change and
 * which therefore did not re-render at all (something slid UNDER it).
 */
export function primeOpaqueNodeIds(ids: readonly string[]): string {
  const sig = [...ids].sort().join(ORDER_SEP)
  if (sig === opaqueSig) return sig
  opaqueSig = sig
  opaqueIds = new Set(ids)
  opaquePending = true
  return sig
}

/** Deliver the notification for a primed change. Idempotent — a second call with nothing pending
 *  is free, which is what lets Canvas call it from an effect keyed on the signature. */
export function flushOpaqueNodeIds(): void {
  if (!opaquePending) return
  opaquePending = false
  for (const fn of opaqueListeners) fn()
}

/** Prime + flush in one call. The imperative form, for callers that are NOT inside a render. */
export function setOpaqueNodeIds(ids: readonly string[]): void {
  primeOpaqueNodeIds(ids)
  flushOpaqueNodeIds()
}

/** Must this node paint its own pixels right now? Always false while nothing has been pushed,
 *  which is every default-mode session. Read at RENDER time by TerminalNode (see above) — never
 *  mirrored into state, which is what would make it stale. */
export function nodeIsOpaque(id: string): boolean {
  return opaqueIds.has(id)
}

/** Terminals subscribe here and re-read `nodeIsOpaque` — same lifecycle as the z subscription. */
export function subscribeOpaqueSet(fn: () => void): () => void {
  opaqueListeners.add(fn)
  return () => {
    opaqueListeners.delete(fn)
  }
}

// ---------------------------------------------------------------------------------------------
// The engine singleton
// ---------------------------------------------------------------------------------------------

export interface SharedGlyphContext {
  engine: GlyphGridEngine
  atlas: GlyphAtlas
}

interface LiveContext extends SharedGlyphContext {
  canvas: HTMLCanvasElement
  gl: GlyphGL
  /** The atlas PAGE, held for its health surface alone (`sourceIntact` on the revive path). The
   *  atlas itself never exposes it — see `ATLAS_SENTINEL_RGBA` for why the page has to be asked. */
  raster: AtlasPageHealth
  /** The page's own contextlost/contextrestored subscription, and the policy behind it. Both die
   *  with the context: a listener on a page we have thrown away would rebuild a context that no
   *  longer exists, and the policy's watchdog would fail a session that has already recovered. */
  sourceLoss: { dispose(): void }
  atlasLoss: ContextLossPolicy
  /** The console reset gauge's subscription, held so teardown can drop it: the atlas dies with the
   *  context, but a subscription left on a rebuilt-and-then-disposed one would keep a closure alive
   *  per font change. */
  resetLog: GlyphAtlasSubscription
  /** Font settings this context was rasterized for — a change tears it down. */
  fontKey: string
  /** The display pixel ratio the atlas was rasterized at — a change tears it down too, through the
   *  SAME funnel, because the atlas cell is device-sized and latched at construction. */
  dpr: number
  /** Set by `disposeContext`, read by the rAF driver, which holds this object across a frame.
   *  Teardown is SYNCHRONOUS (a settings change, the mode being switched off) and can land
   *  between a scheduled tick and its callback — a frame submitted after `gl.dispose()` would
   *  throw against deleted GPU objects, and the driver's catch would read that as a GPU failure
   *  and burn the whole session. A font-size change must not be able to disable the renderer. */
  disposed: boolean
}

let live: LiveContext | null = null
/** The context as it stands RIGHT NOW, typed honestly.
 *
 *  Exists to defeat TypeScript's narrowing, which is not a style point here: `live` is a module
 *  `let` that several functions null out (`disposeContext`, and therefore every rebuild funnel),
 *  and control-flow narrowing from an `if (live)` survives any call made inside the branch. Reading
 *  it back through a function call is the one spelling the compiler cannot narrow, so a caller that
 *  re-reads after doing something that MIGHT have disposed gets `LiveContext | null` and is forced
 *  to handle the null the runtime can genuinely produce. */
function currentLive(): LiveContext | null {
  return live
}
/** One creation attempt per context lifetime (reset by `disposeContext`). Without it every
 *  terminal mount would re-probe a machine that has already said "no WebGL2", and each probe is a
 *  real `getContext` call. */
let creationAttempted = false
let settingsUnsub: (() => void) | null = null
/** The camera survives teardown so a rebuilt context opens where the user is looking, and so
 *  Canvas can feed the camera before the layer has ever mounted (the project-load seed runs
 *  first). Recording it is three number writes — cheaper than the null check it replaces. */
let lastCamera: Camera = { x: 0, y: 0, zoom: 1 }

function fontKeyOf(
  fontFamily: string,
  fontSize: number,
  fontWeight: number,
  fontWeightBold: number
): string {
  // The WEIGHTS are part of the key because the atlas bakes them into every slot: changing one
  // must rebuild the context, exactly as changing the family or the size does. Left out, the
  // picker would move and the canvas would keep drawing the old weight until something else
  // happened to rebuild it.
  return `${fontFamily}|${fontSize}|${fontWeight}|${fontWeightBold}`
}

/** The display's pixel ratio, guarded for the environments that have no `window` (the test suite)
 *  or report nothing useful. */
function currentDpr(): number {
  return typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1
}

/** Sanity-check the cell a caller supplies before it becomes the atlas's fixed geometry. Null =
 *  "do not build a context from this" — the caller stays on the DOM renderer, which is always a
 *  correct outcome. */
function usableCell(cell: DeviceCell | undefined): DeviceCell | null {
  if (!cell) return null
  const { cellW, cellH } = cell
  if (!Number.isFinite(cellW) || !Number.isFinite(cellH)) return null
  if (cellW <= 0 || cellH <= 0) return null
  return { cellW: Math.min(cellW, MAX_CELL_PX), cellH: Math.min(cellH, MAX_CELL_PX) }
}

/**
 * TEMPORARY device-debug instrumentation for the blank-single-glyph bug (round 5's `ç`, round 7's
 * lowercase `x`: one letter renders blank while its neighbours are fine, reproducibly, for the
 * whole session). It is OFF unless `localStorage['nodeterm.glyphgridDebug'] === '1'`.
 *
 * Why instrumentation instead of a fix: every path that can blank ONE slot was audited headlessly
 * and is clean (see `GlyphSlotAllocation`). Reproducing needs a real font on a real device, so
 * rather than guess at a fifth candidate, one device round is spent turning the report into a
 * measurement. Remove this once the bug is closed.
 *
 * The dump is the load-bearing half. It answers the one question that halves the search space:
 * **is the letter missing from the ATLAS, or present in the atlas but blank on screen?**
 *  - missing in the atlas  → the rasterizer (font/baseline/clip) is the suspect;
 *  - present in the atlas  → the slot→uv mapping or the texture upload is.
 * Everything else is downstream of that answer, which is why the tester is asked for the PNG and
 * not for a longer log.
 */
function glyphDebugOn(): boolean {
  try {
    return readLocal('nodeterm.glyphgridDebug') === '1'
  } catch {
    // Storage can throw outright (Safari private mode, a locked-down embedder). Debug off is
    // always a safe answer.
    return false
  }
}

function glyphDebugTap(): ((info: GlyphSlotAllocation) => void) | undefined {
  if (!glyphDebugOn()) return undefined
  return ({ slot, code, bold, italic, x, y, fg, bg, part }): void => {
    console.warn(
      `[glyphgrid] slot ${slot} code 0x${code.toString(16)} ${JSON.stringify(
        String.fromCodePoint(code)
      )}${bold ? ' bold' : ''}${italic ? ' italic' : ''}${
        // Only a WIDE part is called out. Every ordinary glyph is 'whole', so printing that on
        // every line would be noise on the one log a device round reads line by line — and a wide
        // character showing no PAIR here is exactly the failure worth spotting.
        part === 'whole' ? '' : ` ${part}`
      } at ${x},${y} fg=${fg.toString(16)} bg=${bg.toString(16)}`
    )
  }
}

/** Names the author of a cell that HOLDS a character and still packs to "draw nothing".
 *
 *  The three answers are not a list of suspects, they are the three code paths that can produce a
 *  blank lane, so the first report ends the guessing:
 *   - `width 0`   → the buffer says this column is a wide glyph's FOLLOWER. Then the bug is upstream
 *                   of us (or in the lead's width handling), not in the atlas.
 *   - `width -1`  → the buffer had no cell for the column at all, i.e. we packed past the end of a
 *                   line we thought was longer.
 *   - `width >=1` → the cell exists and holds text, and the crash guard still refused the derived
 *                   code: read the reported `code` against `isRenderableCode`.
 *
 *  Throttled per (row, col) so a stuck cell on a repainting row cannot flood the console — the
 *  interesting fact is WHICH cell and WHY, and it does not get truer the hundredth time. */
function installBlankCellProbe(): void {
  if (!glyphDebugOn()) return
  const seen = new Set<string>()
  setBlankCellProbe(({ col, row, width, code, chars }) => {
    const key = `${row}:${col}`
    if (seen.has(key)) return
    seen.add(key)
    console.warn(
      `[glyphgrid] BLANK CELL row ${row} col ${col} holds ${JSON.stringify(chars)} ` +
        `(code 0x${code.toString(16)}, width ${width}) but drew nothing`
    )
  })
}

/** Exposes `window.__glyphgridDump()` → `{ page, ...geometry }`, where `page` is a PNG data URL of
 *  the whole atlas. Installed only under the debug flag; the tester opens the data URL in a tab and
 *  looks for the reported letter.
 *
 *  READING THE PNG SINCE THE ATLAS WENT COLOURED. It is no longer white ink on a black page: each
 *  slot holds the glyph in its real foreground over its real background, so a dark-theme page is
 *  mostly dark-on-dark and the whole page ground OUTSIDE the allocated slots is TRANSPARENT (it
 *  renders as the viewer's own backdrop — white in a browser tab, not black). "The letter's cell is
 *  black" is therefore no longer the test for "missing": the test is whether the cell holds an
 *  inkless expanse of its own BACKGROUND colour. The same letter can also legitimately appear MANY
 *  times, once per colour pair it has been drawn in.
 *
 *  `gutterPx` and `resetCount` ride along for that reading: a slot's ink starts one gutter inside
 *  its pitch cell (so `strideX`-based arithmetic alone lands a couple of texels off), and a page
 *  that has reset is a page whose slot numbering has been reused — a dumped slot index only means
 *  something alongside the reset count it was taken at. */
/**
 * Exposes `window.__glyphgridSnap(on?)` → the live device-pixel snap state.
 *
 * NOT behind the debug flag, unlike the atlas dump. The question it answers — is snapped text
 * crisper on THIS retina display? — can only be answered by the person looking at the screen, and
 * making them set a localStorage key and relaunch first turns a five-second A/B into a session.
 * Called with no argument it only reports.
 *
 * The two `setCamera` calls are the repaint: the engine is change-gated all the way down, so a
 * flag it reads at frame time changes nothing until something dirties it. Nudging the zoom and
 * putting it straight back dirties twice and draws once, with the real camera.
 */
function installSnapToggle(engine: GlyphGridEngine): void {
  if (typeof window === 'undefined') return
  ;(window as unknown as Record<string, unknown>).__glyphgridSnap = (on?: boolean): boolean => {
    if (typeof on === 'boolean') {
      setCellSnap(on)
      engine.setCamera({ ...lastCamera, zoom: lastCamera.zoom * (1 + 1e-6) })
      engine.setCamera(lastCamera)
    }
    return cellSnapEnabled()
  }
}

/**
 * Exposes `window.__glyphgridFillAtlas()` → `{ capacity, resetsBefore, resetsAfter }`, which packs
 * junk keys until the page overflows and the atlas resets.
 *
 * This exists because the only known trigger for issue #377 — a glyph going permanently invisible
 * for one colour pair — is an atlas RESET, and on a real canvas a reset arrives after hours of use
 * at an unpredictable moment. Waiting for it with the debug flag armed is the report nobody can
 * schedule; this makes the reset happen on demand, so the recovery that follows it can be watched
 * deliberately.
 *
 * It uses `glyphFor` and nothing else — no debug-only surface on the atlas — so what it exercises
 * is exactly the production allocation path. The keys are private-use code points paired with a
 * distinct foreground each, which is what makes them distinct keys rather than cache hits.
 *
 * NOT behind the debug flag, for the same reason as `__glyphgridSnap`: a repro that first needs a
 * localStorage key and a relaunch is a repro the reporter runs once and abandons.
 */
function installAtlasFill(atlas: GlyphAtlas): void {
  if (typeof window === 'undefined') return
  ;(window as unknown as Record<string, unknown>).__glyphgridFillAtlas = (): unknown => {
    const resetsBefore = atlas.resetCount
    // One past capacity: the last request is the one that tips the page over.
    for (let i = 0; i <= atlas.capacity; i++) {
      atlas.glyphFor(0xe000 + (i % 0x1000), false, false, 0xff000000 + i, 0xff000000)
    }
    return { capacity: atlas.capacity, resetsBefore, resetsAfter: atlas.resetCount }
  }
}

function installGlyphDump(atlas: GlyphAtlas, raster: { cellW: number; cellH: number }): void {
  if (!glyphDebugOn() || typeof window === 'undefined') return
  ;(window as unknown as Record<string, unknown>).__glyphgridDump = async (): Promise<unknown> => {
    const source = atlas.source
    const geometry = {
      pageSizePx: atlas.sizePx,
      cellW: raster.cellW,
      cellH: raster.cellH,
      strideX: atlas.strideX,
      strideY: atlas.strideY,
      gutterPx: GUTTER_PX,
      cols: Math.floor(atlas.sizePx / atlas.strideX),
      capacity: atlas.capacity,
      resetCount: atlas.resetCount
    }
    // `source` is the rasterizer's OffscreenCanvas; convertToBlob is the only way to read it back.
    if (!source || typeof (source as OffscreenCanvas).convertToBlob !== 'function')
      return { ...geometry, page: null }
    const blob = await (source as OffscreenCanvas).convertToBlob({ type: 'image/png' })
    const page = await new Promise<string>((resolve) => {
      const fr = new FileReader()
      fr.onload = (): void => resolve(String(fr.result))
      fr.readAsDataURL(blob)
    })
    return { ...geometry, page }
  }
}

/** The atlas surface the reset log reads. Structural rather than `GlyphAtlas` so the log can be
 *  exercised without a page full of real glyphs — filling a real one takes a rasterizer, which this
 *  environment does not have. */
export interface AtlasResetSource {
  resetCount: number
  onReset(cb: () => void): GlyphAtlasSubscription
}

/** Quiet period after a logged reset. */
const RESET_LOG_INTERVAL_MS = 1000

/**
 * Announce atlas page resets on the console.
 *
 * NOT gated on the debug flag, unlike the dump and the allocation tap. A reset is the v1
 * reset-on-full model's pressure gauge: it is supposed to be RARE, and the number that decides
 * whether Phase 2 has to build real LRU eviction is how often it actually happens in a day's use —
 * which nobody will have collected if seeing it required knowing to turn a flag on first. It costs a
 * console line per reset on a canvas where resets are rare, which is the case this design claims.
 *
 * THROTTLED, because the case where the claim is wrong is exactly the case that would drown in it: a
 * page too small for the canvas resets on every repack, i.e. once per frame, and an unthrottled warn
 * there is both a real frame cost and a console the tester cannot read the rest of. So at most one
 * line per `RESET_LOG_INTERVAL_MS`, carrying the count of the ones it swallowed — a burst still
 * reports as a burst, in one line instead of sixty.
 *
 * `now` is injected for the tests; production passes nothing.
 */
export function installAtlasResetLog(
  atlas: AtlasResetSource,
  now: () => number = Date.now
): GlyphAtlasSubscription {
  // -Infinity, not 0: the FIRST reset must always print, whatever the clock reads.
  let lastAt = -Infinity
  let swallowed = 0
  return atlas.onReset(() => {
    const t = now()
    if (t - lastAt < RESET_LOG_INTERVAL_MS) {
      swallowed++
      return
    }
    lastAt = t
    const extra = swallowed > 0 ? ` (+${swallowed} more since the last line)` : ''
    swallowed = 0
    console.warn(
      `[glyphgrid] atlas page reset #${atlas.resetCount} — colour key space full, every row repacks${extra}`
    )
  })
}

function createContext(cell: DeviceCell): LiveContext | null {
  if (typeof document === 'undefined' || typeof OffscreenCanvas === 'undefined') return null
  const { fontFamily, fontSize, fontWeight, fontWeightBold } = useSettings.getState().settings
  const dpr = currentDpr()
  // The atlas is rasterized at DEVICE resolution: the addon reports device-pixel cells, and a
  // CSS-sized atlas would be visibly soft on every retina display. The dpr is read ONCE and LATCHED
  // (below, on the context) precisely because it cannot be changed afterwards — the cell, the
  // baseline and every slot already in the page were rasterized for it. Moving the window to a
  // display with a different ratio therefore disposes this context and rebuilds it, exactly as a
  // font change does; `syncAtlasPixelRatio` is the trigger and `rebuildSharedContext` is the shared
  // funnel. The drawing BUFFER follows the dpr independently, on every resize (see the component's
  // `pushViewport`), so geometry is never wrong even in the frames before the rebuild lands.
  const devicePx = Math.max(1, fontSize * dpr)
  const { cellW, cellH } = cell
  // Rasterizer FIRST: it needs no GPU, so a missing OffscreenCanvas bails out before a WebGL
  // context has been created (the harness learned this the expensive way — a context acquired
  // and then dropped unreferenced is exactly the leak this whole layer exists to avoid).
  const raster = createCanvasRasterizer(
    {
      family: fontFamily,
      sizePx: devicePx,
      cellW,
      cellH,
      weight: fontWeight,
      weightBold: fontWeightBold
    },
    ATLAS_PAGE_PX
  )
  if (!raster) return null
  const canvas = document.createElement('canvas')
  canvas.className = 'glyphgrid-canvas'
  // The GL layer sizes the BACKING STORE (canvas.width/height in device px); the CSS box is ours.
  canvas.style.cssText =
    'position:absolute;inset:0;width:100%;height:100%;display:block;pointer-events:none'
  const gl = createWebgl2GL(canvas)
  if (!gl) return null
  const atlas = new GlyphAtlas(raster, ATLAS_PAGE_PX, glyphDebugTap())
  installGlyphDump(atlas, raster)
  installAtlasFill(atlas)
  installBlankCellProbe()
  const engine = new GlyphGridEngine(gl, atlas)
  engine.setCamera(lastCamera)
  installSnapToggle(engine)
  /**
   * The ATLAS PAGE's own loss policy — the 2D half of a GPU reset, which until now had none.
   *
   * It is the SAME policy object the WebGL side uses, and the four rules transfer intact: restore
   * once, give up on a second loss inside the cooldown, give up if the rebuild throws, give up on a
   * bounded watchdog rather than waiting forever. Two details differ and both are spelled here
   * rather than in the policy, because they are properties of the 2D context and not of the rule:
   *
   *  - `onLost()`'s BOOLEAN IS MEANINGLESS HERE and is deliberately dropped. It means "call
   *    preventDefault()", which on a WebGL canvas is how you ASK for a restore and on a 2D canvas is
   *    how you REFUSE automatic restoration — the exact opposite. `onSourceLoss` never cancels.
   *  - REVIVE IS A REBUILD, not a restore. A lost 2D page cannot be restored: its pixels are gone
   *    while `GlyphAtlas.slots` still claims every key is present, so the only correct answer is to
   *    throw the whole context away and let every terminal re-rasterize what it needs against a
   *    fresh page. That is precisely `rebuildSharedContext`, the funnel a font change already uses,
   *    and it begins a new cell epoch for the same reason a font change does.
   *
   * SUSPEND IS A NO-OP, and that is the useful behaviour rather than a gap: the GL texture still
   * holds the LAST GOOD upload of the page, so leaving the canvas exactly as it is shows the user
   * their text — frozen — for the fraction of a second until the restore lands. Parking frames would
   * show the same thing; re-uploading, which is what the un-fixed code did, shows nothing at all.
   */
  const atlasLoss = createContextLossPolicy({
    now: () => Date.now(),
    suspend: () => undefined,
    revive: () => rebuildSharedContext(),
    fail: (reason, err) => failSharedGlyph(reason, err),
    setTimer: (cb, ms) => window.setTimeout(cb, ms),
    clearTimer: (h) => window.clearTimeout(h)
  })
  return {
    engine,
    atlas,
    canvas,
    gl,
    raster,
    atlasLoss,
    sourceLoss: raster.onSourceLoss({
      lost: () => {
        atlasLoss.onLost()
      },
      restored: () => atlasLoss.onRestored()
    }),
    resetLog: installAtlasResetLog(atlas),
    fontKey: fontKeyOf(fontFamily, fontSize, fontWeight, fontWeightBold),
    dpr,
    disposed: false
  }
}

/** Tear the context down and free the GPU objects. Every registered grid is left holding an
 *  INERT handle (`disposeAll`'s contract), so a terminal that writes one more row during
 *  teardown is a no-op rather than a throw. */
function disposeContext(): void {
  const ctx = live
  live = null
  creationAttempted = false
  if (!ctx) return
  // BEFORE any GL call: a rAF tick already scheduled with this context must skip its frame rather
  // than submit against deleted objects (see `LiveContext.disposed`).
  ctx.disposed = true
  try {
    // FIRST, and before anything that can throw: the atlas page's listeners and the watchdog behind
    // them are the two things here that could outlive the context. A surviving listener would drive
    // a rebuild off a page nobody is drawing from, and a surviving watchdog would fail a session
    // whose context was merely handed back (this rebuild, the mode switched off) — which cannot then
    // be re-enabled without a relaunch.
    ctx.sourceLoss.dispose()
    ctx.atlasLoss.stop()
    ctx.resetLog.dispose()
    ctx.engine.disposeAll()
    ctx.gl.dispose()
    // `gl.dispose()` frees the buffers/texture/program but NOT the context itself, and the
    // browser's live-context cap counts contexts, not objects. A rebuild creates a fresh canvas
    // (a canvas hands back the same context forever), so the old one must be explicitly lost or
    // every font change permanently spends one of the ~16 slots the whole app shares.
    const raw = ctx.canvas.getContext('webgl2')
    raw?.getExtension('WEBGL_lose_context')?.loseContext()
  } catch (err) {
    console.warn('[glyphgrid] teardown error (continuing)', err)
  }
  ctx.canvas.remove()
}

/** Warn, drop the context, and put the session on the DOM renderer. The ONE failure funnel — the
 *  store's `markFailed()` delegates here, and this writes the flag DIRECTLY (calling back into the
 *  action would recurse). */
export function failSharedGlyph(reason: string, err?: unknown): void {
  // Checked before the warn so a lost context that arrives twice (throwing frame + event) logs
  // once, and so a second failure never re-notifies the registrants.
  const store = useSharedGlyph.getState()
  if (store.failed) return
  console.warn(`[glyphgrid] shared renderer disabled for this session (${reason})`, err)
  disposeContext()
  // The generation rides along so a node that only subscribes to `generation` still wakes up —
  // it will ask for the context, get null, and stay on the DOM renderer. One signal, one
  // subscription.
  useSharedGlyph.setState({ failed: true, generation: useSharedGlyph.getState().generation + 1 })
}

/**
 * THE re-rasterize path: drop the context and tell every registered terminal to re-evaluate its
 * participation, which is how they end up re-registering their grids against a freshly built atlas.
 *
 * ONE function, because there is now more than one trigger — a font change, a display pixel ratio
 * change, an atlas page whose 2D context was lost, and a cell drift — and they must be the same
 * event. The order is load-bearing and is the same contract `setEnabled(false)` and
 * `failSharedGlyph` honour: dispose FIRST, announce SECOND, never dispose without announcing (every
 * registered grid is holding an inert handle until the bump arrives) and never announce before
 * disposing (a terminal that re-asked for the context in between would adopt the very context we
 * are about to delete).
 *
 * `cellEpoch` is the ONE thing the triggers do not agree on, which is why it is a parameter rather
 * than something this function could decide for itself. Everything that rebuilds because the world
 * changed (a new font, a new display, a fresh atlas page) makes the previous cell measurement
 * meaningless and starts a new epoch — the DEFAULT, so a future trigger gets the safe answer by
 * omission. The drift rebuild alone passes 'same': it is spending that epoch's single allowance, and
 * re-arming the guard from inside the rebuild the guard permitted is exactly the ping-pong loop
 * `CellRebuildGuard` exists to prevent.
 */
type CellEpoch = 'new' | 'same'

function rebuildSharedContext(cellEpoch: CellEpoch = 'new'): void {
  if (cellEpoch === 'new') cellGuard.beginEpoch()
  disposeContext()
  useSharedGlyph.getState().bumpGeneration()
}

/** Rebuild on a terminal font change: the atlas is rasterized for one font, so a new one means a
 *  new atlas — and the engine's grids are re-registered by their owners on the generation bump.
 *
 *  Never unsubscribed, deliberately: the context it watches is a module singleton with no owner
 *  to outlive, and a subscription dropped at teardown would miss the font change that happens
 *  while the mode is momentarily off. It is one closure for the life of the renderer process. */
function ensureSettingsSubscription(): void {
  if (settingsUnsub) return
  settingsUnsub = useSettings.subscribe((s) => {
    if (!live) return
    if (
      live.fontKey ===
      fontKeyOf(
        s.settings.fontFamily,
        s.settings.fontSize,
        s.settings.fontWeight,
        s.settings.fontWeightBold
      )
    )
      return
    // A new font is a new cell epoch, and `rebuildSharedContext` begins one by default — the reset
    // no longer lives here, so every other epoch-establishing trigger gets it too.
    rebuildSharedContext()
  })
}

/** Below this, a difference between two pixel ratios is float noise. Real values are far apart
 *  (1, 1.25, 1.5, 2, 3) and nothing legitimately moves one by a thousandth, while a rebuild costs a
 *  dropped and re-registered grid on every terminal on the canvas. */
const DPR_EPS = 0.001

/**
 * Has the display's pixel ratio moved away from the one the atlas was rasterized at?
 *
 * `current` is `window.devicePixelRatio`, which is not a trustworthy number in every environment
 * (0 on a detached window, NaN through a hostile shim). An unreadable ratio answers "unchanged":
 * the atlas we hold is the one the display we are on asked for, and throwing it away on a bad
 * reading is strictly worse than keeping it.
 */
export function pixelRatioChanged(builtAt: number, current: number): boolean {
  if (!Number.isFinite(current) || current <= 0) return false
  return Math.abs(builtAt - current) > DPR_EPS
}

/** The context surface the dpr reconciliation reads. Structural rather than `LiveContext` — the
 *  same trick `AtlasResetSource` uses — so the rebuild decision is exercisable without a GPU. */
export interface PixelRatioContext {
  /** The ratio the atlas was rasterized at. */
  dpr: number
  /** Already torn down. */
  disposed: boolean
}

/**
 * Rebuild the atlas when the window has moved to a display with a different pixel ratio.
 *
 * WHY A REBUILD, AND WHY NOTHING ELSE FIXES IT. The atlas cell IS xterm's DEVICE cell (see
 * `DeviceCell`) and the baseline is derived from the same font at the same moment — both latched at
 * construction, along with every slot already rasterized into the page. So a retina window dragged
 * onto a 1x display keeps a page drawn at twice the resolution its quads are now sampled at, and
 * the reverse leaves it soft. Nothing downstream rescues that: the grids are registered with the
 * CSS cell, which is dpr-invariant, so the move triggers no re-registration at all and the page
 * stays wrong for the life of the context.
 *
 * It goes through the font change's funnel deliberately (`rebuildSharedContext`): a dpr change is
 * the same event with a different trigger, and a second dispose-and-re-register path is a second
 * place to get the both-renderers invariant wrong.
 *
 * Returns whether it rebuilt, so the caller can skip pushing a viewport into a context it has just
 * disposed.
 */
export function syncAtlasPixelRatio(current: number, ctx: PixelRatioContext): boolean {
  // Re-entry guard. `pushViewport` runs from the ResizeObserver, the window `resize` listener AND
  // the resolution media query, and a display change can fire more than one of them;
  // `disposeContext()` flips this flag on the context the closure still holds, so the second call
  // is a no-op instead of a second epoch bump — which would run teardown/setup twice on every
  // terminal for one display change.
  if (ctx.disposed) return false
  if (!pixelRatioChanged(ctx.dpr, current)) return false
  rebuildSharedContext()
  return true
}

/** The query xterm's own `CoreBrowserService` watches for a device-pixel-ratio change, verbatim.
 *  Exported so the test can assert the form rather than only the behaviour: the ratio is embedded
 *  in the STRING, which is the whole reason the watcher below has to re-arm. */
export function pixelRatioQuery(dpr: number): string {
  return `screen and (resolution: ${dpr}dppx)`
}

/** The two methods of a `MediaQueryList` the watcher uses, both optional: an environment can expose
 *  only the deprecated `addListener` pair, and that degrades to "not watched" rather than a throw. */
export interface PixelRatioMediaQuery {
  addEventListener?(type: 'change', fn: () => void): void
  removeEventListener?(type: 'change', fn: () => void): void
}

/** The browser surface the dpr watcher needs, injected — the component itself has no DOM under the
 *  unit tests, and the re-arm is precisely what needs testing. */
export interface PixelRatioWatchHost {
  /** Read AFRESH at every arm: the query embeds the ratio, so it must be the ratio we are on now. */
  dpr(): number
  /** `window.matchMedia`, or null where the environment has none. */
  match(query: string): PixelRatioMediaQuery | null
}

/**
 * Watch for a device-pixel-ratio change and call back once per change.
 *
 * WHY THIS EXISTS ALONGSIDE `resize`. The move it answers — a window dragged between a retina and a
 * 1x display at the same point size — leaves the host's CSS box identical, so the ResizeObserver is
 * silent, and whether Blink dispatches `resize` for a scale-factor change with an unchanged CSS
 * viewport is not something to bet the atlas on. xterm does not bet on it: `CoreBrowserService`
 * watches exactly this media query. Both triggers run, funnelled through the same `pushViewport`,
 * and `syncAtlasPixelRatio`'s re-entry guard makes the double fire free.
 *
 * THE RE-ARM IS THE WHOLE JOB. `screen and (resolution: 2dppx)` answers the move OFF 2dppx and then
 * never again, so each change disarms the spent query and arms one at the ratio we have just landed
 * on — otherwise the move BACK is silent and the canvas keeps an atlas rasterized for a display it
 * is no longer on. Re-arming happens BEFORE the callback: `onChange` may dispose the context, and
 * the next display change must be watched for either way.
 *
 * No `addListener` fallback: nothing else in this repo carries one, and a query list we cannot
 * subscribe to leaves the `resize` trigger in place.
 */
export function createPixelRatioWatcher(
  host: PixelRatioWatchHost,
  onChange: () => void
): { stop(): void } {
  let mql: PixelRatioMediaQuery | null = null
  let stopped = false

  const disarm = (): void => {
    mql?.removeEventListener?.('change', handler)
    mql = null
  }

  const arm = (): void => {
    disarm()
    if (stopped) return
    const next = host.match(pixelRatioQuery(host.dpr()))
    if (!next || typeof next.addEventListener !== 'function') return
    next.addEventListener('change', handler)
    mql = next
  }

  function handler(): void {
    if (stopped) return
    arm()
    onChange()
  }

  arm()
  return {
    stop(): void {
      stopped = true
      disarm()
    }
  }
}

/**
 * Bring the engine's GPU objects back — UNLESS the atlas page did not survive whatever took them.
 * Returns whether the caller may carry on with this context; false means it has been rebuilt and
 * the generation bump is already on its way.
 *
 * THE CASE THIS CATCHES, and why the WebGL side's own policy cannot. A GPU reset takes the WebGL
 * context AND blanks the OffscreenCanvas the atlas rasterizes into. The WebGL half announces itself
 * and is answered by `engine.reviveGpu`, which re-uploads the atlas page — and `reviveGpu`'s comment
 * says outright that this costs one upload rather than a re-rasterization "because the atlas SOURCE
 * did not die with the context". When it did die, that upload is of an EMPTY page: `GlyphAtlas.slots`
 * still holds every key, so nothing re-rasterizes, and every terminal on the canvas goes blank at
 * once and stays blank until a font or dpr change happens to rebuild.
 *
 * The 2D context usually announces itself too (`onSourceLoss`), and when it does this check never
 * fires. It exists for the case where it does NOT — a backing store that comes back wiped with no
 * event — which is why the question is asked of the PIXELS (`ATLAS_SENTINEL_RGBA`) rather than of a
 * flag. One 1px readback, on a path that runs at most once per context.
 */
function reviveGpuOrRebuild(ctx: LiveContext): boolean {
  // ALREADY GONE. Both halves of a GPU reset land as events, in an order nobody controls, and the
  // 2D half answers by DISPOSING this context — while the generation bump that tears the effect
  // down is a React state update, i.e. not synchronous. So `webglcontextrestored` can arrive for a
  // context that no longer exists, and reviving it would call into a disposed GL layer: a throw the
  // policy reads as a failed rebuild, taking the whole session to the DOM renderer for a context
  // that was merely replaced. Same guard, same reason, as `syncAtlasPixelRatio`'s.
  if (ctx.disposed) return false
  if (!ctx.raster.sourceIntact()) {
    console.warn(
      '[glyphgrid] the atlas page did not survive the GPU outage — every cached glyph now points ' +
        'at a blank texel, so the context is being rebuilt rather than re-uploaded'
    )
    rebuildSharedContext()
    return false
  }
  ctx.engine.reviveGpu()
  return true
}

/** Fires when a context has just been BUILT. The component listens so it can mount the fresh
 *  canvas: creation is now driven by the first terminal that offers a device cell, which can
 *  happen after the layer's own effect has already run and found nothing. Deliberately NOT a
 *  generation bump — that notification is a re-evaluate-your-participation signal to every
 *  registered terminal, and raising it from INSIDE the call one of them is making would re-enter
 *  `setupGlyph` before it has registered its grid. */
const contextListeners = new Set<() => void>()

export function subscribeSharedGlyphContext(fn: () => void): () => void {
  contextListeners.add(fn)
  return () => {
    contextListeners.delete(fn)
  }
}

/** One line per context lifetime: every terminal supplies its own device cell and they are all
 *  supposed to agree (the font settings are global). A disagreement is a real defect — a dpr
 *  change under a live context, a per-terminal letterSpacing — and the symptom is soft text, so
 *  say so rather than silently rescaling. */
/**
 * THE LOOP-GUARD INVARIANT for the drift rebuild, in one object because it was previously two
 * module variables reset in one place and read in another.
 *
 * **One drift rebuild per CELL EPOCH, and an epoch begins only where a new cell is legitimately
 * expected.** Both halves are load-bearing and they fail in opposite directions:
 *
 *  - WITHOUT the cap: the rebuild disposes the context, and `disposeContext` deliberately clears
 *    the other creation state — so a guard stored there would be wiped by the very rebuild it
 *    bounds. Two terminals with genuinely different cells would rebuild for each other forever, one
 *    per registration, and the canvas would never paint. This is why `allowRebuild()` does NOT
 *    re-arm itself and why the funnel it calls must be told not to begin an epoch.
 *  - WITHOUT the re-arm: the FIRST drift in a session spends the only allowance there will ever be.
 *    That is the defect this replaces — the counter was reset in the settings subscription alone, so
 *    a later, unrelated drift (a webfont resolving after a dpr rebuild latched a fallback face's
 *    cell) only warned, and that terminal stayed resampled — soft and 5% wide — for the rest of the
 *    session, with the cause long gone.
 *
 * AN EPOCH BEGINS at every rebuild cause that makes the previous measurement meaningless: a font
 * change, a dpr rebuild, the atlas page being rebuilt after a 2D context loss, and the mode being
 * switched back on. It does NOT begin at the drift rebuild itself — see `rebuildSharedContext`'s
 * `cellEpoch` argument, which is where that distinction is spelled.
 *
 * Pure and injectable-free, so the rule is exercisable without a GPU (the singleton around it is
 * not testable at all — see the header).
 */
export interface CellRebuildGuard {
  /** A fresh cell epoch: the old measurement is meaningless and the next drift may rebuild. */
  beginEpoch(): void
  /** Consume this epoch's rebuild allowance. False = already spent; leave the terminal resampled. */
  allowRebuild(): boolean
  /** True at most once per epoch — the give-up log, which must not repeat per registration. */
  takeWarning(): boolean
}

export function createCellRebuildGuard(limit = 1): CellRebuildGuard {
  let rebuilds = 0
  let warned = false
  return {
    beginEpoch(): void {
      rebuilds = 0
      warned = false
    },
    allowRebuild(): boolean {
      if (rebuilds >= limit) return false
      rebuilds++
      return true
    },
    takeWarning(): boolean {
      if (warned) return false
      warned = true
      return true
    }
  }
}

const cellGuard = createCellRebuildGuard()
/**
 * The atlas cell against a terminal's real one — and REBUILD when they disagree, rather than only
 * saying so.
 *
 * `ensureLiveContext` fixes the atlas geometry from the FIRST terminal that registers, for the life
 * of the context. That is fine when every terminal measures the same cell and wrong the moment one
 * does not: the glyph is rasterized into the atlas's box and drawn into the terminal's, so the
 * whole canvas is resampled by the ratio between them.
 *
 * That is the 2026-08-10 report, measured. Every node reported a device cell of 16.79998×36 while
 * the atlas had latched to 16×36 — a horizontal ratio of 1.05, which is exactly the 4.9% wider
 * advance measured off screenshots against xterm's own WebGL renderer, with the line spacing
 * identical to the pixel because the heights agreed. A glyph stretched 5% is wider, heavier AND
 * softer, which is why the report arrived as "not crisp" and survived four other explanations.
 *
 * The likely latch is a first terminal that measured before its webfont resolved, so the fallback
 * face's metrics fixed the page. Nothing recovered from it: a font change rebuilds the context, a
 * dpr change rebuilds it, but a cell that simply disagreed only logged — and a project switch
 * deliberately does NOT rebuild, so the wrong page outlived everything short of a restart.
 *
 * A drift is therefore treated exactly like a font change, through the same funnel. It CANNOT
 * loop: the cell is read raw from xterm (`deviceCellOf`) and came back identical across all 48
 * nodes in the field dump, so one rebuild settles it — and the guard below makes even a
 * pathological disagreement rebuild once per distinct cell rather than every frame.
 */
export function cellsDisagree(atlas: DeviceCell, cell: DeviceCell): boolean {
  return Math.abs(atlas.cellW - cell.cellW) >= 0.01 || Math.abs(atlas.cellH - cell.cellH) >= 0.01
}

function reconcileAtlasCell(ctx: LiveContext, cell: DeviceCell | null): void {
  if (!cell) return
  if (!cellsDisagree({ cellW: ctx.atlas.cellW, cellH: ctx.atlas.cellH }, cell)) return
  if (!cellGuard.allowRebuild()) {
    // Already spent this epoch's rebuild and a terminal STILL disagrees: two of them want
    // different cells, and rebuilding again would just hand the atlas back and forth. Say so and
    // leave it — one resampled terminal is a cosmetic loss, a rebuild loop is a dead canvas.
    if (cellGuard.takeWarning()) {
      console.warn(
        `[glyphgrid] atlas cell ${ctx.atlas.cellW}×${ctx.atlas.cellH} still does not match a ` +
          `terminal's device cell ${cell.cellW}×${cell.cellH} after a rebuild — terminals disagree ` +
          `about their metrics, so this one's glyphs stay resampled`
      )
    }
    return
  }
  console.warn(
    `[glyphgrid] atlas cell ${ctx.atlas.cellW}×${ctx.atlas.cellH} does not match this terminal's ` +
      `device cell ${cell.cellW}×${cell.cellH} — rebuilding the atlas for it (every glyph was ` +
      `being resampled by the ratio between them)`
  )
  // 'same' is the guard: this rebuild must NOT begin a new epoch, or it would restore the allowance
  // it has just consumed and two disagreeing terminals would rebuild for each other forever.
  rebuildSharedContext('same')
}

/**
 * The singleton, created on first use. Internal because it also exposes the canvas + GL, which
 * only this file's component may touch.
 *
 * Creation needs `cell` — xterm's device cell (see `DeviceCell`) — so a caller that has no
 * terminal to ask (the component itself) gets the EXISTING context or null, and never builds one
 * with guessed metrics. The first caller that does have one fixes the atlas geometry for the life
 * of the context; a font change tears it down and the next caller rebuilds it with the new cell.
 */
function ensureLiveContext(cell?: DeviceCell): LiveContext | null {
  if (!sharedGlyphActive()) return null
  if (live) {
    // `reconcileAtlasCell` CAN DISPOSE THE VERY CONTEXT IT IS HANDED — a cell drift rebuilds, and
    // `disposeContext()` nulls `live`. So the answer has to be re-read afterwards, and it is read
    // through `currentLive()` rather than as `live` because TypeScript's narrowing from the `if`
    // above survives the call: written `return live`, the value is correct at RUNTIME (it is a
    // variable read, not a captured reference) while the compiler believes it is non-null, and the
    // first edit that trusts that type — `live.engine`, a spread, an `!` — hands a caller an engine
    // whose GL objects have been deleted. Null is the DESIGNED answer here: the caller drops to
    // `ensureWebglClient` and the generation bump the rebuild raised brings it back on a fresh
    // context.
    reconcileAtlasCell(live, usableCell(cell))
    return currentLive()
  }
  const seed = usableCell(cell)
  if (!seed) return null
  if (creationAttempted) return null
  creationAttempted = true
  ensureSettingsSubscription()
  // Construction is guarded, and deliberately does NOT go through `failSharedGlyph`: a THROW here
  // (an OffscreenCanvas/2d-context/WebGL constructor that raises instead of returning null on a
  // hostile or exhausted GPU stack) must degrade EXACTLY like the null-returning paths inside
  // `createContext` — return null, the caller stays on the DOM renderer. Setting `failed` would
  // additionally bump the generation and re-notify every registrant from inside a call one of
  // them is already making, and it would mark the whole session dead for a condition the
  // null paths treat as "not available here". `creationAttempted` is already true, so the throw
  // is never retried in a loop.
  try {
    live = createContext(seed)
  } catch (err) {
    console.warn('[glyphgrid] shared context construction threw; staying on the DOM renderer', err)
    live = null
  }
  // Announced only on success, and AFTER `live` is set, so a listener that immediately asks for
  // the context finds it.
  if (live) for (const fn of contextListeners) fn()
  return live
}

/**
 * The shared engine + atlas, created on first use. Null means "stay on the DOM renderer": the
 * mode is off, the session has failed, this machine has no WebGL2/OffscreenCanvas — or no context
 * exists yet and the caller passed no `deviceCell` to build one from.
 *
 * `deviceCell` is xterm's `dimensions.device.cell` for the asking terminal. It is what the atlas
 * rasterizes into, and the invariant it exists for is on `DeviceCell`: **the atlas texel grid is
 * xterm's device cell grid, always.**
 */
export function getSharedGlyphContext(deviceCell?: DeviceCell): SharedGlyphContext | null {
  return ensureLiveContext(deviceCell)
}

/** Camera feed. Always records (so a context created later opens at the right place) and only
 *  reaches the engine — which change-gates it — when one exists.
 *
 *  SANITIZED HERE, at the boundary, rather than at any one call site: the camera arrives from a live
 *  React Flow gesture (already clamped) AND from a persisted project viewport (clamped by nothing),
 *  and a zoom of 0 or NaN from the second blanks every terminal on the canvas at once. See
 *  `sanitizeCamera` for why that is invisible everywhere else. One funnel means a future third
 *  caller cannot reintroduce it. */
export function setSharedGlyphCamera(cam: Camera): void {
  lastCamera = sanitizeCamera(cam)
  live?.engine.setCamera(lastCamera)
}

// ---------------------------------------------------------------------------------------------
// The board gate — no frames under an opaque overlay
// ---------------------------------------------------------------------------------------------

/**
 * Is the kanban board currently covering the canvas?
 *
 * Read imperatively from both stores because the answer needs both: the board is a PER-PROJECT
 * view, so switching to a project that is on the board changes it with no view change at all
 * (`TerminalNode` gets away with reading the project id once because a project switch remounts it;
 * this layer stays mounted across switches).
 *
 * The `activeProjectId` check is not redundant with `viewFor`, which falls through to the GLOBAL
 * default view for an id it does not know: with "Default view = kanban" and no active project (at
 * boot, or after the last project is closed and the WelcomeScreen covers a still-mounted Canvas),
 * an empty id would report "covered" and stop the loop with no board up. This is the same
 * predicate Canvas derives `kanbanOpen` from, and it has to stay literally the same one — two
 * answers to "is the board up" that can disagree is how a canvas ends up not drawing for a reason
 * nobody can find.
 *
 * Including the OMNI board (`isGlobalKanbanOpen`, which already folds in the feature flag): it is
 * the same opaque full-page overlay, and Canvas's `kanbanOpen` is `globalKanbanOpen ||
 * perProjectKanbanOpen`. Leaving it out kept the shared canvas drawing under the all-projects
 * board — the same omission 12564a20 fixed for the window-activation focus restore.
 * Like Canvas's own term, Omni needs no active project.
 */
export function boardCoversCanvas(): boolean {
  if (isGlobalKanbanOpen()) return true
  const { activeProjectId } = useProjects.getState()
  return !!activeProjectId && viewFor(useViewMode.getState(), activeProjectId) === 'kanban'
}

export interface BoardFrameGate {
  /** The loop that is currently in charge — always call through this, never capture the result. */
  loop(): FrameLoop
  /** Re-read the board flag and act on a change. Cheap and change-gated: a store notification that
   *  did not move the board costs one comparison. */
  sync(): void
  /** Teardown. Stops the current loop for good and makes any later `sync` inert. */
  stop(): void
}

/**
 * Gate the frame loop on the kanban board.
 *
 * The board is a FULLY OPAQUE overlay over the whole canvas, so every frame drawn under it is
 * invisible work. Phase 1c's idle park does not cover this case at all: a canvas of streaming
 * terminals under the board never goes quiet, so it repaints at the display's refresh rate for
 * nobody.
 *
 * **STOPPING THE LOOP DOES NOT STOP THE FEED, and that distinction is the whole safety of this.**
 * Nothing about the terminals changes: their PTYs keep running, the addons keep writing rows into
 * the engine's grid buffers, and `markDirty` keeps recording the damage. The ONLY thing that stops
 * is the submission of frames. So the buffers stay current the entire time the board is up, and
 * closing it is a REPAINT of what is already there — not a rebuild, not a re-registration, and not
 * a screen that has to be re-fed from tmux. Nothing is lost by not drawing it.
 *
 * That is also why one frame is drawn IMMEDIATELY on close rather than waiting for the next damage:
 * the engine is still dirty from everything that arrived under the board, and the next write on an
 * idle canvas may be minutes away — a finished agent's terminal would sit there showing the rows it
 * had when the board went up. `start()` schedules that frame; `wake()` alongside it is belt and
 * braces, and free (it only reschedules a frame that draws nothing when there is nothing to draw).
 *
 * **A stopped loop is stopped FOR GOOD** — `createFrameLoop`'s contract, so that a late damage can
 * never resurrect a loop whose context is gone. Leaving the board therefore builds a FRESH loop
 * rather than restarting the old one, which is why every caller must reach the loop through
 * `loop()`: a damage subscription that captured the original would be waking a corpse for the rest
 * of the session, and a frozen canvas is a far worse failure than a wasted frame.
 */
export function createBoardFrameGate(
  boardOpen: () => boolean,
  makeLoop: () => FrameLoop
): BoardFrameGate {
  let covered = boardOpen()
  let loop = makeLoop()
  let torn = false
  // Mounting WHILE the board is up (a project that opens on the board, a remount behind it) must
  // not start drawing either — the gate's state is read at construction, not assumed to be "open
  // canvas". And a loop that is merely NEVER STARTED is not inert: `wake()` starts one, so the
  // damage subscription would schedule frames under the board through the back door. It has to be
  // STOPPED, which is also what makes the close path build a fresh one from either entry.
  if (covered) loop.stop()
  else loop.start()
  return {
    loop: () => loop,
    sync(): void {
      if (torn) return
      const now = boardOpen()
      if (now === covered) return
      covered = now
      if (now) {
        loop.stop()
        return
      }
      loop = makeLoop()
      loop.start()
      loop.wake()
    },
    stop(): void {
      torn = true
      loop.stop()
    }
  }
}

// ---------------------------------------------------------------------------------------------
// The blink clock — ONE for the whole canvas
// ---------------------------------------------------------------------------------------------

/**
 * xterm's own blink half-period (`CursorBlinkStateManager`'s `BLINK_INTERVAL`): 600 ms shown,
 * 600 ms hidden.
 *
 * Matched deliberately rather than picked. A stacked terminal leaves the shared canvas and paints
 * itself on xterm's DOM renderer (see the opaque set above), so two terminals on ONE canvas can be
 * blinking under two different mechanisms at the same moment — ours and xterm's CSS animation. Any
 * other period would make them visibly drift apart.
 */
export const CURSOR_BLINK_INTERVAL_MS = 600

/**
 * The terminal whose cursor is blinking right now — at most ONE, because at most one terminal has
 * focus, which is also why the clock is a canvas-level singleton rather than a timer per node.
 *
 * THE PRODUCER'S CONTRACT, in three parts, because the clock cannot enforce any of them:
 *  1. **Set on focus, cleared on blur.** The clock's "is anything focused" gate IS this value; a
 *     target left behind by a blurred terminal is a repaint twice a second for a cursor nobody is
 *     on.
 *  2. **`setPhase` must repaint SYNCHRONOUSLY.** The clock brackets the call to route the damage it
 *     produces through `pulse()` instead of `wake()` (see `routeDamage`); a phase applied through a
 *     deferred/debounced redraw would land outside that bracket, take the wake path, and put the
 *     idle canvas back at the display's refresh rate — the exact failure this whole design avoids.
 *  3. **Both halves of the cursor.** A block cursor is a CELL rewrite and every other shape is an
 *     overlay (see `glyphgrid/cursor.ts`), so hiding it for a phase means suppressing whichever of
 *     the two this terminal is currently drawing — not just the overlay.
 * A terminal that stops being the target must leave its own cursor SHOWN; the clock restores the
 * target it still holds, but it cannot reach one that has already been dropped.
 *
 * THE PRODUCER is `GlyphGridRendererAddonCore` — `setCursorBlinkPhase` for (2) and (3), published
 * on its own focus edges for (1) through the `blink` seam the attach shell supplies
 * (`terminal/glyphgrid-attach.ts`). It has to be the addon: it is the only thing that tracks which
 * terminal has focus and the only thing that holds both halves of a cursor.
 */
export interface CursorBlinkTarget {
  /** Show or hide this terminal's cursor for the current phase. */
  setPhase(visible: boolean): void
}

let blinkTarget: CursorBlinkTarget | null = null
const blinkTargetListeners = new Set<() => void>()
const blinkRestartListeners = new Set<() => void>()

/** Publish the focused terminal (or null on blur). Change-gated: the producer is a focus handler
 *  that may fire more than once for one focus change. */
export function setCursorBlinkTarget(target: CursorBlinkTarget | null): void {
  if (blinkTarget === target) return
  blinkTarget = target
  for (const fn of blinkTargetListeners) fn()
}

/**
 * Give the blink up — but ONLY if this target still holds it.
 *
 * THE GUARD LIVES HERE, and nowhere else. The browser does not promise that the blurred terminal's
 * blur reaches us before the newly focused one's focus, so an unconditional
 * `setCursorBlinkTarget(null)` on a late blur (or on the teardown of a terminal another node has
 * already taken focus from) would stop the cursor of the terminal the user just clicked into — the
 * only one that is supposed to be blinking. Its natural home would be the attach shell, which is
 * the file with no unit tests by design; keeping the comparison in this function is what puts it
 * under test.
 */
export function releaseCursorBlinkTarget(target: CursorBlinkTarget): void {
  if (blinkTarget !== target) return
  setCursorBlinkTarget(null)
}

/**
 * The cursor MOVED — hold it solid and start the period over.
 *
 * xterm's own `CursorBlinkStateManager.restartBlinkAnimation` does exactly this, and matching it is
 * the same argument that fixed `CURSOR_BLINK_INTERVAL_MS` at 600 ms: a STACKED terminal has left
 * the shared canvas for xterm's DOM renderer, so two terminals on one canvas blink under two
 * mechanisms at once. Without this the stacked one holds its cursor solid while you type and the
 * shared one keeps flashing — the drift the period match exists to prevent, in the most
 * attention-heavy moment there is.
 *
 * Identity-guarded like `releaseCursorBlinkTarget`, for a second reason on top of that one: a
 * background terminal streaming output moves its cursor constantly, and any of them re-arming the
 * focused terminal's period would keep the blink permanently solid.
 */
export function restartCursorBlink(target: CursorBlinkTarget): void {
  if (blinkTarget !== target) return
  for (const fn of blinkRestartListeners) fn()
}

export function cursorBlinkTarget(): CursorBlinkTarget | null {
  return blinkTarget
}

export function subscribeCursorBlinkTarget(fn: () => void): () => void {
  blinkTargetListeners.add(fn)
  return () => {
    blinkTargetListeners.delete(fn)
  }
}

/** A restart is not a target CHANGE, so it needs its own channel — `sync` deliberately does
 *  nothing while the interval is already running. */
export function subscribeCursorBlinkRestart(fn: () => void): () => void {
  blinkRestartListeners.add(fn)
  return () => {
    blinkRestartListeners.delete(fn)
  }
}

/** Everything the clock touches, injected — so the policy is testable without a timer, a DOM or a
 *  GPU, exactly as `createBoardFrameGate`'s is. */
export interface CursorBlinkClockDeps {
  /** `settings.cursorBlink`. */
  enabled(): boolean
  /** Is the kanban board covering the canvas? */
  covered(): boolean
  /** The focused terminal, or null. */
  target(): CursorBlinkTarget | null
  /** The loop in charge RIGHT NOW — always through the board gate, never captured: leaving the
   *  board builds a fresh loop and a captured one is a corpse for the rest of the session. */
  loop(): Pick<FrameLoop, 'wake' | 'pulse'>
  setInterval(cb: () => void, ms: number): number
  clearInterval(handle: number): void
}

export interface CursorBlinkClock {
  /** Re-read the three gates and act on a change. Change-gated and idempotent, so every store
   *  notification that could move any of them can call it unconditionally. */
  sync(): void
  /** The target's cursor moved: show it and start the period over — xterm's
   *  `restartBlinkAnimation`. Inert when nothing is blinking. */
  restart(): void
  /** Route ONE damage notification from the engine to the loop. The clock owns this because it is
   *  the only thing that knows whether the damage is its own. */
  routeDamage(): void
  /** Teardown. Restores the cursor, kills the timer, and makes any later `sync` inert. */
  stop(): void
}

/**
 * The canvas's single cursor-blink clock.
 *
 * **The trap it exists to avoid.** A blink is a TIMED repaint twice a second, and the repaint
 * dirties the engine like any other write — so the ordinary path (`onDamage` → `wake()`) would
 * resume the rAF chain, which then costs `IDLE_FRAMES_BEFORE_PARK` frames before parking again.
 * Thirty frames every 600 ms is a loop that never parks: Phase 1c's idle park silently undone, on
 * every canvas that has a focused terminal, which is most of them. `pulse()` (frame-driver) draws
 * exactly one frame and stays parked — and `routeDamage` is what makes sure the blink's own damage
 * reaches it instead of `wake()`. **Neither half works alone**: `pulse()` without the routing is
 * dead code, since the damage listener would have already woken the loop.
 *
 * **Gated three ways, and torn down when any of them stops holding**: the blink SETTING, a terminal
 * holding FOCUS, and the board not covering the canvas (its gate has stopped the loop, so a phase
 * flip there repacks a row nobody draws). A canvas with no focused terminal has no clock at all —
 * not a clock that ticks and finds nothing to do.
 *
 * **The cursor is always handed back SHOWN.** Every stopping path restores the phase first: a
 * cursor left hidden is an invisible cursor until something unrelated repacks its row, which is the
 * one way this feature can be worse than not having it. Precisely: the restore is PACKED at the
 * moment the clock stops — on the board path that means it is drawn when the board closes and the
 * loop starts again, since the board gate has stopped the loop; on every other path a frame follows
 * immediately.
 */
export function createCursorBlinkClock(deps: CursorBlinkClockDeps): CursorBlinkClock {
  let handle = 0
  /** The target we are actually blinking — held rather than re-read, because a stopping path has to
   *  restore the cursor of the terminal that HAD the clock, not of whoever has focus now. */
  let current: CursorBlinkTarget | null = null
  /** Is the cursor currently shown? Starts true: nothing has hidden it yet. */
  let visible = true
  /** How many `setPhase` calls are on the stack right now — see `routeDamage`.
   *
   *  A DEPTH, not a boolean. Nothing re-enters `apply` today, but a boolean would clear the bracket
   *  at the end of the INNER call and drop the outer one's remaining damage onto `wake()` — and the
   *  bracket is the single invariant this whole design rests on, so it costs nothing to make it
   *  re-entrant rather than to rely on it never being re-entered. */
  let applying = 0
  let torn = false

  const clearTimer = (): void => {
    if (!handle) return
    deps.clearInterval(handle)
    handle = 0
  }

  const apply = (next: boolean): void => {
    visible = next
    const target = current
    if (!target) return
    // The bracket is the whole mechanism: `setPhase` repacks the cursor row synchronously, that
    // repack calls `markDirty`, and the damage lands back in `routeDamage` while this counter is
    // up. `finally`, because a throwing addon must not leave every subsequent damage on the pulse
    // path — that would starve a streaming terminal down to one frame per write.
    applying++
    try {
      target.setPhase(next)
    } finally {
      applying--
    }
  }

  /** Every path that stops blinking goes through here. */
  const stopClock = (): void => {
    clearTimer()
    if (visible) return
    // GUARDED, because `stop()` is the FIRST statement of the layer effect's cleanup. `setPhase`
    // packs a row into the engine, and the engine rejects a row of the wrong length by throwing —
    // a throw here would skip every unsubscribe after it and leave a dead loop reachable from the
    // engine and a damage subscription outliving its context, which is the exact invariant that
    // cleanup exists to hold. A cursor stuck in its hidden phase is cosmetic and self-heals on the
    // next repack of its row; a surviving subscription is a frozen canvas for the session.
    try {
      apply(true)
    } catch (err) {
      console.warn('[glyphgrid] cursor blink restore failed', err)
    }
  }

  return {
    sync(): void {
      if (torn) return
      const next = deps.target()
      if (next !== current) {
        // Restore BEFORE the handover: afterwards there is no handle to fix the old cursor with,
        // and it would sit hidden until something unrelated repacked its row.
        stopClock()
        current = next
      }
      if (!deps.enabled() || deps.covered() || !current) {
        stopClock()
        return
      }
      // Already ticking and every gate still holds — restarting the interval here would re-arm the
      // period on every unrelated settings write, so a canvas whose settings churn would never
      // reach a hide at all.
      if (handle) return
      // A terminal that has just taken focus starts SHOWN and gets a full period before its first
      // hide — xterm's own `_restartInterval` does exactly this, and it is what keeps the cursor
      // solid at the moment the user clicks into a terminal.
      if (!visible) apply(true)
      handle = deps.setInterval(() => apply(!visible), CURSOR_BLINK_INTERVAL_MS)
    },
    restart(): void {
      if (torn || !current) return
      // Show it FIRST, and through `apply` — so the re-shown cursor's repaint goes through the same
      // bracket every other phase does and takes `pulse()`. A restart that repainted outside it
      // would hand the wake path a repaint that happens on EVERY keystroke, which is worse than the
      // twice-a-second one this design was built to keep off it.
      if (!visible) apply(true)
      // Nothing is ticking (the setting is off, or the board is up): there is no period to re-arm,
      // and starting one here would blink a cursor the gates have already stopped. `sync` owns the
      // gates; this only ever restarts a clock that is already running.
      if (!handle) return
      clearTimer()
      handle = deps.setInterval(() => apply(!visible), CURSOR_BLINK_INTERVAL_MS)
    },
    routeDamage(): void {
      const loop = deps.loop()
      // Ours: one frame, still parked. Anyone else's: `wake()`, because ordinary damage (a terminal
      // writing rows) is likely to be followed by more, and a pulse per write would put a
      // scheduling hop in front of every character.
      if (applying > 0) loop.pulse()
      else loop.wake()
    },
    stop(): void {
      torn = true
      stopClock()
      current = null
    }
  }
}

// ---------------------------------------------------------------------------------------------
// Context loss — restore ONCE per context, then fall back for good
// ---------------------------------------------------------------------------------------------

/**
 * How soon after a restore a SECOND loss means "this GPU is not coming back".
 *
 * A minute, because the two cases it separates are that far apart. A sleep/wake or a driver reset
 * takes the context away once and the machine then works for hours — that one is worth restoring,
 * and it is the whole reason this path exists (a GPU reset is what macOS does on wake, and under
 * Phase 1b it silently dropped every user to the DOM renderer until they relaunched). A GPU that is
 * genuinely failing takes it away again almost immediately, and restoring THAT in a loop is how one
 * failure becomes a flicker — the exact trade Phase 1b made by never restoring at all.
 */
export const RESTORE_COOLDOWN_MS = 60_000

/**
 * How long a suspended canvas waits for the restore it asked for before giving up.
 *
 * **`preventDefault()` is a REQUEST, not a guarantee**, and there are two ordinary ways the restore
 * never arrives: Chromium declines to restore a context whose GPU process has reset repeatedly, and
 * a SYNTHETIC loss (`WEBGL_lose_context.loseContext()` — which is how the device checklist forces
 * one) is never auto-restored at all; only an explicit `restoreContext()` on the same extension
 * object brings that one back. Without a watchdog both cases strand the session in the worst state
 * this module can produce: the engine suspended, the runtime stopped, and `failed` still FALSE — so
 * every node keeps a transparent body and keeps writing rows into a canvas that paints nothing,
 * with ONE line on the console and no second one ever, until the app is relaunched. That is
 * strictly worse than the Phase-1b behaviour this task promises to keep as its floor.
 *
 * Five seconds: a real restore lands within a few hundred milliseconds (a GPU-process restart being
 * the slow case), so this is generous by an order of magnitude, while a canvas that is never coming
 * back stays blank for a blink instead of for a session. A bounded ONE-SHOT is not the retry loop
 * the design forbids — it never asks for a second restore, it only stops waiting for the first.
 */
export const RESTORE_TIMEOUT_MS = 5000

/** Everything the policy touches, injected — so the once-only rule, the cooldown and the watchdog
 *  are testable without a GPU, a canvas, a clock or a timer, the same split
 *  `createBoardFrameGate` and `createCursorBlinkClock` make. */
export interface ContextLossDeps {
  now(): number
  /** Park everything that could draw and drop the engine's GPU objects. */
  suspend(): void
  /** Rebuild the GPU objects and resume. MAY THROW — a rebuild that fails is a permanent
   *  fallback, never a retry. */
  revive(): void
  /** The permanent fallback (`failSharedGlyph`). */
  fail(reason: string, err?: unknown): void
  setTimer(cb: () => void, ms: number): number
  clearTimer(handle: number): void
}

export interface ContextLossPolicy {
  /** Handle `webglcontextlost`. Returns whether the caller should `preventDefault()` the event —
   *  i.e. whether we are asking the browser for a restore at all. */
  onLost(): boolean
  /** Handle `webglcontextrestored`. */
  onRestored(): void
  /** Teardown: disarm the watchdog and make every later event inert. The watchdog is the one thing
   *  here that can outlive its owner, and it must not — a timer that fires after the layer has gone
   *  would fail a session whose context was merely handed back (the mode switched off), which then
   *  could not be re-enabled without a relaunch. */
  stop(): void
}

/**
 * The context-loss policy: **restore ONCE per context, never in a loop.**
 *
 * `preventDefault()` on `webglcontextlost` is what asks the browser to fire
 * `webglcontextrestored`, so it is called only when we intend to use the restore. Phase 1b
 * deliberately did not call it: there was nothing to restore into, and a session that lost its
 * context stayed on the DOM renderer until relaunch. That is a fine trade for an experimental mode
 * and an unacceptable one for the DEFAULT, because a GPU reset — sleep/wake, a driver hiccup —
 * would silently take every user's shared renderer away with no message.
 *
 * Four rules, and every one but the first is the floor Phase 1b's behaviour becomes:
 *  1. A first loss suspends and asks for a restore; the restore rebuilds and resumes.
 *  2. A second loss WITHIN `RESTORE_COOLDOWN_MS` of that restore falls back permanently. The
 *     restore is not retried, the event is not prevented, and the session goes back to the DOM
 *     renderer through the usual funnel.
 *  3. A restore that THROWS falls back permanently too — a half-rebuilt context draws nothing, and
 *     a canvas of transparent node bodies drawing nothing is indistinguishable from a freeze.
 *  4. A restore that NEVER ARRIVES falls back on a bounded watchdog (`RESTORE_TIMEOUT_MS`). Waiting
 *     forever is the one outcome that is worse than not restoring at all — see that constant.
 *
 * Every outcome is announced on the console, and that is a requirement rather than a courtesy: a
 * silent restore looks exactly like a frozen canvas to whoever is debugging one, and a silent
 * fallback looks exactly like a soft-text bug.
 */
export function createContextLossPolicy(deps: ContextLossDeps): ContextLossPolicy {
  /** When the last successful restore landed, or null while this context has never been restored. */
  let restoredAt: number | null = null
  /** Have we suspended and asked for a restore that has not arrived yet? */
  let awaiting = false
  /** Terminal: the session has fallen back, and no further event may do anything. */
  let done = false
  /** The armed watchdog, or 0 for none. Exactly one can exist: it is armed only on the transition
   *  into `awaiting` and cleared on every way out of it. */
  let watchdog = 0
  const disarm = (): void => {
    if (!watchdog) return
    deps.clearTimer(watchdog)
    watchdog = 0
  }
  /** The one place a give-up is spelled: disarm first, so no timer can fire a second, contradictory
   *  reason for a failure that has already been reported. */
  const giveUp = (reason: string, err?: unknown): void => {
    disarm()
    done = true
    deps.fail(reason, err)
  }
  return {
    onLost(): boolean {
      if (done) return false
      // A second `webglcontextlost` for the SAME outage (a duplicate event, a loss racing our own
      // teardown) is not a second failure — we are already suspended and already waiting.
      if (awaiting) return true
      if (restoredAt !== null && deps.now() - restoredAt < RESTORE_COOLDOWN_MS) {
        giveUp(
          `the WebGL context was lost again within ${Math.round(
            RESTORE_COOLDOWN_MS / 1000
          )}s of a restore — not restoring a second time`
        )
        return false
      }
      awaiting = true
      console.warn(
        '[glyphgrid] WebGL context lost — GPU objects dropped and frames parked; asking the browser to restore it'
      )
      // Armed BEFORE the suspend, so the wait can never outlive its own bound even if the suspend
      // path throws on its way through the runtime teardown.
      watchdog = deps.setTimer(() => {
        watchdog = 0
        if (done || !awaiting) return
        awaiting = false
        giveUp('the WebGL context was lost and never restored')
      }, RESTORE_TIMEOUT_MS)
      deps.suspend()
      return true
    },
    onRestored(): void {
      // A restore we did not ask for (the browser handing one back after we have already given up)
      // must not rebuild anything: the engine would double-create every grid's buffer, and the
      // session has already been told it is on the DOM renderer.
      if (done || !awaiting) return
      awaiting = false
      // The wait is over however it ends — a watchdog left running would fail a session that has
      // just recovered perfectly well.
      disarm()
      try {
        deps.revive()
      } catch (err) {
        giveUp('rebuilding the GPU objects after a context restore threw', err)
        return
      }
      // Recorded only on SUCCESS — the cooldown measures "how long did the restored context
      // survive", and a failed rebuild never produced one to measure.
      restoredAt = deps.now()
      console.warn(
        '[glyphgrid] WebGL context restored — GPU objects and every registered grid rebuilt; the canvas repaints in full'
      )
    },
    stop(): void {
      disarm()
      done = true
    }
  }
}

// ---------------------------------------------------------------------------------------------
// The component
// ---------------------------------------------------------------------------------------------

/**
 * Hosts the shared canvas inside the React Flow pane and drives its frames.
 *
 * **Stacking.** React Flow's own layers, from `@xyflow/react`'s base.css: `.react-flow__background`
 * is z-index -1 and `.react-flow__renderer` (which contains the pane and the transformed viewport
 * holding every node) is z-index 4, all inside the `.react-flow` wrapper's own stacking context.
 * Children passed to `<ReactFlow>` — this component, like `<Background/>` — render as siblings of
 * both. z-index 0 therefore puts the glyph canvas ABOVE the dot grid and BELOW the nodes, which is
 * where it has to be: node bodies stay opaque in v1, so the DOM keeps owning node chrome and
 * stacking, and the canvas only orders grids among themselves.
 *
 * **Not inside the viewport.** The canvas is screen-space — the engine applies the camera itself
 * in the shader — so it must not sit under React Flow's CSS transform, which would scale its
 * pixels instead.
 */
export function SharedGlyphLayer(): JSX.Element {
  const hostRef = useRef<HTMLDivElement>(null)
  const generation = useSharedGlyph((s) => s.generation)
  const failed = useSharedGlyph((s) => s.failed)
  /** Bumped when a terminal BUILDS the context. The layer cannot build one itself — the atlas
   *  geometry comes from a live terminal's device cell (see `DeviceCell`) — so whichever of the
   *  two runs first, the canvas still gets mounted: if this effect ran first it found nothing and
   *  this tick brings it back. Declared BEFORE the mounting effect so the subscription is live by
   *  the time a terminal in the same commit can create one. */
  const [contextTick, setContextTick] = useState(0)
  useEffect(() => subscribeSharedGlyphContext(() => setContextTick((n) => n + 1)), [])

  useEffect(() => {
    const host = hostRef.current
    if (!host || failed) return
    // No cell argument: the component never CREATES a context, it only adopts one.
    const ctx = ensureLiveContext()
    if (!ctx) return
    const canvas = ctx.canvas
    host.appendChild(canvas)

    // THE ONE INVARIANT SPANNING THE MODULE SINGLETON AND THIS EFFECT: the engine's suspended state
    // outlives the component, while the restore POLICY below is effect-scoped. A layer that
    // unmounted between a loss and its restore would therefore come back with a policy that is not
    // waiting for anything (`awaiting` false, so `onRestored` short-circuits) while the engine is
    // still suspended and `failed` is still false — the stranded canvas again, by a different road.
    // Unreachable today (every path that unmounts this effect disposes the context first, and a
    // fresh context is never suspended), which is exactly why it is worth a guard rather than a
    // comment: nothing enforces that ordering, and a mount is the one moment we can still decide.
    if (ctx.engine.gpuIsSuspended()) {
      try {
        // Rebuilt instead of revived (a blanked atlas page) means this context is gone and the
        // generation bump will re-run this effect against the fresh one.
        if (!reviveGpuOrRebuild(ctx)) return
        console.warn('[glyphgrid] mounted onto a suspended engine — GPU objects rebuilt')
      } catch (err) {
        // The context is still gone (its programs will not compile), so there is nothing to mount
        // onto. `failSharedGlyph` disposes it and re-runs this effect with `failed` true.
        failSharedGlyph('a suspended engine could not be revived at mount', err)
        return
      }
    }

    // DELIBERATELY OUTSIDE `startRuntime` BELOW — it must keep running through a context outage.
    // It draws nothing (`setViewport` only resizes the backing store and dirties), and it is what
    // keeps the GL layer's `deviceW`/`deviceH` current while the context is gone, so the viewport
    // the rebuild re-pushes is the size the canvas actually is. Moved into the runtime, a window
    // resized during an outage would come back with its grids culled against a stale viewport.
    const pushViewport = (): void => {
      const dpr = currentDpr()
      // A display change (the window dragged onto a monitor with a different pixel ratio) arrives
      // HERE, from whichever of the triggers below sees it first, and it is the one viewport input
      // the engine cannot absorb, because the ATLAS was rasterized for the old ratio. So it is
      // checked before the push: on a rebuild the context this closure holds is already gone, and
      // the fresh one gets its viewport from the re-run effect's own `pushViewport()`.
      if (syncAtlasPixelRatio(dpr, ctx) || ctx.disposed) return
      // The engine change-gates all three inputs, so calling this from every observer tick is
      // free when nothing actually moved.
      ctx.engine.setViewport(host.clientWidth, host.clientHeight, dpr)
    }
    pushViewport()

    // ResizeObserver, not just window resize: the pane also changes size when a drawer or the
    // sessions sidebar opens, and a stale viewport culls the wrong grids.
    const ro = new ResizeObserver(pushViewport)
    ro.observe(host)
    // ...and window `resize` on top of it, for the ordinary window-size changes that move the CSS
    // box without moving the host's (and as ONE of the two triggers for a dpr change).
    window.addEventListener('resize', pushViewport)
    // THE OTHER dpr trigger, and DO NOT DELETE EITHER AS REDUNDANT. Dragging the window to a
    // display with a different pixel ratio leaves the CSS box identical, so the ResizeObserver is
    // silent and only `resize` — if Blink dispatches one for a scale-factor change with an
    // unchanged CSS viewport — would carry it. xterm does not rely on that: its `CoreBrowserService`
    // watches this media query, and this atlas latches xterm's own device cell, so it watches the
    // same thing. Both land in `pushViewport`, whose `syncAtlasPixelRatio` re-entry guard makes a
    // double fire free.
    const dprWatch = createPixelRatioWatcher(
      {
        dpr: currentDpr,
        match: (query) =>
          typeof window !== 'undefined' && typeof window.matchMedia === 'function'
            ? window.matchMedia(query)
            : null
      },
      pushViewport
    )

    /**
     * EVERYTHING THAT CAN DRAW OR SCHEDULE A FRAME, as one startable/stoppable unit. (The three
     * viewport triggers above are the deliberate exception — they schedule nothing; see their
     * comments.)
     *
     * It is a unit because a lost context has to take ALL of it down at once and a restore has to
     * bring exactly it back: the rAF chain, the heartbeat timer, the blink clock's interval, the
     * damage subscription and the four store/window subscriptions that can wake or rebuild any of
     * them. A single survivor is a frame submitted against GPU objects that no longer exist — which
     * the driver's catch reads as a GPU failure and answers by burning the session that is in the
     * middle of recovering. And a single thing started twice is two rAF chains on one canvas.
     *
     * The mount path and the restore path therefore run the same function, and the cleanup below
     * and the suspend path run the same `stop()`.
     */
    const startRuntime = (): { stop(): void } => {
      // The frame loop PARKS when the canvas goes quiet — an always-registered rAF keeps Chromium's
      // whole frame pipeline ticking at the display's refresh rate to draw nothing. All the
      // scheduling and the park/heartbeat policy live in `createFrameLoop` (unit-tested there); this
      // only supplies the seams and the wake signals.
      //
      // The gate around it answers the case the park cannot: the kanban board covering the canvas.
      // It owns starting and stopping (including the "mounted while the board is already up" case),
      // which is why there is no `loop.start()` here — see `createBoardFrameGate`.
      const gate = createBoardFrameGate(boardCoversCanvas, () =>
        createFrameLoop({
          // The context can be torn down synchronously between a schedule and its callback (font
          // change, dpr change, mode switched off); the loop stops itself rather than rescheduling,
          // and the cleanup below is idempotent either way.
          alive: () => !ctx.disposed,
          frame: () => ctx.engine.frame(),
          // `frame()` rethrows by contract, having restored its own damage. A throw is a GL error
          // rather than a lost context (that arrives as an EVENT, handled below), and there is no
          // recovery from it: the whole session goes back to the DOM renderer.
          onError: (err) => failSharedGlyph('frame threw', err),
          requestFrame: (cb) => requestAnimationFrame(cb),
          cancelFrame: (h) => cancelAnimationFrame(h),
          setTimer: (cb, ms) => window.setTimeout(cb, ms),
          clearTimer: (h) => window.clearTimeout(h)
        })
      )
      // ONE blink clock for the whole canvas — not one per terminal — because at most one terminal
      // has focus. It reaches the loop through `gate.loop()` for the same reason the damage
      // subscription does, and its own repaints take `pulse()` rather than `wake()`; see
      // `createCursorBlinkClock` for why that distinction is the whole task.
      const clock = createCursorBlinkClock({
        enabled: () => useSettings.getState().settings.cursorBlink,
        covered: boardCoversCanvas,
        target: cursorBlinkTarget,
        loop: () => gate.loop(),
        setInterval: (cb, ms) => window.setInterval(cb, ms),
        clearInterval: (h) => window.clearInterval(h)
      })
      // Mounted with a terminal already focused (a remount, a project switch back, a restore that
      // never took focus away) must start the clock, exactly as the gate reads the board flag at
      // construction rather than assuming.
      clock.sync()
      // THE wake mechanism: the engine funnels every damage write through `markDirty`, which calls
      // out on the clean→dirty edge. A parked loop resumes on the very next damaging write. Reached
      // through `gate.loop()` and never captured — leaving the board builds a fresh loop, and a
      // subscription pinned to the stopped one would freeze the canvas for the rest of the session.
      //
      // Routed through the clock, which is the only thing that can tell the blink's own repaint from
      // everybody else's damage: its repaint is isolated in time and takes `pulse()` (one frame, still
      // parked), while ordinary damage keeps the `wake()` it has always had.
      const damage = ctx.engine.onDamage(() => clock.routeDamage())
      // The two gates that can move without the board moving: the blink SETTING and which terminal
      // holds focus. Both are change-gated inside `sync`.
      const unsubBlinkTarget = subscribeCursorBlinkTarget(() => clock.sync())
      // The settings store moves the board too (the Omni feature flag gates `globalKanban`), so this
      // one subscription re-syncs the gate as well — `syncBoard` below, inlined because it is
      // declared after; both members are change-gated, so a settings write that moved neither is
      // two comparisons.
      const unsubBlinkSetting = useSettings.subscribe(() => {
        gate.sync()
        clock.sync()
      })
      // ...and the cursor MOVING, which is not a gate at all: it holds the cursor solid and starts
      // the period over, exactly as xterm does while you type. Its own channel, because `sync` is
      // deliberately a no-op while the interval is already running.
      const unsubBlinkRestart = subscribeCursorBlinkRestart(() => clock.restart())
      // Belt and braces for the background-throttling case (Task 9): a park entered while the window
      // was occluded must not outlive the return, and a throttled/coalesced rAF can leave the loop
      // parked with damage pending. Both are cheap — `wake()` only schedules a frame that draws
      // nothing when there is nothing to draw, and it is inert while the board is up.
      const onVisible = (): void => {
        if (!document.hidden) gate.loop().wake()
      }
      const onFocus = (): void => gate.loop().wake()
      window.addEventListener('focus', onFocus)
      document.addEventListener('visibilitychange', onVisible)
      // Both stores, because either can move the board over this canvas: the view toggle, and a
      // switch to a project that is already on it. `sync` is change-gated, so the projects store's
      // chattier notifications (it is rewritten on every node serialization) cost a comparison.
      // The board is the blink clock's third gate as well (a stopped loop cannot draw the phase), so
      // the two are synced together — and the gate goes FIRST, so the clock reads the board through
      // an already-updated loop.
      const syncBoard = (): void => {
        gate.sync()
        clock.sync()
      }
      const unsubView = useViewMode.subscribe(syncBoard)
      const unsubProjects = useProjects.subscribe(syncBoard)
      let stopped = false
      return {
        stop(): void {
          // Idempotent: the suspend path and the effect cleanup can both reach the same runtime
          // (a lost context that is immediately followed by an unmount), and every member below
          // would be stopped twice otherwise.
          if (stopped) return
          stopped = true
          // Everything the loop owns goes at once — the pending frame, the heartbeat TIMER and the
          // damage subscription — plus the two store subscriptions that can hand it a new one. A
          // surviving timer would keep calling `frame()` on a context this run has let go of, a
          // surviving damage subscription would keep a dead loop reachable from the engine, and a
          // surviving board subscription would BUILD a loop against a disposed context.
          // `gate.stop()` is idempotent and also makes a `sync` still in flight inert, so the
          // `ctx.disposed` and `failSharedGlyph` paths (which stop the loop themselves) land here
          // safely too.
          // The clock goes FIRST, and before the unsubscribes: it hands the cursor back SHOWN, and
          // it can only do that while it still HOLDS the target — `stop()` drops it. What that buys
          // is the packed ROW, not a drawn frame: the `pulse()` it schedules is cancelled moments
          // later by `gate.stop()`, and the point is that the grid's buffers no longer hold a hidden
          // cursor, so whatever draws them next (a remount, the board closing) draws a cursor. Its
          // restore is guarded inside `stopClock`, so a throwing repack cannot skip the teardown
          // below it.
          clock.stop()
          unsubBlinkTarget()
          unsubBlinkRestart()
          unsubBlinkSetting()
          gate.stop()
          unsubView()
          unsubProjects()
          damage.dispose()
          window.removeEventListener('focus', onFocus)
          document.removeEventListener('visibilitychange', onVisible)
        }
      }
    }
    let runtime = startRuntime()

    /**
     * A lost context is now SURVIVABLE — see `createContextLossPolicy` for the once-only rule and
     * the cooldown that keeps it from becoming a retry loop.
     *
     * The two halves are ordered against each other on purpose. On the way DOWN the runtime stops
     * before the engine drops its GPU objects, so no frame can be submitted in between; on the way
     * UP the GPU objects are rebuilt before a fresh runtime exists to schedule anything, so the
     * first frame of the new context has something to draw with. `reviveGpu` throws if the rebuild
     * fails, and the policy answers that with the permanent fallback — the runtime stays stopped,
     * which is the correct state for a session that is going back to the DOM renderer.
     */
    const policy = createContextLossPolicy({
      now: () => Date.now(),
      suspend: () => {
        runtime.stop()
        ctx.engine.suspendGpu()
      },
      revive: () => {
        // A GPU reset takes the atlas page with the context. Reviving onto a blanked page would
        // upload an empty atlas over every terminal on the canvas, so that case rebuilds instead —
        // and there is no runtime to start here, because there is no longer a context to start it
        // against.
        if (!reviveGpuOrRebuild(ctx)) return
        runtime = startRuntime()
      },
      fail: (reason, err) => failSharedGlyph(reason, err),
      setTimer: (cb, ms) => window.setTimeout(cb, ms),
      clearTimer: (h) => window.clearTimeout(h)
    })
    // `preventDefault()` is the request for a `webglcontextrestored` event, so it is called only
    // when the policy actually intends to use one. Phase 1b never called it at all.
    const onLost = (e: Event): void => {
      if (policy.onLost()) e.preventDefault()
    }
    const onRestored = (): void => policy.onRestored()
    canvas.addEventListener('webglcontextlost', onLost)
    canvas.addEventListener('webglcontextrestored', onRestored)

    return () => {
      // Nothing may outlive the context — this is also the teardown for the `ctx.disposed` and
      // `failSharedGlyph` paths, both of which re-run this effect. `runtime` is read (not captured)
      // so a cleanup after a restore stops the CURRENT runtime rather than the one this effect run
      // started with. The policy goes with it, so its watchdog cannot outlive the context it was
      // waiting on.
      runtime.stop()
      policy.stop()
      ro.disconnect()
      window.removeEventListener('resize', pushViewport)
      dprWatch.stop()
      canvas.removeEventListener('webglcontextlost', onLost)
      canvas.removeEventListener('webglcontextrestored', onRestored)
      // The canvas leaves the DOM with the host div; the CONTEXT stays alive for the next mount
      // (a project switch must not cost a context rebuild). Only `failSharedGlyph` and a font
      // change dispose it.
    }
  }, [generation, failed, contextTick])

  return (
    <div
      ref={hostRef}
      className="glyphgrid-layer"
      style={{ position: 'absolute', inset: 0, zIndex: 0, pointerEvents: 'none' }}
    />
  )
}