CRT Terminal

A real terminal on a curved, glowing CRT.

Experimental · Chrome origin trialChecking support…

Built on the WICG HTML-in-Canvas proposal, which is not a web standard and changes between Chrome versions. Every component works without it: other browsers get the same live DOM with a CSS approximation of the effect.

To try the native version locally, open Chrome Canary and enable chrome://flags/#canvas-draw-element. In production, register for the origin trial and set NEXT_PUBLIC_HTML_IN_CANVAS_OT_TOKEN.

Checking support…

hantui terminal

Type 'help' to see what this shell can do.

Installation

CLI

npx shadcn@latest add https://hantui-theta.vercel.app/r/crt-terminal.json

Manual

Install the dependencies
npm install clsx motion tailwind-merge

Add the shared helpers

Components use cn() from lib/utils.ts and the motion tokens below. See Installation if you have not set them up yet.

lib/html-canvas/gl.ts

/**
 * Small WebGL2 helpers shared by the HTML-in-Canvas components. Shaders work in the canvas's CSS
 * pixels, so a DOMMatrix used to draw an element is the same one passed to `syncElementGeometry`.
 */

/**
 * GLSL: projects a CSS-px position (already multiplied by the draw matrix, so it may carry a
 * perspective w) to clip space. Keeps w for perspective-correct texturing. Needs `uniform vec2 u_canvas`.
 */
export const PROJECT_GLSL = /* glsl */ `
uniform vec2 u_canvas;
vec4 projectCss(vec4 q) {
  return vec4(2.0 * q.x / u_canvas.x - q.w, -(2.0 * q.y / u_canvas.y - q.w), 0.0, q.w);
}`;

/** GLSL: signed distance to a rounded rectangle centered at the origin (half size `b`, radius `r`). */
export const ROUND_RECT_GLSL = /* glsl */ `
float sdRoundRect(vec2 p, vec2 b, float r) {
  vec2 q = abs(p) - b + r;
  return length(max(q, 0.0)) + min(max(q.x, q.y), 0.0) - r;
}`;

function compile(gl: WebGL2RenderingContext, type: number, source: string) {
  const shader = gl.createShader(type);
  if (!shader) throw new Error("Could not create a shader");
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS) && !gl.isContextLost()) {
    const log = gl.getShaderInfoLog(shader);
    gl.deleteShader(shader);
    throw new Error(`Shader compile failed: ${log}`);
  }
  return shader;
}

export interface Program {
  program: WebGLProgram;
  /** Cached uniform location lookup. */
  u: (name: string) => WebGLUniformLocation | null;
}

/** Compiles and links a program. Attribute 0 is always `a_pos`. */
export function createProgram(gl: WebGL2RenderingContext, vertex: string, fragment: string): Program {
  const program = gl.createProgram();
  if (!program) throw new Error("Could not create a program");
  gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, vertex));
  gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, fragment));
  gl.bindAttribLocation(program, 0, "a_pos");
  gl.linkProgram(program);
  if (!gl.getProgramParameter(program, gl.LINK_STATUS) && !gl.isContextLost()) throw new Error(`Program link failed: ${gl.getProgramInfoLog(program)}`);
  const cache = new Map<string, WebGLUniformLocation | null>();
  return {
    program,
    u: (name) => {
      if (!cache.has(name)) cache.set(name, gl.getUniformLocation(program, name));
      return cache.get(name) ?? null;
    },
  };
}

export interface Mesh {
  vao: WebGLVertexArrayObject;
  count: number;
}

/** A unit grid over [0, 1]² as indexed triangles, in attribute 0. One cell is a plain quad. */
export function createGrid(gl: WebGL2RenderingContext, cols = 1, rows = 1): Mesh {
  const vao = gl.createVertexArray();
  if (!vao) throw new Error("Could not create a vertex array");
  gl.bindVertexArray(vao);
  const positions: number[] = [];
  for (let y = 0; y <= rows; y++) for (let x = 0; x <= cols; x++) positions.push(x / cols, y / rows);
  const indices: number[] = [];
  for (let y = 0; y < rows; y++) {
    for (let x = 0; x < cols; x++) {
      const i = y * (cols + 1) + x;
      indices.push(i, i + 1, i + cols + 1, i + 1, i + cols + 2, i + cols + 1);
    }
  }
  const vbo = gl.createBuffer();
  gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
  gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(positions), gl.STATIC_DRAW);
  gl.enableVertexAttribArray(0);
  gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
  const ibo = gl.createBuffer();
  gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, ibo);
  gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, new Uint32Array(indices), gl.STATIC_DRAW);
  gl.bindVertexArray(null);
  return { vao, count: indices.length };
}

/** Draws a mesh from `createGrid`. */
export function drawMesh(gl: WebGL2RenderingContext, mesh: Mesh, instances = 0) {
  gl.bindVertexArray(mesh.vao);
  if (instances > 0) gl.drawElementsInstanced(gl.TRIANGLES, mesh.count, gl.UNSIGNED_INT, 0, instances);
  else gl.drawElements(gl.TRIANGLES, mesh.count, gl.UNSIGNED_INT, 0);
  gl.bindVertexArray(null);
}

/** Uploads a DOMMatrix to a mat4 uniform. */
export function setMatrix(gl: WebGL2RenderingContext, location: WebGLUniformLocation | null, matrix: DOMMatrix) {
  gl.uniformMatrix4fv(location, false, matrix.toFloat32Array());
}

/** Parses "#rrggbb" into 0–1 RGB. */
export function rgb(hex: string): [number, number, number] {
  const h = hex.replace("#", "");
  const n = Number.parseInt(h.length === 3 ? h.replace(/./g, (c) => c + c) : h, 16) || 0;
  return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];
}

lib/html-canvas/setup.ts

import type { HtmlCanvasSupport } from "@/lib/html-canvas/support";

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */

/**
 * Attributes that make a canvas lay out and paint its children, for use in JSX so the canvas is
 * drawable from its first layout: `content="drawable"` on 155+, `layoutsubtree` before that.
 */
export function drawableCanvasAttributes(support: HtmlCanvasSupport): Record<string, string> {
  if (support.version === "155+") return { content: "drawable" };
  if (support.version === "none") return {};
  return { layoutsubtree: "" };
}

/** Makes a canvas drawable after the fact (idempotent). */
export function prepareDrawableCanvas(canvas: HTMLCanvasElement) {
  const c = canvas as any;
  if ("content" in HTMLCanvasElement.prototype) {
    if (canvas.getAttribute("content") !== "drawable") canvas.setAttribute("content", "drawable");
  } else if (!canvas.hasAttribute("layoutsubtree")) {
    canvas.setAttribute("layoutsubtree", "");
    if ("layoutSubtree" in c) c.layoutSubtree = true;
  }
}

/**
 * Attributes for an element the canvas draws on its own. On 155+ it must carry `drawable`; on older
 * versions it must instead be a direct child of the canvas, which callers arrange in their markup.
 */
export function drawableElementAttributes(support: HtmlCanvasSupport): Record<string, string> {
  return support.version === "155+" ? { drawable: "" } : {};
}

/** Asks the canvas for a `paint` event on the next frame, where supported. */
export function requestCanvasPaint(canvas: HTMLCanvasElement) {
  const c = canvas as any;
  if (typeof c.requestPaint === "function") c.requestPaint();
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/support.ts

/**
 * Feature detection for the experimental HTML-in-Canvas API (WICG html-in-canvas). The API is a
 * Chrome origin trial, not a standard, and its shape changed in Chrome 150 and 155. Nothing outside
 * `src/lib/html-canvas/` may touch it: every call goes through these adapters.
 *
 * - 155+: `content="drawable"`, `drawable` descendants, `texElementSubImage2D`,
 *   `canvas.updateElementGeometry()` and automatic hit-testing for 2D draws.
 * - 150–154: `layoutsubtree`, `drawElementImage()` returning a DOMMatrix, `texElementImage2D(target,
 *   internalformat, element)` and `canvas.getElementTransform(element, drawTransform)`.
 * - legacy (< 150): `texElementImage2D(target, level, internalformat, format, type, element)`.
 */

export type HtmlCanvasVersion = "155+" | "150-154" | "legacy" | "none";

export interface HtmlCanvasSupport {
  /** `drawElementImage` on 2D contexts. */
  twoD: boolean;
  /** Element textures in WebGL2. */
  webgl: boolean;
  /** Element textures in WebGPU. */
  webgpu: boolean;
  version: HtmlCanvasVersion;
}

export const NO_SUPPORT: HtmlCanvasSupport = { twoD: false, webgl: false, webgpu: false, version: "none" };

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */
let cached: HtmlCanvasSupport | null = null;

/** What this browser supports. Always "none" on the server. Cached after the first call. */
export function getHtmlCanvasSupport(): HtmlCanvasSupport {
  if (typeof window === "undefined" || typeof HTMLCanvasElement === "undefined") return NO_SUPPORT;
  if (cached) return cached;
  const canvasProto = HTMLCanvasElement.prototype as any;
  const ctx2d = typeof CanvasRenderingContext2D !== "undefined" ? (CanvasRenderingContext2D.prototype as any) : {};
  const gl2 = typeof WebGL2RenderingContext !== "undefined" ? (WebGL2RenderingContext.prototype as any) : {};
  const gpuQueue = typeof (window as any).GPUQueue !== "undefined" ? (window as any).GPUQueue.prototype : {};

  const twoD = "drawElementImage" in ctx2d;
  const sub = "texElementSubImage2D" in gl2;
  const tex = "texElementImage2D" in gl2;
  const webgpu = "drawElementImageToTexture" in gpuQueue || "copyElementImageToTexture" in gpuQueue;

  let version: HtmlCanvasVersion = "none";
  if (sub || "content" in canvasProto || "updateElementGeometry" in canvasProto) version = "155+";
  else if (tex) version = typeof gl2.texElementImage2D === "function" && gl2.texElementImage2D.length >= 6 ? "legacy" : "150-154";
  else if (twoD || "layoutSubtree" in canvasProto) version = "150-154";

  cached = { twoD, webgl: sub || tex, webgpu, version };
  return cached;
}

/** True when the API can draw into the given context type. */
export function supportsContext(support: HtmlCanvasSupport, context: "2d" | "webgl2") {
  return support.version !== "none" && (context === "2d" ? support.twoD : support.webgl);
}

/** A short label for status chips: "Chrome 150–154 API". */
export function describeSupport(support: HtmlCanvasSupport) {
  if (support.version === "none") return "Not supported";
  return { "155+": "Chrome 155+ API", "150-154": "Chrome 150–154 API", legacy: "Pre-150 API" }[support.version];
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/sync-geometry.ts

import { getHtmlCanvasSupport } from "@/lib/html-canvas/support";

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */

/**
 * Tells the browser where an element is drawn, so clicks, text selection, focus rings and screen
 * reader focus land on the drawn pixels. `canvasTransform` maps the element's own CSS px (origin at
 * its top-left) to the canvas's CSS px, and may include perspective; it is converted to the device
 * pixels the API expects.
 *
 * Canvas children are laid out at the canvas's top-left corner (they do not stack), so the transform
 * is the element's whole position.
 *
 * For non-affine warps (ripples, curls, cloth), pass the closest affine approximation and calm the
 * warp while an input inside the element has focus.
 */
export function syncElementGeometry(canvas: HTMLCanvasElement, element: HTMLElement, canvasTransform: DOMMatrix) {
  const c = canvas as any;
  const support = getHtmlCanvasSupport();
  const cssWidth = canvas.clientWidth || canvas.width;
  const cssHeight = canvas.clientHeight || canvas.height;
  // The API works in device pixels on both sides (the element's rendered image and the canvas's backing
  // store), so the CSS-px matrix is conjugated by the pixel ratio: S · M · S⁻¹.
  const toBackingStore = new DOMMatrix().scale(canvas.width / cssWidth, canvas.height / cssHeight, 1);
  const pixels = toBackingStore.multiply(canvasTransform).multiply(toBackingStore.inverse());
  try {
    if (support.version === "155+" && typeof c.updateElementGeometry === "function") {
      c.updateElementGeometry(element, { canvasTransform: pixels });
      return;
    }
    if (typeof c.getElementTransform === "function") {
      element.style.transform = c.getElementTransform(element, pixels).toString();
      return;
    }
  } catch {
    // Fall through to the manual mapping below.
  }
  // Manual: children sit at the canvas origin, so the CSS-px transform applies as is.
  element.style.transformOrigin = "0 0";
  element.style.transform = canvasTransform.toString();
}

/** Clears geometry set by `syncElementGeometry` or a legacy `drawElement2D`. */
export function clearElementGeometry(element: HTMLElement) {
  element.style.transform = "";
  element.style.transformOrigin = "";
}

/** A CSS-px perspective matrix, like `perspective(d)` in CSS. */
export function perspective(distance: number) {
  return new DOMMatrix([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, -1 / distance, 0, 0, 0, 1]);
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/texture-webgl.ts

import { getHtmlCanvasSupport } from "@/lib/html-canvas/support";

/* eslint-disable @typescript-eslint/no-explicit-any -- the API is not in lib.dom yet */

/** A WebGL texture that holds a live element's pixels. */
export interface ElementTexture {
  texture: WebGLTexture;
  /** Natural size of the last upload, in CSS px. */
  width: number;
  height: number;
  /** Allocated size on 155+, where the storage is reused until the element resizes. */
  allocated: { width: number; height: number } | null;
}

/** Creates an empty, linearly filtered, edge-clamped texture for `uploadElementTexture`. */
export function createElementTexture(gl: WebGL2RenderingContext): ElementTexture {
  const texture = gl.createTexture();
  if (!texture) throw new Error("Could not create a texture");
  gl.bindTexture(gl.TEXTURE_2D, texture);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
  return { texture, width: 0, height: 0, allocated: null };
}

/**
 * Uploads an element's current rendering into `target`. Call it from the canvas `paint` event or on
 * resize, never every frame. Returns false when the element could not be uploaded.
 *
 * - 155+: measures with `captureElementImage`, allocates once with `texImage2D(…, null)` (again only
 *   when the size changes), then copies with `texElementSubImage2D`.
 * - 150–154: `texElementImage2D(target, internalformat, element)`.
 * - legacy: `texElementImage2D(target, level, internalformat, format, type, element)`.
 */
export function uploadElementTexture(gl: WebGL2RenderingContext, target: ElementTexture, element: Element) {
  const g = gl as any;
  const support = getHtmlCanvasSupport();
  const box = element.getBoundingClientRect();
  const html = element as HTMLElement;
  // Layout size, unaffected by the CSS transform used for hit-testing.
  const width = html.offsetWidth || box.width;
  const height = html.offsetHeight || box.height;
  if (!width || !height) return false;
  gl.bindTexture(gl.TEXTURE_2D, target.texture);
  try {
    if (support.version === "155+" && typeof g.texElementSubImage2D === "function") {
      const canvas = gl.canvas as any;
      let natural = { width, height };
      if (typeof canvas.captureElementImage === "function") {
        const image = canvas.captureElementImage(element);
        natural = { width: image.width, height: image.height };
        image.close?.();
      }
      if (!target.allocated || target.allocated.width !== natural.width || target.allocated.height !== natural.height) {
        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, natural.width, natural.height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
        target.allocated = natural;
      }
      g.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element);
    } else if (support.version === "legacy") {
      g.texElementImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, element);
    } else if (typeof g.texElementImage2D === "function") {
      g.texElementImage2D(gl.TEXTURE_2D, gl.RGBA8, element);
    } else {
      return false;
    }
  } catch {
    return false;
  }
  target.width = width;
  target.height = height;
  return true;
}
/* eslint-enable @typescript-eslint/no-explicit-any */

lib/html-canvas/use-html-canvas.ts

"use client";

import { useCallback, useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
import { useReducedMotion } from "motion/react";
import { drawableCanvasAttributes, prepareDrawableCanvas, requestCanvasPaint } from "@/lib/html-canvas/setup";
import { getHtmlCanvasSupport, NO_SUPPORT, supportsContext, type HtmlCanvasSupport } from "@/lib/html-canvas/support";

export type HtmlCanvasMode = "auto" | "native" | "fallback";
type ContextType = "2d" | "webgl2";
type ContextFor<C extends ContextType> = C extends "2d" ? CanvasRenderingContext2D : WebGL2RenderingContext;

export interface HtmlCanvasFrame<C extends ContextType> {
  ctx: ContextFor<C>;
  canvas: HTMLCanvasElement;
  /** Canvas size in CSS px. */
  width: number;
  height: number;
  /** Device pixels per CSS px used for the backing store (capped). */
  dpr: number;
  /** Seconds since the hook started. */
  time: number;
  /** Seconds since the previous render. */
  delta: number;
  /** Why this render happened: drawn elements repainted, the canvas resized, or an animation frame. */
  reason: "paint" | "resize" | "frame" | "request";
  /** Elements that repainted (from the paint event), when known. */
  changed: readonly Element[];
}

export interface UseHtmlCanvasOptions<C extends ContextType> {
  /** Context to draw with. */
  context: C;
  /** "auto" uses the API when available, "fallback" never does, "native" requires it. @default "auto" */
  mode?: HtmlCanvasMode;
  /** Run a render every frame while true (e.g. while a ripple is fading). Paused offscreen and in hidden tabs. */
  animating?: boolean;
  /** Called once per context (again after a lost context is restored). Return a cleanup. */
  setup?: (ctx: ContextFor<C>, canvas: HTMLCanvasElement) => void | (() => void);
  /** Draws a frame. Upload element textures only when `reason` is "paint" or "resize". */
  render: (frame: HtmlCanvasFrame<C>) => void;
  /** Highest device pixel ratio for the backing store. @default 2 */
  maxDpr?: number;
  /** Context attributes for WebGL. */
  contextAttributes?: WebGLContextAttributes;
}

export interface HtmlCanvasController {
  /** True when the canvas path is active; render the fallback DOM otherwise. */
  native: boolean;
  /** What the browser supports (none on the server and during hydration). */
  support: HtmlCanvasSupport;
  /** Ref for the <canvas>. */
  canvasRef: (canvas: HTMLCanvasElement | null) => void;
  /** Spread onto the <canvas> so it lays out and paints its children from the first layout. */
  canvasProps: Record<string, string>;
  /** Asks for one more render (and a browser paint event where supported). */
  invalidate: () => void;
}

const noop = () => () => {};

/**
 * Ties the HTML-in-Canvas adapter together: decides native vs. fallback (never during SSR or
 * hydration, never under reduced motion), prepares the canvas, renders on the canvas `paint` event
 * and on resize, runs a frame loop only while `animating`, pauses offscreen and in hidden tabs,
 * recovers from a lost WebGL context and cleans up on unmount.
 */
export function useHtmlCanvas<C extends ContextType>({
  context,
  mode = "auto",
  animating = false,
  setup,
  render,
  maxDpr = 2,
  contextAttributes,
}: UseHtmlCanvasOptions<C>): HtmlCanvasController {
  const hydrated = useSyncExternalStore(
    noop,
    () => true,
    () => false,
  );
  const reduceMotion = useReducedMotion();
  const support = hydrated ? getHtmlCanvasSupport() : NO_SUPPORT;
  const [failed, setFailed] = useState(false);
  const native = hydrated && !failed && mode !== "fallback" && !reduceMotion && supportsContext(support, context);

  // The element lives in a ref (it is mutated: size, attributes); the counter re-runs the effect when it changes.
  const canvasEl = useRef<HTMLCanvasElement | null>(null);
  const [canvasVersion, setCanvasVersion] = useState(0);
  const canvasRef = useCallback((el: HTMLCanvasElement | null) => {
    if (canvasEl.current === el) return;
    canvasEl.current = el;
    setCanvasVersion((v) => v + 1);
  }, []);
  const renderRef = useRef(render);
  const setupRef = useRef(setup);
  const animatingRef = useRef(animating);
  useLayoutEffect(() => {
    renderRef.current = render;
    setupRef.current = setup;
    animatingRef.current = animating;
  });
  const kick = useRef<(reason: HtmlCanvasFrame<C>["reason"]) => void>(() => {});

  useEffect(() => {
    const canvas = canvasEl.current;
    if (!native || !canvas) return;
    prepareDrawableCanvas(canvas);
    const ctx = canvas.getContext(context, context === "webgl2" ? { alpha: true, premultipliedAlpha: true, antialias: true, ...contextAttributes } : undefined) as ContextFor<C> | null;
    if (!ctx) {
      // Defer so the state change happens outside the effect body.
      const t = window.setTimeout(() => setFailed(true), 0);
      return () => window.clearTimeout(t);
    }
    let cleanupSetup: void | (() => void);
    let ready = false;
    const runSetup = () => {
      try {
        cleanupSetup = setupRef.current?.(ctx, canvas);
        ready = true;
      } catch (error) {
        console.error(error);
        ready = false;
        window.setTimeout(() => setFailed(true), 0);
      }
    };
    runSetup();

    const start = performance.now();
    // Frame time is measured between loop frames only, so the first frame after idling has a normal step.
    let lastFrame = 0;
    let size = { width: 0, height: 0, dpr: 1 };
    let visible = true;
    let frame = 0;
    let changed: readonly Element[] = [];

    const draw = (reason: HtmlCanvasFrame<C>["reason"]) => {
      if (!ready || !size.width || !size.height) return;
      const now = performance.now();
      const delta = reason === "frame" && lastFrame ? Math.min(1 / 20, (now - lastFrame) / 1000) : reason === "frame" ? 1 / 60 : 0;
      if (reason === "frame") lastFrame = now;
      try {
        renderRef.current({ ctx, canvas, width: size.width, height: size.height, dpr: size.dpr, time: (now - start) / 1000, delta, reason, changed });
      } catch (error) {
        console.error(error);
      }
      changed = [];
    };

    const loop = () => {
      frame = 0;
      if (!visible || document.hidden || !animatingRef.current) {
        lastFrame = 0;
        return;
      }
      draw("frame");
      frame = requestAnimationFrame(loop);
    };
    const ensureLoop = () => {
      if (!frame && visible && !document.hidden && animatingRef.current) frame = requestAnimationFrame(loop);
    };
    kick.current = (reason) => {
      draw(reason);
      ensureLoop();
    };

    const resize = () => {
      const rect = canvas.getBoundingClientRect();
      const dpr = Math.min(maxDpr, window.devicePixelRatio || 1);
      const width = Math.max(1, Math.round(rect.width));
      const height = Math.max(1, Math.round(rect.height));
      if (width === size.width && height === size.height && dpr === size.dpr) return;
      size = { width, height, dpr };
      canvas.width = Math.round(width * dpr);
      canvas.height = Math.round(height * dpr);
      draw("resize");
      requestCanvasPaint(canvas);
    };
    const resizeObserver = new ResizeObserver(resize);
    resizeObserver.observe(canvas);
    resize();

    const onPaint = (event: Event) => {
      changed = ((event as Event & { changedElements?: Element[] }).changedElements ?? []) as Element[];
      draw("paint");
      ensureLoop();
    };
    canvas.addEventListener("paint", onPaint);

    const io = new IntersectionObserver(([entry]) => {
      visible = entry?.isIntersecting ?? true;
      ensureLoop();
    });
    io.observe(canvas);
    const onVisibility = () => ensureLoop();
    document.addEventListener("visibilitychange", onVisibility);

    const onLost = (event: Event) => {
      event.preventDefault();
      ready = false;
      cancelAnimationFrame(frame);
      frame = 0;
    };
    const onRestored = () => {
      runSetup();
      draw("resize");
      requestCanvasPaint(canvas);
    };
    canvas.addEventListener("webglcontextlost", onLost);
    canvas.addEventListener("webglcontextrestored", onRestored);

    requestCanvasPaint(canvas);

    return () => {
      cancelAnimationFrame(frame);
      resizeObserver.disconnect();
      io.disconnect();
      canvas.removeEventListener("paint", onPaint);
      canvas.removeEventListener("webglcontextlost", onLost);
      canvas.removeEventListener("webglcontextrestored", onRestored);
      document.removeEventListener("visibilitychange", onVisibility);
      kick.current = () => {};
      if (typeof cleanupSetup === "function") cleanupSetup();
    };
    // contextAttributes and maxDpr are read once per canvas.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [native, canvasVersion, context]);

  // Start or stop the loop when `animating` flips.
  useEffect(() => {
    if (animating) kick.current("frame");
  }, [animating]);

  const invalidate = useCallback(() => {
    kick.current("request");
    if (canvasEl.current) requestCanvasPaint(canvasEl.current);
  }, []);

  return { native, support, canvasRef, canvasProps: drawableCanvasAttributes(support), invalidate };
}

Copy the source

components/ui/crt-terminal/crt-terminal.tsx

"use client";

import { useEffect, useId, useRef, useState, type FormEvent } from "react";
import { cn } from "@/lib/utils";
import { createGrid, createProgram, drawMesh, PROJECT_GLSL, type Mesh, type Program } from "@/lib/html-canvas/gl";
import { createElementTexture, uploadElementTexture, type ElementTexture } from "@/lib/html-canvas/texture-webgl";
import { syncElementGeometry } from "@/lib/html-canvas/sync-geometry";
import { useHtmlCanvas, type HtmlCanvasMode } from "@/lib/html-canvas/use-html-canvas";

export type TerminalCommand = (args: string[]) => string | string[];

export interface CrtTerminalProps {
  /** "crt" glows green on black; "paper" is a light e-ink terminal with grain. @default "crt" */
  variant?: "crt" | "paper";
  /** Prompt before the input. @default "guest@hantui:~$" */
  prompt?: string;
  /** Lines printed after boot. */
  welcome?: string[];
  /** Extra commands by name, added to help, clear, about, theme and echo. */
  commands?: Record<string, TerminalCommand>;
  /** Text for `about`. */
  about?: string;
  /** Height in px. @default 320 */
  height?: number;
  /** Called when `theme` switches the variant. */
  onVariantChange?: (variant: "crt" | "paper") => void;
  /** "auto" uses HTML-in-Canvas when available, "fallback" never does. @default "auto" */
  rendering?: HtmlCanvasMode;
  /** Called when the rendering mode is known. */
  onModeChange?: (native: boolean) => void;
  /** Classes for the root. */
  className?: string;
}

const BOOT = 1.4;

const VERT = /* glsl */ `#version 300 es
in vec2 a_pos;
uniform vec2 u_size;
out vec2 v_uv;
${PROJECT_GLSL}
void main() {
  v_uv = a_pos;
  gl_Position = projectCss(vec4(a_pos * u_size, 0.0, 1.0));
}`;

const FRAG = /* glsl */ `#version 300 es
precision highp float;
in vec2 v_uv;
uniform sampler2D u_tex;
uniform vec2 u_size;
uniform float u_time;
uniform float u_paper;
out vec4 outColor;

float hash(vec2 p) { return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453); }

void main() {
  // Barrel curvature: sample further out toward the corners.
  vec2 c = v_uv - 0.5;
  float k = mix(0.045, 0.012, u_paper);
  vec2 uv = 0.5 + c * (1.0 + k * dot(c, c) * 4.0);
  if (uv.x < 0.0 || uv.y < 0.0 || uv.x > 1.0 || uv.y > 1.0) { outColor = vec4(0.0); return; }

  // Boot: the picture opens from a bright line, flickering, then settles.
  float boot = clamp(u_time / ${BOOT.toFixed(1)}, 0.0, 1.0);
  float open = smoothstep(0.0, 0.45, boot);
  float band = abs(uv.y - 0.5) * 2.0;
  if (u_paper < 0.5 && band > open + 0.02) { outColor = vec4(0.0, 0.0, 0.0, 1.0); return; }

  vec2 px = 1.0 / u_size;
  float ab = mix(1.4, 0.0, u_paper) * (0.4 + length(c));
  vec4 base = texture(u_tex, uv);
  float r = texture(u_tex, uv + vec2(ab, 0.0) * px).r;
  float b = texture(u_tex, uv - vec2(ab, 0.0) * px).b;
  vec3 col = vec3(r, base.g, b);

  if (u_paper < 0.5) {
    // Phosphor glow: a cheap 8-tap halo added on top.
    vec3 glow = vec3(0.0);
    for (int i = 0; i < 8; i++) {
      float a = float(i) * 0.785398;
      glow += texture(u_tex, uv + vec2(cos(a), sin(a)) * px * 2.6).rgb;
    }
    col += glow / 8.0 * 0.45;
    // Scanlines and a soft vignette.
    float scan = 0.82 + 0.18 * sin(uv.y * u_size.y * 3.14159);
    col *= scan;
    col *= 1.0 - dot(c, c) * 0.9;
    float flicker = boot < 1.0 ? 0.75 + 0.35 * hash(vec2(floor(u_time * 24.0), 1.0)) : 1.0;
    col *= flicker;
    col += vec3(0.9, 1.0, 0.9) * (1.0 - open) * 0.6 * (1.0 - smoothstep(0.0, 0.03, abs(uv.y - 0.5)));
    outColor = vec4(col, 1.0);
  } else {
    // Paper: fine grain and a faint fade toward the edges.
    float grain = (hash(floor(uv * u_size)) - 0.5) * 0.06;
    col += grain;
    col *= 1.0 - dot(c, c) * 0.12;
    outColor = vec4(col * base.a, base.a);
  }
}`;

type Line = { id: number; kind: "out" | "in" | "err"; text: string };

/**
 * A real terminal through HTML-in-Canvas: the scrollback is selectable DOM text and the prompt is a
 * real input, drawn on a curved CRT with scanlines, phosphor glow, chromatic fringing and a flicker on
 * boot (or as a light e-ink terminal with grain). A small mock shell answers help, clear, about,
 * theme and echo. Without the API, it is a monospace terminal with a CSS scanline overlay.
 */
export function CrtTerminal({
  variant: variantProp = "crt",
  prompt = "guest@hantui:~$",
  welcome = ["hantui terminal", "Type 'help' to see what this shell can do."],
  commands = {},
  about = "A live DOM terminal rendered through the experimental HTML-in-Canvas API. Select any line to copy it.",
  height = 320,
  onVariantChange,
  rendering = "auto",
  onModeChange,
  className,
}: CrtTerminalProps) {
  const id = useId();
  const [variant, setVariant] = useState(variantProp);
  const [prevProp, setPrevProp] = useState(variantProp);
  if (prevProp !== variantProp) {
    setPrevProp(variantProp);
    setVariant(variantProp);
  }
  const [lines, setLines] = useState<Line[]>(() => welcome.map((text, i) => ({ id: i, kind: "out", text })));
  const [value, setValue] = useState("");
  const [history, setHistory] = useState<string[]>([]);
  const [cursor, setCursor] = useState(-1);
  const counter = useRef(welcome.length);
  const termRef = useRef<HTMLDivElement>(null);
  const scrollRef = useRef<HTMLDivElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);
  const [booting, setBooting] = useState(true);
  const clock = useRef(0);
  const gl = useRef<{ program: Program; mesh: Mesh; texture: ElementTexture } | null>(null);
  const paper = variant === "paper";

  const { native, canvasRef, canvasProps } = useHtmlCanvas({
    context: "webgl2",
    mode: rendering,
    animating: booting,
    setup: (ctx) => {
      clock.current = performance.now();
      gl.current = { program: createProgram(ctx, VERT, FRAG), mesh: createGrid(ctx), texture: createElementTexture(ctx) };
      return () => {
        if (!gl.current) return;
        ctx.deleteProgram(gl.current.program.program);
        ctx.deleteTexture(gl.current.texture.texture);
        gl.current = null;
      };
    },
    render: ({ ctx, canvas, width, height: h, reason }) => {
      const g = gl.current;
      const term = termRef.current;
      if (!g || !term) return;
      if (reason !== "frame" || !g.texture.width) {
        uploadElementTexture(ctx, g.texture, term);
        syncElementGeometry(canvas, term, new DOMMatrix());
      }
      const t = (performance.now() - clock.current) / 1000;
      if (t > BOOT + 0.1 && booting) window.setTimeout(() => setBooting(false), 0);
      ctx.viewport(0, 0, canvas.width, canvas.height);
      ctx.clearColor(0, 0, 0, 0);
      ctx.clear(ctx.COLOR_BUFFER_BIT);
      ctx.useProgram(g.program.program);
      const { u } = g.program;
      ctx.uniform2f(u("u_canvas"), width, h);
      ctx.uniform2f(u("u_size"), width, h);
      ctx.uniform1f(u("u_time"), t);
      ctx.uniform1f(u("u_paper"), paper ? 1 : 0);
      ctx.activeTexture(ctx.TEXTURE0);
      ctx.bindTexture(ctx.TEXTURE_2D, g.texture.texture);
      ctx.uniform1i(u("u_tex"), 0);
      drawMesh(ctx, g.mesh);
    },
  });

  useEffect(() => onModeChange?.(native), [native, onModeChange]);

  // Keep the newest line in view.
  useEffect(() => {
    const el = scrollRef.current;
    if (el) el.scrollTop = el.scrollHeight;
  }, [lines]);

  const print = (kind: Line["kind"], text: string | string[]) =>
    setLines((l) => [...l, ...(Array.isArray(text) ? text : [text]).map((t) => ({ id: counter.current++, kind, text: t }))]);

  const run = (raw: string) => {
    const input = raw.trim();
    print("in", `${prompt} ${raw}`);
    if (!input) return;
    setHistory((h) => [input, ...h].slice(0, 50));
    const [name, ...args] = input.split(/\s+/);
    const builtins: Record<string, TerminalCommand> = {
      help: () => ["Commands:", ...["help", "clear", "about", "theme", "echo", ...Object.keys(commands)].map((c) => `  ${c}`)],
      about: () => about,
      echo: (a) => a.join(" "),
      theme: () => {
        const next = paper ? "crt" : "paper";
        setVariant(next);
        onVariantChange?.(next);
        return `Switched to the ${next === "crt" ? "CRT" : "paper"} theme.`;
      },
    };
    if (name === "clear") {
      setLines([]);
      return;
    }
    const command = commands[name] ?? builtins[name];
    if (!command) {
      print("err", `command not found: ${name}`);
      return;
    }
    print("out", command(args));
  };

  const submit = (event: FormEvent) => {
    event.preventDefault();
    run(value);
    setValue("");
    setCursor(-1);
  };

  const onKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
    if (event.key === "ArrowUp" || event.key === "ArrowDown") {
      event.preventDefault();
      const next = Math.max(-1, Math.min(history.length - 1, cursor + (event.key === "ArrowUp" ? 1 : -1)));
      setCursor(next);
      setValue(next === -1 ? "" : history[next]);
    } else if (event.key === "l" && event.ctrlKey) {
      event.preventDefault();
      setLines([]);
    }
  };

  const colors = paper
    ? "bg-[#f3f1ea] text-[#26241f] [--term-dim:#6f6a5e] [--term-err:#a3341f] [--term-accent:#26241f] selection:bg-[#26241f] selection:text-[#f3f1ea]"
    : "bg-[#071008] text-[#7dff9a] [--term-dim:#3fae5c] [--term-err:#ff7a6b] [--term-accent:#b8ffc8] selection:bg-[#7dff9a] selection:text-[#071008]";

  const terminal = (
    <div
      ref={termRef}
      role="region"
      aria-label="Terminal"
      onClick={() => {
        if (!window.getSelection()?.toString()) inputRef.current?.focus();
      }}
      className={cn("relative flex w-full flex-col overflow-hidden rounded-2xl p-4 font-mono text-[13px] leading-[1.55]", colors, !native && !paper && "[text-shadow:0_0_6px_rgb(125_255_154/0.45)]")}
      style={{ height }}
    >
      <div ref={scrollRef} role="log" aria-live="polite" aria-label="Output" className="min-h-0 flex-1 overflow-y-auto [scrollbar-width:none]">
        {lines.map((line) => (
          <p key={line.id} className={cn("break-words whitespace-pre-wrap", line.kind === "in" && "text-[var(--term-accent)]", line.kind === "err" && "text-[var(--term-err)]")}>
            {line.text}
          </p>
        ))}
      </div>
      <form onSubmit={submit} className="mt-1 flex items-center gap-2">
        <label htmlFor={`${id}-input`} className="shrink-0 text-[var(--term-dim)]">
          {prompt}
        </label>
        <input
          ref={inputRef}
          id={`${id}-input`}
          value={value}
          onChange={(e) => setValue(e.target.value)}
          onKeyDown={onKeyDown}
          autoComplete="off"
          autoCapitalize="off"
          spellCheck={false}
          aria-label="Command"
          className="min-w-0 flex-1 bg-transparent caret-current outline-none"
        />
      </form>
      {!native ? (
        <span
          aria-hidden="true"
          className="pointer-events-none absolute inset-0 rounded-2xl"
          style={{
            background: paper
              ? "radial-gradient(ellipse at center, transparent 60%, rgb(0 0 0 / 0.06))"
              : "repeating-linear-gradient(to bottom, rgb(0 0 0 / 0.22) 0 1px, transparent 1px 3px), radial-gradient(ellipse at center, transparent 55%, rgb(0 0 0 / 0.45))",
          }}
        />
      ) : null}
    </div>
  );

  if (!native) return <div className={cn("w-full max-w-xl", className)}>{terminal}</div>;

  return (
    <div className={cn("relative w-full max-w-xl", className)} style={{ height }}>
      <canvas ref={canvasRef} {...canvasProps} className="absolute inset-0 block size-full rounded-2xl">
        {terminal}
      </canvas>
    </div>
  );
}

Usage

import { CrtTerminal } from "@/components/ui/crt-terminal/crt-terminal";

<CrtTerminal
  prompt="guest@acme:~$"
  commands={{ whoami: () => "guest", deploy: (args) => `Deploying ${args[0] ?? "main"}…` }}
/>

API reference

Prop	Type	Default	Description
`variant`	`"crt" \| "paper"`	`"crt"`	"crt" glows green on black; "paper" is a light e-ink terminal with grain.
`prompt`	`string`	`"guest@hantui:~$"`	Prompt before the input.
`welcome`	`string[]`	–	Lines printed after boot.
`commands`	`Record<string, TerminalCommand>`	–	Extra commands by name, added to help, clear, about, theme and echo.
`about`	`string`	–	Text for `about`.
`height`	`number`	`320`	Height in px.
`onVariantChange`	`(variant: "crt" \| "paper") => void`	–	Called when `theme` switches the variant.
`rendering`	`HtmlCanvasMode`	`"auto"`	"auto" uses HTML-in-Canvas when available, "fallback" never does.
`onModeChange`	`(native: boolean) => void`	–	Called when the rendering mode is known.
`className`	`string`	–	Classes for the root.

Experimental: uses the HTML-in-Canvas origin trial through src/lib/html-canvas/. Works in every browser via the fallback.
The curvature is mild and the drawn terminal is synced to its unwarped geometry, so clicks and selection stay within a few pixels at the corners. The texture is re-uploaded only when the browser repaints the terminal; the frame loop runs only during the boot flicker.
Built-in commands are help, clear, about, theme (switches between CRT and paper) and echo. Your `commands` are added to them and listed by help.

Accessibility

The scrollback is a role="log" region of real text, so screen readers hear new output and every line can be selected and copied. The prompt is a labelled input; clicking anywhere in the terminal focuses it unless you are selecting text.
↑ and ↓ walk the command history; Ctrl+L clears the screen.
With reduced motion, or without the HTML-in-Canvas API, it renders as a plain monospace terminal with a CSS scanline overlay and no boot flicker.

Installation#

CLI

Manual

Install the dependencies

Add the shared helpers

Copy the source

Usage#

API reference#

Accessibility#

Installation

Usage

API reference

Accessibility