@nastechai-research/ui 0.13.2

package/src/fonts.ts

@@ -0,0 +1,6 @@
+/** CSS variable names for the design language fonts. Set automatically by fonts.css. */
+export const FONT_SANS = '--font-sans'
+export const FONT_MONO = '--font-mono'
+export const FONT_RULES_COMPRESSED = '--font-rules-compressed'
+export const FONT_RULES_EXPANDED = '--font-rules-expanded'
+export const FONT_MONDWEST = '--font-mondwest'

package/src/hooks/use-below-breakpoint.ts

@@ -0,0 +1,21 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+/** True when viewport width is strictly below `px`. */
+export function useBelowBreakpoint(px: number) {
+  const query = `(max-width: ${px - 1}px)`
+  const [matches, setMatches] = useState(() =>
+    typeof window !== 'undefined' ? window.matchMedia(query).matches : false
+  )
+
+  useEffect(() => {
+    const mql = window.matchMedia(query)
+    const sync = () => setMatches(mql.matches)
+    sync()
+    mql.addEventListener('change', sync)
+    return () => mql.removeEventListener('change', sync)
+  }, [query])
+
+  return matches
+}

package/src/hooks/use-capped-frame.ts

@@ -0,0 +1,18 @@
+'use client'
+
+import { useFrame, useThree } from '@react-three/fiber'
+import type { RenderCallback } from '@react-three/fiber'
+import { useRef } from 'react'
+
+export function useCappedFrame(cb: RenderCallback, max?: number) {
+  const last = useRef(performance.now())
+  const { size } = useThree()
+  const interval = 1e3 / (max ?? (size.width < 1024 ? 60 : 120))
+
+  useFrame((st, delta) => {
+    if (performance.now() - last.current > interval) {
+      last.current = performance.now()
+      cb(st, delta)
+    }
+  })
+}

package/src/hooks/use-confirm-delete.ts

@@ -0,0 +1,43 @@
+'use client'
+
+import { useCallback, useState } from 'react'
+
+export function useConfirmDelete<TId>({
+  onDelete
+}: {
+  onDelete: (id: TId) => Promise<void>
+}) {
+  const [pendingId, setPendingId] = useState<TId | null>(null)
+  const [isDeleting, setIsDeleting] = useState(false)
+
+  const requestDelete = useCallback((id: TId) => {
+    setPendingId(id)
+  }, [])
+
+  const cancel = useCallback(() => {
+    if (!isDeleting) setPendingId(null)
+  }, [isDeleting])
+
+  const confirm = useCallback(async () => {
+    if (pendingId === null) return
+    const id = pendingId
+    setIsDeleting(true)
+    try {
+      await onDelete(id)
+      setPendingId(null)
+    } catch {
+      // Dialog stays open; caller can surface errors in onDelete
+    } finally {
+      setIsDeleting(false)
+    }
+  }, [pendingId, onDelete])
+
+  return {
+    cancel,
+    confirm,
+    isDeleting,
+    isOpen: pendingId !== null,
+    pendingId,
+    requestDelete
+  } as const
+}

package/src/hooks/use-css-var-dims.ts

@@ -0,0 +1,39 @@
+'use client'
+
+import { useEffect } from 'react'
+
+export function useCssVarDims(
+  name: string,
+  ref: React.RefObject<HTMLElement | null>
+) {
+  useEffect(() => {
+    if (!ref.current) {
+      return
+    }
+
+    const update = (width: number, height: number) => {
+      document.documentElement.style.setProperty(
+        `--${name}-width`,
+        `${width}px`
+      )
+
+      document.documentElement.style.setProperty(
+        `--${name}-height`,
+        `${height}px`
+      )
+    }
+
+    const { height, width } = ref.current.getBoundingClientRect()
+    update(width, height)
+
+    const ro = new ResizeObserver(entries => {
+      for (const entry of entries) {
+        update(entry.contentRect.width, entry.contentRect.height)
+      }
+    })
+
+    ro.observe(ref.current)
+
+    return () => ro.disconnect()
+  }, [name, ref])
+}

package/src/hooks/use-gpu-tier.ts

@@ -0,0 +1,190 @@
+'use client'
+
+import { useStore } from '@nanostores/react'
+import { atom } from 'nanostores'
+
+/**
+ * Tiers:
+ *  0 — no WebGL / software renderer / prefers-reduced-motion / WebGL ctx
+ *      creation failed / detection not yet run
+ *  1 — low-end GPU (integrated, mobile, or failed perf benchmark)
+ *  2 — capable GPU (discrete / high-end integrated)
+ *
+ * The atom starts **pessimistic** (`0`) and the probe is scheduled to run
+ * *after the first paint* (see `scheduleDetection` below), never synchronously
+ * at module-evaluation time.
+ *
+ * Why pessimistic + deferred:
+ *  - Every consumer gates its `<canvas>` / `THREE.WebGLRenderer` on `tier > 0`
+ *    (or `=== 2`). Starting at `0` means a consumer reading `$gpuTier` during
+ *    its first render never attempts to create a renderer before detection has
+ *    run, so the `THREE.WebGLRenderer: Error creating WebGL context` crash on
+ *    hardware where context creation fails cannot happen — the component
+ *    renders its fallback and upgrades once detection resolves to a capable
+ *    tier. (A previous version made the probe synchronous-at-module-load to
+ *    dodge this crash; the pessimistic default removes the crash without that
+ *    cost.)
+ *  - Probing WebGL is *expensive* on software renderers: creating a context
+ *    under SwiftShader / llvmpipe can block the main thread for hundreds of
+ *    milliseconds. Running it synchronously at module load stalled first paint
+ *    and produced a visible boot-time flash in apps that merely import this
+ *    hook (e.g. the Hermes dashboard backdrop). Deferring past first paint
+ *    keeps boot smooth; the tier just upgrades a frame or two later.
+ *  - For SSR the server keeps the default `0` and the client's first render
+ *    also reads `0`, so there is no hydration mismatch.
+ */
+export const $gpuTier = atom<GpuTier>(0)
+
+const SOFTWARE_PATTERNS =
+  /swiftshader|llvmpipe|softpipe|software|microsoft basic/i
+
+const LOW_END_PATTERNS =
+  /intel.*hd|intel.*uhd|intel.*iris|mali|adreno\s?[1-5]|powervr|apple gpu/i
+
+let detected = false
+
+function detectGpuTier() {
+  if (detected || typeof window === 'undefined') {
+    return
+  }
+
+  detected = true
+
+  // The atom already holds 0; the early returns below simply leave it there.
+  if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+    return
+  }
+
+  let gl: null | WebGLRenderingContext = null
+
+  try {
+    const canvas = document.createElement('canvas')
+    gl = (canvas.getContext('webgl') ||
+      canvas.getContext('experimental-webgl')) as null | WebGLRenderingContext
+  } catch {
+    // Some sandboxed / hardened contexts throw on getContext rather than
+    // returning null (e.g. certain corporate browser policies). Treat as
+    // "no WebGL available".
+    return
+  }
+
+  if (!gl) {
+    return
+  }
+
+  const ext = gl.getExtension('WEBGL_debug_renderer_info')
+  const renderer = String(
+    ext
+      ? gl.getParameter(ext.UNMASKED_RENDERER_WEBGL)
+      : gl.getParameter(gl.RENDERER)
+  )
+
+  if (SOFTWARE_PATTERNS.test(renderer)) {
+    gl.getExtension('WEBGL_lose_context')?.loseContext()
+
+    return
+  }
+
+  if (LOW_END_PATTERNS.test(renderer)) {
+    $gpuTier.set(1)
+    gl.getExtension('WEBGL_lose_context')?.loseContext()
+
+    return
+  }
+
+  $gpuTier.set(2)
+
+  runBenchmark(gl)
+    .then(fps => $gpuTier.set(fps < 30 ? 1 : 2))
+    .catch(() => $gpuTier.set(1))
+    .finally(() => gl?.getExtension('WEBGL_lose_context')?.loseContext())
+}
+
+/**
+ * Run detection once, *after* the first paint so the (potentially expensive)
+ * WebGL probe never blocks initial render. Prefer `requestIdleCallback` so the
+ * probe yields to rendering and input; fall back to a double
+ * `requestAnimationFrame` (guarantees at least one painted frame) and finally
+ * `setTimeout` where neither exists.
+ */
+function scheduleDetection() {
+  if (typeof window === 'undefined') {
+    return
+  }
+
+  if (typeof window.requestIdleCallback === 'function') {
+    window.requestIdleCallback(() => detectGpuTier(), { timeout: 1000 })
+  } else if (typeof window.requestAnimationFrame === 'function') {
+    window.requestAnimationFrame(() =>
+      window.requestAnimationFrame(() => detectGpuTier())
+    )
+  } else {
+    setTimeout(() => detectGpuTier(), 0)
+  }
+}
+
+scheduleDetection()
+
+function runBenchmark(gl: WebGLRenderingContext): Promise<number> {
+  return new Promise(resolve => {
+    const vs = gl.createShader(gl.VERTEX_SHADER)!
+    const fs = gl.createShader(gl.FRAGMENT_SHADER)!
+    gl.shaderSource(
+      vs,
+      'attribute vec2 a;void main(){gl_Position=vec4(a,0,1);}'
+    )
+    gl.shaderSource(
+      fs,
+      'precision highp float;uniform float t;void main(){float v=0.;for(int i=0;i<64;i++)v+=sin(float(i)*t*.01);gl_FragColor=vec4(v*.001);}'
+    )
+    gl.compileShader(vs)
+    gl.compileShader(fs)
+
+    const prog = gl.createProgram()!
+    gl.attachShader(prog, vs)
+    gl.attachShader(prog, fs)
+    gl.linkProgram(prog)
+    gl.useProgram(prog)
+
+    const buf = gl.createBuffer()
+    gl.bindBuffer(gl.ARRAY_BUFFER, buf)
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      new Float32Array([-1, -1, 1, -1, -1, 1, 1, 1]),
+      gl.STATIC_DRAW
+    )
+    const a = gl.getAttribLocation(prog, 'a')
+    gl.enableVertexAttribArray(a)
+    gl.vertexAttribPointer(a, 2, gl.FLOAT, false, 0, 0)
+
+    const uT = gl.getUniformLocation(prog, 't')
+    let frames = 0
+    const start = performance.now()
+
+    const tick = () => {
+      gl.uniform1f(uT, frames)
+      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4)
+      gl.finish()
+      frames++
+
+      if (performance.now() - start < 200) {
+        requestAnimationFrame(tick)
+      } else {
+        const elapsed = performance.now() - start
+        gl.deleteProgram(prog)
+        gl.deleteShader(vs)
+        gl.deleteShader(fs)
+        gl.deleteBuffer(buf)
+        resolve((frames / elapsed) * 1000)
+      }
+    }
+
+    requestAnimationFrame(tick)
+  })
+}
+
+export function useGpuTier() {
+  return useStore($gpuTier)
+}
+
+type GpuTier = 0 | 1 | 2

package/src/hooks/use-render-loop.ts

@@ -0,0 +1,121 @@
+'use client'
+
+/**
+ * Visibility- and intersection-aware render-loop helper for the WebGL
+ * overlays.
+ *
+ * The overlays were previously running fragment shaders at 60fps for the
+ * entire lifetime of the page — including when the tab was hidden, the
+ * canvas had been scrolled out of view, or the user had been idle for
+ * hours. On retina laptops the compositor cost of mix-blend-mode on a
+ * full-viewport canvas plus continuous WebGL rasterisation is enough to
+ * keep the GPU hot indefinitely, which is what manifests as "fans go
+ * crazy after 2 hours of idle".
+ *
+ * `runRenderLoop` wraps a frame callback so that it:
+ *
+ *   1. Pauses entirely when `document.hidden` is true (background tab,
+ *      minimised window, screen locked).
+ *   2. Pauses when the canvas's bounding rect is offscreen (we tell
+ *      `IntersectionObserver` to look at the canvas itself).
+ *   3. Optionally caps the frame rate via a min-interval — the previous
+ *      `gpuTier === 1 ? setTimeout(loop, 100) : raf` trick is preserved
+ *      and extended so even tier-2 GPUs cap at e.g. 30fps for overlays
+ *      that don't need 60.
+ *
+ * The callback receives the *delta* time in seconds since the last call
+ * (so `uTime` advances correctly across pauses without ever skipping
+ * forward by hours).
+ */
+
+interface RunRenderLoopOptions {
+  /** Element to observe with IntersectionObserver. When fully out of
+   *  view, the loop pauses. Pass the canvas element itself. */
+  el: Element
+  /** Min ms between frames. 0 = no cap (uses requestAnimationFrame).
+   *  Anything > 0 uses setTimeout-driven scheduling. */
+  minIntervalMs?: number
+  /** Frame callback. Receives the elapsed seconds since the previous
+   *  *executed* frame (not since the previous scheduled frame), so
+   *  uniforms keyed off this value will not jump after a long pause. */
+  onFrame: (deltaSeconds: number) => void
+}
+
+export function runRenderLoop({
+  el,
+  minIntervalMs = 0,
+  onFrame
+}: RunRenderLoopOptions) {
+  let running = true
+  let visible = !document.hidden
+  let inView = true
+  let last = performance.now()
+  let raf = 0
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const onVisibility = () => {
+    visible = !document.hidden
+
+    // When we come back from a hidden tab, reset the clock so the next
+    // frame's delta is ~one frame, not "hours since I was hidden".
+    if (visible) {
+      last = performance.now()
+      schedule()
+    }
+  }
+
+  const io = new IntersectionObserver(
+    entries => {
+      const wasInView = inView
+      inView = entries.some(e => e.isIntersecting)
+
+      if (!wasInView && inView) {
+        last = performance.now()
+        schedule()
+      }
+    },
+    { threshold: 0 }
+  )
+
+  io.observe(el)
+  document.addEventListener('visibilitychange', onVisibility)
+
+  const tick = () => {
+    if (!running) return
+
+    if (!visible || !inView) {
+      // Don't reschedule — we'll be re-kicked by visibilitychange or IO.
+      return
+    }
+
+    const now = performance.now()
+    const delta = (now - last) / 1000
+    last = now
+
+    onFrame(delta)
+    schedule()
+  }
+
+  function schedule() {
+    if (!running || !visible || !inView) return
+
+    if (minIntervalMs > 0) {
+      timer = setTimeout(tick, minIntervalMs)
+    } else {
+      raf = requestAnimationFrame(tick)
+    }
+  }
+
+  schedule()
+
+  return () => {
+    running = false
+    io.disconnect()
+    document.removeEventListener('visibilitychange', onVisibility)
+    cancelAnimationFrame(raf)
+
+    if (timer !== undefined) {
+      clearTimeout(timer)
+    }
+  }
+}