DX feedback (dogfooding): uv convention docs, quieter `vgpu check`, Node still-render helper

Context

Dogfooding vgpu@0.2.0 by building fullscreen effect() fragment shaders in a Next.js (App Router, Turbopack) app, driven end-to-end by an LLM coding agent (Claude Code).

Scope, so you can weight this: narrow and mostly happy-path. I only exercised single-pass fullscreen effect() with one Params { time, texel } uniform, rendered both in the browser (init/surface/clock/frameLoop) and headless (vgpu/node: target → effect.draw → target.read → PNG). I did not touch draw() with meshes/vertex/instancing, storage buffers, compute, real multi-pass, timer(), render bundles, or WGSL module imports — and I hit zero compile/binding errors, so I can't speak to diagnostics quality. This is startup/DX feedback, not deep coverage.

Overall it was a great experience for an agent: vgpu doctor + headless target.read() turn "looks right" into pixels you can assert on, and the CLI docs (npx vgpu docs cat ...) are written for exactly that loop. Three small suggestions below.

1. Document the fullscreen uv convention

When writing a fullscreen effect, I couldn't find where the docs state the uv origin/orientation (top-left vs bottom-left, y-up vs y-down). I needed a bottom-edge glow and had to render a frame to discover which way was "down", then flip with h = 1.0 - uv.y.

Suggestion: one line in getting-started / concepts-effects stating that fragment uv ∈ [0,1] and where its origin is.

2. A concise pass/fail from vgpu check

vgpu check <file.wgsl> prints the full reflection JSON plus the rewritten (name-mangled) WGSL. To answer the only question I had — "does it compile?" — I had to grep the output.

Suggestion: a final summary line (e.g. ✓ valid — 1 entry point, 1 binding / ✗ 2 errors) and/or a --quiet flag that prints only diagnostics and sets an exit code. Very handy for CI, and for agents that just want a yes/no.

3. A first-class Node "still render" helper

The shader→image path (init → target → effect.draw → target.read → encode) was central enough to my workflow (previews, per-experiment thumbnails) that I ended up factoring my own helper around it.

Suggestion: a convenience like renderStill(gpu, source, { size, set }) that returns RGBA bytes (leaving PNG/WebP encoding to the caller) would remove boilerplate for tests, thumbnails, and CI snapshots — the exact "prove the pixels" loop the docs already advocate.

Minor

No obvious exported context type — I typed the Gpu context as Awaited<ReturnType<typeof init>>. If a public Gpu/context type exists, surfacing it in the docs would help; if not, exporting one would.

---

_{Filed from a dogfooding session with Claude Code. Happy to share the shader/app that produced this if useful.}