Primitives are boring on purpose.

// call at scene-build time; returns a shared handle keyed on src
function prepareImage(src: string, onReady?: () => void): PreparedImage

type PreparedImage = {
  src: string
  naturalWidth: number   // 0 until ready
  naturalHeight: number
  aspect: number         // 1 until ready (safe default)
  ready: boolean
  error: boolean
}

function layoutImage(p: PreparedImage, targetWidth: number)
  : { width: number; height: number }   // pure

Shared cache means ten cells pointing at the same url share one load. Render loop discovers readiness by calling layoutImage every frame.

function gridLayout(items: GridItem[], opts: GridOptions): GridLaidOut

type GridOptions = {
  viewportWidth: number
  padding: number
  gap: number
  minCellWidth: number
  maxColumns: number
}
type GridLaidOut = {
  columns: number
  cellWidth: number
  cells: GridCell[]                       // { id, x, y, width, height }
  totalHeight: number
}

function hitTestGrid(laid: GridLaidOut, x: number, y: number)
  : string | null

Re-laid every frame in the gallery. The hit-test mirrors the layout so dragging over a cell is a reverse lookup, not a DOM query.

function prepareWithSegments(
  text: string,
  font: string,
  options?: PrepareOptions,
): PreparedTextWithSegments

function layoutWithLines(
  p: PreparedTextWithSegments,
  maxWidth: number,
  lineHeight: number,
): LayoutLinesResult   // pure

function measureLineStats(
  p: PreparedTextWithSegments,
  maxWidth: number,
): { lineCount: number; maxLineWidth: number }

function measureNaturalWidth(
  p: PreparedTextWithSegments,
): number   // widest unforced line

The one vendor primitive so far — bun add @chenglou/pretext. We don't reimplement bidi + grapheme handling when the canonical package ships it. Admission rule still holds: the second demo needed it.

function pointerOn(el: HTMLElement): PointerHandle

type PointerHandle = {
  onPress(fn): void
  onMove(fn):  void
  onRelease(fn): void
  dispose(): void
}
// handler receives: { pointerId, x, y, clientX, clientY, target }

Handlers are intentionally void-returning. They stash into your state and call schedule() — keeping every decision inside the render loop, same as every other primitive.

type DragState =
  | { kind: 'idle' }
  | { kind: 'pressing',  pointerId, id, originX, originY, grabDX, grabDY }
  | { kind: 'dragging',  pointerId, id, originX, originY,
      cursorX, cursorY, grabDX, grabDY }

type DragEvent =
  | { type: 'press',   pointerId, id, x, y, grabDX, grabDY }
  | { type: 'move',    pointerId, x, y }
  | { type: 'release', pointerId }

function dragReduce(s, ev, opts): DragState

No hidden fields, no __grab stashes, no escape hatches. Any render phase can read state without worrying whose side effect ordered what. The press threshold lives in opts; invariants are obvious by inspection.

type LayoutTween = {
  fromX: Map<string, number>
  fromY: Map<string, number>
  t0: number
  durationMs: number
}

function startLayoutTween(grid: GridLaidOut, now: number, durationMs: number): LayoutTween
function tweenProgress(tw: LayoutTween, now: number): number   // 0..1
function tweenCell(tw: LayoutTween, cell: GridCell, progressEased: number): { x: number; y: number }
function easeOutCubic(t: number): number

The render loop owns Tween | null as state. Reorder an item and call startLayoutTween with the grid you just laid out; next frame, tweenCell returns blended positions. Easing is a pure function you compose yourself — no spring configs, no callbacks.

function ensure<T>(
  cache: Map<string, T>,
  id: string,
  create: () => T
): T

function evictStale<T>(
  cache: Map<string, T>,
  keepIds: Iterable<string>,
  dispose: (v, id) => void
): void

Every render loop that writes to the DOM ends with the same pair: "make nodes for every id in the scene; remove nodes for every id that's no longer there." It's short, but cross-cutting enough that writing it wrong is a source of leaks. Two helpers, no surprises.