onejs-sl 0.3.0 → 0.5.0

package/src/lang/parser.ts

@@ -13,7 +13,7 @@
 
 import {
     type AssignOp, type Attribute, type AttributeArg, type BinaryOp, type Expr, type FuncDecl, type Param, type Stmt,
-    type TextureDecl, type TypeName, type UniformDecl, type Unit,
+    type SwitchCase, type TextureDecl, type TypeName, type UniformDecl, type Unit,
 } from "./ast"
 import { SLParseError, tokenize, type Pos, type SLFix, type Token } from "./lexer"
 import { KEYWORD_SET, TYPE_SET } from "./words"
@@ -29,9 +29,16 @@ const NOT_A_TYPE: Record<string, string> = {
     vec2: "use float2",
     vec3: "use float3",
     vec4: "use float4",
-    int: "there are no integers; a whole number is a float, so write float",
-    uint: "there are no integers; a whole number is a float, so write float",
-    bool: "there is no bool; a comparison is a float that is 0 or 1",
+    int2: "there are no int vectors yet; use an int for each component",
+    int3: "there are no int vectors yet; use an int for each component",
+    int4: "there are no int vectors yet; use an int for each component",
+    uint2: "there are no uint vectors yet; use a uint for each component",
+    uint3: "there are no uint vectors yet; use a uint for each component",
+    uint4: "there are no uint vectors yet; use a uint for each component",
+    bool2: "there are no bool vectors; use a bool for each component",
+    bool3: "there are no bool vectors; use a bool for each component",
+    bool4: "there are no bool vectors; use a bool for each component",
+    ivec2: "there are no int vectors yet; use an int for each component",
     half: "use float; the IR has one precision",
     double: "use float; the IR has one precision",
     fixed: "use float; the IR has one precision",
@@ -52,13 +59,17 @@ const TYPE_FIX: Record<string, TypeName> = {
 const BINDING: Record<string, number> = {
     "||": 1,
     "&&": 2,
-    "==": 3, "!=": 3,
-    "<": 4, "<=": 4, ">": 4, ">=": 4,
-    "+": 5, "-": 5,
-    "*": 6, "/": 6, "%": 6,
+    "|": 3,
+    "^": 4,
+    "&": 5,
+    "==": 6, "!=": 6,
+    "<": 7, "<=": 7, ">": 7, ">=": 7,
+    "<<": 8, ">>": 8,
+    "+": 9, "-": 9,
+    "*": 10, "/": 10, "%": 10,
 }
 
-const ASSIGN_OPS = new Set(["=", "+=", "-=", "*=", "/=", "%="])
+const ASSIGN_OPS = new Set(["=", "+=", "-=", "*=", "/=", "%=", "&=", "|=", "^=", "<<=", ">>="])
 
 class Parser {
     private i = 0
@@ -170,7 +181,7 @@ class Parser {
         const to = TYPE_FIX[t.text]
         const fix = to === undefined ? undefined : { title: `Replace ${t.text} with ${to}`, replacement: to }
         if (why !== undefined) this.fail(`"${t.text}" is not a type here: ${why}`, t, fix)
-        this.fail(`"${t.text}" is not a type; the types are float, float2, float3 and float4`, t)
+        this.fail(`"${t.text}" is not a type; the types are float, float2, float3, float4, int, uint and bool`, t)
     }
 
     // MARK: the file
@@ -339,28 +350,25 @@ class Parser {
     private parseStmt(): Stmt {
         const t = this.peek()
 
+        if (t.text === "{") return { k: "block", body: this.parseBlock(), pos: t }
         if (t.text === "const") return this.parseConst()
         if (t.text === "if") return this.parseIf()
         if (t.text === "for") return this.parseFor()
-        if (t.text === "while" || t.text === "do") {
-            this.fail(
-                `there is no ${t.text} loop: a loop unrolls at build time, and only a for loop ` +
-                `with constant bounds can. See a for loop`,
-                t,
-            )
+        if (t.text === "while") return this.parseWhile()
+        if (t.text === "switch") return this.parseSwitch()
+        if (t.text === "do") {
+            this.fail("there is no do loop; write it as a while loop, `while (condition) { ... }`", t)
         }
         if (t.text === "discard") {
             this.fail("there is no discard; return a colour with alpha 0 instead", t)
         }
         if (t.text === "break" || t.text === "continue") {
-            this.fail(
-                `there is no ${t.text}: a for loop unrolls, so every iteration runs. Put the rest of ` +
-                `the body under an if instead`,
-                t,
-            )
+            this.next()
+            this.expect(";", `after ${t.text}`)
+            return { k: t.text, pos: t }
         }
-        if (t.text === "switch") {
-            this.fail("there is no switch; write it as an if and else if", t)
+        if (t.text === "case" || t.text === "default") {
+            this.fail(`${t.text} belongs inside a switch's braces`, t)
         }
         if (t.text === "return") {
             this.next()
@@ -384,26 +392,50 @@ class Parser {
                     this.peek(),
                 )
             }
-            this.expect("=", `after ${name.text}; every local is declared with a value`)
-            const init = this.parseExpr()
-            this.expect(";", "after a declaration")
+            // A local declared without a value holds zero, or false, until it
+            // is assigned: the same on every backend, where HLSL leaves it
+            // undefined.
+            let init: Expr
+            if (this.eat(";")) {
+                init = zeroOf(type, name)
+            } else {
+                this.expect("=", `after ${name.text}, or ";" to declare it holding zero`)
+                init = this.parseExpr()
+                this.expect(";", "after a declaration")
+            }
             return { k: "var", type, name: name.text, init, pos: t }
         }
 
+        const s = this.parseSimple(t)
+        this.expect(";", "after an assignment")
+        return s
+    }
+
+    /**
+     * An assignment, or `x++`, `++x`, `x--`, `--x`, with no semicolon: a
+     * statement's body, and a for loop's update.
+     */
+    private parseSimple(t: Token): Extract<Stmt, { k: "assign" }> {
+        const one = (at: Token): Expr => ({ k: "num", value: 1, whole: true, pos: at })
+        if (t.text === "++" || t.text === "--") {
+            this.next()
+            const target = this.parseUnary()
+            return { k: "assign", target, op: t.text === "++" ? "+=" : "-=", value: one(t), pos: t }
+        }
         const target = this.parseExpr()
         const op = this.peek()
         if (op.kind === "punct" && ASSIGN_OPS.has(op.text)) {
             this.next()
             const value = this.parseExpr()
-            this.expect(";", "after an assignment")
             return { k: "assign", target, op: op.text as AssignOp, value, pos: t }
         }
         if (op.text === "++" || op.text === "--") {
-            this.fail(`${op.text} is only a for loop's update; write \`x = x + 1;\``, op)
+            this.next()
+            return { k: "assign", target, op: op.text === "++" ? "+=" : "-=", value: one(op), pos: t }
         }
         this.fail(
             "this statement has no effect. A statement is a declaration, an assignment, an if, a " +
-            "for or a return",
+            "loop, a switch or a return",
             t,
         )
     }
@@ -423,63 +455,86 @@ class Parser {
     }
 
     /**
-     * `for (int i = A; i < B; i++)`, and nothing more exotic than `i += K`.
-     *
-     * The shape is narrow because the loop UNROLLS: the counter is a compile
-     * time number, not a value, and every form this refuses is one where it
-     * could not be. Section 3.6 of the spec, and the error says so rather than
-     * leaving an author to guess which part offended.
+     * `for (int i = A; condition; update)`, where the update changes the
+     * counter: `i++`, `i--`, `i += k`, `i = i * 2`. The loop unrolls when its
+     * turns are known at build time and few, and is a real loop otherwise.
      */
     private parseFor(): Stmt {
         const kw = this.next()
         this.expect("(", "after for")
 
         const decl = this.peek()
-        if (decl.text !== "int" && decl.text !== "float") {
+        if (decl.kind !== "ident" || this.peek(1).kind !== "ident") {
             this.fail(
                 `a for loop starts by declaring its counter, as in \`for (int i = 0; i < 4; i++)\`, ` +
                 `got ${describe(decl)}`, decl,
             )
         }
-        this.next()
+        const type = this.expectType("the counter's type")
         const counter = this.expectName("a counter name")
         this.expect("=", "after the counter")
         const from = this.parseExpr()
         this.expect(";", "after the counter's start")
 
-        const lhs = this.expectIdent("the counter in the loop's condition")
-        if (lhs.text !== counter.text) {
-            this.fail(`this loop counts ${counter.text}, so its condition has to test ${counter.text}`, lhs)
-        }
-        const cmp = this.peek()
-        if (cmp.text !== "<" && cmp.text !== "<=") {
-            this.fail(
-                `a for loop counts up, so its condition is \`${counter.text} <\` or \`${counter.text} <=\`, ` +
-                `got ${describe(cmp)}`, cmp,
-            )
-        }
-        this.next()
-        const to = this.parseExpr()
-        this.expect(";", "after the loop's bound")
+        const cond = this.parseExpr()
+        this.expect(";", "after the loop's condition")
 
-        const up = this.expectIdent("the counter in the loop's update")
-        if (up.text !== counter.text) {
+        const up = this.peek()
+        const update = this.parseSimple(up)
+        const target = update.target.k === "ident" ? update.target.name : null
+        if (target !== counter.text) {
             this.fail(`this loop counts ${counter.text}, so its update has to change ${counter.text}`, up)
         }
-        let step: Expr = { k: "num", value: 1, pos: up }
-        if (this.eat("++")) {
-            // nothing: the step is 1
-        } else if (this.eat("+=")) {
-            step = this.parseExpr()
-        } else {
-            this.fail(
-                `a for loop's update is \`${counter.text}++\` or \`${counter.text} += n\`, got ` +
-                `${describe(this.peek())}`, this.peek(),
-            )
-        }
         this.expect(")", "after the loop's update")
         const body = this.parseBody()
-        return { k: "for", counter: counter.text, from, to, inclusive: cmp.text === "<=", step, body, pos: kw }
+        return { k: "for", type, counter: counter.text, from, cond, update, body, pos: kw }
+    }
+
+    private parseWhile(): Stmt {
+        const kw = this.next()
+        this.expect("(", "after while")
+        const cond = this.parseExpr()
+        this.expect(")", "after a while condition")
+        const body = this.parseBody()
+        return { k: "while", cond, body, pos: kw }
+    }
+
+    /**
+     * `switch (x) { case 0: ... break; case 1: case 2: ... return c; default: ... }`.
+     *
+     * Cases never fall through. Labels stack, and each group of them ends in a
+     * break, a return or a continue, which the checker holds it to; the closing
+     * break is dropped here, since leaving the switch is all it says.
+     */
+    private parseSwitch(): Stmt {
+        const kw = this.next()
+        this.expect("(", "after switch")
+        const value = this.parseExpr()
+        this.expect(")", "after the switch's value")
+        this.expect("{", "to open the switch's cases")
+        const cases: SwitchCase[] = []
+        while (!this.at("}")) {
+            const t = this.peek()
+            if (t.kind === "eof") this.fail("this switch is never closed", t)
+            if (t.text !== "case" && t.text !== "default") {
+                this.fail(`a switch holds cases, as in \`case 0: ... break;\`, got ${describe(t)}`, t)
+            }
+            const labels: Array<Expr | null> = []
+            while (this.at("case") || this.at("default")) {
+                if (this.next().text === "case") labels.push(this.parseExpr())
+                else labels.push(null)
+                this.expect(":", "after a case label")
+            }
+            const body: Stmt[] = []
+            while (!this.at("case") && !this.at("default") && !this.at("}")) {
+                if (this.peek().kind === "eof") this.fail("this switch is never closed", this.peek())
+                const s = this.recover(() => this.parseStmt(), "statement")
+                if (s !== null) body.push(s)
+            }
+            cases.push({ labels, body, closed: dropClosingBreak(body), pos: t })
+        }
+        this.next()
+        return { k: "switch", value, cases, pos: kw }
     }
 
     // MARK: expressions
@@ -511,12 +566,12 @@ class Parser {
 
     private parseUnary(): Expr {
         const t = this.peek()
-        if (t.kind === "punct" && (t.text === "-" || t.text === "+" || t.text === "!")) {
+        if (t.kind === "punct" && (t.text === "-" || t.text === "+" || t.text === "!" || t.text === "~")) {
             this.next()
             return { k: "unary", op: t.text, arg: this.parseUnary(), pos: t }
         }
         if (t.text === "++" || t.text === "--") {
-            this.fail(`${t.text} is only a for loop's update`, t)
+            this.fail(`${t.text} changes a local, so it is a statement of its own, \`i++;\`, and not part of an expression`, t)
         }
         return this.parsePostfix(this.parsePrimary())
     }
@@ -551,7 +606,10 @@ class Parser {
 
     private parsePrimary(): Expr {
         const t = this.next()
-        if (t.kind === "number") return { k: "num", value: t.value!, pos: t }
+        if (t.kind === "number") return t.unsigned === true
+            ? { k: "num", value: t.value!, whole: true, unsigned: true, pos: t }
+            : { k: "num", value: t.value!, whole: t.whole === true, pos: t }
+        if (t.text === "true" || t.text === "false") return { k: "bool", value: t.text === "true", 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") {
@@ -566,6 +624,26 @@ class Parser {
     }
 }
 
+/** What a local declared without a value holds: zero in each component, or false. */
+function zeroOf(type: TypeName, at: Pos): Expr {
+    if (type === "bool") return { k: "bool", value: false, pos: at }
+    return { k: "num", value: 0, whole: type === "int" || type === "uint", unsigned: type === "uint" || undefined, pos: at }
+}
+
+/**
+ * Whether a case's body ends in the break that closes it, which is dropped,
+ * since leaving the switch is all it says. The break may be the last thing
+ * inside braces that are the case's last statement, as in `case 0: { ...; break; }`.
+ */
+function dropClosingBreak(body: Stmt[]): boolean {
+    const last = body.at(-1)
+    if (last?.k === "break") {
+        body.pop()
+        return true
+    }
+    return last?.k === "block" && dropClosingBreak(last.body)
+}
+
 function describe(t: Token): string {
     if (t.kind === "eof") return "the end of the file"
     return `"${t.text}"`

package/src/lang/words.ts

@@ -9,12 +9,11 @@
 
 import { TYPE_WIDTH, type TypeName } from "./ast"
 
-/**
- * Declaration and statement words. `int` is here rather than among the types
- * because it is only ever a for loop's counter, `for (int i = 0; i < 4; i++)`;
- * a value cannot be declared as one.
- */
-export const SL_KEYWORDS = ["uniform", "texture2D", "const", "if", "else", "for", "return", "int"] as const
+/** Declaration and statement words, and the two bool literals. */
+export const SL_KEYWORDS = [
+    "uniform", "texture2D", "const", "if", "else", "for", "while", "break", "continue", "switch", "case", "default",
+    "return", "true", "false",
+] as const
 
 /** The types a value, a uniform or a function can have. */
 export const SL_TYPES = Object.keys(TYPE_WIDTH) as readonly TypeName[]

package/src/ops.ts

@@ -49,6 +49,9 @@ export const SLOP = {
     UNIFORM: 2,
     COMPOSE: 3,   // build a wider value from narrower parts
     SWIZZLE: 4,
+    // To the node's kind (a float when it has none) from the operand's: a
+    // float to an int truncates toward zero, held to the int's range (IR 4).
+    CAST: 5,
 
     // Arithmetic
     ADD: 16,
@@ -59,6 +62,23 @@ export const SLOP = {
     POW: 21,
     NEG: 22,
     RECIP: 23,
+    // IR 4: comparisons give a bool; logic takes and gives bools; the bitwise
+    // ops take ints or uints. ADD to NEG take ints as well, by the node's kind.
+    LT: 24,
+    LE: 25,
+    GT: 26,
+    GE: 27,
+    EQ: 28,
+    NE: 29,
+    AND: 30,
+    OR: 31,
+    NOT: 32,
+    BIT_AND: 33,
+    BIT_OR: 34,
+    BIT_XOR: 35,
+    BIT_NOT: 36,
+    SHL: 37,
+    SHR: 38,
 
     // Maths
     SIN: 48,
@@ -95,6 +115,8 @@ export const SLOP = {
     SMOOTHSTEP: 98,
     SELECT: 99,
     REMAP: 100,
+    // `c ? a : b` on a bool, for values SELECT's arithmetic cannot carry (IR 4).
+    CHOOSE: 101,
 
     // Colour
     RAMP: 112,
@@ -137,7 +159,11 @@ export type SLOpCode = (typeof SLOP)[keyof typeof SLOP]
  */
 export const SL_ARITY: Record<number, number> = {
     [SLOP.CONST]: 0, [SLOP.INPUT]: 0, [SLOP.UNIFORM]: 0,
-    [SLOP.COMPOSE]: -1, [SLOP.SWIZZLE]: 1,
+    [SLOP.COMPOSE]: -1, [SLOP.SWIZZLE]: 1, [SLOP.CAST]: 1,
+    [SLOP.LT]: 2, [SLOP.LE]: 2, [SLOP.GT]: 2, [SLOP.GE]: 2, [SLOP.EQ]: 2, [SLOP.NE]: 2,
+    [SLOP.AND]: 2, [SLOP.OR]: 2, [SLOP.NOT]: 1,
+    [SLOP.BIT_AND]: 2, [SLOP.BIT_OR]: 2, [SLOP.BIT_XOR]: 2, [SLOP.BIT_NOT]: 1, [SLOP.SHL]: 2, [SLOP.SHR]: 2,
+    [SLOP.CHOOSE]: 3,
 
     [SLOP.ADD]: 2, [SLOP.SUB]: 2, [SLOP.MUL]: 2, [SLOP.DIV]: 2,
     [SLOP.MOD]: 2, [SLOP.POW]: 2, [SLOP.NEG]: 1, [SLOP.RECIP]: 1,
@@ -156,8 +182,10 @@ export const SL_ARITY: Record<number, number> = {
 
     [SLOP.RAMP]: -1, [SLOP.HSV2RGB]: 1, [SLOP.RGB2HSV]: 1, [SLOP.LUMINANCE]: 1, [SLOP.TO_LINEAR]: 1,
 
-    [SLOP.NOISE]: 1, [SLOP.SIMPLEX]: 1, [SLOP.FBM]: 1, [SLOP.SDF]: 1,
-    [SLOP.VORONOI]: 1, [SLOP.TURBULENCE]: 1, [SLOP.RIDGED]: 1,
+    // An SDF takes the point, or the point and its parameters as operands; an
+    // octave op the point, or the point and its count (`formProblem` in ir.ts).
+    [SLOP.NOISE]: 1, [SLOP.SIMPLEX]: 1, [SLOP.FBM]: -1, [SLOP.SDF]: -1,
+    [SLOP.VORONOI]: 1, [SLOP.TURBULENCE]: -1, [SLOP.RIDGED]: -1,
 
     [SLOP.SAMPLE]: 1, [SLOP.SAMPLE_LOD]: 2,
 }
@@ -206,6 +234,23 @@ export const SL_HLSL: Record<number, SLSurface> = {
     [SLOP.UNIFORM]: { syntax: "uniform <type> name = <default>;" },
     [SLOP.COMPOSE]: { syntax: "float2(), float3(), float4()" },
     [SLOP.SWIZZLE]: { syntax: ".xyzw / .rgba" },
+    [SLOP.CAST]: { syntax: "int(), uint(), float(), bool()" },
+    [SLOP.LT]: { syntax: "<" },
+    [SLOP.LE]: { syntax: "<=" },
+    [SLOP.GT]: { syntax: ">" },
+    [SLOP.GE]: { syntax: ">=" },
+    [SLOP.EQ]: { syntax: "==" },
+    [SLOP.NE]: { syntax: "!=" },
+    [SLOP.AND]: { syntax: "&&" },
+    [SLOP.OR]: { syntax: "||" },
+    [SLOP.NOT]: { syntax: "!" },
+    [SLOP.BIT_AND]: { syntax: "&" },
+    [SLOP.BIT_OR]: { syntax: "|" },
+    [SLOP.BIT_XOR]: { syntax: "^" },
+    [SLOP.BIT_NOT]: { syntax: "~" },
+    [SLOP.SHL]: { syntax: "<<" },
+    [SLOP.SHR]: { syntax: ">>" },
+    [SLOP.CHOOSE]: { syntax: "?: on a bool" },
 
     [SLOP.ADD]: { syntax: "+" },
     [SLOP.SUB]: { syntax: "-" },
@@ -282,7 +327,6 @@ export const SL_HLSL: Record<number, SLSurface> = {
  */
 export const SL_UNIMPLEMENTED: Record<number, string> = {
     [SLOP.RGB2HSV]: "no backend has a case for it yet",
-    [SLOP.SAMPLE_LOD]: "no backend samples at an explicit LOD yet; use tex2D",
     [SLOP.REMAP]: "the surface form is a macro over arithmetic, so the opcode is unused",
 }
 

package/src/params.ts

@@ -54,6 +54,7 @@ const INTRINSIC: Record<string, readonly string[]> = {
     distance: ["x", "y"], dot: ["x", "y"], cross: ["x", "y"], reflect: ["i", "n"],
     lerp: ["x", "y", "s"], step: ["y", "x"], smoothstep: ["min", "max", "x"],
     tex2D: ["s", "t"],
+    tex2Dlod: ["s", "t", "lod"],
 }
 
 /**
@@ -161,6 +162,7 @@ export const BUILTIN_DOCS: Readonly<Record<string, string>> = {
     turbulence: "Simplex creases layered in octaves, 1 to 4: fire, smoke, marble.",
     ridged: "Turbulence made bright at its creases: ridges, lightning, cracks.",
     tex2D: "The colour of texture s at the uv t, with straight alpha.",
+    tex2Dlod: "The colour of texture s at the uv t from mip level lod: 0 is the full size, 1 half, and so on.",
     sdf: "The signed distance from p to a shape, negative inside: `sdf.circle(p, r)`.",
     ramp: "t mapped through evenly spaced colour stops, from the first at 0 to the last at 1.",
 }

package/src/serial.ts

@@ -9,14 +9,16 @@
  * older one is migrated to this one and rehashed under it.
  */
 import {
-    INPUTS, SLError, SL_IR_VERSION, TYPE, checkCaps, controlOf, controlProblem, hashProgram,
-    type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
+    INPUTS, SLError, SL_HASH_VERSION, SL_IR_VERSION, TYPE, checkCaps, controlOf, controlProblem, formProblem, hashProgram,
+    programVersion, type NodeRef, type Program, type SLNode, type SLType, type TextureDecl, type UniformDecl,
 } from "./ir"
-import { SL_ARITY, SL_NAME } from "./ops"
+import { SLOP, SL_ARITY, SL_NAME } from "./ops"
 
 export interface ProgramJSON {
     /** `SL_IR_VERSION` of the writer. Absent means 1. */
     v: number
+    /** `SL_HASH_VERSION` of the writer, which `hash` was computed under. Absent means 1. */
+    h?: number
     nodes: SLNode[]
     result: NodeRef
     uniforms: UniformDecl[]
@@ -25,7 +27,10 @@ export interface ProgramJSON {
 }
 
 export function toJSON(p: Program): ProgramJSON {
-    return { v: p.version, nodes: p.nodes, result: p.result, uniforms: p.uniforms, textures: p.textures, hash: p.hash }
+    return {
+        v: p.version, h: SL_HASH_VERSION, nodes: p.nodes, result: p.result, uniforms: p.uniforms, textures: p.textures,
+        hash: p.hash,
+    }
 }
 
 export function fromJSON(json: unknown): Program {
@@ -38,29 +43,107 @@ export function fromJSON(json: unknown): Program {
             `Update onejs-sl to read it, or rebuild it from its .sl source.`)
     }
     if (!Array.isArray(j.nodes) || j.nodes.length === 0) fail("it has no nodes")
-    const nodes = j.nodes.map((n, i) => node(n, i))
-    const result = j.result
-    if (!Number.isInteger(result) || result! < 0 || result! >= nodes.length) fail(`its result ${String(result)} is not a node`)
-    if (nodes[result!]!.type !== TYPE.VEC4) fail("its result is not a float4")
+    const written = j.nodes.map((n, i) => node(n, i))
+    if (!Number.isInteger(j.result) || j.result! < 0 || j.result! >= written.length) {
+        fail(`its result ${String(j.result)} is not a node`)
+    }
+    // The lowest version that has these nodes, which is what the writer
+    // recorded unless the file predates version 2 (whose nodes version 2 reads
+    // as they are) or was edited. One that claims less than its nodes need
+    // holds something its version never had, and a version 1 file has
+    // nothing IR 3 added.
+    const needs = programVersion(written, j.result!)
+    if (v < needs && (v >= 2 || needs >= 3)) fail(`it says IR version ${v} and holds nodes version ${needs} added; it was changed after it was written`)
+    const { nodes, result } = v < 3 ? toOperands(written, j.result!) : { nodes: written, result: j.result! }
+    nodes.forEach((n, i) => {
+        const problem = n.k === "call" ? formProblem(n, nodes) : null
+        if (problem !== null) fail(`node ${i} is not a form its op has: ${problem}`)
+    })
+    const out = nodes[result]!
+    if (out.k === "if" || out.k === "loop" || out.type !== TYPE.VEC4 || out.kind !== undefined) fail("its result is not a float4")
     const uniforms = (j.uniforms ?? []).map(uniform)
     const textures = (j.textures ?? []).map(texture)
     checkCaps({ uniforms, textures })
     for (const n of nodes) {
         if (n.k === "uniform" && n.slot >= uniforms.length) fail(`a node reads uniform slot ${n.slot}, which is not declared`)
     }
-    const hash = hashProgram(nodes, result!, uniforms, textures)
-    // Same version, so the same maths and the same hash; a different one means
-    // the file was edited or damaged, and its cached shader belongs to
-    // something else. An older version is rehashed under this one on purpose.
-    if (v === SL_IR_VERSION && j.hash !== undefined && j.hash !== hash) {
+    const version = programVersion(nodes, result)
+    const hash = hashProgram(nodes, result, uniforms, textures)
+    // The same IR version and hash scheme, so the same hash; a different one
+    // means the file was edited or damaged, and its cached shader belongs to
+    // something else. A file an older version or scheme wrote is rehashed under
+    // this one on purpose.
+    if (v === version && (j.h ?? 1) === SL_HASH_VERSION && j.hash !== undefined && j.hash !== hash) {
         fail(`its hash ${j.hash} does not match its nodes (${hash}); it was changed after it was written`)
     }
-    return { version: SL_IR_VERSION, nodes, result: result!, uniforms, textures, hash }
+    return { version, nodes, result, uniforms, textures, hash }
+}
+
+/**
+ * A graph written before IR 3, with the forms it had then moved to the one each
+ * op has now: an sdf's shape parameters after its id and an octave op's count
+ * were immediates, and are operands. Each constant goes in just before the
+ * call that reads it, and every later reference moves along.
+ */
+function toOperands(written: readonly SLNode[], writtenResult: NodeRef): { nodes: SLNode[]; result: NodeRef } {
+    const nodes: SLNode[] = []
+    const at: NodeRef[] = []
+    const constant = (type: SLType, v: number[]): NodeRef => nodes.push({ k: "const", type, v }) - 1
+    written.forEach((n, i) => {
+        const imm = n.k === "call" ? n.imm ?? [] : []
+        if (n.k === "call" && n.op === SLOP.SDF && n.args.length === 1) {
+            if (imm.length < 5) fail(`node ${i} is an sdf with ${imm.length} immediates; one written before IR 3 has at least 5`)
+            const q = constant(TYPE.VEC4, [imm[1]!, imm[2]!, imm[3]!, imm[4]!])
+            const r = constant(TYPE.VEC2, [imm[5] ?? 0, imm[6] ?? 0])
+            at[i] = nodes.push({ ...n, args: [at[n.args[0]!]!, q, r], imm: [imm[0]!] }) - 1
+            return
+        }
+        const octaves = n.k === "call" && (n.op === SLOP.FBM || n.op === SLOP.TURBULENCE || n.op === SLOP.RIDGED)
+        if (octaves && n.args.length === 1) {
+            if (imm.length < 1) fail(`node ${i} is ${SL_NAME[n.op]} with no octave count`)
+            const count = constant(TYPE.FLOAT, [imm[0]!])
+            at[i] = nodes.push({ ...n, args: [at[n.args[0]!]!, count], imm: imm.slice(1) }) - 1
+            return
+        }
+        const moved: SLNode = n.k === "call" ? { ...n, args: n.args.map((a) => at[a]!) }
+            : n.k === "swizzle" ? { ...n, src: at[n.src]! } : n
+        at[i] = nodes.push(moved) - 1
+    })
+    return { nodes, result: at[writtenResult]! }
 }
 
 function node(n: unknown, i: number): SLNode {
     if (typeof n !== "object" || n === null) fail(`node ${i} is not an object`)
     const x = n as Record<string, unknown>
+    const refs = (a: unknown, what: string): NodeRef[] => {
+        if (!Array.isArray(a) || !a.every((r) => Number.isInteger(r) && r >= 0 && r < i)) fail(`node ${i}'s ${what} do not all refer to earlier nodes`)
+        return a as number[]
+    }
+    const whole = (v: unknown, what: string): number => {
+        if (!Number.isInteger(v) || (v as number) < 0) fail(`node ${i}'s ${what} is not a whole number`)
+        return v as number
+    }
+    // IR 4's control nodes carry no type of their own.
+    if (x.k === "if") {
+        const [cond, then, otherwise] = [refs([x.cond], "condition")[0]!, refs(x.then, "then results"), refs(x.else, "else results")]
+        if (then.length !== otherwise.length) fail(`node ${i} is an if whose two sides give different numbers of results`)
+        return { k: "if", cond, then, else: otherwise }
+    }
+    if (x.k === "loop") {
+        const init = refs(x.init, "starting values"), next = refs(x.next, "next values")
+        if (init.length !== next.length) fail(`node ${i} is a loop whose next values do not match its starting values`)
+        if (!Number.isInteger(x.max) || (x.max as number) < 1) fail(`node ${i} is a loop with no turn limit`)
+        return { k: "loop", id: whole(x.id, "loop id"), init, cond: refs([x.cond], "condition")[0]!, next, max: x.max as number }
+    }
+    const kind = x.kind
+    if (kind !== undefined && kind !== "int" && kind !== "uint" && kind !== "bool") fail(`node ${i} holds a "${String(kind)}", which is not a kind`)
+    const withKind = <T extends SLNode>(v: T): T => (kind === undefined ? v : { ...v, kind })
+    if (x.k === "param" || x.k === "proj") {
+        const type = x.type
+        if (type !== 1 && type !== 2 && type !== 3 && type !== 4) fail(`node ${i} has no width 1 to 4`)
+        if (x.k === "param") return withKind({ k: "param", type: type as SLType, loop: whole(x.loop, "loop"), index: whole(x.index, "index") })
+        return withKind({ k: "proj", type: type as SLType, src: refs([x.src], "source")[0]!, index: whole(x.index, "index") })
+    }
     const type = x.type
     if (type !== 1 && type !== 2 && type !== 3 && type !== 4) fail(`node ${i} has no width 1 to 4`)
     const t = type as SLType
@@ -80,7 +163,7 @@ function node(n: unknown, i: number): SLNode {
         case "const": {
             const v = nums(x.v, "value")
             if (v.length !== t) fail(`node ${i} is a float${t === 1 ? "" : t} constant with ${v.length} values`)
-            return { k: "const", type: t, v }
+            return withKind({ k: "const", type: t, v })
         }
         case "input": {
             const name = x.name as keyof typeof INPUTS
@@ -96,7 +179,7 @@ function node(n: unknown, i: number): SLNode {
             if (chans.length !== t || !chans.every((c) => Number.isInteger(c) && c >= 0 && c <= 3)) {
                 fail(`node ${i}'s swizzle does not pick ${t} channels`)
             }
-            return { k: "swizzle", type: t, src: ref(x.src, "source"), chans }
+            return withKind({ k: "swizzle", type: t, src: ref(x.src, "source"), chans })
         }
         case "call": {
             const op = x.op as number
@@ -110,7 +193,7 @@ function node(n: unknown, i: number): SLNode {
             if (arity !== undefined && arity >= 0 && args.length !== arity) {
                 fail(`node ${i} calls ${SL_NAME[op]} with ${args.length} arguments; it takes ${arity}`)
             }
-            const out: SLNode = { k: "call", type: t, op: op as never, args }
+            const out: SLNode = withKind({ k: "call", type: t, op: op as never, args })
             if (x.imm !== undefined) out.imm = nums(x.imm, "immediates")
             return out
         }