# Shader Desk

> Paste one GLSL shader. The browser hands it to your own GPU driver, shows the real
> compiler diagnostics against your line numbers, renders it live if it builds, counts
> what it costs per pixel — and then a reviewer works it through one of four lanes:
> diagnose, explain, optimize, port.

Live at https://shader-desk.skillsafe.ai/ · API tutorial at /api.html · tokens at /tokens.html

## What the work object is

One GLSL shader source. Usually a fragment shader — copied out of a Shadertoy tab, lifted
from a three.js `ShaderMaterial`, or half-written in somebody's own editor. Optionally the
vertex shader that pairs with it. Every lane operates on that same artifact; there is no
second unrelated paste anywhere in the app.

## What runs for free, in the browser, with no account

This is most of the app, and it is not a preview of the paid part — it is a different
kind of answer.

- **A real compile.** The source is handed to `compileShader` on the visitor's own
  machine. The `ERROR: 0:14:` lines that come back are from their GPU vendor's GLSL
  compiler, which is why two machines can disagree. The program is linked too, and the
  uniforms the driver *kept* after optimisation are listed — a uniform that is declared
  but missing from that list is one the host code will look up and get `null` for.
  Where a Shadertoy wrapper had to be added, the reported line numbers are corrected
  back to the user's own source before they are shown.
- **A live preview.** A full-screen-quad render with the Shadertoy uniform set
  (`iResolution`, `iTime`, `iTimeDelta`, `iFrame`, `iMouse`, `iDate`), with play, pause,
  reset, a resolution scale and an fps readout.
- **Dialect detection.** GLSL ES 1.00 vs 3.00, Shadertoy style vs three.js style,
  fragment vs vertex stage, and which entry point (`main` / `mainImage`) is present.
- **A declaration inventory.** Every uniform, attribute, varying, `in`, `out`, `const`,
  struct and function, with a use count, and the Shadertoy uniforms the paste relies on
  without declaring.
- **A counted per-pixel cost profile.** Texture fetches; transcendental calls broken down
  per function; branch and discard counts; every loop with its bound and whether that
  bound is a compile-time constant; nesting depth; and a cost tier derived from all of it.
- **28 GX lint rules**, each with a stable id, a severity, a line and a fix.
- **A portability matrix** — exactly what breaks moving this source to 3.00, and what
  breaks moving it back to 1.00.
- **A deterministic dialect translation.** The half of a port that has exactly one
  correct answer, done without a model: `attribute`/`varying` to `in`/`out`, `texture2D`
  to `texture`, `gl_FragColor` to a declared output, the `#version` line rewritten, every
  rename listed, and the residual judgement named honestly rather than guessed at.
- **Exports** — findings CSV, interface CSV, a Markdown report, the translated source.

Nothing is uploaded until a lane is run.

## The four lanes

Each is a separate skill's contribution over the same shader, and each hands its
conclusions to the next through a button rather than a copy-paste.

| Lane | Question | Verdicts | Lane block |
| --- | --- | --- | --- |
| `diagnose` | Why will it not compile, and what is the fix? | `compiles` / `fixable` / `broken` | `repair` |
| `explain` | What is the maths actually doing? | `clear` / `dense` / `obscure` | `walkthrough` |
| `optimize` | What does it cost per pixel, and what can come out? | `lean` / `tunable` / `expensive` | `budget` |
| `port` | Will it run in my own page, and what glue does it need? | `direct` / `adapted` / `blocked` | `port` |

- **diagnose** accounts for every driver diagnostic — each one becomes a fix or an
  explicit still-open line — and returns a complete patched source, with `ready: true`
  only when it compiles as written. Fixes are marked `certain` / `likely` / `guess`.
- **explain** names the technique honestly, spells out the coordinate space, walks the
  source top-to-bottom in non-overlapping ranges, tabulates the uniform contract, and
  lists the numbers worth turning with a concrete alternative for each.
- **optimize** prices the per-pixel work *against the browser's own counts*, shows the
  arithmetic behind its reduction estimate, and ranks savings each carrying real before
  and after GLSL plus an honest `none` / `subtle` / `visible` note on whether the image
  changes.
- **port** returns the ported fragment and vertex source, the uniform map, runnable host
  JavaScript, and the behavioural differences the renames hide — Shadertoy's
  `fragCoord` is window space, not UV; `iResolution` is the canvas, not the mesh; the
  time origin differs.

## The output contract

One JSON object per run. A shared envelope — `lane`, `shader_name`, `verdict`,
`headline`, `overview`, `checks[]` (exactly the lane's ten named checks, in order),
`findings[]` (`SD-nnn`, severity-sorted), `coverage_check[]`, `next_steps[]` — plus
exactly one lane block. The full field-by-field shape, with a worked example per lane and
client code in eight languages, is at /api.html.

## Reconciliation — why the free lane exists

Every flag the browser measured is sent to the reviewer as a fact it must answer, and the
result page renders the answer flag by flag. A flag the reviewer handled shows its
reasoning. A flag it declined shows the stated reason. **A flag it never mentioned is
rendered as unreviewed, not as cleared** — and a `GX` id the reviewer invented is shown as
invented. The optimize lane goes further: if its stated cost does not quote the numbers
the browser counted, both figures are shown side by side and the measured ones are
labelled as the measured ones.

## Cost and access

Metered: a run costs the signed-in user credits at the `gpt-terra` tier with a 10%
publisher markup. `estimate` is free and is re-taken on every lane switch, the reserve is
shown as a reserve rather than a price, and the run button stays disabled when the balance
cannot cover it. Guests can use every free surface above. Two bundled examples replay
saved runs at zero cost without an account: the Shadertoy raymarcher for the explain,
optimize and port lanes, and the half-ported post effect for the diagnose lane.

## Sources

A derived work built on four agent skills, credited in the app footer and in the system
prompt:

- `@minimax-ai/shader-dev` — GLSL technique: ray marching, SDF modelling, procedural
  generation, lighting. Drives the optimize lane.
- `@sickn33/shader-programming-glsl` — writing efficient vertex and fragment shaders:
  syntax, uniforms, common pitfalls. Drives the diagnose lane.
- `@bbeierle12/shader-fundamentals` — the pipeline itself: uniforms, varyings,
  attributes, coordinate systems, built-in variables and data types. Drives the explain
  lane.
- `@cloudai-x/threejs-shaders` — `ShaderMaterial`, uniform objects and custom effects in
  three.js. Drives the port lane.

Shadertoy, three.js, WebGL and OpenGL are trademarks of their respective owners. This app
is not affiliated with or endorsed by any of them.