onejs-sl 0.1.0

package/src/sl.ts

@@ -0,0 +1,721 @@
+/**
+ * The authoring surface: a TypeScript EDSL that records a shader graph.
+ *
+ * Phase 1 of `Specs/SHADER_LANG.md` section 3. Calling a program function does
+ * not execute per pixel; it records a DAG once, at module load.
+ *
+ * Why an EDSL and not a text language: completion on every function, type errors
+ * at the call site, jump to definition, rename, and the author's existing editor,
+ * all for free. Monaco in the Play editor already has these types. A text syntax
+ * remains possible later and costs only a parser, because the parser would emit
+ * this same IR.
+ *
+ * It also gives common subexpression elimination for nothing, which is the most
+ * valuable optimisation here: a `const` in the host language IS the shared node.
+ *
+ *     const plasma = sl.program(({ uv, time }) => {
+ *         const p = uv.mul(8).add(time.mul(0.4))
+ *         const v = sl.sin(p.x).add(sl.sin(p.y))
+ *         return sl.vec4(v.mul(0.5).add(0.5), 0, 0, 1)
+ *     })
+ *
+ * `p` is written once and used twice, so it is one node with two references.
+ */
+
+import { parseColor as parseHex } from "./color"
+import {
+    Builder, INPUTS, SLError, SL_IR_VERSION, TYPE, hashProgram, widthName,
+    type InputName, type NodeRef, type Program, type SLNode, type SLType,
+} from "./ir"
+import { SLOP, type SLOpCode } from "./ops"
+import { SL_SDF_PARAMS, SL_SDF_SHAPES, type SlSdfKind } from "./shapes"
+
+// MARK: values
+
+type Swz = "x" | "y" | "z" | "w" | "r" | "g" | "b" | "a"
+const CHAN: Record<string, number> = { x: 0, y: 1, z: 2, w: 3, r: 0, g: 1, b: 2, a: 3 }
+
+/** Width of a swizzle string, at the type level, so `swz("wzyx")` is a Vec4. */
+type Widen<S extends string> =
+    S extends `${Swz}${Swz}${Swz}${Swz}` ? Vec4 :
+    S extends `${Swz}${Swz}${Swz}` ? Vec3 :
+    S extends `${Swz}${Swz}` ? Vec2 :
+    S extends `${Swz}` ? Float : never
+
+/** Anything acceptable where a value is expected. Plain numbers broadcast. */
+export type Num = Val | number
+
+/**
+ * A recorded value. One runtime class; the four exported types are TypeScript's
+ * view of it, which is where mixing a Vec2 with a Vec3 becomes an error at the
+ * call site rather than a black rectangle.
+ */
+// The `interface Val` further down declares the swizzle getters that the PAIRS
+// loop installs on this prototype. They exist at runtime, so the merge is the
+// point rather than a hazard; see the comment above that loop.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class Val {
+    constructor(readonly owner: Builder, readonly ref: NodeRef, readonly width: SLType) {}
+
+    // Arithmetic. Mixing a vector with a Float broadcasts, as in HLSL.
+    add(o: Num): this { return bin(SLOP.ADD, this, o) as this }
+    sub(o: Num): this { return bin(SLOP.SUB, this, o) as this }
+    mul(o: Num): this { return bin(SLOP.MUL, this, o) as this }
+    div(o: Num): this { return bin(SLOP.DIV, this, o) as this }
+    mod(o: Num): this { return bin(SLOP.MOD, this, o) as this }
+    pow(o: Num): this { return bin(SLOP.POW, this, o) as this }
+    neg(): this { return un(SLOP.NEG, this) as this }
+    recip(): this { return un(SLOP.RECIP, this) as this }
+    abs(): this { return un(SLOP.ABS, this) as this }
+    saturate(): this { return un(SLOP.SATURATE, this) as this }
+    fract(): this { return un(SLOP.FRACT, this) as this }
+    floor(): this { return un(SLOP.FLOOR, this) as this }
+    min(o: Num): this { return bin(SLOP.MIN, this, o) as this }
+    max(o: Num): this { return bin(SLOP.MAX, this, o) as this }
+    clamp(lo: Num, hi: Num): this {
+        const { refs, width } = alignN([this, lo, hi])
+        return mk(this.owner, this.owner.call(SLOP.CLAMP, width, refs), width) as this
+    }
+
+    /** Length, distance and dot collapse to a Float whatever the input width. */
+    length(): Float { return mk(this.owner, this.owner.call(SLOP.LENGTH, TYPE.FLOAT, [this.ref]), TYPE.FLOAT) }
+    distance(o: Num): Float {
+        const [a, c] = align2(this, o)
+        return mk(this.owner, this.owner.call(SLOP.DISTANCE, TYPE.FLOAT, [a, c]), TYPE.FLOAT)
+    }
+    dot(o: Num): Float {
+        const [a, c] = align2(this, o)
+        return mk(this.owner, this.owner.call(SLOP.DOT, TYPE.FLOAT, [a, c]), TYPE.FLOAT)
+    }
+    normalize(): this { return un(SLOP.NORMALIZE, this) as this }
+
+    /**
+     * Arbitrary swizzle. The common single and full width ones are also getters
+     * (`p.x`, `c.rgb`); this covers everything else and is typed by its argument,
+     * so `c.swz("wzyx")` is a Vec4 and `c.swz("yx")` is a Vec2.
+     */
+    swz<S extends string>(s: S): Widen<S> {
+        if (s.length < 1 || s.length > 4) throw new SLError(`a swizzle takes 1 to 4 components, got "${s}"`)
+        const chans: number[] = []
+        for (const ch of s) {
+            const c = CHAN[ch]
+            if (c === undefined) throw new SLError(`"${ch}" is not a component; use xyzw or rgba`)
+            if (c >= this.width) {
+                throw new SLError(`"${ch}" is component ${c + 1} of a ${widthName(this.width)}, which has ${this.width}`)
+            }
+            chans.push(c)
+        }
+        const t = chans.length as SLType
+        return mk(this.owner, this.owner.add({ k: "swizzle", type: t, src: this.ref, chans }), t) as Widen<S>
+    }
+
+    get x(): Float { return this.swz("x") }
+    get y(): Float { return this.swz("y") }
+    get z(): Float { return this.swz("z") }
+    get w(): Float { return this.swz("w") }
+    get r(): Float { return this.swz("r") }
+    get g(): Float { return this.swz("g") }
+    get b(): Float { return this.swz("b") }
+    get a(): Float { return this.swz("a") }
+    get xyz(): Vec3 { return this.swz("xyz") }
+    get xyzw(): Vec4 { return this.swz("xyzw") }
+    get rgb(): Vec3 { return this.swz("rgb") }
+    get rgba(): Vec4 { return this.swz("rgba") }
+}
+
+/**
+ * Every two component swizzle, as a real getter.
+ *
+ * These are defined rather than listed because `uv.yx` is an ordinary thing to
+ * write and JavaScript answers an undeclared property with `undefined` rather
+ * than an error. That `undefined` then travels into `vec4(...)` and fails
+ * somewhere else entirely, about a value the author never wrote. Anything
+ * reachable at runtime should be reachable in the types too, so the interfaces
+ * below declare the same set.
+ *
+ * Three and four component permutations stay on `swz()`, which is typed by its
+ * argument. There are 320 of them and almost nobody writes `.zwyx`.
+ */
+const PAIRS: string[] = []
+for (const set of ["xyzw", "rgba"]) {
+    for (const a of set) for (const b of set) PAIRS.push(a + b)
+}
+for (const p of PAIRS) {
+    if (p in Val.prototype) continue
+    Object.defineProperty(Val.prototype, p, {
+        get(this: Val) { return this.swz(p) },
+        enumerable: false,
+        configurable: true,
+    })
+}
+
+/** The two component swizzles defined above, so the types match the runtime. */
+type Pair<S extends string> = { readonly [K in `${S}${S}` & string]: Vec2 }
+// Deliberate: the type half of the getters defined on Val.prototype directly above.
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export interface Val extends Pair<"x" | "y" | "z" | "w">, Pair<"r" | "g" | "b" | "a"> {}
+
+/** TypeScript's view of a recorded value. One runtime class, four static types. */
+export interface Float extends Val { readonly width: 1 }
+export interface Vec2 extends Val { readonly width: 2 }
+export interface Vec3 extends Val { readonly width: 3 }
+export interface Vec4 extends Val { readonly width: 4 }
+
+function mk(b: Builder, ref: NodeRef, width: SLType): any {
+    return new Val(b, ref, width)
+}
+
+// MARK: recording context
+
+let current: Builder | null = null
+
+function ctx(): Builder {
+    if (current === null) {
+        throw new SLError(
+            "sl values can only be built inside sl.program(). A value recorded outside one has no " +
+            "graph to belong to, and a value from a different program cannot be mixed into this one.",
+        )
+    }
+    return current
+}
+
+/** Lifts a plain number to a node of the given width. */
+function lift(b: Builder, v: Num, width: SLType): NodeRef {
+    if (typeof v === "number") return b.constant(new Array(width).fill(v))
+    if (v.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+    return v.ref
+}
+
+/**
+ * Aligns two operands. A Float broadcasts against a vector, as in HLSL; two
+ * vectors of different widths are a type error, which TypeScript already catches
+ * at the call site for typed code and this catches for everything else.
+ */
+function align2(a: Val, o: Num): [NodeRef, NodeRef] {
+    if (typeof o === "number") return [a.ref, lift(a.owner, o, a.width)]
+    if (o.owner !== a.owner) throw new SLError("a value from another program cannot be used in this one")
+    if (o.width === a.width) return [a.ref, o.ref]
+    if (o.width === 1) return [a.ref, broadcast(o, a.width)]
+    if (a.width === 1) return [broadcast(a, o.width), o.ref]
+    throw new SLError(`cannot combine a ${widthName(a.width)} with a ${widthName(o.width)}`)
+}
+
+/**
+ * Aligns any number of operands of a component wise op to their widest.
+ *
+ * THE RESULT WIDTH IS THE WIDEST OPERAND, not the first one. `align2` gets that
+ * right for two operands because `bin` takes the max itself; the three and four
+ * operand ops used to take the width from one chosen operand, so
+ * `mix(0, aVec3, t)` produced a node typed float that held three components.
+ * The VM keeps every value in a float4 register and never noticed, while the
+ * HLSL emitter declared `float` and truncated, so the two backends rendered
+ * different pictures from one program. Anything component wise with more than
+ * two operands goes through here.
+ */
+function alignN(vs: Num[]): { refs: NodeRef[]; width: SLType } {
+    let width: SLType = 1
+    let owner: Builder | null = null
+    for (const v of vs) {
+        if (typeof v === "number") continue
+        if (owner === null) owner = v.owner
+        else if (v.owner !== owner) throw new SLError("a value from another program cannot be used in this one")
+        if (v.width > width) width = v.width
+    }
+    const b = owner ?? ctx()
+    const refs = vs.map((v) => {
+        if (typeof v === "number") return lift(b, v, width)
+        if (v.width === width) return v.ref
+        if (v.width === 1) return broadcast(v, width)
+        throw new SLError(`cannot combine a ${widthName(v.width)} with a ${widthName(width)}`)
+    })
+    return { refs, width }
+}
+
+/** float -> vecN by repeating the component. */
+function broadcast(v: Val, width: SLType): NodeRef {
+    return v.owner.add({ k: "swizzle", type: width, src: v.ref, chans: new Array(width).fill(0) })
+}
+
+function bin(op: SLOpCode, a: Val, o: Num): Val {
+    const [x, y] = align2(a, o)
+    const width = typeof o === "number" ? a.width : (Math.max(a.width, o.width) as SLType)
+    return mk(a.owner, a.owner.call(op, width, [x, y]), width)
+}
+
+function un(op: SLOpCode, a: Val): Val {
+    return mk(a.owner, a.owner.call(op, a.width, [a.ref]), a.width)
+}
+
+// MARK: the public surface
+
+export interface ProgramInputs {
+    uv: Vec2
+    fragCoord: Vec2
+    resolution: Vec2
+    time: Float
+    aspect: Float
+}
+
+/**
+ * Records a program. The function runs ONCE, here, not per pixel.
+ *
+ * It must return a Vec4: a program produces a colour.
+ */
+export function program(fn: (inputs: ProgramInputs) => Vec4): Program {
+    if (current !== null) throw new SLError("sl.program() cannot be nested")
+    const b = new Builder()
+    current = b
+    try {
+        const inputs = {} as ProgramInputs
+        for (const [name, width] of Object.entries(INPUTS)) {
+            const ref = b.add({ k: "input", type: width as SLType, name: name as InputName })
+            ;(inputs as any)[name] = mk(b, ref, width as SLType)
+        }
+        const out = fn(inputs)
+        if (!(out instanceof Val)) throw new SLError("a program must return an sl value, not " + typeof out)
+        if (out.width !== TYPE.VEC4) {
+            throw new SLError(`a program must return a vec4, got a ${widthName(out.width)}. Wrap it: sl.vec4(value, 1)`)
+        }
+        const nodes: SLNode[] = b.nodes.slice()
+        return {
+            version: SL_IR_VERSION,
+            nodes,
+            result: out.ref,
+            uniforms: b.uniforms.slice(),
+            textures: b.textures.slice(),
+            hash: hashProgram(nodes, out.ref, b.uniforms, b.textures),
+            loops: b.loops.slice(),
+        }
+    } finally {
+        current = null
+    }
+}
+
+export function float(v: Num): Float {
+    const b = ctx()
+    return typeof v === "number" ? mk(b, b.constant([v]), TYPE.FLOAT) : (v as Float)
+}
+
+/** Builds a wider value from narrower parts, which must add up exactly. */
+function compose(width: SLType, parts: Num[]): Val {
+    const b = ctx()
+    // Wide parts are SPLIT into their components here, so COMPOSE only ever
+    // sees scalars.
+    //
+    // The VM keeps every value in a float4 register and took the x of each
+    // operand, which silently dropped everything after the first component:
+    // vec4(uv, 0, 1) rendered (uv.x, 0, 1, 0) instead of (uv.x, uv.y, 0, 1).
+    // Teaching the shader each part's width would need widths in an encoding
+    // that has no room for them, and would put the complexity in the half that
+    // is hardest to test. Splitting at record time costs a few extra swizzle
+    // nodes, which the register allocator reclaims immediately, and leaves the
+    // VM's COMPOSE trivially correct.
+    // A constructor of literals is ONE constant, not a COMPOSE of four.
+    //
+    // `vec4(0.1, 0.2, 0.3, 0.4)` was five instructions holding four registers
+    // at once, because every part became its own CONST and COMPOSE kept them
+    // all live. The IR has always been able to say it in one node: a const
+    // carries up to four components. A two stop `ramp` used five of the eight
+    // registers on nothing but its own stop colours, which put the language's
+    // headline colour tool within one or two registers of unusable in any
+    // program that also did something.
+    if (parts.length === width && parts.every((p) => typeof p === "number")) {
+        return mk(b, b.constant(parts as number[]), width)
+    }
+
+    const refs: NodeRef[] = []
+    let total = 0
+    for (const p of parts) {
+        if (typeof p === "number") { refs.push(b.constant([p])); total += 1; continue }
+        if (p.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+        if (p.width === 1) { refs.push(p.ref); total += 1; continue }
+        for (let c = 0; c < p.width; c++) {
+            refs.push(b.add({ k: "swizzle", type: TYPE.FLOAT, src: p.ref, chans: [c] }))
+            total += 1
+        }
+    }
+    if (total !== width) {
+        throw new SLError(`vec${width} needs ${width} components, got ${total}`)
+    }
+    return mk(b, b.call(SLOP.COMPOSE, width, refs), width)
+}
+
+export function vec2(...parts: Num[]): Vec2 { return compose(TYPE.VEC2, parts) as Vec2 }
+export function vec3(...parts: Num[]): Vec3 { return compose(TYPE.VEC3, parts) as Vec3 }
+export function vec4(...parts: Num[]): Vec4 { return compose(TYPE.VEC4, parts) as Vec4 }
+
+/**
+ * A one argument op, typed so the width survives.
+ *
+ * Overloads rather than a conditional return type: the conditional form widened
+ * `sl.sin(aFloat)` to `Float | Val`, so `let v = uv.x; v = sl.sin(v)` failed to
+ * typecheck. An author hitting that would reasonably conclude the types were
+ * decorative.
+ */
+function unary(op: SLOpCode) {
+    function f(v: number): Float
+    function f<T extends Val>(v: T): T
+    function f(v: Num): Val {
+        return un(op, typeof v === "number" ? (float(v) as Val) : v)
+    }
+    return f
+}
+
+export const sin = unary(SLOP.SIN)
+export const cos = unary(SLOP.COS)
+export const tan = unary(SLOP.TAN)
+export const asin = unary(SLOP.ASIN)
+export const acos = unary(SLOP.ACOS)
+export const exp = unary(SLOP.EXP)
+export const log = unary(SLOP.LOG)
+export const sqrt = unary(SLOP.SQRT)
+export const sign = unary(SLOP.SIGN)
+export const ceil = unary(SLOP.CEIL)
+export const round = unary(SLOP.ROUND)
+
+/**
+ * Collapses a colour to a single brightness.
+ *
+ * NOT declared through `unary`, which preserves width. Luminance is one of the
+ * few ops whose result is narrower than its input, and having it return a Vec4
+ * meant `sl.vec4(sl.mix(lum, c.x, 0.5), c.y, c.z, c.w)` silently became seven
+ * components. The error surfaced two calls away from the cause, which is what
+ * width preserving by default costs when it is wrong.
+ */
+/**
+ * A colour as written (sRGB, the way CSS reads a hex) to the working space the
+ * target holds. `ramp` and `color` already apply it; call it yourself on a
+ * vec4 built from raw components that mean a colour. Alpha is left alone.
+ */
+export const toLinear = unary(SLOP.TO_LINEAR)
+
+/** A hex colour as a vec4 in the working space: `parseColor` plus `toLinear`. */
+export function color(hex: string): Vec4 {
+    const v = parseColor(hex)
+    return toLinear(vec4(v[0], v[1], v[2], v[3]))
+}
+
+export function luminance(c: Num): Float {
+    const v = typeof c === "number" ? float(c) : c
+    return mk(v.owner, v.owner.call(SLOP.LUMINANCE, TYPE.FLOAT, [v.ref]), TYPE.FLOAT)
+}
+
+/**
+ * Hue, saturation and value to RGB.
+ *
+ * The opcode was already implemented in both backends and simply had no name
+ * out here, which is the kind of gap only writing something real finds: a demo
+ * wanted a hue uniform, and a ramp cannot have one because its stops are
+ * constants.
+ */
+export function hsv2rgb(c: Vec3): Vec3 {
+    return mk(c.owner, c.owner.call(SLOP.HSV2RGB, TYPE.VEC3, [c.ref]), TYPE.VEC3)
+}
+
+/**
+ * Cross and reflect, both vec3 only.
+ *
+ * The VM evaluates them as `cross(a.xyz, b.xyz)`, so a vec2 or vec4 would mean
+ * one thing in a compiled build and another in the interpreter. Refusing the
+ * other widths here is what keeps the two honest.
+ */
+export function cross(a: Vec3, b: Vec3): Vec3 {
+    if (a.width !== TYPE.VEC3 || b.width !== TYPE.VEC3) {
+        throw new SLError(`cross takes two vec3s, got a ${widthName(a.width)} and a ${widthName(b.width)}`)
+    }
+    const [x, y] = align2(a, b)
+    return mk(a.owner, a.owner.call(SLOP.CROSS, TYPE.VEC3, [x, y]), TYPE.VEC3)
+}
+
+export function reflect(incident: Vec3, normal: Vec3): Vec3 {
+    if (incident.width !== TYPE.VEC3 || normal.width !== TYPE.VEC3) {
+        throw new SLError(
+            `reflect takes two vec3s, got a ${widthName(incident.width)} and a ${widthName(normal.width)}`,
+        )
+    }
+    const [i, n] = align2(incident, normal)
+    return mk(incident.owner, incident.owner.call(SLOP.REFLECT, TYPE.VEC3, [i, n]), TYPE.VEC3)
+}
+
+/**
+ * One range to another, linearly and without clamping.
+ *
+ * A MACRO, like `ramp`, and for the same reason: it expands into arithmetic
+ * both backends already have, so it needs no opcode, no second implementation
+ * in the emitter and no VM case. `SLOP.REMAP` stays a reserved number.
+ *
+ * Unclamped on purpose, which is what HLSL authors expect of the one liner they
+ * would otherwise write; wrap it in `saturate` when the ends matter.
+ */
+export function remap(v: Num, fromMin: Num, fromMax: Num, toMin: Num, toMax: Num): Val {
+    const x = typeof v === "number" ? float(v) : v
+    const t = x.sub(fromMin).div(difference(fromMax, fromMin))
+    return mix(toMin, toMax, t)
+}
+
+/** `a - b` where either side may still be a plain number, so a constant stays one. */
+function difference(a: Num, b: Num): Num {
+    if (typeof a === "number" && typeof b === "number") return a - b
+    return (typeof a === "number" ? float(a) : a).sub(b)
+}
+
+export function atan2(y: Num, x: Num): Float {
+    const b = ctx()
+    const yy = typeof y === "number" ? float(y) : y
+    const [a, c] = align2(yy as Val, x)
+    return mk(b, b.call(SLOP.ATAN2, TYPE.FLOAT, [a, c]), TYPE.FLOAT)
+}
+
+/**
+ * Branchless selection. Both sides are evaluated, which is why v1 has this
+ * rather than an `if`: a real branch would have to survive both backends
+ * identically, and this does not.
+ */
+export function select(cond: Num, whenTrue: Num, whenFalse: Num): Val {
+    const b = ctx()
+    const c = typeof cond === "number" ? float(cond) : cond
+    const t = typeof whenTrue === "number" ? float(whenTrue) : whenTrue
+    const f = typeof whenFalse === "number" ? float(whenFalse) : whenFalse
+    // The condition is widened with the branches, not left at its own width.
+    // A register is a float4 whatever it holds, so a scalar condition sits
+    // there as (c, 0, 0, 0) and the VM's `step(0.5, cond)` answered 0 for
+    // components y, z and w, while the HLSL backend broadcasts a scalar
+    // itself. The two DISAGREED on every vector valued select, which is the one
+    // failure this design cannot tolerate.
+    const { refs, width } = alignN([c, t, f])
+    return mk(b, b.call(SLOP.SELECT, width, refs), width)
+}
+
+/**
+ * The interpolant is broadcast to the operand width before it crosses.
+ *
+ * A register is a float4 whatever it holds, so a scalar `t` sits there as
+ * (t, 0, 0, 0) and the shader's lerp ran per component against those zeros:
+ * a black to white ramp at its midpoint rendered (0.5, 0, 0, 1) instead of
+ * grey. Broadcasting here rather than in the shader keeps `t` free to be a
+ * genuine per component vector when an author wants one.
+ */
+export function mix(a: Num, bv: Num, t: Num): Val {
+    const { refs, width } = alignN([a, bv, t])
+    const b = ctx()
+    return mk(b, b.call(SLOP.MIX, width, refs), width)
+}
+
+export function step(edge: Num, x: Num): Val {
+    const { refs, width } = alignN([edge, x])
+    const b = ctx()
+    return mk(b, b.call(SLOP.STEP, width, refs), width)
+}
+
+export function smoothstep(e0: Num, e1: Num, x: Num): Val {
+    const { refs, width } = alignN([e0, e1, x])
+    const b = ctx()
+    return mk(b, b.call(SLOP.SMOOTHSTEP, width, refs), width)
+}
+
+/** Uniform defaults, in slot order, for a host that has to seed them. */
+export function uniformDefaults(p: Program): number[] {
+    const out: number[] = []
+    for (const u of p.uniforms) {
+        for (let i = 0; i < 4; i++) out.push(u.value[i] ?? (i === 3 ? 1 : 0))
+    }
+    return out
+}
+
+/**
+ * Noise, as superinstructions rather than graphs of primitives, and the same
+ * fields `fx.noise` draws: a value or simplex base, layered as fBm, or the
+ * turbulence and ridged variants built on simplex. A program has no seed;
+ * offset the input for a different field. Octaves are 1 to 4, as in fx.
+ */
+export function noise(p: Vec2): Float {
+    return mk(p.owner, p.owner.call(SLOP.NOISE, TYPE.FLOAT, [p.ref]), TYPE.FLOAT)
+}
+export function simplex(p: Vec2): Float {
+    return mk(p.owner, p.owner.call(SLOP.SIMPLEX, TYPE.FLOAT, [p.ref]), TYPE.FLOAT)
+}
+function octaveCount(name: string, octaves: number): number {
+    if (!Number.isInteger(octaves) || octaves < 1 || octaves > 4) {
+        throw new SLError(`${name} octaves must be a whole number from 1 to 4, got ${octaves}`)
+    }
+    return octaves
+}
+/** Layered noise. `base` picks the grid ("value", the default) or triangles ("simplex"). */
+export function fbm(p: Vec2, octaves = 3, base: "value" | "simplex" = "value"): Float {
+    const kind = base === "simplex" ? 1 : 0
+    return mk(p.owner, p.owner.call(SLOP.FBM, TYPE.FLOAT, [p.ref], [octaveCount("fbm", octaves), kind]), TYPE.FLOAT)
+}
+/** Sum of |simplex| octaves: creases that stack into veins and licks. Fire, smoke, marble. */
+export function turbulence(p: Vec2, octaves = 3): Float {
+    return mk(p.owner, p.owner.call(SLOP.TURBULENCE, TYPE.FLOAT, [p.ref], [octaveCount("turbulence", octaves)]), TYPE.FLOAT)
+}
+/** The turbulence crease made bright and squared: ridges, lightning, cracks. */
+export function ridged(p: Vec2, octaves = 3): Float {
+    return mk(p.owner, p.owner.call(SLOP.RIDGED, TYPE.FLOAT, [p.ref], [octaveCount("ridged", octaves)]), TYPE.FLOAT)
+}
+
+/** "#rgb", "#rrggbb" or "#rrggbbaa" to 0..1 components. Shared with fx. */
+export function parseColor(hex: string): [number, number, number, number] {
+    try {
+        return parseHex(hex)
+    } catch (e) {
+        throw new SLError((e as Error).message)
+    }
+}
+
+/**
+ * Maps 0..1 through evenly spaced colour stops.
+ *
+ * A MACRO, not an opcode. It expands into the mixes and smoothsteps already in
+ * the table, which is worth more than a dedicated instruction would be: it needs
+ * no new encoding, no ramp uniforms competing for space with the program, and no
+ * second implementation in the HLSL emitter. Both backends get it right by
+ * getting `mix` right, and a ramp of any length works rather than however many
+ * stops an instruction could carry.
+ *
+ * This is the argument for the EDSL in miniature. A library function that
+ * composes from primitives costs one function here and nothing anywhere else.
+ */
+export function ramp(t: Num, stops: Array<string | [number, number, number, number]>): Vec4 {
+    if (stops.length < 2) throw new SLError(`a ramp needs at least 2 stops, got ${stops.length}`)
+    const tv = (typeof t === "number" ? float(t) : t).saturate()
+    // Each stop is built IMMEDIATELY BEFORE the mix that consumes it, not all
+    // of them up front. The graph is identical either way and so is the hash,
+    // which is a Merkle hash over the shape and not over storage order, but the
+    // register allocator walks the array: built up front, every stop stayed
+    // live until the last mix, and a four stop ramp reserved four of the VM's
+    // eight registers before the program did anything. That put the language's
+    // headline colour tool a couple of registers from unusable.
+    const colourAt = (i: number) => {
+        const v = typeof stops[i] === "string" ? parseColor(stops[i] as string) : (stops[i] as number[])
+        return vec4(v[0], v[1], v[2], v[3])
+    }
+    const spans = stops.length - 1
+    let out = colourAt(0)
+    for (let i = 0; i < spans; i++) {
+        // Local 0..1 across this span, clamped, so stops outside it contribute
+        // nothing and the chain reads as "each span paints over the last".
+        const local = (tv.mul(spans).sub(i) as Float).saturate()
+        out = mix(out, colourAt(i + 1), local) as Vec4
+    }
+    // The stops are sRGB as written and the mixes ran in that space, which is
+    // what reads as an even ramp; one conversion at the end puts the result in
+    // the target's working space. Same rule as fx's gradient and ramp.
+    return toLinear(out)
+}
+
+/**
+ * Signed distance to a shape, positive outside and negative inside.
+ *
+ * The 42 shapes are the same ones `fx` draws, from the same HLSL, so a hexagon
+ * means one thing across the whole library rather than two.
+ *
+ *     const d = sl.sdf("hexagon", uv.sub(0.5), [0.3])
+ *     return sl.vec4(sl.smoothstep(0.01, 0, d), 0, 0, 1)
+ *
+ * POSITION AND ROTATION ARE NOT PARAMETERS, deliberately. Transform the point
+ * before calling, as `uv.sub(centre)` above does. That is how signed distance
+ * code is normally written and it composes with everything else in the language.
+ *
+ * A shape takes up to `SL_SDF_PARAMS[kind]` parameters, six at most. Fewer
+ * fills zeros, which is all a program could pass before six shapes grew their
+ * fifth and sixth.
+ *
+ * Which parameters a shape takes is the shape's own business; `circle` wants a
+ * radius, `roundedBox` wants half extents and a corner. See SDF2D.cginc.
+ */
+export function sdf(kind: SlSdfKind, p: Vec2, params: number[] = []): Float {
+    const id = SL_SDF_SHAPES[kind]
+    if (id === undefined) throw new SLError(`"${kind}" is not a shape; see SL_SDF_SHAPES for the 42 names`)
+    // At least four, so a program that passed a shape more than it reads, which
+    // was harmless when every shape took four, still builds.
+    const most = Math.max(4, SL_SDF_PARAMS[kind])
+    if (params.length > most) {
+        throw new SLError(`sl.sdf("${kind}") takes at most ${most} parameters and was given ${params.length}`)
+    }
+    for (const v of params) {
+        if (!Number.isFinite(v)) throw new SLError(`sl.sdf parameters must be finite, got ${v}`)
+    }
+    // Four always, as before, and a fifth and sixth only when given: a program
+    // using four or fewer is the same node, and hashes the same, as it was.
+    const imm = [params[0] ?? 0, params[1] ?? 0, params[2] ?? 0, params[3] ?? 0, ...params.slice(4)]
+    return mk(p.owner, p.owner.call(SLOP.SDF, TYPE.FLOAT, [p.ref], [id, ...imm]), TYPE.FLOAT)
+}
+
+/** Distance to the nearest point of a jittered lattice. Cells, cracks, scales. */
+export function voronoi(p: Vec2): Float {
+    return mk(p.owner, p.owner.call(SLOP.VORONOI, TYPE.FLOAT, [p.ref]), TYPE.FLOAT)
+}
+
+export const uniform = {
+    float(name: string, value = 0): Float {
+        const b = ctx()
+        return mk(b, b.uniform(name, TYPE.FLOAT, [value]), TYPE.FLOAT)
+    },
+    vec2(name: string, value: [number, number] = [0, 0]): Vec2 {
+        const b = ctx()
+        return mk(b, b.uniform(name, TYPE.VEC2, value), TYPE.VEC2)
+    },
+    vec3(name: string, value: [number, number, number] = [0, 0, 0]): Vec3 {
+        const b = ctx()
+        return mk(b, b.uniform(name, TYPE.VEC3, value), TYPE.VEC3)
+    },
+    vec4(name: string, value: [number, number, number, number] = [0, 0, 0, 1]): Vec4 {
+        const b = ctx()
+        return mk(b, b.uniform(name, TYPE.VEC4, value), TYPE.VEC4)
+    },
+}
+
+export interface Texture {
+    sample(uv: Vec2): Vec4
+}
+
+export function texture(name: string): Texture {
+    const b = ctx()
+    const slot = b.texture(name)
+    return {
+        sample(uv: Vec2): Vec4 {
+            if (uv.owner !== b) throw new SLError("a value from another program cannot be used in this one")
+            return mk(b, b.call(SLOP.SAMPLE, TYPE.VEC4, [uv.ref], [slot]), TYPE.VEC4)
+        },
+    }
+}
+
+/**
+ * A loop that UNROLLS at record time. `n` is a JavaScript number, so the count
+ * is known while the graph is being built and both backends see straight line
+ * code.
+ *
+ * Honest about what it is: a macro, not a loop. It covers fbm, layered noise and
+ * small iterated distance fields, which is most of what 2D shaders loop for. A
+ * data dependent loop is out of scope, because in the VM it would need a nested
+ * bounded loop with a dynamic trip count while codegen would handle it fine, and
+ * the two backends agreeing is the property this whole design protects.
+ */
+export function repeat<T extends Val>(n: number, body: (i: number, acc: T) => T, seed: T): T {
+    if (!Number.isInteger(n) || n < 0 || n > 64) {
+        throw new SLError(`repeat count must be a whole number from 0 to 64, got ${n}`)
+    }
+    return unrolled(n, () => {
+        let acc = seed
+        for (let i = 0; i < n; i++) acc = body(i, acc)
+        return acc
+    })
+}
+
+/**
+ * Records the nodes a body produced as one unrolled span.
+ *
+ * Diagnostic only: the instruction ceiling error uses the span to say which
+ * loop spent the budget, so the fix reads as "lower this count" rather than
+ * "fewer instructions". `repeat` is the EDSL's form of it and the text
+ * language's `for` is the other, and neither should be reaching into the
+ * Builder to push a span itself.
+ */
+export function unrolled<T>(count: number, body: () => T): T {
+    const b = ctx()
+    const start = b.nodes.length
+    const out = body()
+    b.loops.push({ count, start, end: b.nodes.length })
+    return out
+}