onejs-sl 0.1.0

package/src/hlsl.ts

@@ -0,0 +1,275 @@
+/**
+ * The second backend: prints a program as real HLSL, compiled at build time.
+ *
+ * Phase 3 of `Specs/SHADER_LANG.md` section 6, and the half the whole design
+ * exists for. Unity cannot compile a shader at runtime in a player build, so on
+ * play.onejs.com a program has to be interpreted. Ejecting to a Unity project
+ * does not change what the author wrote, it changes what is POSSIBLE, because
+ * an editor compiles shaders at build time.
+ *
+ * So the same source is interpreted in the browser and compiled after an eject,
+ * with no edit in between. That is what stops "Play games eject cleanly" from
+ * quietly acquiring an asterisk.
+ *
+ * WHY THIS IS THE EASY BACKEND. The VM keeps every value in a float4 register
+ * and has to be told how wide each one really is. Here the IR's types become the
+ * HLSL types directly, so `float2` is a `float2` and nothing needs padding or
+ * explaining. One local per node also gives common subexpression elimination for
+ * free: a node is emitted once no matter how many nodes reference it.
+ *
+ * The generated names are `n<index>` and are unreadable on purpose. Generated
+ * code that looks hand written invites hand editing, and a hand edit is lost the
+ * next time it is generated.
+ */
+
+import { SLError, TYPE, type Program, type SLNode, type SLType } from "./ir"
+import { INPUT_ID, SLOP } from "./ops"
+
+const HLSL_TYPE: Record<SLType, string> = { 1: "float", 2: "float2", 3: "float3", 4: "float4" }
+
+/** A literal that survives a float32 round trip and never reads as an int. */
+function lit(n: number): string {
+    if (!Number.isFinite(n)) throw new SLError(`cannot emit ${n} as a shader literal`)
+    const s = Number.isInteger(n) ? n.toFixed(1) : String(n)
+    return s
+}
+
+function ctor(type: SLType, parts: string[]): string {
+    return type === TYPE.FLOAT ? parts[0] : `${HLSL_TYPE[type]}(${parts.join(", ")})`
+}
+
+const SWZ = "xyzw"
+
+/** The property name a uniform gets. Prefixed so it cannot collide with ours. */
+export function uniformProperty(name: string): string {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new SLError(`uniform "${name}" is not a usable shader property name`)
+    }
+    return "_u_" + name
+}
+
+export interface EmitOptions {
+    /** Shader name. Defaults to a name derived from the program hash. */
+    name?: string
+    /**
+     * Path used for the shared helpers include. Unity resolves this relative to
+     * the generated shader's own folder, so a generator writing somewhere other
+     * than beside SLCommon.cginc has to say where it went.
+     */
+    include?: string
+}
+
+/**
+ * Emits a complete `.shader` for a program.
+ *
+ * The shader's name carries the program hash, which is how the runtime finds it
+ * again. If that link breaks, the runtime silently falls back to the VM and
+ * nobody is told: correct output, quietly slow, no error. See `hashProgram`.
+ */
+export function emitShader(p: Program, options: EmitOptions = {}): string {
+    const name = options.name ?? `Hidden/SLGenerated/${p.hash}`
+    const include = options.include ?? "SLCommon.cginc"
+    const body = emitFragmentBody(p)
+
+    const props: string[] = [
+        `        _Secs ("Seconds", Float) = 0`,
+        `        _FlipY ("Flip Y", Float) = 0`,
+        `        _Res ("Target size", Vector) = (1, 1, 0, 0)`,
+    ]
+    const decls: string[] = [`            float _Secs;`, `            float _FlipY;`, `            float4 _Res;`]
+
+    for (const u of p.uniforms) {
+        const prop = uniformProperty(u.name)
+        // Declared as a float4 whatever its width, so the host sets uniforms the
+        // same way for every program and a widening edit does not change the
+        // binding. The body swizzles down to the width the program uses.
+        const d = [u.value[0] ?? 0, u.value[1] ?? 0, u.value[2] ?? 0, u.value[3] ?? 1]
+        props.push(`        ${prop} ("${u.name}", Vector) = (${d.map(lit).join(", ")})`)
+        decls.push(`            float4 ${prop};`)
+    }
+    for (const t of p.textures) {
+        props.push(`        _Tex${t.slot} ("${t.name}", 2D) = "white" {}`)
+        decls.push(`            sampler2D _Tex${t.slot};`)
+    }
+
+    return `// GENERATED from a shader language program. Do not edit.
+//
+// Source of truth is the program this was emitted from; edits here are lost the
+// next time it is generated. The name carries the program hash, which is how the
+// runtime pairs the two. See Specs/SHADER_LANG.md section 6.
+Shader "${name}"
+{
+    Properties
+    {
+${props.join("\n")}
+    }
+
+    SubShader
+    {
+        Cull Off ZWrite Off ZTest Always
+        Pass
+        {
+            CGPROGRAM
+            #pragma vertex vert
+            #pragma fragment frag
+            #pragma target 3.0
+            #include "UnityCG.cginc"
+            // Shared with the VM, so both backends compute the same noise.
+            #include "${include}"
+
+${decls.join("\n")}
+
+            struct appdata { float4 vertex : POSITION; float2 uv : TEXCOORD0; };
+            struct v2f { float4 pos : SV_POSITION; float2 uv : TEXCOORD0; };
+
+            v2f vert(appdata v)
+            {
+                v2f o;
+                o.pos = UnityObjectToClipPos(v.vertex);
+                // Origin corrected here exactly as the VM does it, so an ejected
+                // game is not upside down relative to the one on the site.
+                o.uv = float2(v.uv.x, lerp(v.uv.y, 1.0 - v.uv.y, _FlipY));
+                return o;
+            }
+
+            fixed4 frag(v2f i) : SV_Target
+            {
+${body}
+            }
+            ENDCG
+        }
+    }
+}
+`
+}
+
+/** The straight line body: one local per reachable node, in order. */
+export function emitFragmentBody(p: Program): string {
+    const lines: string[] = []
+    const name = (ref: number) => `n${ref}`
+    const emitted = new Set<number>()
+
+    const walk = (ref: number): void => {
+        if (emitted.has(ref)) return
+        const n = p.nodes[ref]
+        const deps = n.k === "swizzle" ? [n.src] : n.k === "call" ? n.args : []
+        for (const d of deps) walk(d)
+        emitted.add(ref)
+        lines.push(`                ${HLSL_TYPE[n.type]} ${name(ref)} = ${expr(n, name, p)};`)
+    }
+    walk(p.result)
+    lines.push(`                return ${name(p.result)};`)
+    return lines.join("\n")
+}
+
+function expr(n: SLNode, name: (r: number) => string, p: Program): string {
+    switch (n.k) {
+        case "const":
+            return ctor(n.type, n.v.map(lit))
+        case "input": {
+            // `_Res` is the TARGET's size, set by the host, not `_ScreenParams`.
+            //
+            // A program is drawn with Graphics.Blit into the element's own
+            // render texture, and Unity leaves _ScreenParams at whatever the
+            // last camera set: blitting into a 64x256 target reads it as the
+            // game view's 1737x1226. So `resolution` and `fragCoord` were the
+            // window's and `aspect` was the window's ratio, identically wrong
+            // on both backends, which is why nothing caught it. Aspect
+            // correction, the thing `aspect` exists for, stretched every
+            // circle by the shape of the window it happened to be in.
+            switch (INPUT_ID[n.name]) {
+                case 0: return "i.uv"
+                case 1: return "i.uv * _Res.xy"
+                case 2: return "_Res.xy"
+                case 3: return "_Secs"
+                default: return "(_Res.x / max(_Res.y, 1.0))"
+            }
+        }
+        case "uniform": {
+            const u = p.uniforms[n.slot]
+            const prop = uniformProperty(u.name)
+            return n.type === TYPE.VEC4 ? prop : `${prop}.${SWZ.slice(0, n.type)}`
+        }
+        case "swizzle":
+            return `${name(n.src)}.${n.chans.map((c) => SWZ[c]).join("")}`
+        case "call":
+            return call(n, name)
+    }
+}
+
+function call(n: Extract<SLNode, { k: "call" }>, name: (r: number) => string): string {
+    const a = n.args.map(name)
+    const imm = n.imm ?? []
+    switch (n.op) {
+        case SLOP.COMPOSE: return ctor(n.type, a)
+
+        case SLOP.ADD: return `(${a[0]} + ${a[1]})`
+        case SLOP.SUB: return `(${a[0]} - ${a[1]})`
+        case SLOP.MUL: return `(${a[0]} * ${a[1]})`
+        case SLOP.DIV: return `(${a[0]} / ${a[1]})`
+        case SLOP.MOD: return `fmod(${a[0]}, ${a[1]})`
+        // abs on the base, matching the VM. pow of a negative base is undefined
+        // in HLSL and the two backends must be undefined in the same direction.
+        case SLOP.POW: return `pow(abs(${a[0]}), ${a[1]})`
+        case SLOP.NEG: return `(-${a[0]})`
+        case SLOP.RECIP: return `(1.0 / ${a[0]})`
+
+        case SLOP.SIN: return `sin(${a[0]})`
+        case SLOP.COS: return `cos(${a[0]})`
+        case SLOP.TAN: return `tan(${a[0]})`
+        case SLOP.ASIN: return `asin(clamp(${a[0]}, -1, 1))`
+        case SLOP.ACOS: return `acos(clamp(${a[0]}, -1, 1))`
+        case SLOP.ATAN2: return `atan2(${a[0]}, ${a[1]})`
+        case SLOP.EXP: return `exp(${a[0]})`
+        case SLOP.LOG: return `log(max(${a[0]}, 1e-8))`
+        case SLOP.SQRT: return `sqrt(max(${a[0]}, 0))`
+        case SLOP.ABS: return `abs(${a[0]})`
+        case SLOP.SIGN: return `sign(${a[0]})`
+        case SLOP.FLOOR: return `floor(${a[0]})`
+        case SLOP.CEIL: return `ceil(${a[0]})`
+        case SLOP.ROUND: return `round(${a[0]})`
+        case SLOP.FRACT: return `frac(${a[0]})`
+        case SLOP.MIN: return `min(${a[0]}, ${a[1]})`
+        case SLOP.MAX: return `max(${a[0]}, ${a[1]})`
+        case SLOP.CLAMP: return `clamp(${a[0]}, ${a[1]}, ${a[2]})`
+        case SLOP.SATURATE: return `saturate(${a[0]})`
+
+        case SLOP.LENGTH: return `length(${a[0]})`
+        case SLOP.DISTANCE: return `distance(${a[0]}, ${a[1]})`
+        case SLOP.DOT: return `dot(${a[0]}, ${a[1]})`
+        case SLOP.CROSS: return `cross(${a[0]}, ${a[1]})`
+        case SLOP.NORMALIZE: return `normalize(${a[0]})`
+        case SLOP.REFLECT: return `reflect(${a[0]}, ${a[1]})`
+        case SLOP.LUMINANCE: return `sl_luminance(${a[0]}.rgb)`
+        case SLOP.TO_LINEAR: return `sl_toLinear(${a[0]})`
+
+        case SLOP.MIX: return `lerp(${a[0]}, ${a[1]}, ${a[2]})`
+        case SLOP.STEP: return `step(${a[0]}, ${a[1]})`
+        case SLOP.SMOOTHSTEP: return `smoothstep(${a[0]}, ${a[1]}, ${a[2]})`
+        // Matches the VM exactly, branchlessly, rather than using an if. Two
+        // backends that pick differently here disagree on every edge value.
+        case SLOP.SELECT: return `lerp(${a[2]}, ${a[1]}, step(0.5, ${a[0]}))`
+
+        case SLOP.HSV2RGB: return `sl_hsv2rgb(${a[0]})`
+        case SLOP.NOISE: return `sl_valueNoise(${a[0]})`
+        case SLOP.SIMPLEX: return `sl_simplex(${a[0]})`
+        case SLOP.FBM: return `sl_fbm(${a[0]}, ${Math.round(imm[0] ?? 3)}, ${Math.round(imm[1] ?? 0)})`
+        case SLOP.TURBULENCE: return `sl_fbm(${a[0]}, ${Math.round(imm[0] ?? 3)}, 2)`
+        case SLOP.RIDGED: return `sl_fbm(${a[0]}, ${Math.round(imm[0] ?? 3)}, 3)`
+        case SLOP.SDF: {
+            const id = Math.round(imm[0] ?? 0)
+            const q = [imm[1] ?? 0, imm[2] ?? 0, imm[3] ?? 0, imm[4] ?? 0].map(lit)
+            const r = [imm[5] ?? 0, imm[6] ?? 0].map(lit)
+            return `sl_sdfDistance(${id}, ${a[0]}, float4(${q.join(", ")}), float2(${r.join(", ")}))`
+        }
+        case SLOP.VORONOI: return `sl_voronoi(${a[0]})`
+        case SLOP.SAMPLE: return `tex2D(_Tex${Math.round(imm[0] ?? 0)}, ${a[0]})`
+
+        default:
+            throw new SLError(
+                `the HLSL emitter has no case for opcode ${n.op}. A program using it would silently ` +
+                `differ between the VM and a compiled build, which is the one failure this design ` +
+                `cannot tolerate.`,
+            )
+    }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * `onejs-sl`: the shader language, with no Unity in it.
+ *
+ * Source text or the TypeScript form in, a `Program` out: a flat typed graph
+ * with a hash. Everything a host does with a program (run it on the VM, emit
+ * HLSL, WGSL or GLSL ES) is a separate entry, so a host bundles only what it
+ * calls:
+ *
+ *   onejs-sl             this: parse, the TypeScript form, the IR, its JSON
+ *   onejs-sl/core        the same without the parser, for a game at run time
+ *   onejs-sl/tables      builtins, opcodes, inputs, shapes: what an editor reads
+ *   onejs-sl/limits      whether a program fits the VM, without encoding it
+ *   onejs-sl/vm          the VM encoder
+ *   onejs-sl/emit/unity  the ShaderLab shader a Unity editor generates
+ *   onejs-sl/emit/web    WGSL and GLSL ES with OneJS's web frame
+ *
+ * Plain TypeScript with no Node or DOM API anywhere, so it runs in a browser,
+ * a Cloudflare worker, and QuickJS; `npm run test:quickjs` holds it to that.
+ */
+export * from "./core"
+export {
+    analyze, parse, parseUnit, preludeFunctions, tokenize, PRELUDE_SOURCE, SLParseError,
+} from "./lang"
+export type { Checked, Expr, FuncDecl, ParseOptions, Pos, Stmt, Token, Unit } from "./lang"

package/src/ir.ts

@@ -0,0 +1,301 @@
+/**
+ * The shader language IR: one graph, two consumers.
+ *
+ * Phase 1 of `Specs/SHADER_LANG.md` section 4. Everything the VM encoder and the
+ * HLSL emitter do is a function of this shape, so it is the part worth getting
+ * right before either exists.
+ *
+ * Four properties are load bearing:
+ *
+ * **Every node carries its type.** Both backends need it and computing it twice
+ * is how they would disagree. It is inferred while recording, which is also what
+ * produces the author facing type errors.
+ *
+ * **Nodes are a flat array in topological order.** A node refers to earlier
+ * nodes by index only, never forwards, so an encoder can walk the array once and
+ * emit in order. The hash deliberately does NOT depend on that order; see
+ * `hashProgram`.
+ *
+ * **The graph is a DAG, not a tree.** `const p = ...` used twice is one node
+ * with two references, enforced here by hash consing rather than left to a later
+ * pass. A tree would silently square the cost of the most natural way to write a
+ * shader.
+ *
+ * **Nothing here knows about shaders.** No HLSL, no texture layout, no register
+ * allocation. Those belong to the backends; this file is the contract between
+ * them, and it is fully testable with no GPU.
+ */
+
+import { SLOP, SL_ARITY, SL_NAME, type SLOpCode } from "./ops"
+
+/** Component count. The only notion of type the IR has. */
+export const TYPE = { FLOAT: 1, VEC2: 2, VEC3: 3, VEC4: 4 } as const
+export type SLType = 1 | 2 | 3 | 4
+
+/** What a program is given per pixel. See section 3.4. */
+export const INPUTS = {
+    uv: TYPE.VEC2,
+    fragCoord: TYPE.VEC2,
+    resolution: TYPE.VEC2,
+    time: TYPE.FLOAT,
+    aspect: TYPE.FLOAT,
+} as const
+export type InputName = keyof typeof INPUTS
+
+/** Index into `Program.nodes`. Always refers backwards. */
+export type NodeRef = number
+
+export type SLNode =
+    | { k: "const"; type: SLType; v: number[] }
+    | { k: "input"; type: SLType; name: InputName }
+    | { k: "uniform"; type: SLType; slot: number }
+    | { k: "swizzle"; type: SLType; src: NodeRef; chans: number[] }
+    | { k: "call"; type: SLType; op: SLOpCode; args: NodeRef[]; imm?: number[] }
+
+export interface UniformDecl {
+    name: string
+    type: SLType
+    /** Default, used when a caller does not supply the uniform. */
+    value: number[]
+}
+
+export interface TextureDecl {
+    name: string
+    /** Sampler slot, assigned in declaration order. */
+    slot: number
+}
+
+/**
+ * The nodes one `sl.repeat` call unrolled into, as the half open range
+ * `[start, end)` of `nodes`. Diagnostic only: the instruction ceiling error
+ * uses it to say which loop the operations came from, since a program that is
+ * "too long" has usually been made so by one count.
+ */
+export interface LoopSpan {
+    count: number
+    start: NodeRef
+    end: NodeRef
+}
+
+export interface Program {
+    /** The `SL_IR_VERSION` this program's nodes mean what they mean under. */
+    version: number
+    nodes: SLNode[]
+    /** Must be VEC4: a program produces a colour. */
+    result: NodeRef
+    uniforms: UniformDecl[]
+    textures: TextureDecl[]
+    /** Canonical, stable across machines. See `hashProgram`. */
+    hash: string
+    /** Not part of the hash: it changes nothing about what the program computes. */
+    loops: LoopSpan[]
+}
+
+/**
+ * Sampler slots in a fragment shader on the WebGL2 baseline, minus one for the
+ * program texture itself. Exceeding it is refused when the program is written
+ * rather than when it is drawn, with a message naming the limit.
+ */
+export const MAX_TEXTURES = 15
+
+/** Instructions a single program may hold. Generous; the ceiling that matters is registers. */
+export const MAX_NODES = 4096
+
+export class SLError extends Error {
+    constructor(message: string) {
+        super("[onejs sl] " + message)
+        this.name = "SLError"
+    }
+}
+
+/**
+ * Records a graph. One per `program()` call.
+ *
+ * Hash consing happens here, at `add`, rather than as a later pass, because the
+ * author already told us what is shared when they wrote `const`. Recomputing it
+ * afterwards would be doing work to recover information we were handed.
+ */
+export class Builder {
+    readonly nodes: SLNode[] = []
+    readonly uniforms: UniformDecl[] = []
+    readonly textures: TextureDecl[] = []
+    readonly loops: LoopSpan[] = []
+    private readonly interned = new Map<string, NodeRef>()
+
+    add(node: SLNode): NodeRef {
+        if (this.nodes.length >= MAX_NODES) {
+            throw new SLError(`a program may hold at most ${MAX_NODES} operations`)
+        }
+        const key = keyOf(node)
+        const seen = this.interned.get(key)
+        if (seen !== undefined) return seen
+        const ref = this.nodes.push(node) - 1
+        this.interned.set(key, ref)
+        return ref
+    }
+
+    call(op: SLOpCode, type: SLType, args: NodeRef[], imm?: number[]): NodeRef {
+        const arity = SL_ARITY[op]
+        if (arity >= 0 && args.length !== arity) {
+            throw new SLError(`${SL_NAME[op]} takes ${arity} argument(s), got ${args.length}`)
+        }
+        for (const a of args) {
+            if (a < 0 || a >= this.nodes.length) {
+                throw new SLError(`${SL_NAME[op]} refers to a node that does not exist yet`)
+            }
+        }
+        return this.add(imm === undefined ? { k: "call", type, op, args } : { k: "call", type, op, args, imm })
+    }
+
+    constant(v: number[]): NodeRef {
+        for (const n of v) {
+            if (!Number.isFinite(n)) throw new SLError(`a constant must be finite, got ${n}`)
+        }
+        return this.add({ k: "const", type: v.length as SLType, v: v.slice() })
+    }
+
+    uniform(name: string, type: SLType, value: number[]): NodeRef {
+        const existing = this.uniforms.findIndex((u) => u.name === name)
+        if (existing >= 0) {
+            const u = this.uniforms[existing]
+            if (u.type !== type) {
+                throw new SLError(`uniform "${name}" is declared as both a ${widthName(u.type)} and a ${widthName(type)}`)
+            }
+            return this.add({ k: "uniform", type, slot: existing })
+        }
+        const slot = this.uniforms.length
+        this.uniforms.push({ name, type, value: value.slice() })
+        return this.add({ k: "uniform", type, slot })
+    }
+
+    texture(name: string): number {
+        const existing = this.textures.findIndex((t) => t.name === name)
+        if (existing >= 0) return this.textures[existing].slot
+        if (this.textures.length >= MAX_TEXTURES) {
+            throw new SLError(
+                `a program may sample at most ${MAX_TEXTURES} textures, and this one asks for ` +
+                `${this.textures.length + 1}. That ceiling is the fragment shader's sampler slots ` +
+                `on the WebGL2 baseline, so it cannot be widened.`,
+            )
+        }
+        const slot = this.textures.length
+        this.textures.push({ name, slot })
+        return slot
+    }
+}
+
+/** Structural key for hash consing. Order matters and is fixed by the node shape. */
+function keyOf(n: SLNode): string {
+    switch (n.k) {
+        case "const": return `c:${n.type}:${n.v.map(fixed).join(",")}`
+        case "input": return `i:${n.name}`
+        case "uniform": return `u:${n.slot}`
+        case "swizzle": return `s:${n.src}:${n.chans.join("")}`
+        case "call": return `f:${n.op}:${n.args.join(",")}:${(n.imm ?? []).map(fixed).join(",")}`
+    }
+}
+
+/**
+ * Constants at a fixed precision, so two constants that differ only in float
+ * noise intern to one node and, more importantly, hash the same on every
+ * machine. See `hashProgram` for why that matters.
+ */
+export function fixed(n: number): string {
+    return Object.is(n, -0) ? "0" : n.toPrecision(9)
+}
+
+export function widthName(t: SLType): string {
+    return t === 1 ? "float" : `vec${t}`
+}
+
+/**
+ * A canonical, machine independent hash of a program.
+ *
+ * This is the link between a program and its compiled shader. If it differs
+ * between the machine that generated the shader and the machine that runs it,
+ * the runtime silently falls back to the VM and nobody is told, which is the
+ * worst failure this design can have: correct output, quietly slow, no error.
+ *
+ * So it hashes the canonicalised node array and nothing else. Never object
+ * identity, never insertion order of a Map, never a JSON stringify whose key
+ * order is an implementation detail. Constants go through `fixed` so 0.1 + 0.2
+ * and 0.30000000000000004 do not produce different shaders.
+ *
+ * FNV-1a, because it needs to be stable and identical in TypeScript and in C#,
+ * not cryptographic.
+ */
+export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformDecl[], textures: TextureDecl[]): string {
+    // MERKLE, not a walk of the array in storage order.
+    //
+    // The first version hashed nodes[] front to back, which made the hash depend
+    // on the order the author happened to build things in. Hoisting a shared
+    // subexpression into a `const` moved a node earlier, changed the hash, and
+    // orphaned the program from a shader generated for it, without changing what
+    // the program computes. That is the exact failure this hash exists to
+    // prevent, so the fix is to hash the SHAPE and not the storage.
+    //
+    // Each node's digest is computed from its kind, its type and its children's
+    // digests, so two graphs that compute the same thing agree however they were
+    // assembled. It also ignores nodes not reachable from the result, which is
+    // correct: dead nodes generate no shader code.
+    const digest = new Map<NodeRef, string>()
+
+    const of = (ref: NodeRef): string => {
+        const seen = digest.get(ref)
+        if (seen !== undefined) return seen
+        const n = nodes[ref]
+        let body: string
+        switch (n.k) {
+            case "const": body = `c:${n.type}:${n.v.map(fixed).join(",")}`; break
+            case "input": body = `i:${n.name}`; break
+            // By slot rather than by name: the slot is what the generated shader
+            // lays out, so two programs whose uniforms differ only in name still
+            // produce different shaders and must not share a hash. The names go
+            // in separately below.
+            case "uniform": body = `u:${n.slot}:${n.type}`; break
+            case "swizzle": body = `s:${of(n.src)}:${n.chans.join("")}`; break
+            case "call": body = `f:${n.op}:${n.args.map(of).join(",")}:${(n.imm ?? []).map(fixed).join(",")}`; break
+        }
+        const d = fnv1a(body + "|" + n.type)
+        digest.set(ref, d)
+        return d
+    }
+
+    // The IR version is in the hash, so a change to what an opcode computes
+    // changes every hash and every cache keyed by one (an editor's generated
+    // shaders, Magerie's pipelines) recompiles rather than serving the old maths.
+    const parts: string[] = [`v${SL_HASH_VERSION}:${SL_IR_VERSION}`, of(result)]
+    for (const u of uniforms) parts.push(`U:${u.name}:${u.type}:${u.value.map(fixed).join(",")}`)
+    for (const t of textures) parts.push(`T:${t.name}:${t.slot}`)
+    return fnv1a(parts.join("|"))
+}
+
+/** Bumped when the hashing scheme changes, which invalidates generated shaders. */
+export const SL_HASH_VERSION = 1
+
+/**
+ * Bumped whenever the IR changes in a way a reader has to know about: a new
+ * opcode, a new shape, a change to what an existing opcode computes, or a
+ * change to the JSON shape (which also gets a migration in `fromJSON`).
+ *
+ * A reader accepts every version up to its own and refuses a newer one with a
+ * message naming both, the rule the particle wire and fx follow. Part of the
+ * hash, so a bump recompiles every cached shader.
+ *
+ *   1  the first versioned IR
+ *   2  an SDF call carries up to six shape parameters, not four (#129)
+ */
+export const SL_IR_VERSION = 2
+
+function fnv1a(s: string): string {
+    let h = 0x811c9dc5
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i)
+        // >>> 0 after each step: JS bitwise ops are signed 32 bit, and a C#
+        // implementation of the same hash must agree bit for bit.
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0
+    }
+    return h.toString(16).padStart(8, "0")
+}
+
+export { SLOP }