onejs-sl 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.1.10
+
+Attributes on uniforms, for a host's controls (`Specs/SL_NEXT.md` 1). A program that has none compiles to exactly what it did, and one that has them hashes as it would without.
+
+- `[Range]`, `[Toggle]`, `[Enum]`, `[Header]`, `[Label]`, `[Color]` and `[Hide]` before a uniform
+- `UniformDecl` carries `range`, `toggle`, `options`, `header`, `label` and `hide`, never hashed
+- `sl.uniform.float` and the rest take the same control as a last argument
+- `sl.uniform.colour` takes components as well as a hex string
+- `controlProblem` and `CONTROL_FIELDS` are exported from the core
+- `ATTRIBUTE_NAMES` and `ATTRIBUTE_DOCS` are exported from `onejs-sl/tables`
+- `classify` marks an attribute's name and a string
+
+## 0.1.9
+
+Two inputs built from the others (`Specs/SL_NEXT.md` 6), and a converter that carries more of a pasted shader over. A program that names neither input compiles to exactly what it did.
+
+- `texel` is one pixel in uv, and `centered` is uv with 0 at the centre and x scaled by aspect
+- A local, parameter or uniform named `texel` or `centered` keeps working
+- A local named after a builtin can be assigned to
+- `fromGLSL` reads `u_time` and `u_resolution` as the inputs, and drops their declarations
+- `fromGLSL` turns a mat2 rotation into `rotate()`, and points any other mat2 at it
+- `INPUT_DOCS` say `uv` and `fragCoord` are the centre of the pixel
+
 ## 0.1.8
 
 A pasted GLSL shader becomes a `.sl` file (`Specs/SL_NEXT.md` 5). Nothing a program compiles to changes.

package/README.md

@@ -345,8 +345,18 @@ reset takes the whole page's device, Unity's included.
 ## What a program is given
 
 `uv`, `fragCoord`, `resolution`, `time` and `aspect`, and the last three are the
-**target's**, not the window's. A program is drawn with `Graphics.Blit` into the
-element's own render texture, and Unity sets `_ScreenParams` per camera and
+**target's**, not the window's. `uv` and `fragCoord` are the centre of the pixel
+being drawn, so the first column's `fragCoord.x` is 0.5 on both backends.
+
+Two more are built from those: `texel`, one pixel in uv (`1 / resolution`), and
+`centered`, uv with 0 at the centre and x scaled by `aspect`, so a circle drawn
+in it stays round. They are recorded only when a program names them, so every
+program that does not compiles to the bytes it always did, and a program with a
+`texel` of its own keeps it: a local, a parameter or a uniform of that name
+shadows the input.
+
+Why `resolution` and `aspect` are the target's: a program is drawn with
+`Graphics.Blit` into the element's own render texture, and Unity sets `_ScreenParams` per camera and
 leaves it alone for a blit: reading it from a 64x256 target answers with the
 game view's size. Both backends read the same wrong thing, so they agreed with
 each other and the eject test, which compares them, saw nothing. What saw it was
@@ -357,6 +367,28 @@ sets `_Res` from the target and both backends read that.
 `fx` had already learned this: `ShaderEffectElement` sets `_Aspect` from the
 render texture with a comment saying why. The lesson did not travel.
 
+## Controls
+
+A uniform can say how a host should present it: `range` (a slider, with an
+optional `step`), `toggle`, `options` (a dropdown whose value is the index),
+`header`, `label` and `hide`, all on the `UniformDecl`. A `.sl` file writes them
+as Unity's attributes (`[Range(0, 2)] uniform float warp = 1;`), the EDSL as the
+last argument of `sl.uniform.float` and the rest. They are metadata: the hash
+never reads them, so two programs that differ only in a control share one
+compiled shader, and `toJSON` carries them for a host that stores a program.
+
+The generated shader's Properties block does not carry them, and that was
+measured rather than assumed (Unity 6000.5, 2026-09-27). Unity binds a material
+property by the HLSL variable's type, not the Properties type: a `float4`
+variable takes only `SetVector`, a `float` only `SetFloat`. Every uniform is a
+`float4` set with `SetVector`, so a `Range(0, 2)` property over one draws a
+slider whose default and every drag never reach the shader. A `Color` property
+is worse, since `SetVector` on one converts sRGB to linear and the program
+already converts a colour uniform. Carrying them means declaring a scalar
+control as `float`, with a matching Properties line (`[ToggleUI]`, since
+`[Toggle]` also defines a keyword; `[Enum]` as name, value pairs), and the bridge
+setting it with `SetFloat`. `Specs/SL_NEXT.md` 1 keeps that as a later change.
+
 ## Colours
 
 A hex colour is sRGB as written, the way CSS reads it, and the target holds

package/goldens/goldens.json

@@ -1,6 +1,6 @@
 {
  "generatedBy": "onejs-sl goldens/run.mjs",
- "package": "0.1.2",
+ "package": "0.1.10",
  "ir": 2,
  "target": "rgba8unorm-srgb: straight alpha, 8 bit, sRGB encoded, the stored bytes of a Linear OneJS game's element",
  "size": [
@@ -108,6 +108,14 @@
     "1.25": [255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255,255,128,64,255]
    }
   },
+  "inputs.sl": {
+   "hash": "07cd901a",
+   "source": "// texel and centered, the inputs built from the others (Specs/SL_NEXT.md 6).\n// A ring that stays round in any output shape, over cells 16 pixels wide.\nfloat4 main() {\n    float ring = smoothstep(0.02, 0.0, abs(length(centered) - 0.3));\n    float2 cell = frac(uv / (texel * 16.0));\n    return float4(ring, cell, 1);\n}\n",
+   "samples": {
+    "0": [0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,173,171,86,255,139,212,86,255,0,244,86,255,0,110,86,255,207,171,86,255,24,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,253,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,193,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,173,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,139,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,253,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,188,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,207,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,207,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,226,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,24,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,193,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,253,212,237,255,188,244,237,255,207,110,237,255,226,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255],
+    "1.25": [0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,173,171,86,255,139,212,86,255,0,244,86,255,0,110,86,255,207,171,86,255,24,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,253,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,193,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,173,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,139,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,253,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,188,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,207,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,207,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,226,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,24,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,193,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,253,212,237,255,188,244,237,255,207,110,237,255,226,171,237,255,0,212,237,255,0,244,237,255,0,110,237,255,0,171,237,255,0,212,237,255,0,244,237,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,202,255,0,171,202,255,0,212,202,255,0,244,202,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,158,255,0,171,158,255,0,212,158,255,0,244,158,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255,0,110,86,255,0,171,86,255,0,212,86,255,0,244,86,255]
+   }
+  },
   "orient.sl": {
    "hash": "f3b299ff",
    "source": "// An anchor: red is uv.x, green is uv.y, so a golden's orientation and its\n// linear-to-sRGB store can be checked against arithmetic, not against itself.\nfloat4 main() { return float4(uv.x, uv.y, 0, 1); }\n",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onejs-sl",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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/core.ts

@@ -11,9 +11,10 @@ export * as sl from "./sl"
 export type { Float, Vec2, Vec3, Vec4, Num, ProgramInputs, Texture } from "./sl"
 export {
     TYPE, INPUTS, MAX_TEXTURES, MAX_NODES, SLError, hashProgram, widthName, SL_IR_VERSION, inputsUsed,
+    CONTROL_FIELDS, controlProblem,
 } from "./ir"
 export type {
-    SLType, InputName, NodeRef, SLNode, Program, UniformDecl, TextureDecl,
+    SLType, InputName, NodeRef, SLNode, Program, UniformDecl, UniformControl, TextureDecl,
 } from "./ir"
 export { SLOP, SL_ARITY, SL_NAME, INPUT_ID, isSampling } from "./ops"
 export type { SLOpCode } from "./ops"

package/src/ir.ts

@@ -42,6 +42,27 @@ export const INPUTS = {
 } as const
 export type InputName = keyof typeof INPUTS
 
+/**
+ * Inputs a program can name that are built from the ones above rather than
+ * handed over by the host (`Specs/SL_NEXT.md` 6). Each read records the same
+ * few nodes a program would if it wrote the expression out, and the builder's
+ * hash consing makes every later read the same node. So there is no new
+ * instruction, no VM or host change, and a program that never names one holds
+ * no extra node, compiling to the bytes it always did.
+ *
+ *   texel     1 / resolution: one pixel, in uv
+ *   centered  (uv - 0.5) * float2(aspect, 1): 0 at the centre, circles stay round
+ */
+export const DERIVED_INPUTS = {
+    texel: TYPE.VEC2,
+    centered: TYPE.VEC2,
+} as const
+export type DerivedInputName = keyof typeof DERIVED_INPUTS
+
+/** Every input a program can name: the host's, then the derived ones. */
+export type SourceInputName = InputName | DerivedInputName
+export const SOURCE_INPUTS: Readonly<Record<SourceInputName, SLType>> = { ...INPUTS, ...DERIVED_INPUTS }
+
 /** Index into `Program.nodes`. Always refers backwards. */
 export type NodeRef = number
 
@@ -52,7 +73,86 @@ export type SLNode =
     | { k: "swizzle"; type: SLType; src: NodeRef; chans: number[] }
     | { k: "call"; type: SLType; op: SLOpCode; args: NodeRef[]; imm?: number[] }
 
-export interface UniformDecl {
+/**
+ * How a host presents a uniform: a slider, a checkbox, a dropdown, a heading
+ * above it, the name it shows, or no control at all (`Specs/SL_NEXT.md` 1).
+ * Written in a `.sl` file as Unity's attributes, `[Range(0, 2)]` and the rest,
+ * and in the EDSL as the last argument of `sl.uniform.float`.
+ *
+ * Metadata for a host, like `colour`: it changes nothing a program computes, so
+ * it is never part of the hash, and two programs that differ only in it share
+ * one compiled shader.
+ */
+export interface UniformControl {
+    /** A slider from `min` to `max`, moving by `step` when there is one. A float only. */
+    range?: { min: number; max: number; step?: number }
+    /** A checkbox. The value is 0 or 1. A float only. */
+    toggle?: true
+    /** A dropdown of these names. The value is the index of the chosen one. A float only. */
+    options?: string[]
+    /** A heading shown above this uniform's control, starting a group. */
+    header?: string
+    /** The name the control shows, in place of the uniform's own. */
+    label?: string
+    /** No control: the host sets this one from code. */
+    hide?: true
+}
+
+/** The fields of `UniformControl`, in the order a host reads them. */
+export const CONTROL_FIELDS = ["range", "toggle", "options", "header", "label", "hide"] as const
+
+/**
+ * What is wrong with giving a uniform of `type` and default `value` this
+ * control, or null. Names the field at fault, so the text form can mark the
+ * attribute that wrote it. The one check, for `.sl` files and the EDSL alike.
+ */
+export function controlProblem(type: SLType, value: readonly number[], c: UniformControl): { field: keyof UniformControl; message: string } | null {
+    const kinds = (["range", "toggle", "options"] as const).filter((k) => c[k] !== undefined)
+    if (kinds.length > 1) {
+        return { field: kinds[1]!, message: `a uniform is one control, so it cannot have both ${ATTRIBUTE_OF[kinds[0]!]} and ${ATTRIBUTE_OF[kinds[1]!]}` }
+    }
+    const kind = kinds[0]
+    if (kind !== undefined && type !== TYPE.FLOAT) {
+        return { field: kind, message: `${ATTRIBUTE_OF[kind]} is for a float, and this is a ${widthName(type)}` }
+    }
+    const v = value[0] ?? 0
+    if (c.range !== undefined) {
+        const { min, max, step } = c.range
+        if (![min, max].every(Number.isFinite) || !(min < max)) {
+            return { field: "range", message: `a range runs from a smaller number to a larger one, and this is ${min} to ${max}` }
+        }
+        if (step !== undefined && !(Number.isFinite(step) && step > 0)) {
+            return { field: "range", message: `a range's step is a number above 0, and this is ${step}` }
+        }
+        if (v < min || v > max) {
+            return { field: "range", message: `the default ${v} is outside the range ${min} to ${max}` }
+        }
+    }
+    if (c.toggle === true && v !== 0 && v !== 1) {
+        return { field: "toggle", message: `a toggle is 0 or 1, and the default is ${v}` }
+    }
+    if (c.options !== undefined) {
+        if (c.options.length < 2) return { field: "options", message: "an enum lists at least two options" }
+        const empty = c.options.findIndex((o) => o.trim() === "")
+        if (empty >= 0) return { field: "options", message: `option ${empty + 1} of the enum has no name` }
+        const twice = c.options.findIndex((o, i) => c.options!.indexOf(o) !== i)
+        if (twice >= 0) return { field: "options", message: `the enum lists "${c.options[twice]}" twice` }
+        if (!Number.isInteger(v) || v < 0 || v >= c.options.length) {
+            return { field: "options", message: `an enum's value is the index of an option, 0 to ${c.options.length - 1}, and the default is ${v}` }
+        }
+    }
+    for (const f of ["header", "label"] as const) {
+        if (c[f] !== undefined && c[f]!.trim() === "") return { field: f, message: `${ATTRIBUTE_OF[f]} needs some text` }
+    }
+    return null
+}
+
+/** How each field is written in a `.sl` file, for the messages above. */
+const ATTRIBUTE_OF: Record<keyof UniformControl, string> = {
+    range: "[Range]", toggle: "[Toggle]", options: "[Enum]", header: "[Header]", label: "[Label]", hide: "[Hide]",
+}
+
+export interface UniformDecl extends UniformControl {
     name: string
     type: SLType
     /** Default, used when a caller does not supply the uniform. */
@@ -161,7 +261,7 @@ export class Builder {
         return this.add({ k: "const", type: v.length as SLType, v: v.slice() })
     }
 
-    uniform(name: string, type: SLType, value: number[], colour = false): NodeRef {
+    uniform(name: string, type: SLType, value: number[], colour = false, control: UniformControl = {}): NodeRef {
         const existing = this.uniforms.findIndex((u) => u.name === name)
         if (existing >= 0) {
             const u = this.uniforms[existing]
@@ -171,10 +271,27 @@ export class Builder {
             if ((u.colour === true) !== colour) {
                 throw new SLError(`uniform "${name}" is declared both as a colour and as plain numbers`)
             }
+            // A second read may say nothing about the control, or the same thing again.
+            const merged = { ...controlOf(u) }
+            for (const f of CONTROL_FIELDS) {
+                if (control[f] === undefined) continue
+                if (merged[f] !== undefined && JSON.stringify(merged[f]) !== JSON.stringify(control[f])) {
+                    throw new SLError(`uniform "${name}" is given two different ${f === "options" ? "enums" : f + "s"}`)
+                }
+                Object.assign(merged, { [f]: control[f] })
+            }
+            const problem = controlProblem(type, u.value, merged)
+            if (problem !== null) throw new SLError(`uniform "${name}": ${problem.message}`)
+            Object.assign(u, merged)
             return this.add({ k: "uniform", type, slot: existing })
         }
+        const problem = controlProblem(type, value, control)
+        if (problem !== null) throw new SLError(`uniform "${name}": ${problem.message}`)
         const slot = this.uniforms.length
-        this.uniforms.push(colour ? { name, type, value: value.slice(), colour: true } : { name, type, value: value.slice() })
+        const decl: UniformDecl = { name, type, value: value.slice() }
+        if (colour) decl.colour = true
+        Object.assign(decl, controlOf(control))
+        this.uniforms.push(decl)
         return this.add({ k: "uniform", type, slot })
     }
 
@@ -317,6 +434,18 @@ export function hashProgram(nodes: SLNode[], result: NodeRef, uniforms: UniformD
     return fnv1a(parts.join("|"))
 }
 
+/** The control fields of `c` that are set, copied, in `CONTROL_FIELDS` order. */
+export function controlOf(c: UniformControl): UniformControl {
+    const out: UniformControl = {}
+    if (c.range !== undefined) out.range = c.range.step === undefined ? { min: c.range.min, max: c.range.max } : { ...c.range }
+    if (c.toggle === true) out.toggle = true
+    if (c.options !== undefined) out.options = c.options.slice()
+    if (c.header !== undefined) out.header = c.header
+    if (c.label !== undefined) out.label = c.label
+    if (c.hide === true) out.hide = true
+    return out
+}
+
 /** Bumped when the hashing scheme changes, which invalidates generated shaders. */
 export const SL_HASH_VERSION = 1
 

package/src/lang/README.md

@@ -121,7 +121,8 @@ the generated shader's Properties block shows, and every read of `tint` goes
 through `toLinear`. Without that rule, `#ff8040` written as a literal and
 `#ff8040` written as a default would be two different colours in one file.
 A default built out of numbers (`float4(1, 0.5, 0.25, 1)`) is not a colour and
-is read unconverted.
+is read unconverted, unless the uniform says `[Color]`, which makes it one
+exactly as a hex default does.
 
 **A uniform's default has to be written out.** Numbers, constructors of numbers
 and colours, and nothing else. It is baked into the program before anything
@@ -166,6 +167,26 @@ browser and correct after an eject. A `.sl` file is held to the real number, 4,
 reported at the declaration. The EDSL's ceiling is untouched here because
 lowering it changes recorded behaviour rather than parser behaviour.
 
+## Attributes
+
+Unity's names, before a uniform, say what its control is: `[Range(0, 2)]`, with
+an optional third number for the step, `[Toggle]`, `[Enum(Soft, Hard, Glow)]`,
+`[Header("Shape")]`, `[Label("Glow colour")]`, `[Color]` and `[Hide]`. They go
+on the uniform's line or the lines above it, in any order. A string exists only
+here, which is the one reason the lexer reads one.
+
+Three files share the work. The parser reads the shape (`[Name(args)]`, numbers,
+words and strings); `attributes.ts` says what each one means and refuses what it
+cannot mean, offering Unity's and English spellings as a fix (`Colour` to
+`Color`, `HideInInspector` to `Hide`); `controlProblem` in `ir.ts` refuses what
+does not fit the uniform's type and default, and is the same check the EDSL's
+`sl.uniform.float(name, value, control)` runs. The last one needs the default,
+so its errors come from lowering, marked on the attribute at fault.
+
+What they produce is metadata on the uniform (`range`, `toggle`, `options`,
+`header`, `label`, `hide`), which the hash never reads. `[Color]` is the
+exception, because it changes the reads: it is the same as a hex default.
+
 ## Errors
 
 Every one carries file, line, column, offset and length, and `text`, the
@@ -204,14 +225,15 @@ same place, over every program one token short of a real one.
 ## For an editor
 
 `classify(source)` is every token with its class (keyword, type, builtin,
-input, prelude, number, hex, comment, punct, member, ident, or invalid), built
+input, prelude, number, hex, string, comment, punct, member, attribute, ident,
+or invalid), built
 on the parser's own scanner and word lists, so the highlighting is the parser's.
 It never throws, since it runs on every keystroke. It classifies by spelling,
 not scope: a local named `circle` still reads as a builtin where it is used.
 
 `SL_KEYWORDS` and `SL_TYPES` (`words.ts`) are the lists the parser reads, and a
-name may be neither. `onejs-sl/tables` carries them with a one line description
-of every builtin, input and prelude function; a prelude function's is the
+name may be neither. `onejs-sl/tables` carries them, and `ATTRIBUTE_NAMES`, with
+a one line description of every builtin, input, attribute and prelude function; a prelude function's is the
 comment above it in `prelude-source.ts`.
 
 ## From GLSL
@@ -234,7 +256,18 @@ where they were, so the result reads as the shader it came from. What it does:
   same. Shadertoy's `uv = fragCoord / iResolution.xy` line is dropped, since
   that is the input `uv`.
 - `iResolution`, `iMouse`, `iChannel0` to `3` and `uniform sampler2D` become
-  `resolution`, a `mouse` uniform and declared textures. `#define NAME value`
+  `resolution`, a `mouse` uniform and declared textures. The Book of Shaders'
+  `u_time` and `u_resolution`, glslsandbox's `time` and `resolution`, and
+  Shadertoy's own inputs where a tool declares them are the inputs: their
+  `uniform` declarations go, so the shader does not arrive frozen.
+- A mat2 rotation becomes `rotate(p, angle)`: a function or macro returning
+  `mat2(c, -s, s, c)` or `mat2(c, s, -s, c)` of one angle, or the same written
+  in place, wherever a vector is multiplied by it (`p *= rot(a)`,
+  `rot(a) * p`, `p * rot(a)`). The sign of the angle comes from the matrix and
+  from which side the vector is on, since GLSL fills a matrix by columns. The
+  function or macro goes once every use is converted; otherwise it stays, and
+  the notes point at `rotate()`. A file with a `rotate` of its own is left
+  alone, since the calls would reach it. `#define NAME value`
   becomes a const; any other directive is kept as a comment, with a note.
 - A name the language already means something by gets a `_` suffix, and an
   `int` becomes a float (a for-loop counter stays an int), each with a note.

package/src/lang/ast.ts

@@ -63,11 +63,28 @@ export interface FuncDecl {
     prelude: boolean
 }
 
+/** An argument to an attribute: a number, a quoted string, or a bare word. */
+export type AttributeArg =
+    | { k: "num"; value: number; pos: Pos; length: number }
+    | { k: "str"; text: string; pos: Pos; length: number }
+    | { k: "ident"; name: string; pos: Pos; length: number }
+
+/** `[Range(0, 2)]` before a uniform: Unity's spelling of what its control is. */
+export interface Attribute {
+    name: string
+    args: AttributeArg[]
+    /** Where the name starts, and how long it is, for a marker. */
+    pos: Pos
+    length: number
+}
+
 export interface UniformDecl {
     name: string
     type: TypeName
     /** Null when the declaration gave no default; the slot then starts at zero. */
     init: Expr | null
+    /** In the order written. What each means is decided by the checker, not the parser. */
+    attrs: Attribute[]
     pos: Pos
 }
 

package/src/lang/attributes.ts

@@ -0,0 +1,116 @@
+/**
+ * A uniform's attributes, read into what its control is (`Specs/SL_NEXT.md` 1).
+ *
+ * Unity's names, so a Unity developer already knows them: `[Range(0, 2)]`,
+ * `[Toggle]`, `[Enum(Soft, Hard, Glow)]`, `[Header("Shape")]`,
+ * `[Label("Glow colour")]`, `[Color]` and `[Hide]`. The parser reads their
+ * shape only; this says what each one means and what is wrong with it, for the
+ * checker to report and for lowering to build. What depends on the default
+ * (a default outside its range, say) is `controlProblem`'s, which the EDSL
+ * shares.
+ */
+
+import type { UniformControl } from "../ir"
+import { TYPE_WIDTH, type Attribute, type AttributeArg, type UniformDecl } from "./ast"
+import type { Pos, SLFix } from "./lexer"
+
+export interface AttributeProblem {
+    message: string
+    pos: Pos
+    length: number
+    fix?: SLFix
+}
+
+export interface ReadAttributes {
+    /** Every attribute that could be read. One that could not is left out, and is in `problems`. */
+    control: UniformControl
+    /** `[Color]`: the value is a colour as written, the same as a hex default. */
+    colour: boolean
+    /** The attribute that wrote each field, to mark when the default does not fit it. */
+    from: Partial<Record<keyof UniformControl, Attribute>>
+    problems: AttributeProblem[]
+}
+
+/** Every attribute, in the order the docs list them. */
+export const ATTRIBUTE_NAMES = ["Range", "Toggle", "Enum", "Header", "Label", "Color", "Hide"] as const
+export type AttributeName = (typeof ATTRIBUTE_NAMES)[number]
+
+/** Spellings from Unity, from other engines, or from English, that mean one of ours. */
+const ALIASES: Record<string, AttributeName> = {
+    Colour: "Color", HideInInspector: "Hide", ToggleUI: "Toggle", KeywordEnum: "Enum", IntRange: "Range",
+}
+
+const LIST = "Range, Toggle, Enum, Header, Label, Color and Hide"
+
+export function readAttributes(u: UniformDecl): ReadAttributes {
+    const out: ReadAttributes = { control: {}, colour: false, from: {}, problems: [] }
+    const seen = new Set<string>()
+    const problem = (at: Attribute | AttributeArg, message: string, fix?: SLFix) => {
+        out.problems.push({ message, pos: at.pos, length: at.length, ...(fix === undefined ? {} : { fix }) })
+    }
+    const text = (a: AttributeArg): string | null => a.k === "str" ? a.text : a.k === "ident" ? a.name : null
+    const none = (a: Attribute) => {
+        if (a.args.length === 0) return true
+        problem(a.args[0]!, `[${a.name}] takes no arguments`)
+        return false
+    }
+    const one = (a: Attribute, what: string): string | null => {
+        const t = a.args.length === 1 ? text(a.args[0]!) : null
+        if (t === null) problem(a.args[0] ?? a, `[${a.name}] takes ${what} in quotes, as in [${a.name}("${a.name === "Header" ? "Shape" : "Glow colour"}")]`)
+        return t
+    }
+
+    for (const a of u.attrs) {
+        const known = (ATTRIBUTE_NAMES as readonly string[]).includes(a.name)
+        if (!known) {
+            const to = ALIASES[a.name] ?? ATTRIBUTE_NAMES.find((n) => n.toLowerCase() === a.name.toLowerCase())
+            const hint = a.name === "IntRange" ? "; a whole number slider is [Range(min, max, 1)]" : ""
+            problem(a, `"${a.name}" is not an attribute; the attributes are ${LIST}${to === undefined ? "" : `. Did you mean ${to}?`}${hint}`,
+                to === undefined || a.name === "IntRange" ? undefined : { title: `Replace ${a.name} with ${to}`, replacement: to })
+            continue
+        }
+        if (seen.has(a.name)) { problem(a, `this uniform already has [${a.name}]`); continue }
+        seen.add(a.name)
+        switch (a.name) {
+            case "Range": {
+                const n = a.args.map((x) => x.k === "num" ? x.value : null)
+                if ((n.length !== 2 && n.length !== 3) || n.includes(null)) {
+                    problem(a, "[Range] takes a minimum, a maximum and an optional step, all numbers: [Range(0, 1)] or [Range(1, 16, 1)]")
+                    break
+                }
+                out.control.range = n.length === 3 ? { min: n[0]!, max: n[1]!, step: n[2]! } : { min: n[0]!, max: n[1]! }
+                out.from.range = a
+                break
+            }
+            case "Toggle":
+                if (none(a)) { out.control.toggle = true; out.from.toggle = a }
+                break
+            case "Enum": {
+                const num = a.args.find((x) => x.k === "num")
+                if (num !== undefined) {
+                    problem(num, "[Enum] lists names only, as in [Enum(Soft, Hard, Glow)]; the value is the chosen name's index, from 0")
+                    break
+                }
+                out.control.options = a.args.map((x) => text(x)!)
+                out.from.options = a
+                break
+            }
+            case "Header":
+            case "Label": {
+                const t = one(a, a.name === "Header" ? "a heading" : "a name")
+                const f = a.name === "Header" ? "header" : "label"
+                if (t !== null) { out.control[f] = t; out.from[f] = a }
+                break
+            }
+            case "Color":
+                if (!none(a)) break
+                if (TYPE_WIDTH[u.type] < 3) problem(a, `[Color] is for a float3 or a float4, and this is a ${u.type}`)
+                else out.colour = true
+                break
+            case "Hide":
+                if (none(a)) { out.control.hide = true; out.from.hide = a }
+                break
+        }
+    }
+    return out
+}

package/src/lang/check.ts

@@ -28,15 +28,22 @@
  * is refused with the reason.
  */
 
-import { INPUTS } from "../ir"
+import { DERIVED_INPUTS, INPUTS } from "../ir"
 import { VM_TEXTURES, VM_UNIFORMS } from "../ops"
 import { SL_GLSL_HINT } from "../ops"
 import { BUILTINS, NOT_YET } from "./builtins"
 import { SL_SDF_SHAPES } from "../shapes"
 import type { Expr, FuncDecl, Stmt, Unit } from "./ast"
+import { readAttributes } from "./attributes"
 import { SLParseError, type Pos, type SLFix } from "./lexer"
 
 const INPUT_NAMES = new Set(Object.keys(INPUTS))
+/**
+ * Inputs built from the others (`texel`, `centered`). A declaration may take
+ * one's name, as it may a builtin's, because programs wrote their own `texel`
+ * long before the language had one, and that must keep compiling.
+ */
+const DERIVED_NAMES = new Set(Object.keys(DERIVED_INPUTS))
 
 /**
  * The GLSL spellings whose HLSL name means the same wherever it is written, so
@@ -133,13 +140,14 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         if (uniforms.has(n)) return "a uniform"
         if (textures.has(n)) return "a texture"
         if (consts.has(n)) return "a const"
+        if (DERIVED_NAMES.has(n)) return "a derived input"
         return 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
+        if (why !== null && why !== "a builtin" && why !== "a derived input") return why
         const fn = funcs.get(n)
         return fn !== undefined && !fn.prelude ? "a function" : null
     }
@@ -149,6 +157,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
             const clash = valueClash(u.name)
             if (clash !== null) fail(`"${u.name}" already names ${clash}`, u.pos, u.name.length)
         })
+        for (const p of readAttributes(u).problems) attempt(() => fail(p.message, p.pos, p.length, p.fix))
         if (!uniforms.has(u.name)) uniforms.set(u.name, u)
     }
     attempt(() => {
@@ -220,7 +229,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
         if (main.params.length > 0) {
             fail(
                 "main takes no parameters: what a program is given are the free identifiers uv, " +
-                "fragCoord, resolution, time and aspect",
+                "fragCoord, resolution, time, aspect, texel and centered",
                 main.params[0]!.pos,
             )
         }
@@ -365,7 +374,9 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
                     }
                     if (target.k !== "ident") fail("only a local can be assigned to", target.pos)
                     const n = target.name
-                    const why = taken(n)
+                    // A local shadows what it is named after, a builtin or a
+                    // derived input, so it is assignable like any other local.
+                    const why = scope.has(n) ? null : taken(n)
                     if (why !== null) fail(`"${n}" is ${why} and cannot be assigned to`, target.pos, n.length)
                     if (counters.has(n)) {
                         fail(
@@ -423,7 +434,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
             case "hex":
                 return
             case "ident": {
-                if (scope.has(e.name) || INPUT_NAMES.has(e.name) || uniforms.has(e.name) || consts.has(e.name)) return
+                if (scope.has(e.name) || INPUT_NAMES.has(e.name) || DERIVED_NAMES.has(e.name) || uniforms.has(e.name) || consts.has(e.name)) return
                 if (textures.has(e.name)) {
                     fail(
                         `"${e.name}" is a texture, and a texture is only ever the first argument of ` +
@@ -581,7 +592,7 @@ export function check(unit: Unit, prelude: FuncDecl[], options: CheckOptions = {
     /** Refuses a name nothing declares, offering the nearest one spelled almost like it. */
     function unknown(n: string, scope: Set<string>, pos: Pos): never {
         const near = nearest(n, [
-            ...scope, ...INPUT_NAMES, ...uniforms.keys(), ...textures.keys(), ...consts.keys(),
+            ...scope, ...INPUT_NAMES, ...DERIVED_NAMES, ...uniforms.keys(), ...textures.keys(), ...consts.keys(),
             ...funcs.keys(), ...Object.keys(BUILTINS),
         ])
         if (near === null) fail(`"${n}" is not declared`, pos, n.length)