onejs-sl 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.1.4
+
+Four things that were errors now compile, the most common mistakes in cold runs of authors writing from the docs alone (`Specs/SL_NEXT.md` 2). Every program that compiled before compiles to exactly what it did.
+
+- A swizzle can be assigned to: `p.x = 1;`, `c.rgb *= 0.5;`
+- A single number fills a vector in a declaration, an assignment or a uniform default: `float3 c = 0.5;`
+- A float4 goes into a float3 by dropping its fourth component: `float3 c = #ff8040;`
+- A local or a uniform may take a builtin's or a prelude function's name
+
+## 0.1.3
+
+`onejs-sl/tables` names every parameter, so an editor can offer `lerp(x, y, s)` rather than an argument count. Nothing a program compiles to changes.
+
+- `BUILTIN_PARAMS` names every builtin's parameters
+- `SL_SDF_PARAM_NAMES` names every shape's parameters
+- `LIB_SIGNATURES` gives every library function's parameter names and types
+
 ## 0.1.2
 
 The helper library has one source, `lib/*.hlsl`, translated at build time into GLSL ES, WGSL and the shared subset and copied into OneJS as its `.cginc` files. The web draws exactly what it drew; the Unity shader's text changes where Metal needed it to, and draws the same.

package/README.md

@@ -37,7 +37,7 @@ only what it calls.
 |---|---|
 | `onejs-sl` | `parse` and `analyze`, the TypeScript form `sl`, the IR types, `SL_IR_VERSION`, `toJSON`/`fromJSON`, `SLParseError` (file, line, column, length) |
 | `onejs-sl/core` | the same without the parser: what a game needs at run time |
-| `onejs-sl/tables` | `BUILTINS`, `SL_HLSL`, `INPUTS`, `SL_SDF_SHAPES`, `SL_SDF_PARAMS`: what completion and highlighting read |
+| `onejs-sl/tables` | `BUILTINS`, `SL_HLSL`, `INPUTS`, `SL_SDF_SHAPES`, `SL_SDF_PARAMS`: what completion and highlighting read. `BUILTIN_PARAMS`, `SL_SDF_PARAM_NAMES` and `LIB_SIGNATURES` name every parameter, so an editor can show `lerp(x, y, s)` |
 | `onejs-sl/limits` | `vmFit(program)`: whether the VM runs it, and why not, without encoding |
 | `onejs-sl/vm` | `encode`, `SL_WIRE_VERSION` |
 | `onejs-sl/emit/hlsl-body` | `emitBody`: a program as a function body for a host's own frame; `emitLibrary`: the library functions it calls |
@@ -92,6 +92,8 @@ by `npm run lib`, and nobody edits the copies:
   the shape table read from `sl_sdfDistance`'s switch), and the text of each
   function as GLSL ES (`glsl.ts`), WGSL (`wgsl.ts`) and the shared subset
   (`hlsl.ts`). The web emitters and `emitLibrary` take only what a program calls.
+  `names.ts` holds each function's parameter names, which only
+  `onejs-sl/tables` reads.
 
 `lib/translate.ts` does the printing, at build time only. It reads a subset of
 HLSL, listed at its top (functions, locals, `if`, bounded `for`, `switch`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-sl",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The OneJS shader language: a small typed language for per pixel programs, compiled to a portable IR and emitted as HLSL, WGSL, GLSL ES or a VM buffer",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/lang/README.md

@@ -127,11 +127,25 @@ is read unconverted.
 and colours, and nothing else. It is baked into the program before anything
 runs, so it cannot name a const, which could itself name a uniform.
 
-**Shadowing is refused.** A local may not take the name of an input, a uniform,
-a texture, a const or a builtin. Allowing it would make "is this a texture?"
-depend on where the question is asked, for no gain in a language whose
-functions are six lines long. A file function may shadow a *prelude* function,
-which is the sanctioned way to replace one.
+**Shadowing is refused between values.** A local may not take the name of an
+input, a uniform, a texture or a const. Allowing it would make "is this a
+texture?" depend on where the question is asked, for no gain in a language whose
+functions are six lines long. A value *may* take a builtin's or a prelude
+function's name (`float circle`, `uniform float turbulence`), which hides that
+function wherever the value is visible, and a call there says so. A file
+function may shadow a *prelude* function, which is the sanctioned way to replace
+one.
+
+**Declarations and assignments convert two ways, and only two.** A single
+number fills every component (`float3 c = 0.5;`, and a uniform default such as
+`uniform float2 offset = 0;`), and a float4 goes into a float3 by dropping its
+fourth component, which is how a colour becomes an rgb. Every other width change
+is refused with the swizzle that fixes it.
+
+**A swizzle can be assigned to.** `p.x *= aspect;` rebuilds `p` from the
+components it names and keeps the rest, so it is the same program as
+`p = float2(p.x * aspect, p.y);`. A swizzle that names a component twice, or
+one the local does not have, is refused.
 
 ## Not yet spellable
 

package/src/lang/check.ts

@@ -14,11 +14,18 @@
  * whether a name exists, whether a body is shaped like a body, and whether the
  * program fits the budgets before anything is built.
  *
- * SHADOWING IS REFUSED. HLSL would let a local called `time` hide the input, or
- * a parameter called `tint` hide a uniform. Allowing it would mean every later
- * question about a name ("is this a texture?") depends on where it is asked
- * from, for no expressive gain in a language whose functions are half a dozen
- * lines long.
+ * SHADOWING IS REFUSED, between values. HLSL would let a local called `time`
+ * hide the input, or a parameter called `tint` hide a uniform. Allowing it would
+ * mean every later question about a name ("is this a texture?") depends on where
+ * it is asked from, for no expressive gain in a language whose functions are
+ * half a dozen lines long.
+ *
+ * A value MAY take the name of a builtin or a prelude function: `float circle`,
+ * `uniform float turbulence`. Those are the names an author reaches for first,
+ * and refusing them was the most common error left once the others were fixed
+ * (`Specs/SL_NEXT.md` 2d). Calls and values never meet in one position, so the
+ * only question left is a call to the name where the value is visible, and that
+ * is refused with the reason.
  */
 
 import { INPUTS } from "../ir"
@@ -84,8 +91,8 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
      *
      * Functions are NOT in here, because a file function shadowing a prelude
      * function of the same name is the sanctioned way to replace one
-     * (`Specs/SL_TEXT.md` 3.8). Every other kind of declaration checks `asFunc`
-     * as well, so only a function may take a function's name.
+     * (`Specs/SL_TEXT.md` 3.8). Every other kind of declaration checks
+     * `valueClash`, which adds the file's own functions.
      */
     const taken = (n: string): string | null => {
         if (INPUT_NAMES.has(n)) return "an input"
@@ -98,14 +105,16 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         return null
     }
 
-    const asFunc = (n: string): string | null => {
+    /** What a value may not be called: anything spoken for, except a builtin's or a prelude function's name. */
+    const valueClash = (n: string): string | null => {
+        const why = taken(n)
+        if (why !== null && why !== "a builtin") return why
         const fn = funcs.get(n)
-        if (fn === undefined) return null
-        return fn.prelude ? "a prelude function" : "a function"
+        return fn !== undefined && !fn.prelude ? "a function" : null
     }
 
     for (const u of unit.uniforms) {
-        const clash = taken(u.name) ?? asFunc(u.name)
+        const clash = valueClash(u.name)
         if (clash !== null) fail(`"${u.name}" already names ${clash}`, u.pos, u.name.length)
         uniforms.set(u.name, u)
     }
@@ -121,7 +130,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     }
 
     for (const t of unit.textures) {
-        const clash = taken(t.name) ?? asFunc(t.name)
+        const clash = valueClash(t.name)
         if (clash !== null) fail(`"${t.name}" already names ${clash}`, t.pos, t.name.length)
         textures.set(t.name, t)
     }
@@ -136,7 +145,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     }
 
     for (const c of unit.consts) {
-        const clash = taken(c.name) ?? asFunc(c.name)
+        const clash = valueClash(c.name)
         if (clash !== null) fail(`"${c.name}" already names ${clash}`, c.pos, c.name.length)
         consts.set(c.name, c)
     }
@@ -251,7 +260,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     function checkFunction(fn: FuncDecl): void {
         const params = new Set<string>()
         for (const p of fn.params) {
-            const clash = taken(p.name) ?? asFunc(p.name)
+            const clash = valueClash(p.name)
             if (clash !== null) fail(`"${p.name}" already names ${clash}`, p.pos, p.name.length)
             if (params.has(p.name)) fail(`${fn.name} already has a parameter called "${p.name}"`, p.pos)
             params.add(p.name)
@@ -275,7 +284,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
             switch (s.k) {
                 case "var":
                 case "const": {
-                    const clash = taken(s.name) ?? asFunc(s.name)
+                    const clash = valueClash(s.name)
                     if (clash !== null) fail(`"${s.name}" already names ${clash}`, s.pos, s.name.length)
                     if (scope.has(s.name)) fail(`"${s.name}" is already declared in this body`, s.pos)
                     checkExpr(fn, s.init, scope)
@@ -283,26 +292,32 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                     break
                 }
                 case "assign": {
-                    if (s.target.k === "member") {
-                        fail(
-                            "a swizzle is read only; build the value you want instead, as in " +
-                            "`p = float2(1, p.y);`",
-                            s.target.pos,
-                        )
+                    // `p.x = 1` and `c.rgb *= 0.5` write the components they name
+                    // and keep the rest; lowering rebuilds the local from both.
+                    let target = s.target
+                    if (target.k === "member") {
+                        const sw = target.name
+                        if (!/^([xyzw]{1,4}|[rgba]{1,4})$/.test(sw)) {
+                            fail(`${sw} is not a swizzle that can be assigned to; name components with xyzw or rgba`, target.pos, sw.length)
+                        }
+                        if (new Set(sw).size !== sw.length) {
+                            fail(`${sw} names a component twice, so assigning to it would write one component two ways`, target.pos, sw.length)
+                        }
+                        target = target.obj
                     }
-                    if (s.target.k !== "ident") fail("only a local can be assigned to", s.target.pos)
-                    const n = s.target.name
+                    if (target.k !== "ident") fail("only a local can be assigned to", target.pos)
+                    const n = target.name
                     const why = taken(n)
-                    if (why !== null) fail(`"${n}" is ${why} and cannot be assigned to`, s.target.pos, n.length)
+                    if (why !== null) fail(`"${n}" is ${why} and cannot be assigned to`, target.pos, n.length)
                     if (counters.has(n)) {
                         fail(
                             `"${n}" is a loop counter. The loop unrolls and substitutes it as a ` +
                             `number, so assigning to it would change nothing. Use another local`,
-                            s.target.pos, n.length,
+                            target.pos, n.length,
                         )
                     }
                     if (!scope.has(n)) {
-                        fail(unknown(n, scope), s.target.pos, n.length)
+                        fail(unknown(n, scope), target.pos, n.length)
                     }
                     checkExpr(fn, s.value, scope)
                     break
@@ -313,7 +328,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                     checkBody(fn, s.else, new Set(scope), false)
                     break
                 case "for": {
-                    const clash = taken(s.counter) ?? asFunc(s.counter)
+                    const clash = valueClash(s.counter)
                     if (clash !== null) fail(`"${s.counter}" already names ${clash}`, s.pos, s.counter.length)
                     if (scope.has(s.counter)) fail(`"${s.counter}" is already declared in this body`, s.pos)
                     checkExpr(fn, s.from, scope)
@@ -435,6 +450,16 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
             )
         }
 
+        // A value that took a builtin's or a prelude function's name hides it
+        // wherever the value is visible.
+        const value = scope.has(n) ? "a local" : uniforms.has(n) ? "a uniform" : consts.has(n) ? "a const" : null
+        if (value !== null) {
+            fail(`"${n}" is ${value} here, so it cannot be called. Rename it to call ${n}(...)`, callee.pos, n.length)
+        }
+        if (textures.has(n)) {
+            fail(`"${n}" is a texture; sample it with \`tex2D(${n}, uv)\``, callee.pos, n.length)
+        }
+
         const builtin = BUILTINS[n]
         if (builtin !== undefined) {
             if (n === "tex2D") {
@@ -471,9 +496,6 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         if (SL_GLSL_HINT[n] !== undefined) {
             fail(`${n} is GLSL; this is HLSL, so write ${SL_GLSL_HINT[n]}`, callee.pos, n.length)
         }
-        if (textures.has(n)) {
-            fail(`"${n}" is a texture; sample it with \`tex2D(${n}, uv)\``, callee.pos, n.length)
-        }
         fail(unknown(n, scope), callee.pos, n.length)
     }
 

package/src/lang/lower.ts

@@ -158,7 +158,7 @@ export function lower(checked: Checked): Program {
             for (const t of unit.textures) samplers.set(t.name, at(t.pos, () => sl.texture(t.name)))
 
             for (const c of unit.consts) {
-                const v = lowerExpr(c.init, global)
+                const v = fit(lowerExpr(c.init, global), TYPE_WIDTH[c.type], c.pos)
                 assertWidth(v, TYPE_WIDTH[c.type], c.name, c.type, c.pos)
                 global.declare(c.name, { width: TYPE_WIDTH[c.type], value: v })
             }
@@ -227,6 +227,8 @@ export function lower(checked: Checked): Program {
                 init.pos,
             )
         }
+        if (c.length === 1 && width > 1) return { components: new Array<number>(width).fill(c[0]!), colour: false }
+        if (c.length === 4 && width === 3) return { components: c.slice(0, 3), colour: false }
         if (c.length !== width) {
             fail(
                 `this default has ${c.length} component${c.length === 1 ? "" : "s"} and the uniform is ` +
@@ -284,19 +286,25 @@ export function lower(checked: Checked): Program {
             switch (s.k) {
                 case "var":
                 case "const": {
-                    const v = lowerExpr(s.init, scope)
+                    const v = fit(lowerExpr(s.init, scope), TYPE_WIDTH[s.type], s.pos)
                     assertWidth(v, TYPE_WIDTH[s.type], s.name, s.type, s.pos)
                     scope.declare(s.name, { width: TYPE_WIDTH[s.type], value: v })
                     break
                 }
                 case "assign": {
-                    const name = (s.target as Extract<Expr, { k: "ident" }>).name
+                    // The checker allowed exactly two shapes: a local, or a
+                    // swizzle of one with no component named twice.
+                    const member = s.target.k === "member" ? s.target : null
+                    const name = ((member?.obj ?? s.target) as Extract<Expr, { k: "ident" }>).name
                     const b = scope.lookup(name)!
                     let v = lowerExpr(s.value, scope)
                     if (s.op !== "=") {
                         const op = s.op[0] as ArithOp
-                        v = at(s.pos, () => arithmetic(op, b.value, v, s.pos))
+                        const old = member === null ? b.value : lowerExpr(member, scope)
+                        v = at(s.pos, () => arithmetic(op, old, v, s.pos))
                     }
+                    if (member !== null) v = writeComponents(b, member, v, s.pos)
+                    else v = fit(v, b.width, s.pos)
                     assertWidth(v, b.width, name, widthType(b.width), s.pos)
                     b.value = v
                     break
@@ -381,13 +389,52 @@ export function lower(checked: Checked): Program {
         return typeof a !== "number" && typeof b !== "number" && a.ref === b.ref && a.width === b.width
     }
 
+    /**
+     * The two conversions a declaration or an assignment makes for the author
+     * (`Specs/SL_NEXT.md` 2b and 2c): a single number fills every component, as
+     * `float3(0.5)` would, and a float4 goes into a float3 by dropping its
+     * fourth, which is how a colour (a hex, a ramp, a texture sample) becomes
+     * an rgb. Every other width change is left for `assertWidth` to refuse.
+     */
+    function fit(v: LV, want: SLType, pos: Pos): LV {
+        const got = typeof v === "number" ? 1 : v.width
+        if (got === 1 && want > 1) return at(pos, () => compose(want, new Array<LV>(want).fill(v)))
+        if (got === 4 && want === 3) return at(pos, () => asVal(v).swz("xyz") as unknown as Val)
+        return v
+    }
+
+    /**
+     * `p.x = v`, `c.rgb *= k`: the local rebuilt from the components the
+     * swizzle names, taken from `v`, and the rest kept from what it held. A
+     * single number fills every named component.
+     */
+    function writeComponents(b: Binding, member: Extract<Expr, { k: "member" }>, v: LV, pos: Pos): LV {
+        const letters = member.name.replace(/[rgba]/g, (c) => "xyzw"["rgba".indexOf(c)]!)
+        const names = "xyzw".slice(0, b.width)
+        for (const c of letters) {
+            if (!names.includes(c)) {
+                fail(`${member.name} writes a component a ${widthType(b.width)} does not have`, member.pos)
+            }
+        }
+        const got = typeof v === "number" ? 1 : v.width
+        if (got !== 1 && got !== letters.length) {
+            fail(`${member.name} is ${letters.length} components and this is a ${widthType(got as SLType)}`, pos)
+        }
+        const parts: LV[] = [...names].map((c) => {
+            const j = letters.indexOf(c)
+            if (j < 0) return b.width === 1 ? b.value : at(pos, () => asVal(b.value).swz(c) as unknown as Val)
+            return got === 1 ? v : at(pos, () => asVal(v).swz("xyzw"[j]!) as unknown as Val)
+        })
+        return b.width === 1 ? parts[0]! : at(pos, () => compose(b.width, parts))
+    }
+
     function assertWidth(v: LV, want: SLType, name: string, type: TypeName, pos: Pos): void {
         const got = typeof v === "number" ? 1 : v.width
         if (got === want) return
         // A declaration is an assertion, not an input to inference
         // (`Specs/SL_TEXT.md` 3.2), so this says which half is wrong rather
         // than quietly promoting one to the other.
-        const hint = got === 1 ? ` Wrap it in ${type}(...) to broadcast the value across ${want} components.` : ""
+        const hint = got > want ? ` Take the components you want with a swizzle, as in .${"xyzw".slice(0, want)}.` : ""
         fail(`${name} is declared ${type} and this is a ${widthType(got as SLType)}.${hint}`, pos)
     }
 

package/src/lib/names.ts

@@ -0,0 +1,77 @@
+// GENERATED by lib/generate.ts from lib/*.hlsl. Do not edit: change the
+// .hlsl and run `npm run lib`. src/lib/lib.test.ts fails when this is stale.
+
+/** Parameter names as the source writes them, by `LIB_FUNCTIONS` index. `onejs-sl/tables` reads them. */
+export const LIB_PARAM_NAMES: ReadonlyArray<readonly string[]> = [
+    ["x", "y"],
+    ["a", "b"],
+    ["v"],
+    ["p", "r"],
+    ["p", "b", "r"],
+    ["p", "b"],
+    ["p", "a", "b", "th"],
+    ["p", "a", "b"],
+    ["p", "b"],
+    ["p", "r1", "r2", "he"],
+    ["p", "wi", "he", "sk"],
+    ["p", "r"],
+    ["p", "q"],
+    ["p", "p0", "p1", "p2"],
+    ["p", "r1", "r2", "h"],
+    ["p", "r"],
+    ["p", "r"],
+    ["p", "r"],
+    ["p", "r"],
+    ["p", "r", "rf"],
+    ["p", "r", "n", "m"],
+    ["p", "c", "r"],
+    ["p", "r", "h"],
+    ["p", "sc", "ra", "rb"],
+    ["p", "n", "r", "th"],
+    ["p", "c", "r", "w"],
+    ["p", "r", "d"],
+    ["p", "a", "b", "w"],
+    ["p", "d", "ra", "rb"],
+    ["p", "h"],
+    ["p", "he", "ra", "rb", "bu"],
+    ["p"],
+    ["p", "b", "r"],
+    ["p", "w", "r"],
+    ["p", "ab"],
+    ["pos", "k"],
+    ["pos", "wi", "he"],
+    ["pos", "A", "B", "C"],
+    ["pos", "he"],
+    ["p", "wh"],
+    ["p", "wh", "n"],
+    ["p"],
+    ["p", "k", "he"],
+    ["p"],
+    ["p", "tb", "ra"],
+    ["p", "seed"],
+    ["p", "seed"],
+    ["p", "seed", "octaves", "lacunarity", "gain"],
+    ["p", "seed", "octaves"],
+    ["x"],
+    ["x"],
+    ["x"],
+    ["v"],
+    ["p", "seed"],
+    ["p", "seed", "octaves", "lacunarity", "gain"],
+    ["p", "seed", "octaves", "lacunarity", "gain"],
+    ["p", "seed", "octaves", "lacunarity", "gain"],
+    ["kind", "p", "seed", "octaves", "lacunarity", "gain"],
+    ["p"],
+    ["p"],
+    ["p"],
+    ["p", "octaves", "kind"],
+    ["c"],
+    ["id", "p", "a", "b"],
+    ["p"],
+    ["c"],
+    ["c"],
+    ["c"],
+    ["c"],
+    ["c"],
+    ["c"],
+]

package/src/params.ts

@@ -0,0 +1,113 @@
+/**
+ * Parameter names, for an editor's completions and signature help: so it can
+ * offer `lerp(x, y, s)` rather than "lerp takes 3 arguments".
+ *
+ * Metadata only. Nothing that checks or emits a program reads this file, and
+ * only `onejs-sl/tables` imports it, so it cannot change what any program
+ * compiles to. Each table is built by a call marked pure, so a bundle that
+ * imports `onejs-sl/tables` for BUILTINS alone (the Play editor's parser) drops
+ * all of it.
+ *
+ * The intrinsics carry the names the HLSL documentation gives them. Everything
+ * the library implements is named as `lib/*.hlsl` writes it, read by the
+ * translator into `src/lib/names.ts` when `npm run lib` runs, so there is no
+ * second list of those to drift: a builtin that lowers to a library helper takes
+ * that helper's names, and a shape's parameters are named after its function's
+ * parameters, in the slots `sl_sdfDistance` passes them in.
+ */
+
+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"
+
+/** One function of the helper library, as its source declares it. */
+export interface LibSignature {
+    name: string
+    params: ReadonlyArray<{ name: string; type: string }>
+    ret: string
+}
+
+/** Every function in the helper library, by `LIB_FUNCTIONS` index, overloads included. */
+export const LIB_SIGNATURES: readonly LibSignature[] = /* @__PURE__ */ LIB_FUNCTIONS.map((f, i) => ({
+    name: f.name,
+    params: f.params.map((type, j) => ({ name: LIB_PARAM_NAMES[i]![j]!, type })),
+    ret: f.ret,
+}))
+
+/** A library function's parameter names, the same for every overload of it. */
+function namesOf(fn: string): readonly string[] {
+    const found = LIB_SIGNATURES.filter((s) => s.name === fn).map((s) => s.params.map((p) => p.name).join(", "))
+    if (found.length === 0) throw new Error(`the library has no ${fn}`)
+    if (new Set(found).size > 1) throw new Error(`${fn}'s overloads name their parameters differently: ${found.join(" / ")}`)
+    return found[0]!.split(", ")
+}
+
+/** The HLSL documentation's names. */
+const INTRINSIC: Record<string, readonly string[]> = {
+    sin: ["x"], cos: ["x"], tan: ["x"], asin: ["x"], acos: ["x"], exp: ["x"], log: ["x"], sqrt: ["x"],
+    sign: ["x"], ceil: ["x"], round: ["x"], abs: ["x"], floor: ["x"], frac: ["x"], saturate: ["x"],
+    rcp: ["x"], normalize: ["x"], length: ["x"],
+    pow: ["x", "y"], min: ["x", "y"], max: ["x", "y"], clamp: ["x", "min", "max"], atan2: ["y", "x"],
+    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"],
+}
+
+/**
+ * The library helper each builtin lowers to (`emitBody` calls it, and a test
+ * checks that it does), and how many of its parameters an author writes: fbm's
+ * third, the kind, is the opcode's own.
+ */
+export const LIBRARY: Readonly<Record<string, [string, number]>> = {
+    toLinear: ["sl_toLinear", 1], hsv2rgb: ["sl_hsv2rgb", 1], luminance: ["sl_luminance", 1],
+    noise: ["sl_valueNoise", 1], simplex: ["sl_simplex", 1], voronoi: ["sl_voronoi", 1],
+    fbm: ["sl_fbm", 2], turbulence: ["sl_fbm", 2], ridged: ["sl_fbm", 2],
+    // The point; the shape's own parameters are SL_SDF_PARAM_NAMES.
+    sdf: ["sl_sdfDistance", 0],
+}
+
+/** The two the language defines itself, named as the EDSL's `sl.remap` and `sl.ramp` name theirs. */
+const MACRO: Record<string, readonly string[]> = {
+    remap: ["v", "fromMin", "fromMax", "toMin", "toMax"],
+    // At least two stops, and as many more as `max` allows.
+    ramp: ["t", "stop", "stop..."],
+}
+
+/**
+ * Each builtin's parameter names, one per argument up to its `max`; those past
+ * its `min` are optional. A name ending in `...` repeats up to `max`. `sdf` is
+ * written `sdf.circle(p, r)`: its entry names the point, and the shape's own
+ * parameters are `SL_SDF_PARAM_NAMES[shape]`.
+ */
+export const BUILTIN_PARAMS: Readonly<Record<string, readonly string[]>> = /* @__PURE__ */ Object.fromEntries(
+    Object.keys(BUILTINS).map((name) => {
+        const lib = LIBRARY[name]
+        if (name === "sdf") return [name, [namesOf(lib![0])[1]!]]
+        const names = INTRINSIC[name] ?? MACRO[name] ?? (lib && namesOf(lib[0]).slice(0, lib[1]))
+        if (names === undefined) throw new Error(`builtin ${name} has no parameter names in params.ts`)
+        return [name, names]
+    }),
+)
+
+/**
+ * Each shape's parameters, in the order `sdf.<shape>(p, ...)` takes them, named
+ * after its function's: a vector parameter's components as `b.x`, `b.y`.
+ */
+export const SL_SDF_PARAM_NAMES: Readonly<Record<SlSdfKind, readonly string[]>> = /* @__PURE__ */ shapeNames()
+
+function shapeNames(): Record<SlSdfKind, readonly string[]> {
+    const out = {} as Record<SlSdfKind, readonly string[]>
+    for (const shape of Object.keys(SL_SDF_SHAPES) as SlSdfKind[]) {
+        const call = SDF_CALLS[SL_SDF_SHAPES[shape]]!
+        // The function's first parameter is the point, which `sl_sdfDistance` passes itself.
+        const fn = namesOf(call.fn).slice(1)
+        const slots = new Array<string>(SL_SDF_PARAMS[shape])
+        call.args.forEach((arg, i) => {
+            const at = "int" in arg ? [arg.int] : arg
+            at.forEach((slot, j) => { slots[slot] = at.length === 1 ? fn[i]! : `${fn[i]}.${"xyzw"[j]}` })
+        })
+        out[shape] = slots
+    }
+    return out
+}

package/src/tables.ts

@@ -2,7 +2,8 @@
  * `onejs-sl/tables`: what completion and highlighting read.
  *
  * The same tables the checker and the emitters use, so an editor offers
- * exactly the builtins that compile, with the arities they take.
+ * exactly the builtins that compile, with the arities they take and the names
+ * of their parameters (`params.ts`), and the helper library's signatures.
  */
 export { BUILTINS, NOT_YET } from "./lang/builtins"
 export type { Builtin } from "./lang/builtins"
@@ -12,4 +13,6 @@ export {
 export type { SLSurface } from "./ops"
 export { INPUTS } from "./ir"
 export { SL_SDF_SHAPES, SL_SDF_PARAMS } from "./shapes"
+export { BUILTIN_PARAMS, LIB_SIGNATURES, SL_SDF_PARAM_NAMES } from "./params"
+export type { LibSignature } from "./params"
 export type { SlSdfKind } from "./shapes"