Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

9.4 KB
Raw Blame
/**
 * The canvas render loop: a thin, framework-agnostic shell around the pure math
 * and the recursive draw. Browser code.
 *
 * Dirty-flag `requestAnimationFrame`: the loop only paints when something
 * actually changed (`invalidate()`), then stops, so an idle canvas costs zero
 * CPU. A running camera fly (`animateTo` / `frameNode`) keeps the loop alive for
 * its duration and then settles. The backing store is sized to `devicePixelRatio`
 * for crisp text, and a short low-detail window after a pan suppresses
 * labels/relations so dragging stays smooth. A WebGL upgrade path is open: the
 * draw layer is isolated behind `drawScene`, so a future GPU backend can replace
 * it without touching camera, culling or scene code.
 */

import { type Camera, type Viewport, fitRoot, frameRect } from "./camera";
import { flyDuration, interpolateCamera } from "./camera-anim";
import { type DrawStats, drawScene, pickNode } from "./draw-tree";
import { focusChain } from "./focus-path";
import { PaperTexture } from "./paper";
import type { ZoomScene } from "./scene";
import type { ZoomPalette } from "./theme";
import type { ZoomNode } from "./types";

/**
 * Set equality, so a caller that rebuilds its verb set every render does not
 * force a repaint. The sets hold at most the label vocabulary (seven verbs), so
 * a pair of loops beats keeping a sorted key around.
 */
function sameVerbs(a: ReadonlySet<string> | null, b: ReadonlySet<string> | null): boolean {
  if (a === b) return true;
  if (a === null || b === null || a.size !== b.size) return false;
  for (const v of a) if (!b.has(v)) return false;
  return true;
}

export interface FrameStats {
  drawn: number;
  culled: number;
  maxDepthDrawn: number;
  frameMs: number;
}

export interface FlyOptions {
  /** Explicit duration in ms; omitted -> derived from travel distance. */
  durationMs?: number;
  /** Skip the tween and jump (used for reduced-motion and URL restore). */
  reducedMotion?: boolean;
  /** Fraction of the viewport the framed node should fill. */
  fill?: number;
}

export interface ZoomRendererOptions {
  canvas: HTMLCanvasElement;
  palette: ZoomPalette;
  onStats?: ((stats: FrameStats) => void) | undefined;
  /** Fires (with the root -> focus chain) whenever the focus node changes. */
  onFocus?: ((chain: ZoomNode[]) => void) | undefined;
}

const PAN_LOW_DETAIL_FRAMES = 2;

interface Tween {
  from: Camera;
  to: Camera;
  start: number;
  dur: number;
}

function now(): number {
  return typeof performance !== "undefined" ? performance.now() : 0;
}

export class ZoomRenderer {
  private readonly canvas: HTMLCanvasElement;
  private readonly ctx: CanvasRenderingContext2D;
  private palette: ZoomPalette;
  private readonly onStats: ((stats: FrameStats) => void) | undefined;
  private readonly onFocus: ((chain: ZoomNode[]) => void) | undefined;
  /** Shared ruled-paper card texture; repaints once when the asset loads. */
  private readonly paper: PaperTexture;

  private scene: ZoomScene | null = null;
  private cam: Camera = { cx: 0.5, cy: 0.5, scale: 600 };
  private vp: Viewport = { w: 1, h: 1 };
  private dpr = 1;
  private hasFramedScene = false;

  private selectedId: string | null = null;
  private hoveredId: string | null = null;
  private relationVerbs: ReadonlySet<string> | null = null;
  private lowDetailFrames = 0;
  private tween: Tween | null = null;
  private lastFocusId: string | null = null;
  private dirty = true;
  private rafId: number | null = null;
  private lastStats: DrawStats | null = null;

  constructor(opts: ZoomRendererOptions) {
    this.canvas = opts.canvas;
    const ctx = opts.canvas.getContext("2d");
    if (!ctx) throw new Error("ZoomRenderer: 2D canvas context unavailable");
    this.ctx = ctx;
    this.palette = opts.palette;
    this.onStats = opts.onStats;
    this.onFocus = opts.onFocus;
    // Repaint once the paper photo decodes so the first frame picks up the texture.
    this.paper = new PaperTexture(() => this.invalidate());
    this.resize();
  }

  getCamera(): Camera {
    return this.cam;
  }

  getViewport(): Viewport {
    return this.vp;
  }

  /** Manual camera set (pan/zoom): cancels any running fly. */
  setCamera(cam: Camera): void {
    this.tween = null;
    this.cam = cam;
    this.invalidate();
  }

  setPalette(palette: ZoomPalette): void {
    this.palette = palette;
    this.invalidate();
  }

  setSelected(id: string | null): void {
    if (id === this.selectedId) return;
    this.selectedId = id;
    this.invalidate();
  }

  /** The hovered node lifts its incident relations and firms its border. */
  setHovered(id: string | null): void {
    if (id === this.hoveredId) return;
    this.hoveredId = id;
    this.invalidate();
  }

  /** Restrict drawn relations to these verbs, or null for all of them. */
  setRelationVerbs(verbs: ReadonlySet<string> | null): void {
    if (sameVerbs(verbs, this.relationVerbs)) return;
    this.relationVerbs = verbs;
    this.invalidate();
  }

  setScene(scene: ZoomScene): void {
    this.scene = scene;
    // Only frame once we have a real layout size; otherwise the first resize
    // callback (which delivers the true dimensions) does the initial fit.
    if (!this.hasFramedScene && this.vp.w > 1) {
      this.cam = fitRoot(this.vp);
      this.hasFramedScene = true;
    }
    this.invalidate();
  }

  /** Has the scene been framed at least once (initial fit done)? */
  isFramed(): boolean {
    return this.hasFramedScene;
  }

  /**
   * Animate the camera to `target`. Reduced-motion or duration<=0 jumps. Calling
   * this mid-fly is intentional: `this.cam` is the live tweened position the last
   * frame drew, so a new fly starts smoothly from there (and `flyDuration` sizes
   * itself to the now-shorter remaining travel) rather than snapping.
   */
  animateTo(target: Camera, opts: FlyOptions = {}): void {
    if (opts.reducedMotion) {
      this.setCamera(target);
      return;
    }
    const dur = opts.durationMs ?? flyDuration(this.cam, target);
    if (dur <= 0) {
      this.setCamera(target);
      return;
    }
    this.tween = { from: this.cam, to: target, start: now(), dur };
    this.invalidate();
  }

  /** Fly the camera to frame a node by id. Returns false if it is not laid out. */
  frameNode(id: string, opts: FlyOptions = {}): boolean {
    if (!this.scene) return false;
    const rect = this.scene.worldRects.get(id);
    if (!rect) return false;
    this.animateTo(frameRect(this.vp, rect, opts.fill ?? 0.72), opts);
    return true;
  }

  /** Re-read the element size and resize the backing store for crisp pixels. */
  resize(): void {
    const cssW = Math.max(1, this.canvas.clientWidth);
    const cssH = Math.max(1, this.canvas.clientHeight);
    const dpr = typeof window === "undefined" ? 1 : window.devicePixelRatio || 1;
    this.dpr = dpr;
    this.vp = { w: cssW, h: cssH };
    this.canvas.width = Math.round(cssW * dpr);
    this.canvas.height = Math.round(cssH * dpr);
    // Deferred initial fit, once the element has a real size.
    if (this.scene && !this.hasFramedScene && cssW > 1) {
      this.cam = fitRoot(this.vp);
      this.hasFramedScene = true;
    }
    this.invalidate();
  }

  /** Flag the next pan window so labels/relations are suppressed briefly. */
  markPanFrame(): void {
    this.lowDetailFrames = PAN_LOW_DETAIL_FRAMES;
  }

  /** Hit-test the most recently drawn frame. */
  pick(sx: number, sy: number): string | null {
    return this.lastStats ? pickNode(this.lastStats, sx, sy) : null;
  }

  invalidate(): void {
    this.dirty = true;
    if (this.rafId === null && typeof requestAnimationFrame !== "undefined") {
      this.rafId = requestAnimationFrame(this.frame);
    }
  }

  destroy(): void {
    if (this.rafId !== null && typeof cancelAnimationFrame !== "undefined") {
      cancelAnimationFrame(this.rafId);
    }
    this.rafId = null;
  }

  private emitFocus(): void {
    if (!this.scene || !this.onFocus) return;
    const chain = focusChain(this.scene, this.cam, this.vp);
    const id = chain.length > 0 ? chain[chain.length - 1]!.id : this.scene.rootId;
    if (id !== this.lastFocusId) {
      this.lastFocusId = id;
      this.onFocus(chain);
    }
  }

  private readonly frame = (): void => {
    this.rafId = null;

    let animating = false;
    if (this.tween) {
      const t = (now() - this.tween.start) / this.tween.dur;
      if (t >= 1) {
        this.cam = this.tween.to;
        this.tween = null;
      } else {
        this.cam = interpolateCamera(this.tween.from, this.tween.to, t);
        animating = true;
      }
      this.dirty = true;
    }

    if (!this.dirty) return;

    const start = now();
    this.ctx.setTransform(this.dpr, 0, 0, this.dpr, 0, 0);

    if (this.scene) {
      const lowDetail = this.lowDetailFrames > 0;
      this.lastStats = drawScene(this.ctx, this.scene, this.cam, this.vp, this.palette, {
        selectedId: this.selectedId,
        hoveredId: this.hoveredId,
        lowDetail,
        paper: this.paper,
        relationVerbs: this.relationVerbs,
      });
      if (this.onStats) {
        this.onStats({
          drawn: this.lastStats.drawn,
          culled: this.lastStats.culled,
          maxDepthDrawn: this.lastStats.maxDepthDrawn,
          frameMs: now() - start,
        });
      }
      this.emitFocus();
    }

    this.dirty = false;
    if (this.lowDetailFrames > 0) this.lowDetailFrames--;
    // Keep the loop alive while a fly is in flight or a pan window is settling.
    if (animating || this.lowDetailFrames > 0) this.invalidate();
  };
}