tjs-lang 0.9.0 → 0.9.1

package/docs/type-system-north-star.md

@@ -0,0 +1,100 @@
+# North star: JSON-Schema + predicates as the single source of truth for types
+
+> **Status: strategic direction (2026-07-06, user-set). Possibly post-1.0. Use as
+> a decision lens NOW.** Related: `$predicate` keyword
+> (`src/lang/predicate-schema.ts`), `createPredicateEvaluator`, the `tjs-lang/css`
+> library, `docs/ambient-contracts.md`, PRINCIPLES.md.
+
+## The principle
+
+**A TJS type is, canonically, a JSON-Schema node — optionally carrying a
+`$predicate` (a verified-pure predicate cluster) for the computational part that
+plain JSON-Schema can't express.** Everything else — examples-as-types (`x: 0`),
+TS-derived types, `Type`/`Generic` declarations, `TypeDescriptor` — is **surface
+syntax or an internal projection** of that one canonical form, not a competing
+source of truth.
+
+- **Structure** (shape, required keys, enums, ranges, nesting) → JSON-Schema
+  keywords, which any validator understands.
+- **Computation** (open value grammars, cross-field invariants, recursive
+  grammars — the things TS/JSON-Schema cave to `string`/`any` on) → `$predicate`,
+  which a predicate-aware validator runs.
+
+Together they express the full range of what TJS types mean, in a **standard,
+serializable, inspectable, cross-language** form.
+
+## The decision lens
+
+For any architecture or implementation choice, ask:
+
+> **Does this move types toward — or away from — being fully expressible as
+> JSON-Schema + `$predicate`?**
+
+Concretely, *toward* looks like:
+
+- New type capabilities are added by (a) a JSON-Schema keyword, or (b) a
+  predicate — never a bespoke `TypeDescriptor` field that can't round-trip to
+  JSON-Schema + `$predicate`.
+- `TypeDescriptor` is treated as a **lossless projection** of the canonical form
+  (a convenient in-memory shape), not a superset. If something can live in
+  `TypeDescriptor` but not in JSON-Schema + `$predicate`, that's a smell.
+- `.d.ts` emission, runtime validation, inference, and autocomplete all **derive
+  from** the canonical form rather than from a parallel representation.
+- The predicate subset stays **small and portable** (see below) so `$predicate`
+  can run anywhere — expanding it is a cost, not a free win.
+
+*Away* looks like: a TJS-only internal type IR that accretes features JSON-Schema
++ `$predicate` can't carry; validation logic that only the JS runtime can do;
+predicate features that need a full JS engine.
+
+## Why this is the right endgame
+
+- **Types as data.** JSON-Schema + `$predicate` is just JSON — it travels, it's
+  inspectable, it's diffable, it survives a network hop or a file. Types stop
+  being a compile-time-only artifact.
+- **Cross-language by construction.** Any language with a JSON-Schema validator
+  gets TJS *structure* for free; add a small predicate VM (below) and it gets the
+  *computational* half too. TJS types become a contract multiple runtimes share.
+- **Standard, not bespoke.** We ride the JSON-Schema ecosystem (tooling, docs,
+  editors) instead of reinventing it, and add exactly the one thing it lacks.
+- **It's already real.** `tjs-lang/css` is a working JSON-Schema + `$predicate`
+  artifact; `tosijs-schema` (via `createPredicateEvaluator`) already runs it;
+  `cssStyleSchema()` produces exactly this shape. The endgame exists in miniature.
+
+## The priority that unlocks it: a small, portable predicate VM
+
+For "types across language boundaries" to be real, `$predicate` must **run
+anywhere**, not just in JS. The priority is a **reference implementation of a tiny,
+portable VM that safely evaluates the predicate subset** — ideally smaller than a
+JS runtime, implementable in a few hundred lines in any language.
+
+It's tractable precisely because the predicate subset is deliberately minimal
+(the verifier enforces it): pure, synchronous, **no loops** (recursion + array
+methods only), fuel-bounded, no IO, a whitelist of pure operations (member access,
+comparisons, `&&`/`||`/ternary, `typeof`, a fixed set of string/array/Math/regex
+methods). That's a small tree-walking interpreter — no closures-over-mutable-state,
+no async, no allocation surprises, no host access.
+
+**Key architectural implication — carry the AST, not (only) the source.** Today
+`$predicate` is predicate *source* (JS/AJS text). A portable VM in Rust/Go/Python
+shouldn't have to embed a JS parser. So the canonical portable form of a predicate
+should be its **serialized AST** (JSON) — which is the original AJS thesis ("code
+travels as data") applied here. Source stays the authoring form; the serialized
+AST is the wire/exec form the small VM walks. A `$predicate` could carry either,
+with the AST as the portable default.
+
+## Open questions
+
+- **`TypeDescriptor`'s fate:** keep it as a cached projection of JSON-Schema +
+  `$predicate`, or eventually retire it? At minimum, guard that it can't express
+  what the canonical form can't.
+- **The predicate ISA:** pin down the exact minimal node set + operation whitelist
+  the reference VM must support (a spec), and a **conformance suite** every port
+  runs — so "TJS types" means the same thing in every language.
+- **AST format:** settle the serialized predicate AST schema (it should itself be
+  describable — turtles: the AST format as a JSON-Schema).
+- **Fuel across languages:** the fuel model must be spec'd (per-node cost) so a
+  runaway predicate is bounded identically everywhere.
+- **Structure/predicate split:** conventions for what belongs in JSON-Schema
+  keywords vs `$predicate` (prefer standard keywords; reach for `$predicate` only
+  for the genuinely computational).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Type-safe JavaScript dialect with runtime validation, sandboxed VM execution, and AI agent orchestration. Transpiles TypeScript to validated JS with fuel-metered execution for untrusted code.",
   "keywords": [
     "typescript",

package/src/lang/emitters/js-wasm.ts

@@ -19,6 +19,8 @@ export function generateWasmBootstrap(blocks: WasmBlock[]): {
     error?: string
     byteLength?: number
   }[]
+  /** Compile-time lints (e.g. i32/i32 integer-division) across all blocks. */
+  warnings: string[]
 } {
   const compiled = compileBlocksToModule(blocks)
 
@@ -40,7 +42,7 @@ export function generateWasmBootstrap(blocks: WasmBlock[]): {
   })
 
   if (compiled.exports.length === 0) {
-    return { code: '', results }
+    return { code: '', results, warnings: compiled.warnings }
   }
 
   // WAT comment block — one section per included function
@@ -72,7 +74,9 @@ export function generateWasmBootstrap(blocks: WasmBlock[]): {
   const anyNeedsMemory = compiled.needsMemory
 
   const code = `${watComments}
-;(async()=>{
+;(globalThis.__tjs_wasm_pending??=[]);
+globalThis.__tjs_wasm_ready??=(()=>Promise.all(globalThis.__tjs_wasm_pending));
+globalThis.__tjs_wasm_pending.push((async()=>{
 const __wasmExports=[${exportData}];
 const __wasmModuleB64=${JSON.stringify(moduleBase64)};
 const __b64ToBytes=s=>{const b=atob(s),a=new Uint8Array(b.length);for(let i=0;i<b.length;i++)a[i]=b.charCodeAt(i);return a};
@@ -105,11 +109,11 @@ for(const{id,n,c,m}of __wasmExports){
         if(a.buffer===__wasmMem.buffer) continue;
         const ab=new Uint8Array(a.buffer,a.byteOffset,a.byteLength);off=(off+15)&~15;ab.set(mv.slice(off,off+ab.length));off+=ab.length}}
     return r};
-}})();
+}})().catch(()=>{}));
 `.trim()
 
   // Strip the temporary _exportName field before returning to caller.
   const publicResults = results.map(({ _exportName: _, ...rest }) => rest)
 
-  return { code, results: publicResults }
+  return { code, results: publicResults, warnings: compiled.warnings }
 }

package/src/lang/emitters/js.ts

@@ -682,18 +682,26 @@ export function transpileToJS(
 
   // Mirror unverifiable Type/Generic predicates into `warnings` (they still
   // compile — as plain functions — but aren't fuel-bounded / safe on untrusted
-  // data). The full per-predicate status is returned as `predicates`.
-  for (const p of preprocessed.predicates) {
-    if (!p.verified) {
-      warnings.push(
-        `${p.kind} '${
-          p.name
-        }': predicate is not verifiable, compiled as a plain function (not fuel-bounded, not safe on untrusted data)${
-          p.reason ? ` — ${p.reason.replace(/\s+/g, ' ').trim()}` : ''
-        }`
-      )
-    }
+  // data). The full per-predicate status is returned as `predicates`. Under the
+  // explicit `TjsStrict` opt-in these escalate to a transpile error (the subset
+  // invariant: warn by default, error only when the author asked for strict).
+  const unverified = preprocessed.predicates.filter((p) => !p.verified)
+  const predicateMsg = (p: PredicateVerification) =>
+    `${p.kind} '${
+      p.name
+    }': predicate is not verifiable, compiled as a plain function (not fuel-bounded, not safe on untrusted data)${
+      p.reason ? ` — ${p.reason.replace(/\s+/g, ' ').trim()}` : ''
+    }`
+  if (unverified.length && preprocessed.tjsModes.tjsStrict) {
+    throw new Error(
+      `TjsStrict: ${
+        unverified.length
+      } predicate(s) could not be verified:\n${unverified
+        .map((p) => `  ${predicateMsg(p)}`)
+        .join('\n')}`
+    )
   }
+  for (const p of unverified) warnings.push(predicateMsg(p))
   const predicateReport = preprocessed.predicates.length
     ? preprocessed.predicates
     : undefined
@@ -1202,6 +1210,23 @@ export function transpileToJS(
       code = wasmBootstrap.code + '\n' + code
     }
     wasmCompiled = wasmBootstrap.results
+    // Surface WASM compile failures as warnings (they were only in
+    // `wasmCompiled` before, so a `wasm{}` block that can't compile fell back to
+    // its `fallback{}` SILENTLY — the worst failure mode for a perf feature).
+    // The full status stays on `wasmCompiled`; this just makes it visible.
+    for (const w of wasmCompiled) {
+      if (!w.success) {
+        warnings.push(
+          `wasm{} block '${
+            w.id
+          }' did not compile — running the fallback{} (JS)${
+            w.error ? `: ${w.error}` : ''
+          }`
+        )
+      }
+    }
+    // Compile-time wasm lints (e.g. i32/i32 integer division — UI-#4).
+    for (const w of wasmBootstrap.warnings) warnings.push(`wasm{}: ${w}`)
   }
 
   return {

package/src/lang/parser-transforms.ts

@@ -260,7 +260,10 @@ export function extractWasmBlocks(source: string): {
           ? `globalThis.${block.id}(${captureArgs})`
           : `globalThis.${block.id}()`
 
-      const dispatch = `(globalThis.${block.id} ? ${wasmCall} : (() => {${fallbackCode}})())`
+      // `globalThis.__tjs_wasm_enabled === false` forces the fallback path even
+      // when the WASM is instantiated — a public toggle for A/B benchmarking
+      // (WASM vs JS) without poking the internal `__tjs_wasm_<id>` globals (UI-#3).
+      const dispatch = `((globalThis.__tjs_wasm_enabled !== false && globalThis.${block.id}) ? ${wasmCall} : (() => {${fallbackCode}})())`
 
       result += dispatch
       i = matchEnd

package/src/lang/parser-types.ts

@@ -196,6 +196,13 @@ export interface TjsModes {
   tjsNoVar: boolean
   /** TjsSafeAssign: let declarations need an initializer or `: example` annotation; literal undefined/null/void 0 assigned to typed lets is flagged */
   tjsSafeAssign: boolean
+  /**
+   * TjsStrict: the author explicitly opted into strict semantics (via the
+   * `TjsStrict` directive). Distinct from "all modes on" (native TJS's default) —
+   * only `true` when the directive is present. Escalates soft diagnostics (e.g. an
+   * unverifiable `Type`/`Generic` predicate) from a warning to a transpile error.
+   */
+  tjsStrict: boolean
 }
 
 /**

package/src/lang/parser.ts

@@ -158,6 +158,7 @@ export function preprocess(
         tjsSafeEval: false,
         tjsNoVar: false,
         tjsSafeAssign: false,
+        tjsStrict: false,
       }
     : {
         tjsEquals: true,
@@ -168,6 +169,10 @@ export function preprocess(
         tjsSafeEval: false, // opt-in only (adds import)
         tjsNoVar: true,
         tjsSafeAssign: true,
+        // Native TJS has all modes on by default, but is NOT "strict" unless the
+        // author writes the `TjsStrict` directive — that opt-in is what escalates
+        // e.g. unverifiable predicates from a warning to a hard error.
+        tjsStrict: false,
       }
 
   // Safety: native TJS defaults to 'inputs' (runtime default),
@@ -203,7 +208,8 @@ export function preprocess(
     const directive = match[2]
 
     if (directive === 'TjsStrict') {
-      // Enable all TJS modes
+      // Enable all TJS modes + mark strict (the author's explicit opt-in, which
+      // escalates soft diagnostics like unverifiable predicates to hard errors).
       tjsModes.tjsEquals = true
       tjsModes.tjsClass = true
       tjsModes.tjsDate = true
@@ -211,6 +217,7 @@ export function preprocess(
       tjsModes.tjsNoVar = true
       tjsModes.tjsStandard = true
       tjsModes.tjsSafeAssign = true
+      tjsModes.tjsStrict = true
     } else if (directive === 'TjsCompat') {
       // Disable all TJS modes (JS-compatible)
       tjsModes.tjsEquals = false
@@ -519,6 +526,7 @@ export function parse(
           tjsSafeEval: false,
           tjsNoVar: false,
           tjsSafeAssign: false,
+          tjsStrict: false,
         } as TjsModes,
       }
 

package/src/lang/predicate-report.test.ts

@@ -52,3 +52,27 @@ describe('predicate verification is reported on the transpile result', () => {
     expect(tjs('function f() { return 1 }').predicates).toBeUndefined()
   })
 })
+
+describe('TjsStrict escalates an unverifiable predicate to a transpile error', () => {
+  const bad =
+    "Type Bad 'bad' { predicate(xs) { for (const x of xs) {} return true } }"
+
+  it('warns (does not throw) without the directive', () => {
+    const r = tjs(bad)
+    expect(r.predicates?.[0]?.verified).toBe(false)
+    expect(r.warnings?.length).toBeGreaterThan(0)
+  })
+
+  it('throws under TjsStrict, naming the predicate + reason', () => {
+    expect(() => tjs('TjsStrict\n' + bad)).toThrow(
+      /TjsStrict.*could not be verified/s
+    )
+    expect(() => tjs('TjsStrict\n' + bad)).toThrow(/Bad/)
+  })
+
+  it('does NOT throw under TjsStrict when the predicate verifies', () => {
+    const r = tjs("TjsStrict\nType Pos 'p' { predicate(x) { return x > 0 } }")
+    expect(r.predicates?.[0]?.verified).toBe(true)
+    expect(r.warnings).toBeUndefined()
+  })
+})

package/src/lang/wasm-fallback-warning.test.ts

@@ -0,0 +1,50 @@
+/**
+ * A `wasm{}` block that can't compile falls back to its `fallback{}` (JS) — which
+ * used to happen SILENTLY (the failure was only on `result.wasmCompiled`, which
+ * consumers don't inspect), so WASM looked like it "worked" when it was running
+ * the JS fallback. Now the failure is also mirrored into `result.warnings`.
+ * (tosijs-ui feedback UI-#1.)
+ */
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+
+const UNSUPPORTED = `function fill(out: [0.0], w: 0, h: 0) {
+  wasm {
+    for (let y = 0; y < h; y += 1) {
+      for (let x = 0; x < w; x += 1) { out[y * w + x] = 1.0 }
+    }
+  } fallback {
+    for (let i = 0; i < w * h; i++) out[i] = 0
+  }
+  return out
+}`
+
+const SUPPORTED = `function scale(arr: [0.0], len: 0, factor: 0.0) {
+  wasm {
+    for (let i = 0; i < len; i += 4) {
+      let off = i * 4
+      f32x4_store(arr, off, f32x4_mul(f32x4_load(arr, off), f32x4_splat(factor)))
+    }
+  } fallback {
+    for (let i = 0; i < len; i++) arr[i] *= factor
+  }
+  return arr
+}`
+
+describe('silent wasm{} fallback is now surfaced as a warning', () => {
+  it('warns (with the reason) when a block cannot compile', () => {
+    const r = tjs(UNSUPPORTED)
+    expect(r.wasmCompiled?.[0]?.success).toBe(false) // signal already existed…
+    const w = r.warnings?.find((w) =>
+      /wasm\{\} block .* did not compile/.test(w)
+    )
+    expect(w).toBeTruthy() // …now it's in warnings too
+    expect(w).toMatch(/fallback/)
+  })
+
+  it('does not warn when the block compiles to WASM', () => {
+    const r = tjs(SUPPORTED)
+    expect(r.wasmCompiled?.[0]?.success).toBe(true)
+    expect(r.warnings?.some((w) => /wasm\{\}/.test(w)) ?? false).toBe(false)
+  })
+})

package/src/lang/wasm-intdiv-lint.test.ts

@@ -0,0 +1,45 @@
+/**
+ * Lint the i32/i32 integer-division footgun inside `wasm{}`: `/` with two integer
+ * operands truncates, and coercion to f64 only happens at the *next* operator, so
+ * `x / w - 0.5` is silently `0 - 0.5` for all `x < w` — it silently broke a real
+ * Mandelbrot kernel (tosijs-ui UI-#4). Now it's surfaced in `result.warnings`.
+ */
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+
+const intDivWarning = (r: { warnings?: string[] }) =>
+  r.warnings?.find((w) => /integer division/.test(w))
+
+describe('i32/i32 division lint', () => {
+  it('warns when both operands are i32 (loop vars)', () => {
+    const r = tjs(`function f(n: 0) {
+      wasm {
+        for (let y = 1; y < n; y += 1) {
+          for (let x = 1; x < n; x += 1) { let r = x / y }
+        }
+      } fallback { }
+      return n
+    }`)
+    expect(r.wasmCompiled?.[0]?.success).toBe(true) // block compiled…
+    expect(intDivWarning(r)).toBeTruthy() // …and the footgun was flagged
+    expect(intDivWarning(r)).toMatch(/\+ 0\.0/) // suggests the fix
+  })
+
+  it('warns once per block, not per occurrence', () => {
+    const r = tjs(`function f(n: 0) {
+      wasm {
+        for (let i = 1; i < n; i += 1) { let a = i / n; let b = n / i; let c = i / i }
+      } fallback { }
+      return n
+    }`)
+    expect(r.warnings?.filter((w) => /integer division/.test(w)).length).toBe(1)
+  })
+
+  it('does NOT warn on float division', () => {
+    const r = tjs(`function g(a: 0.0, b: 0.0) {
+      wasm { let r = a / b } fallback { }
+      return a
+    }`)
+    expect(intDivWarning(r)).toBeUndefined()
+  })
+})

package/src/lang/wasm-ready.test.ts

@@ -0,0 +1,94 @@
+/**
+ * `globalThis.__tjs_wasm_ready()` — an awaitable signal for WASM instantiation.
+ *
+ * The emitted bootstrap instantiates WASM asynchronously (fire-and-forget), so
+ * synchronous code right after transpile+eval used to hit the JS `fallback{}`
+ * because `globalThis.__tjs_wasm_N` wasn't set yet — with no way to await it
+ * (tosijs-ui feedback UI-#2, "bit us hard"). Now each module pushes its
+ * instantiation promise onto `globalThis.__tjs_wasm_pending` and
+ * `__tjs_wasm_ready()` awaits them all.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'bun:test'
+import { tjs } from './index'
+import { createRuntime } from './runtime'
+
+const g = globalThis as any
+g.__tjs = createRuntime()
+
+// The `__tjs_wasm_*` globals are shared process-wide, so other test files that
+// eval a bootstrap can leave them set. Clear before each test so the
+// "undefined before ready" assertion reflects THIS module's state.
+const clearWasmGlobals = () => {
+  delete g.__tjs_wasm_pending
+  delete g.__tjs_wasm_ready
+  delete g.__tjs_wasm_0
+}
+
+const KERNEL = `function scale(arr: [0.0], len: 0, f: 0.0) {
+  wasm {
+    let s = f32x4_splat(f)
+    for (let i = 0; i < len; i += 4) { let o = i * 4; f32x4_store(arr, o, f32x4_mul(f32x4_load(arr, o), s)) }
+  } fallback { for (let i = 0; i < len; i++) arr[i] *= f }
+  return arr
+}`
+
+beforeEach(clearWasmGlobals)
+afterEach(clearWasmGlobals)
+
+describe('__tjs_wasm_ready', () => {
+  it('resolves once WASM is instantiated (was a fallback race before)', async () => {
+    const { code } = tjs(KERNEL)
+    new Function(code)() // run the bootstrap (fire-and-forget instantiation)
+
+    expect(typeof g.__tjs_wasm_ready).toBe('function')
+    // synchronously right after eval, the module isn't ready yet…
+    expect(g.__tjs_wasm_0).toBeUndefined()
+
+    await g.__tjs_wasm_ready()
+
+    // …now it is — a sync call here takes the WASM path, not the fallback.
+    expect(typeof g.__tjs_wasm_0).toBe('function')
+  })
+
+  it('accumulates pending across modules and awaits all', async () => {
+    new Function(tjs(KERNEL).code)()
+    const firstReady = g.__tjs_wasm_ready
+    new Function(tjs(KERNEL.replace('scale', 'scale2')).code)()
+    // same shared helper + a growing pending list, not overwritten per module
+    expect(g.__tjs_wasm_ready).toBe(firstReady)
+    expect(g.__tjs_wasm_pending.length).toBe(2)
+
+    await g.__tjs_wasm_ready()
+    expect(typeof g.__tjs_wasm_0).toBe('function')
+  })
+})
+
+describe('__tjs_wasm_enabled toggle (force the JS fallback for benchmarking)', () => {
+  // A scalar kernel so input validation passes (a Float32Array isn't
+  // `Array.isArray`, which would early-return before the dispatch). We spy on the
+  // compiled export to detect which path the dispatch takes.
+  const SCALAR = `function pick(x: 0.0) { wasm { return x } fallback { return x } }`
+
+  it('routes to the fallback when disabled, even though WASM is ready', async () => {
+    const pick = new Function(tjs(SCALAR).code + '\nreturn pick')()
+    await g.__tjs_wasm_ready()
+    const real = g.__tjs_wasm_0
+    let wasmCalls = 0
+    g.__tjs_wasm_0 = (...a: any[]) => {
+      wasmCalls++
+      return real(...a)
+    }
+
+    pick(1) // default (enabled) → WASM path
+    expect(wasmCalls).toBe(1)
+
+    g.__tjs_wasm_enabled = false
+    pick(1) // forced fallback → WASM not called
+    expect(wasmCalls).toBe(1)
+
+    g.__tjs_wasm_enabled = true
+    pick(1) // back to WASM
+    expect(wasmCalls).toBe(2)
+    delete g.__tjs_wasm_enabled
+  })
+})

package/src/lang/wasm-simd-ops.test.ts

@@ -0,0 +1,84 @@
+/**
+ * f32x4 min/max, lane comparisons (lt/le/gt/ge/eq/ne → mask), and select
+ * (branch-free blend) — the intrinsics that unlock DATA-DEPENDENT SIMD (clamp,
+ * saturate, SIMD Mandelbrot). Before this, f32x4 was arithmetic-only, so masked
+ * SIMD was impossible (tosijs-ui feedback UI-#6). Executed as real WASM and
+ * checked lane 0 via `extract_lane` (compares are checked through `select`, since
+ * a raw mask isn't a meaningful float).
+ */
+import { describe, it, expect } from 'bun:test'
+import { compileToWasm, instantiateWasm, type WasmBlock } from './wasm'
+
+/** Compile+instantiate a 2-arg f32 kernel `compute(a, b)` from a block body. */
+async function kernel(body: string, captures: string[]) {
+  const block: WasmBlock = { id: 'k', body, captures, start: 0, end: 0 }
+  const result = compileToWasm(block)
+  expect(result.error).toBeFalsy()
+  // SIMD modules import env.memory (for potential v128 load/store); provide one.
+  const memory = new WebAssembly.Memory({ initial: 16 })
+  const instance = await instantiateWasm(result.bytes, memory)
+  return instance.exports.compute as (...a: number[]) => number
+}
+
+describe('f32x4 min / max', () => {
+  it('max', async () => {
+    const f = await kernel(
+      'return f32x4_extract_lane(f32x4_max(f32x4_splat(a), f32x4_splat(b)), 0)',
+      ['a', 'b']
+    )
+    expect(f(3, 5)).toBe(5)
+    expect(f(-2, -8)).toBe(-2)
+    expect(f(4.5, 4.5)).toBe(4.5)
+  })
+  it('min', async () => {
+    const f = await kernel(
+      'return f32x4_extract_lane(f32x4_min(f32x4_splat(a), f32x4_splat(b)), 0)',
+      ['a', 'b']
+    )
+    expect(f(3, 5)).toBe(3)
+    expect(f(-2, -8)).toBe(-8)
+  })
+})
+
+describe('f32x4 select + comparisons (branch-free lane blend)', () => {
+  // select(cmp(a,b), 1, 2) → 1 when the comparison is true (mask lane all-1s), else 2
+  const via = (cmp: string) =>
+    kernel(
+      `return f32x4_extract_lane(f32x4_select(${cmp}(f32x4_splat(a), f32x4_splat(b)), f32x4_splat(1.0), f32x4_splat(2.0)), 0)`,
+      ['a', 'b']
+    )
+
+  it('gt', async () => {
+    const f = await via('f32x4_gt')
+    expect(f(5, 3)).toBe(1)
+    expect(f(3, 5)).toBe(2)
+  })
+  it('lt', async () => {
+    const f = await via('f32x4_lt')
+    expect(f(3, 5)).toBe(1)
+    expect(f(5, 3)).toBe(2)
+  })
+  it('ge / le at equality', async () => {
+    expect(await (await via('f32x4_ge'))(4, 4)).toBe(1)
+    expect(await (await via('f32x4_le'))(4, 4)).toBe(1)
+    expect(await (await via('f32x4_ge'))(3, 4)).toBe(2)
+  })
+  it('eq / ne', async () => {
+    expect(await (await via('f32x4_eq'))(4, 4)).toBe(1)
+    expect(await (await via('f32x4_eq'))(4, 5)).toBe(2)
+    expect(await (await via('f32x4_ne'))(4, 5)).toBe(1)
+  })
+})
+
+describe('clamp via min/max (the canonical use)', () => {
+  it('clamps to [lo, hi] on lane 0', async () => {
+    // clamp(v, lo, hi) = min(max(v, lo), hi); fix lo=0, hi=3 via constants
+    const f = await kernel(
+      'return f32x4_extract_lane(f32x4_min(f32x4_max(f32x4_splat(a), f32x4_splat(0.0)), f32x4_splat(3.0)), 0)',
+      ['a', 'b']
+    )
+    expect(f(-5, 0)).toBe(0)
+    expect(f(1.5, 0)).toBe(1.5)
+    expect(f(10, 0)).toBe(3)
+  })
+})