onejs-sl 0.1.8 → 0.1.10

package/src/lang/classify.ts

@@ -13,7 +13,7 @@
  * wants that should ask it.
  */
 
-import { INPUTS } from "../ir"
+import { SOURCE_INPUTS } from "../ir"
 import { BUILTINS } from "./builtins"
 import { lex } from "./lexer"
 import { PRELUDE_NAMES } from "./prelude-source"
@@ -21,7 +21,9 @@ import { KEYWORD_SET, TYPE_SET } from "./words"
 
 export type SLTokenClass =
     | "keyword" | "type" | "builtin" | "input" | "prelude"
-    | "number" | "hex" | "comment" | "punct"
+    | "number" | "hex" | "string" | "comment" | "punct"
+    /** An attribute's name, as in `[Range(0, 1)]`. */
+    | "attribute"
     /** A component after a dot, as in `c.rgb`. */
     | "member"
     /** Any other name: a uniform, a local, a function the file declares. */
@@ -40,7 +42,7 @@ export interface SLClassifiedToken {
     length: number
 }
 
-const INPUT_NAMES: ReadonlySet<string> = new Set(Object.keys(INPUTS))
+const INPUT_NAMES: ReadonlySet<string> = new Set(Object.keys(SOURCE_INPUTS))
 
 /** The tokens of `source`, comments included, in order, each with its class. */
 export function classify(source: string): SLClassifiedToken[] {
@@ -54,6 +56,8 @@ export function classify(source: string): SLClassifiedToken[] {
         let kind: SLTokenClass
         if (t.kind === "ident") {
             if (before === ".") kind = beforeThat === "sdf" ? "builtin" : "member"
+            // There are no arrays, so a name straight after "[" is an attribute's.
+            else if (before === "[") kind = "attribute"
             else if (KEYWORD_SET.has(t.text)) kind = "keyword"
             else if (TYPE_SET.has(t.text)) kind = "type"
             else if (INPUT_NAMES.has(t.text)) kind = "input"

package/src/lang/glsl.ts

@@ -107,6 +107,83 @@ const MISSING: Record<string, string> = {
     dFdx: "there are no derivatives", dFdy: "there are no derivatives", fwidth: "there are no derivatives",
 }
 
+/**
+ * Uniforms other hosts declare for what is an input here: the Book of Shaders'
+ * and glslCanvas's `u_time`, glslsandbox's `time`, and Shadertoy's own when a
+ * tool declares them. The declaration goes and every use reads the input, so a
+ * pasted shader does not arrive frozen on a uniform nothing sets.
+ */
+const HOST_UNIFORMS: Record<string, string> = {
+    u_time: "time", u_resolution: "resolution", time: "time", resolution: "resolution",
+    iTime: "time", iGlobalTime: "time", iResolution: "resolution", iMouse: "mouse",
+}
+
+const QUALIFIERS = new Set(["highp", "mediump", "lowp"])
+/** Words that take a bracket without being called. */
+const CONTROL = new Set(["if", "for", "while", "switch", "return"])
+
+/**
+ * Whether a `mat2(...)`, given its four arguments as words, is a rotation, and
+ * which way: +1 for `mat2(c, s, -s, c)`, the matrix R(a), and -1 for
+ * `mat2(c, -s, s, c)`, which is R(-a) since GLSL fills a matrix by columns.
+ * `cos` and `sin` are the words that stand for the cosine and sine.
+ */
+function rotationSign(matArgs: string[], cos: string[], sin: string[]): 1 | -1 | null {
+    const kind = (w: string) => cos.includes(w) ? "C" : sin.includes(w) ? "S"
+        : w.startsWith("- ") && sin.includes(w.slice(2)) ? "-S" : "?"
+    const k = matArgs.map(kind).join(",")
+    return k === "C,S,-S,C" ? 1 : k === "C,-S,S,C" ? -1 : null
+}
+
+/** Words split at the commas outside any bracket. */
+function splitTop(words: string[]): string[] {
+    const out: string[] = []
+    let depth = 0
+    let cur: string[] = []
+    for (const w of words) {
+        if (w === "(" || w === "[") depth++
+        else if (w === ")" || w === "]") depth--
+        if (w === "," && depth === 0) { out.push(cur.join(" ")); cur = [] } else cur.push(w)
+    }
+    out.push(cur.join(" "))
+    return out
+}
+
+/** The arguments of `mat2 ( ... )` as words, when `words` is exactly that, in any number of brackets. */
+function mat2Args(words: string[]): string[] | null {
+    while (words[0] === "(" && words[words.length - 1] === ")") words = words.slice(1, -1)
+    if (words[0] !== "mat2" || words[1] !== "(" || words[words.length - 1] !== ")") return null
+    const inner = words.slice(2, -1)
+    let depth = 0
+    for (const w of inner) { if (w === "(") depth++; else if (w === ")" && --depth < 0) return null }
+    return splitTop(inner)
+}
+
+/**
+ * The sign of a function body that returns a rotation of its parameter:
+ * `return mat2(cos(a), -sin(a), sin(a), cos(a));`, or the same after
+ * `float c = cos(a), s = sin(a);`. Null for anything else.
+ */
+function rotationBody(words: string[], param: string): 1 | -1 | null {
+    const cos = [`cos ( ${param} )`]
+    const sin = [`sin ( ${param} )`]
+    const statements = words.join(" ").split(/\s*;\s*/).filter((x) => x !== "")
+    const last = statements.pop()
+    const binding = new RegExp(`^(\\w+) = (cos|sin) \\( ${param} \\)$`)
+    for (const st of statements) {
+        const parts = splitTop(st.replace(/^float /, "").split(" "))
+        for (const part of parts) {
+            const m = binding.exec(part)
+            if (m === null) return null
+            if (m[2] === "cos") cos.push(m[1]!)
+            else sin.push(m[1]!)
+        }
+    }
+    if (last === undefined || !last.startsWith("return ")) return null
+    const a = mat2Args(last.slice("return ".length).split(" "))
+    return a === null || a.length !== 4 ? null : rotationSign(a, cos, sin)
+}
+
 /** Names a pasted value or function cannot keep, because the language already means something by them. */
 function taken(name: string, isFunction: boolean): boolean {
     if (name in INPUTS || (SL_KEYWORDS as readonly string[]).includes(name) || (SL_TYPES as readonly string[]).includes(name)) return true
@@ -141,6 +218,61 @@ export function fromGLSL(glsl: string, options: { file?: string } = {}): FromGLS
         }
         return toks.length
     }
+    /** The index of the bracket opening the one at `close`, or -1. */
+    const opening = (close: number): number => {
+        const [o, c] = toks[close]!.text === ")" ? ["(", ")"] : ["[", "]"]
+        let depth = 0
+        for (let i = close; i >= 0; i--) {
+            if (toks[i]!.kind !== "punct") continue
+            if (toks[i]!.text === c) depth++
+            else if (toks[i]!.text === o && --depth === 0) return i
+        }
+        return -1
+    }
+    /** Words for tokens `from` to `to`: no layout, no comments, one space between. */
+    const words = (from: number, to: number) =>
+        toks.slice(from, to).filter((t) => t.kind !== "ws" && t.kind !== "comment").map((t) => t.text)
+    /**
+     * The last token of the operand starting at `i`: a name, a number, a call
+     * or a bracket, then any members and indexes. -1 when it is none of those.
+     */
+    const operandAfter = (i: number): number => {
+        const t = toks[i]
+        let j: number
+        if (t === undefined) return -1
+        if (t.kind === "number") j = i
+        else if (is(i, "(")) j = closing(i)
+        else if (t.kind === "ident") { const n = skip(i + 1); j = is(n, "(") ? closing(n) : i }
+        else return -1
+        for (;;) {
+            if (j >= toks.length) return -1
+            const n = skip(j + 1)
+            if (is(n, ".") && toks[skip(n + 1)]?.kind === "ident") j = skip(n + 1)
+            else if (is(n, "[")) j = closing(n)
+            else return j
+        }
+    }
+    /** The first token of the operand ending at `j`, the same shapes read backwards. -1 when there is none. */
+    const operandBefore = (j: number): number => {
+        let i = j
+        for (;;) {
+            if (is(i, "]")) { const o = opening(i); if (o < 0) return -1; i = back(o - 1); continue }
+            let start: number
+            if (is(i, ")")) {
+                const o = opening(i)
+                if (o < 0) return -1
+                const p = back(o - 1)
+                start = toks[p]?.kind === "ident" && !CONTROL.has(toks[p]!.text) ? p : o
+            } else if (toks[i]?.kind === "ident" || toks[i]?.kind === "number") {
+                start = i
+            } else {
+                return -1
+            }
+            const p = back(start - 1)
+            if (!is(p, ".")) return start
+            i = back(p - 1)
+        }
+    }
     /** A call's arguments, as token ranges, for the call whose "(" is at `open`. */
     const args = (open: number, close: number): Array<[number, number]> => {
         const out: Array<[number, number]> = []
@@ -173,6 +305,142 @@ export function fromGLSL(glsl: string, options: { file?: string } = {}): FromGLS
         if (taken(name, isFunction)) clashes.set(name, name + "_")
     }
 
+    // ---------- what other hosts declare ----------
+
+    /**
+     * Token ranges written as something else, keyed by their first token: a
+     * declaration that goes, a rotation that becomes a call. They nest, and
+     * never cross.
+     */
+    const spans = new Map<number, { end: number; render: (inEntry: boolean) => string }>()
+    const crosses = (start: number, end: number) =>
+        [...spans].some(([s, v]) => (s < start && start <= v.end && v.end < end) || (start < s && s <= end && end < v.end))
+    /** A range and the whitespace after it, gone. */
+    const drop = (start: number, end: number) => {
+        spans.set(start, { end: toks[end + 1]?.kind === "ws" ? end + 1 : end, render: () => "" })
+    }
+
+    const hostUniforms = new Set<string>()
+    for (let i = 0; i < toks.length; i++) {
+        if (!is(i, "uniform")) continue
+        let t = skip(i + 1)
+        while (QUALIFIERS.has(toks[t]?.text ?? "")) t = skip(t + 1)
+        const n = skip(t + 1)
+        const name = toks[n]?.text ?? ""
+        const semi = skip(n + 1)
+        if (toks[n]?.kind !== "ident" || HOST_UNIFORMS[name] === undefined || !is(semi, ";")) continue
+        hostUniforms.add(name)
+        // Its name is the input, not a clash with it.
+        clashes.delete(name)
+        const input = HOST_UNIFORMS[name]!
+        noteOnce("host:" + name, toks[i]!.line, `the uniform ${name} is the input ${input}, so its declaration is dropped`)
+        drop(i, semi)
+    }
+
+    // ---------- rotations ----------
+
+    /**
+     * There are no matrices, and the matrix a shader almost always has is a
+     * rotation: `mat2 rot(float a)` returning `mat2(c, -s, s, c)`, the same as
+     * a macro, or written in place. Each use that multiplies a vector becomes
+     * `rotate(p, angle)`, the angle's sign set by the matrix and by which side
+     * the vector is on, since GLSL's `p * M` is M transposed times p. A
+     * function or macro whose every use is converted goes. Anything else keeps
+     * its `mat2`, which `errors` then points at, with a note naming rotate().
+     */
+    const rotations = new Map<string, { sign: 1 | -1; def: [number, number]; line: number; uses: number; converted: number }>()
+    for (let i = 0; i < toks.length; i++) {
+        const t = toks[i]!
+        if (t.kind === "directive") {
+            const m = /^#\s*define\s+([A-Za-z_]\w*)\(\s*([A-Za-z_]\w*)\s*\)(.*)$/s.exec(t.text)
+            if (m === null) continue
+            const body = tokenize(m[3]!.replace(/\\\n/g, " ")).filter((x) => x.kind !== "ws" && x.kind !== "comment").map((x) => x.text)
+            const a = mat2Args(body)
+            const sign = a === null || a.length !== 4 ? null : rotationSign(a, [`cos ( ${m[2]} )`], [`sin ( ${m[2]} )`])
+            if (sign !== null) rotations.set(m[1]!, { sign, def: [i, i], line: t.line, uses: 0, converted: 0 })
+            continue
+        }
+        if (!is(i, "mat2")) continue
+        const n = skip(i + 1)
+        const open = skip(n + 1)
+        if (toks[n]?.kind !== "ident" || !is(open, "(")) continue
+        const close = closing(open)
+        const params = words(open + 1, close).filter((w) => w !== "in")
+        const body = skip(close + 1)
+        if (params.length !== 2 || params[0] !== "float" || !is(body, "{")) continue
+        const end = closing(body)
+        const sign = rotationBody(words(body + 1, end), params[1]!)
+        if (sign !== null) rotations.set(toks[n]!.text, { sign, def: [i, end], line: t.line, uses: 0, converted: 0 })
+    }
+    // A file with a rotate of its own would have the calls written here call it.
+    const ownRotate = toks.some((t, i) => t.text === "rotate" && t.kind === "ident" && GLSL_TYPES.has(toks[back(i - 1)]?.text ?? "") &&
+        !(rotations.has("rotate") && toks[back(i - 1)]!.text === "mat2"))
+
+    /** The angle, negated when `sign` is -1, as text. */
+    const angle = (range: [number, number], sign: 1 | -1, inEntry: boolean) => {
+        const a = emit(range[0], range[1], inEntry).trim()
+        if (sign === 1) return a
+        if (/^-[\w.]+$/.test(a)) return a.slice(1)
+        return /^[\w.]+$/.test(a) ? `-${a}` : `-(${a})`
+    }
+    for (let i = 0; i < toks.length && !ownRotate; i++) {
+        if (toks[i]!.kind !== "ident" || is(back(i - 1), ".")) continue
+        const open = skip(i + 1)
+        if (!is(open, "(")) continue
+        const close = closing(open)
+        const a = args(open, close)
+        const fn = rotations.get(toks[i]!.text)
+        let sign: 1 | -1 | null = null
+        let range: [number, number] | null = null
+        if (fn !== undefined && (i < fn.def[0] || i > fn.def[1])) {
+            fn.uses++
+            if (a.length === 1) { sign = fn.sign; range = a[0]! }
+        } else if (is(i, "mat2") && a.length === 4) {
+            // In place: the angle is whatever cos() is given.
+            const first = skip(a[0]![0])
+            const inner = skip(first + 1)
+            if (is(first, "cos") && is(inner, "(") && closing(inner) === back(a[0]![1] - 1)) {
+                const x = words(inner + 1, closing(inner)).join(" ")
+                sign = rotationSign(a.map(([x0, x1]) => words(x0, x1).join(" ")), [`cos ( ${x} )`], [`sin ( ${x} )`])
+                range = [inner + 1, closing(inner)]
+            }
+        }
+        if (sign === null || range === null) continue
+        const r = range
+        const s = sign
+        const before = back(i - 1)
+        const after = skip(close + 1)
+        let span: [number, number, (inEntry: boolean) => string] | null = null
+        if (is(before, "=") && is(before - 1, "*") && is(after, ";")) {
+            // p *= M is p = p * M.
+            const lhsEnd = back(before - 2)
+            const lhs = operandBefore(lhsEnd)
+            if (lhs >= 0) span = [lhs, close, (e) => { const p = emit(lhs, lhsEnd + 1, e).trim(); return `${p} = rotate(${p}, ${angle(r, -s as 1 | -1, e)})` }]
+        } else if (is(after, "*") && !is(after + 1, "=") && !["/", "%", "*"].includes(toks[before]?.text ?? "")) {
+            // M * p.
+            const x = skip(after + 1)
+            const xEnd = operandAfter(x)
+            if (xEnd >= 0) span = [i, xEnd, (e) => `rotate(${emit(x, xEnd + 1, e).trim()}, ${angle(r, s, e)})`]
+        } else if (is(before, "*") && !is(after, "*")) {
+            // p * M.
+            const xEnd = back(before - 1)
+            const x = operandBefore(xEnd)
+            if (x >= 0 && !["/", "%"].includes(toks[back(x - 1)]?.text ?? "")) {
+                span = [x, close, (e) => `rotate(${emit(x, xEnd + 1, e).trim()}, ${angle(r, -s as 1 | -1, e)})`]
+            }
+        }
+        if (span === null || crosses(span[0], span[1]) || spans.has(span[0])) continue
+        const [start, end, render] = span
+        spans.set(start, { end, render })
+        noteOnce("rotation", toks[i]!.line, "a mat2 rotation is rotate(p, angle) here, since there are no matrices; the angle's sign follows which side p was multiplied on")
+        if (fn !== undefined) fn.converted++
+    }
+    for (const [name, fn] of rotations) {
+        if (ownRotate || fn.converted !== fn.uses) continue
+        drop(fn.def[0], fn.def[1])
+        note(fn.line, `${name} built a rotation matrix, and each use of it is rotate() now, so it is removed`)
+    }
+
     // ---------- the entry point ----------
 
     let colour = "fragColor"
@@ -231,6 +499,8 @@ export function fromGLSL(glsl: string, options: { file?: string } = {}): FromGLS
         let out = ""
         for (let i = from; i < to; i++) {
             const t = toks[i]!
+            const span = spans.get(i)
+            if (span !== undefined && span.end < to) { out += span.render(inEntry); i = span.end; continue }
             if (t.kind === "directive") { out += directive(t); continue }
             if (t.kind === "number") { out += t.text.replace(/[uU]$/, ""); continue }
             if (t.kind !== "ident") { out += t.text; continue }
@@ -286,6 +556,16 @@ export function fromGLSL(glsl: string, options: { file?: string } = {}): FromGLS
                 out += to2
                 continue
             }
+            if (hostUniforms.has(name) && (name === "u_time" || name === "u_resolution")) { out += HOST_UNIFORMS[name]; continue }
+            if (name === "mat2") {
+                noteOnce("mat2", t.line, "there are no matrices here; a mat2 rotation is rotate(p, angle): p *= mat2(c, -s, s, c) is rotate(p, a), and mat2(c, -s, s, c) * p is rotate(p, -a)")
+                out += name
+                continue
+            }
+            const unconverted = rotations.get(name)
+            if (unconverted !== undefined && called && (i < unconverted.def[0] || i > unconverted.def[1])) {
+                noteOnce("rot:" + t.line + name, t.line, `${name} builds a rotation matrix, and this use of it was not converted; write it as rotate(p, angle)`)
+            }
             if (/^iChannel\d$/.test(name)) { textures.add(name); out += name; continue }
             if (name === "iMouse") {
                 mouse = true

package/src/lang/lexer.ts

@@ -13,7 +13,8 @@
 
 import { SLError } from "../ir"
 
-export type TokenKind = "ident" | "number" | "hex" | "punct" | "eof"
+/** `string` only ever appears in an attribute: `[Label("Glow colour")]`. */
+export type TokenKind = "ident" | "number" | "hex" | "string" | "punct" | "eof"
 
 export interface Pos {
     /** 1 based, the way every editor counts. */
@@ -30,6 +31,8 @@ export interface Token extends Pos {
     text: string
     /** Numbers only: the parsed value. */
     value?: number
+    /** Strings only: the text between the quotes, with `\"` and `\\` read. */
+    str?: string
 }
 
 /**
@@ -206,6 +209,25 @@ export function lex(source: string, file: string, keep: boolean): Token[] | Lexe
             continue
         }
 
+        if (c === "\"") {
+            const start = here()
+            let j = i + 1
+            let str = ""
+            while (j < source.length && source[j] !== "\"" && source[j] !== "\n") {
+                if (source[j] === "\\" && (source[j + 1] === "\"" || source[j + 1] === "\\")) j++
+                str += source[j]
+                j++
+            }
+            if (source[j] !== "\"") {
+                fail("this string is never closed; it ends at the end of its line", start, j - i)
+            } else {
+                push({ kind: "string", text: source.slice(i, j + 1), str, ...start }, j + 1)
+                j++
+            }
+            i = j
+            continue
+        }
+
         if (isIdentStart(c)) {
             const start = here()
             let j = i

package/src/lang/lower.ts

@@ -33,11 +33,12 @@
  * than an optimisation.
  */
 
-import { INPUTS, type Program, type SLType } from "../ir"
+import { controlProblem, DERIVED_INPUTS, INPUTS, type Program, type SLType, type UniformControl } from "../ir"
 import type { SlSdfKind } from "../shapes"
 import * as sl from "../sl"
 import type { Num, Val } from "../sl"
 import { TYPE_WIDTH, type Expr, type FuncDecl, type Stmt, type TypeName } from "./ast"
+import { readAttributes } from "./attributes"
 import { BUILTINS } from "./builtins"
 import type { Checked } from "./check"
 import { SLParseError, type Pos } from "./lexer"
@@ -161,6 +162,17 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
             for (const [name, width] of Object.entries(INPUTS)) {
                 global.declare(name, { width: width as SLType, value: (inputs as never)[name] })
             }
+            // Read through, so a program that never names one records nothing
+            // for it. The setter only serves a refused assignment, which the
+            // checker has already reported and lowering carries on past.
+            for (const [name, width] of Object.entries(DERIVED_INPUTS)) {
+                let value: LV | undefined
+                global.declare(name, {
+                    width: width as SLType,
+                    get value() { return value ??= (inputs as never)[name] },
+                    set value(v: LV) { value = v },
+                })
+            }
 
             // Uniforms and textures take their slots in DECLARATION order, before
             // anything is lowered, so a slot is a property of the file rather than
@@ -177,9 +189,20 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
                 // that, `#ff8040` and a uniform defaulting to `#ff8040` would be two
                 // different colours in one file. `sl.uniform.colour` also marks
                 // the declaration, for a host's colour picker.
-                const value = colour && u.init?.k === "hex"
-                    ? at(u.pos, () => sl.uniform.colour(u.name, (u.init as { hex: string }).hex, width as 3 | 4) as unknown as Val)
-                    : at(u.pos, () => declareUniform(u.name, u.type, components))
+                // What the attributes say the control is, and whether the default
+                // fits it, marked on the attribute that does not fit.
+                const read = readAttributes(u)
+                const problem = recover(() => {
+                    const p = controlProblem(width as SLType, components, read.control)
+                    const attr = p === null ? undefined : read.from[p.field]
+                    if (p !== null) fail(inFileWords(p.message), attr?.pos ?? u.pos, attr?.length ?? 1)
+                    return false
+                }, () => true)
+                const control = problem ? {} : read.control
+                // `[Color]` says the same as a hex default, for a default written as numbers.
+                const value = (colour && u.init?.k === "hex") || read.colour
+                    ? at(u.pos, () => sl.uniform.colour(u.name, components, width as 3 | 4, control) as unknown as Val)
+                    : at(u.pos, () => declareUniform(u.name, u.type, components, control))
                 global.declare(u.name, { width, value })
             }
 
@@ -217,12 +240,12 @@ export function lower(checked: Checked, errors?: SLParseError[]): Program {
 
     // MARK: declarations
 
-    function declareUniform(name: string, type: TypeName, c: number[]): Val {
+    function declareUniform(name: string, type: TypeName, c: number[], control: UniformControl): Val {
         switch (type) {
-            case "float": return sl.uniform.float(name, c[0]!) as unknown as Val
-            case "float2": return sl.uniform.vec2(name, [c[0]!, c[1]!]) as unknown as Val
-            case "float3": return sl.uniform.vec3(name, [c[0]!, c[1]!, c[2]!]) as unknown as Val
-            case "float4": return sl.uniform.vec4(name, [c[0]!, c[1]!, c[2]!, c[3]!]) as unknown as Val
+            case "float": return sl.uniform.float(name, c[0]!, control) as unknown as Val
+            case "float2": return sl.uniform.vec2(name, [c[0]!, c[1]!], control) as unknown as Val
+            case "float3": return sl.uniform.vec3(name, [c[0]!, c[1]!, c[2]!], control) as unknown as Val
+            case "float4": return sl.uniform.vec4(name, [c[0]!, c[1]!, c[2]!, c[3]!], control) as unknown as Val
         }
     }
 

package/src/lang/parser.ts

@@ -12,7 +12,7 @@
  */
 
 import {
-    type AssignOp, type BinaryOp, type Expr, type FuncDecl, type Param, type Stmt,
+    type AssignOp, type Attribute, type AttributeArg, type BinaryOp, type Expr, type FuncDecl, type Param, type Stmt,
     type TextureDecl, type TypeName, type UniformDecl, type Unit,
 } from "./ast"
 import { SLParseError, tokenize, type Pos, type SLFix, type Token } from "./lexer"
@@ -199,7 +199,18 @@ class Parser {
     private parseDeclaration(unit: Unit): void {
         const t = this.peek()
 
-        if (t.text === "uniform") { unit.uniforms.push(this.parseUniform()); return }
+        if (t.text === "[") {
+            const attrs = this.parseAttributes()
+            if (!this.at("uniform")) {
+                this.fail(
+                    `an attribute belongs on a uniform, as in \`[Range(0, 1)] uniform float amount = 0.5;\`, ` +
+                    `and this one is followed by ${describe(this.peek())}`, t,
+                )
+            }
+            unit.uniforms.push(this.parseUniform(attrs))
+            return
+        }
+        if (t.text === "uniform") { unit.uniforms.push(this.parseUniform([])); return }
         if (t.text === "texture2D") { unit.textures.push(this.parseTexture()); return }
         if (t.text === "const") { unit.consts.push(this.parseConst()); return }
         if (t.kind === "ident") {
@@ -214,14 +225,45 @@ class Parser {
         )
     }
 
-    private parseUniform(): UniformDecl {
+    private parseUniform(attrs: Attribute[]): UniformDecl {
         const kw = this.next()
         const type = this.expectType("a type after uniform")
         const name = this.expectName("a uniform name")
         let init: Expr | null = null
         if (this.eat("=")) init = this.parseExpr()
         this.expect(";", "after a uniform declaration")
-        return { name: name.text, type, init, pos: kw }
+        return { name: name.text, type, init, attrs, pos: kw }
+    }
+
+    /** `[Name]` or `[Name(arg, ...)]`, one or more. Shape only: the checker says what each means. */
+    private parseAttributes(): Attribute[] {
+        const out: Attribute[] = []
+        while (this.eat("[")) {
+            const name = this.expectIdent("an attribute's name, such as Range")
+            const args: AttributeArg[] = []
+            if (this.eat("(")) {
+                if (!this.at(")")) {
+                    do args.push(this.parseAttributeArg())
+                    while (this.eat(","))
+                }
+                this.expect(")", "to close the attribute's arguments")
+            }
+            this.expect("]", "to close the attribute")
+            out.push({ name: name.text, args, pos: name, length: name.text.length })
+        }
+        return out
+    }
+
+    private parseAttributeArg(): AttributeArg {
+        const t = this.next()
+        if (t.kind === "string") return { k: "str", text: t.str!, pos: t, length: t.text.length }
+        if (t.kind === "ident") return { k: "ident", name: t.text, pos: t, length: t.text.length }
+        if (t.kind === "number") return { k: "num", value: t.value!, pos: t, length: t.text.length }
+        if (t.text === "-" && this.peek().kind === "number") {
+            const n = this.next()
+            return { k: "num", value: -n.value!, pos: t, length: n.offset + n.text.length - t.offset }
+        }
+        this.fail(`expected a number, a word or a "string" as an attribute's argument, got ${describe(t)}`, t)
     }
 
     private parseTexture(): TextureDecl {
@@ -512,6 +554,9 @@ class Parser {
         if (t.kind === "number") return { k: "num", value: t.value!, pos: t }
         if (t.kind === "hex") return { k: "hex", hex: t.text, pos: t }
         if (t.kind === "ident") return { k: "ident", name: t.text, pos: t }
+        if (t.kind === "string") {
+            this.fail(`a string is only an attribute's argument, as in [Label("Glow colour")]; a value is a number`, t)
+        }
         if (t.text === "(") {
             const inner = this.parseExpr()
             this.expect(")", "to close a group")

package/src/params.ts

@@ -20,7 +20,8 @@ import { BUILTINS } from "./lang/builtins"
 import { LIB_FUNCTIONS, SDF_CALLS } from "./lib/table"
 import { LIB_PARAM_NAMES } from "./lib/names"
 import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
-import type { InputName } from "./ir"
+import type { SourceInputName } from "./ir"
+import type { AttributeName } from "./lang/attributes"
 
 /** One function of the helper library, as its source declares it. */
 export interface LibSignature {
@@ -164,15 +165,31 @@ export const BUILTIN_DOCS: Readonly<Record<string, string>> = {
     ramp: "t mapped through evenly spaced colour stops, from the first at 0 to the last at 1.",
 }
 
+/**
+ * One line on each attribute, for the same tooltips: what the control is, and
+ * how it is written.
+ */
+export const ATTRIBUTE_DOCS: Readonly<Record<AttributeName, string>> = {
+    Range: "A slider from the first number to the second: [Range(0, 2)]. A third number is its step. A float only.",
+    Toggle: "A checkbox. The value is 0 or 1. A float only.",
+    Enum: "A dropdown of names: [Enum(Soft, Hard, Glow)]. The value is the chosen name's index, from 0. A float only.",
+    Header: "A heading above this control, starting a group: [Header(\"Shape\")].",
+    Label: "The name the control shows, in place of the uniform's: [Label(\"Glow colour\")].",
+    Color: "A colour picker, the value a colour as written, the same as a hex default. A float3 or a float4.",
+    Hide: "No control: the host sets this uniform from code.",
+}
+
 /**
  * One line on each input, for the same tooltips. In the words of no one host:
  * the output is a UI element in OneJS and an image on a Magerie board, and the
  * clock is whichever one the host runs.
  */
-export const INPUT_DOCS: Readonly<Record<InputName, string>> = {
-    uv: "Where this pixel is in the output, 0 to 1 on each axis, with y up.",
-    fragCoord: "Where this pixel is in the output, in pixels, with y up.",
+export const INPUT_DOCS: Readonly<Record<SourceInputName, string>> = {
+    uv: "The centre of this pixel in the output, 0 to 1 on each axis, with y up.",
+    fragCoord: "The centre of this pixel in the output, in pixels, with y up: the first column is at 0.5.",
     resolution: "The output's size in pixels.",
     time: "The clock, in seconds.",
     aspect: "The output's width divided by its height.",
+    texel: "One pixel, in uv: 1 / resolution. Step by it to read a neighbouring pixel.",
+    centered: "uv with 0 at the centre and x scaled by aspect, so a circle drawn in it stays round.",
 }

package/src/serial.ts

@@ -9,7 +9,7 @@
  * older one is migrated to this one and rehashed under it.
  */
 import {
-    INPUTS, SLError, SL_IR_VERSION, TYPE, hashProgram,
+    INPUTS, SLError, SL_IR_VERSION, TYPE, controlOf, controlProblem, hashProgram,
     type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
 } from "./ir"
 import { SL_ARITY, SL_NAME } from "./ops"
@@ -125,7 +125,27 @@ function uniform(u: unknown, i: number): UniformDecl {
     }
     const out: UniformDecl = { name: x.name!, type: x.type as SLType, value: x.value!.slice() }
     if (x.colour === true) out.colour = true
-    return out
+    // Its control: shapes checked here, sense checked by the one check the
+    // compiler uses, so a hand edited file cannot give a host a range it would
+    // choke on.
+    const r = x.range as { min?: unknown; max?: unknown; step?: unknown } | undefined
+    if (r !== undefined && (typeof r !== "object" || r === null || typeof r.min !== "number" || typeof r.max !== "number" ||
+        (r.step !== undefined && typeof r.step !== "number"))) {
+        fail(`uniform ${i}'s range needs a min and a max, and a step if any, as numbers`)
+    }
+    if (x.options !== undefined && (!Array.isArray(x.options) || !x.options.every((o) => typeof o === "string"))) {
+        fail(`uniform ${i}'s options must be a list of names`)
+    }
+    for (const f of ["header", "label"] as const) {
+        if (x[f] !== undefined && typeof x[f] !== "string") fail(`uniform ${i}'s ${f} must be text`)
+    }
+    for (const f of ["toggle", "hide"] as const) {
+        if (x[f] !== undefined && x[f] !== true) fail(`uniform ${i}'s ${f} can only be true`)
+    }
+    const control = controlOf(x)
+    const problem = controlProblem(out.type, out.value, control)
+    if (problem !== null) fail(`uniform ${i}: ${problem.message}`)
+    return Object.assign(out, control)
 }
 
 function texture(t: unknown, i: number): TextureDecl {