onejs-sl 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+The shader language compiler as its own package, moved out of `onejs-unity` with its history and its tests. It behaves exactly as `onejs-unity` 0.5.15's `sl` did, at IR version 2 and VM wire version 2.
+
+- Entry points `onejs-sl`, `/core`, `/tables`, `/limits`, `/vm`, `/emit/unity` and `/emit/web`
+- `vmFit` says whether the VM runs a program, and why not, without encoding it
+- `parseColor` is exported from `onejs-sl/core`
+- The test suite also runs in QuickJS-ng and must match Node byte for byte

package/README.md

@@ -0,0 +1,266 @@
+# onejs-sl
+
+The OneJS shader language: a small typed language for per pixel programs. A
+program is written as a `.sl` file (HLSL text) or with the TypeScript form, and
+recorded as one portable IR, a flat typed graph with a hash. The package emits
+that IR as the buffer OneJS's VM evaluates, a Unity ShaderLab shader, WGSL and
+GLSL ES.
+
+It is the compiler [OneJS](https://onejs.com) uses, taken out of `onejs-unity`
+so a host without Unity can run it too. `onejs-unity/sl` and
+`onejs-unity/sl/compiler` re-export it, so nothing in a OneJS project imports
+this package directly. User documentation is the
+[shader language guide](https://onejs.com/docs/guides/shader-language); this
+file is the design.
+
+```ts
+import { parse, sl } from "onejs-sl"
+
+const ripple = parse(`float4 main() {
+    float v = sin(length(uv - 0.5) * 40 - time * 4);
+    return float4(v * 0.5 + 0.5, 0, 0, 1);
+}`, { file: "ripple.sl" })
+
+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)
+})
+```
+
+## Entry points
+
+`"sideEffects": false`, and each backend is its own entry, so a host bundles
+only what it calls.
+
+| Entry | Contents |
+|---|---|
+| `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/limits` | `vmFit(program)`: whether the VM runs it, and why not, without encoding |
+| `onejs-sl/vm` | `encode`, `SL_WIRE_VERSION` |
+| `onejs-sl/emit/unity` | `emitShader`: the `.shader` a Unity editor generates |
+| `onejs-sl/emit/web` | `emitWGSL`, `emitGLSL`: OneJS's web frame |
+
+`src/entries.test.ts` pins every name, since removing one breaks a host.
+
+## Runs anywhere ES2020 runs
+
+The source reaches for no host API: no `fs`, `process`, `Buffer`,
+`TextEncoder`, `performance`, `structuredClone` or `Intl`. It runs in a
+browser (the Play editor's diagnostics), a Cloudflare worker (the Play build)
+and QuickJS (Magerie). Two checks hold it to that:
+
+- lint refuses those globals and any Node module in `src/`;
+- `npm run test:quickjs` bundles `quickjs/corpus.ts` as one ES2020 IIFE, the
+  way Magerie bundles a script, runs it in QuickJS-ng and in a bare Node
+  context, and fails unless the two results agree byte for byte. The corpus
+  parses, encodes, fits and emits every program in `quickjs/corpus/`, every
+  shape at its full parameter count, and the error paths. `npm test` runs it
+  after vitest.
+
+## Releasing
+
+Push a tag `v<version>` matching `package.json`; `.github/workflows/publish.yml`
+publishes through npm trusted publishing (OIDC), so no token exists anywhere.
+Note the release in `CHANGELOG.md` first. The one exception is the first version: npm
+attaches a trusted publisher to a package that already exists, so 0.1.0 was
+published by hand, and the workflow checks its tag and publishes nothing. In the OneJS container this package
+is checked out at `JSModules/onejs-sl`, and `onejs-unity` links it with
+`file:../onejs-sl` as a dev dependency beside its `^` peer range.
+
+## The one idea
+
+**One authoring surface, one IR, two backends.** Unity cannot compile a shader
+at runtime in a player build, on any graphics API, so in the browser a program
+has to become data that a fixed shader evaluates. Ejecting to a Unity project
+does not change what the author wrote, it changes what is possible, because an
+editor compiles shaders at build time.
+
+So the same source is interpreted by a VM on play.onejs.com and compiled from
+generated HLSL after an eject, with no edit in between. Both backends exist:
+`encode.ts` feeds OneJS's `Runtime/SL/SLProgramBridge.cs` and `FxProgram.shader`,
+and `hlsl.ts` feeds its `Editor/SLShaderGenerator.cs`. Nobody writes a manifest for the
+second: an editor that interprets a program asks the encoded program for its
+`hlsl` (a lazy getter, never read in Play), records it into
+`Assets/OneJS.Generated/Shaders/Recorded.sl.json`, generates the shader and
+moves the live material onto it. `manifest()` is still there for an app that
+would rather write its programs out at build time.
+
+**A third and fourth backend, for the browser.** A player cannot compile a
+shader, but the page it runs in can. `web.ts` prints every program as WGSL and
+as GLSL ES 3.00 (`weblib.ts` holds the noise, colour and 42 distance functions
+ported from `SLCommon.cginc`, `Noise2D.cginc` and `SDF2D.cginc`), and OneJS's
+`Plugins/WebGL/OneJSSLWeb.jslib` compiles whichever one Unity's device speaks
+and draws it into the element's target in place of the VM. A `.sl` import
+carries both strings, printed at build time; an `encode()` result has them as
+lazy getters, like `hlsl`. The VM draws until the compiled program is ready,
+and for good if it fails to compile. The host contract (the frame block, the
+16 uniform slots, one binding pair per sampled texture) is written out at the
+top of `web.ts`.
+
+The emitters match the HLSL emitter's semantics rather than each language's
+own: `%` truncates like `fmod`, `pow` takes `abs` of its base, `asin` and
+`acos` clamp, `log` and `sqrt` guard their argument, a select is the VM's
+branchless `lerp`. `web.test.ts` checks the structure (every shape, every
+opcode, the library order); whether the output matches the VM within 1/255 is
+measured in a browser, through the real element, by `Tools/sl-web-parity` in
+the container.
+
+## Two ways to write one
+
+A `.sl` file is HLSL text and `sl.program` is a TypeScript EDSL, and they record
+the same graph: a file lowers THROUGH the EDSL, so `sin(x)` and `sl.sin(x)` are
+one call. `lang/` is the parser and `lang/README.md` covers it; the rest of this
+file is the IR, the hash and the EDSL, which both surfaces sit on.
+
+```hlsl
+float4 main() {
+    float2 p = uv * 8 + time * 0.4;
+    float v = sin(p.x) + sin(p.y);
+    return float4(v * 0.5 + 0.5, 0, 0, 1);
+}
+```
+
+Docs lead with the file. The EDSL is the programmatic form: the IR builder, the
+parser's target, and what a program built by code uses.
+
+## Why an EDSL came first
+
+A TypeScript EDSL inherits completion, type errors at the call site, jump to
+definition, rename and the author's editor for free. Monaco in the Play editor
+already has these types loaded.
+
+It also gives common subexpression elimination for nothing, which is the most
+valuable optimisation here, because **a `const` in the host language IS the
+shared node**. `const p = uv.mul(8)` used three times is one node with three
+references, and writing it out long hand three times costs exactly the same,
+because nodes are interned as they are built.
+
+That reasoning is why the parser, when it came, cost only a parser: it emits
+this same IR, so it inherited the encoder, the emitter, the hash and every test
+that runs on a program.
+
+## What is checked, and when
+
+Everything an author can get wrong is refused **when the program is written**,
+at module load, not at draw time:
+
+| Mistake | What happens |
+|---|---|
+| `vec2` combined with a `vec3` | TypeScript error at the call site, and a runtime error behind it |
+| `uv.z` on a two component value | "z is component 3 of a vec2, which has 2" |
+| A program returning something other than a `vec4` | "a program must return a vec4. Wrap it: sl.vec4(value, 1)" |
+| `vec4` given the wrong number of parts | "vec4 needs 4 components, got 3" |
+| One uniform name at two widths | "declared as both a float and a vec4" |
+| More than 15 textures | Names the limit and why it cannot be widened |
+| A value borrowed from another program | "a value from another program cannot be used in this one" |
+
+The texture ceiling is the fragment shader's sampler slots on the WebGL2
+baseline, which is the one resource neither backend can widen.
+
+## The hash is the fragile part
+
+`Program.hash` is what will link a program to its compiled shader. If it differs
+between the machine that generated the shader and the machine that runs it, the
+runtime falls back to the VM and **nobody is told**: correct output, quietly
+slow, no error. That is the worst failure this design can have.
+
+So it is a Merkle hash over the graph reachable from the result, not a walk of
+the node array. An earlier version hashed storage order, which meant hoisting a
+shared subexpression into a `const` changed the hash without changing what the
+program computed. Constants go through a fixed precision, so `0.1 + 0.2` and
+`0.3` do not produce different shaders. It is eight lowercase hex characters
+from FNV-1a, chosen so a C# implementation can produce the same string rather
+than for any cryptographic reason.
+
+## Versions
+
+Two numbers, with one rule: a reader accepts every version up to its own and
+refuses a newer one with a message naming both.
+
+- **`SL_IR_VERSION`** (`ir.ts`) is on every `Program` and in the hash, and is
+  bumped whenever an opcode, a shape or what one computes changes. Because it
+  is in the hash, a bump recompiles every cached shader. `toJSON` and
+  `fromJSON` (`serial.ts`) are the IR as JSON for a host that stores programs;
+  `fromJSON` checks everything an emitter relies on, refuses a newer version,
+  and migrates an older one.
+- **`SL_WIRE_VERSION`** (`ops.ts`) is the newest VM encoding, and
+  `SLProgramBridge.WireVersion` in OneJS must match it (a container test
+  compares the two). `Encoded.wire`, and the `wire` in a `.sl` import, is the
+  LOWEST version that can run that program, so a program using nothing new
+  stays 1 and still runs on an older Play container. The VM refuses a newer
+  one, only where the VM runs; a WebGL player draws compiled and never reads
+  the buffer.
+
+IR 2 and wire 2 came with #129. A shape takes as many parameters as it reads
+(`SL_SDF_PARAMS`, six at most, and never fewer than four accepted), where it
+used to take four and lose the rest. One instruction holds a shape id and four
+immediates, so the encoder's `forVm` turns a shape given a fifth or sixth into
+`SDF_WIDE`, which reads the remaining four from a constant register. Only the
+VM sees it, and only those programs are wire 2.
+
+## Control flow
+
+There is none in the IR, deliberately. `sl.select`, `sl.step`, `sl.smoothstep` and
+`sl.mix` cover branching without branching, and `sl.repeat(n, body, seed)`
+unrolls at record time because `n` is a JavaScript number.
+
+`repeat` is honest about being a macro rather than 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: the VM 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 the whole design protects.
+Because it unrolls, the count multiplies the body's operation count toward the
+VM's 256-instruction ceiling. The ceiling error names any `repeat` that fills a
+quarter of the budget or more, so the fix reads as "lower this count" rather
+than "fewer instructions".
+
+Every loop that reaches a GPU is therefore bounded by a constant: `repeat` is
+unrolled, fbm's octaves are a constant 1 to 4, the helper loops in the noise
+and Voronoi functions have fixed trip counts. No program can hang a GPU today,
+so the compiled backends carry no loop cap. A data dependent loop (the
+raymarching tier) would need one emitted into every loop it prints, since a GPU
+reset takes the whole page's device, Unity's included.
+
+## See also
+
+- `Specs/SHADER_LANG.md` in the OneJS container, sections 3 and 4, and section 5.4 for the Phase 0
+  measurements that decided the VM's shape
+- `Tools/shader-vm-spike/`, the harness behind those numbers
+- `onejs-unity`'s `fx`, the image pipeline this becomes a source and an operand for
+
+## 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
+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
+a picture, because aspect correction, the one thing `aspect` exists for,
+stretched every circle by the shape of whatever window it was in. The host now
+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.
+
+## Colours
+
+A hex colour is sRGB as written, the way CSS reads it, and the target holds
+linear light. `sl.ramp` mixes its stops in sRGB, which is what reads as an even
+ramp, and converts the result once through `TO_LINEAR`; `sl.color("#hex")` is
+`parseColor` plus that conversion, and `sl.toLinear` is the conversion on its
+own for a vec4 built from raw components. Both backends implement it gamma
+aware (`sl_toLinear` in `SLCommon.cginc`), so a Gamma project gets the value as
+written. Alpha is coverage and is never converted. Same rule as `fx`.
+
+## Noise
+
+`sl.noise`, `sl.simplex`, `sl.fbm(p, octaves, base)`, `sl.turbulence` and
+`sl.ridged` are the fields `fx.noise` draws, from the same `Noise2D.cginc`, so
+a simplex here is the simplex there. Octaves are 1 to 4. A program has no seed;
+offset the input for a different field. `sl.simplex` used to be value noise on
+a rotated lattice, and `sl.fbm` had its own value noise; both changed on
+2026-09-06 when the fields were unified.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "onejs-sl",
+  "version": "0.1.0",
+  "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",
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core.ts",
+    "./tables": "./src/tables.ts",
+    "./limits": "./src/limits.ts",
+    "./vm": "./src/vm.ts",
+    "./emit/unity": "./src/emit/unity.ts",
+    "./emit/web": "./src/emit/web.ts"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/fixtures",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "onejs",
+    "shader",
+    "shading-language",
+    "hlsl",
+    "wgsl",
+    "glsl",
+    "compiler",
+    "sdf",
+    "noise",
+    "procedural"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Singtaa/onejs-sl.git"
+  },
+  "homepage": "https://onejs.com/docs/guides/shader-language",
+  "author": "Singtaa",
+  "license": "MIT",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run && node quickjs/run.mjs",
+    "test:quickjs": "node quickjs/run.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@jitl/quickjs-ng-wasmfile-release-sync": "^0.32.0",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "eslint": "^10.9.1",
+    "globals": "^17.11.0",
+    "quickjs-emscripten-core": "^0.32.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/color.ts

@@ -0,0 +1,16 @@
+/**
+ * "#rgb", "#rrggbb" or "#rrggbbaa" to 0..1 components.
+ *
+ * Shared by `sl` and `fx`, so a colour is written the same way in a program
+ * and in an image chain and neither has to import the other.
+ */
+export function parseColor(hex: string): [number, number, number, number] {
+    const m = /^#([0-9a-fA-F]{3,8})$/.exec(hex.trim())
+    if (m === null) throw new Error(`"${hex}" is not a colour; use #rgb, #rrggbb or #rrggbbaa`)
+    const h = m[1]!
+    const grab = (i: number, n: number) => parseInt(n === 1 ? h[i]! + h[i]! : h.slice(i * 2, i * 2 + 2), 16) / 255
+    if (h.length === 3) return [grab(0, 1), grab(1, 1), grab(2, 1), 1]
+    if (h.length === 6) return [grab(0, 2), grab(1, 2), grab(2, 2), 1]
+    if (h.length === 8) return [grab(0, 2), grab(1, 2), grab(2, 2), grab(3, 2)]
+    throw new Error(`"${hex}" is not a colour; use #rgb, #rrggbb or #rrggbbaa`)
+}

package/src/core.ts

@@ -0,0 +1,24 @@
+/**
+ * `onejs-sl/core`: a program and nothing that reads source text.
+ *
+ * The TypeScript form, the IR, its version and its JSON, the opcode and shape
+ * tables. What a game needs at run time, which is why OneJS's `onejs-unity/sl`
+ * is built on this entry and not on `onejs-sl`: the eject scaffold vendors
+ * every file an entry reaches, and the parser is two thousand lines a played
+ * game never executes.
+ */
+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,
+} from "./ir"
+export type {
+    SLType, InputName, NodeRef, SLNode, Program, UniformDecl, TextureDecl,
+} from "./ir"
+export { SLOP, SL_ARITY, SL_NAME, INPUT_ID, isSampling } from "./ops"
+export type { SLOpCode } from "./ops"
+export { SL_SDF_SHAPES, SL_SDF_PARAMS } from "./shapes"
+export type { SlSdfKind } from "./shapes"
+export { toJSON, fromJSON } from "./serial"
+export type { ProgramJSON } from "./serial"
+export { parseColor } from "./color"

package/src/emit/unity.ts

@@ -0,0 +1,3 @@
+/** `onejs-sl/emit/unity`: the ShaderLab `.shader` a Unity editor generates for a program. */
+export { emitShader, emitFragmentBody, uniformProperty } from "../hlsl"
+export type { EmitOptions } from "../hlsl"

package/src/emit/web.ts

@@ -0,0 +1,3 @@
+/** `onejs-sl/emit/web`: WGSL and GLSL ES 3.00 in OneJS's web frame, for a browser to compile. */
+export { emitGLSL, emitWGSL, WEB_UNIFORM_SLOTS } from "../web"
+export type { WebLanguage } from "../web"