tjs-lang 0.8.1 → 0.8.3

package/editors/scope-symbols.ts

@@ -0,0 +1,173 @@
+/**
+ * Scope-aware symbol collection for autocomplete.
+ *
+ * Replaces the regex `const NAME =` scraping (which missed ALL destructuring —
+ * and the tosijs examples bind everything via destructuring, so nothing was
+ * suggested). This parses the source (acorn, falling back to acorn-loose for
+ * mid-edit / not-yet-valid source) and walks binding patterns properly:
+ * `const { todoApp } = tosi(...)`, `const { h1, ul } = elements`,
+ * `const [a, , b] = xs`, rename, defaults, rest — all yield their bound names.
+ *
+ * Each symbol also records its **origin** (the initializer expression text, and
+ * for object-destructuring the key it came from). That origin is the hook the
+ * runtime-introspection layer uses: to introspect `h1` it can evaluate
+ * `elements.h1` in the live scope. Names are plumbing; the *types* come from
+ * introspecting real values (see the introspection bridge), not from this parse.
+ */
+import * as acorn from 'acorn'
+import * as acornLoose from 'acorn-loose'
+import * as walk from 'acorn-walk'
+
+export interface SymbolOrigin {
+  /** How the binding was produced. */
+  via: 'init' | 'destructure' | 'param' | 'import' | 'function'
+  /** Source text of the initializer expression (e.g. `elements`, `tosi({...})`). */
+  expr?: string
+  /** For object-destructuring: the key on `expr` this name came from (`elements.h1` → `h1`). */
+  member?: string
+  /** Module specifier, for imports. */
+  module?: string
+}
+
+export interface ScopeSymbol {
+  name: string
+  kind: 'variable' | 'function' | 'parameter' | 'import'
+  origin?: SymbolOrigin
+}
+
+function parse(source: string): any {
+  try {
+    return acorn.parse(source, { ecmaVersion: 'latest' })
+  } catch {
+    try {
+      // Best-effort AST from incomplete / not-yet-valid source.
+      return acornLoose.parse(source, { ecmaVersion: 'latest' })
+    } catch {
+      return null
+    }
+  }
+}
+
+type NameSink = (name: string, member?: string) => void
+
+/** Walk a binding pattern, emitting each bound name (and, one level deep for
+ *  object patterns, the source key it came from). */
+function collectPattern(pat: any, onName: NameSink, member?: string): void {
+  if (!pat) return
+  switch (pat.type) {
+    case 'Identifier':
+      onName(pat.name, member)
+      return
+    case 'ObjectPattern':
+      for (const p of pat.properties) {
+        if (p.type === 'RestElement') {
+          collectPattern(p.argument, onName)
+        } else {
+          const key = p.key && (p.key.name ?? p.key.value)
+          collectPattern(
+            p.value,
+            onName,
+            typeof key === 'string' ? key : undefined
+          )
+        }
+      }
+      return
+    case 'ArrayPattern':
+      for (const el of pat.elements) collectPattern(el, onName)
+      return
+    case 'AssignmentPattern':
+      collectPattern(pat.left, onName, member)
+      return
+    case 'RestElement':
+      collectPattern(pat.argument, onName)
+      return
+  }
+}
+
+const inRange = (node: any, position: number) =>
+  typeof node.start === 'number' &&
+  typeof node.end === 'number' &&
+  node.start <= position &&
+  position <= node.end
+
+/**
+ * Collect the symbols in scope at `position` (defaults to end of source):
+ * variable/function/import bindings declared before the cursor, plus the
+ * parameters of any function whose body the cursor sits inside. Destructuring
+ * is fully handled; results are de-duplicated by name (last declaration wins).
+ */
+export function collectScopeSymbols(
+  source: string,
+  position: number = source.length
+): ScopeSymbol[] {
+  const ast = parse(source)
+  if (!ast) return []
+
+  const byName = new Map<string, ScopeSymbol>()
+  const add = (s: ScopeSymbol) => byName.set(s.name, s)
+
+  walk.full(ast, (node: any) => {
+    switch (node.type) {
+      case 'VariableDeclaration': {
+        // Only count declarations that appear before the cursor.
+        if (node.start >= position) return
+        for (const decl of node.declarations) {
+          const initText =
+            decl.init && typeof decl.init.start === 'number'
+              ? source.slice(decl.init.start, decl.init.end)
+              : undefined
+          collectPattern(decl.id, (name, member) =>
+            add({
+              name,
+              kind: 'variable',
+              origin: {
+                via: member != null ? 'destructure' : 'init',
+                expr: initText,
+                member,
+              },
+            })
+          )
+        }
+        return
+      }
+      case 'FunctionDeclaration': {
+        if (node.id && node.start < position)
+          add({
+            name: node.id.name,
+            kind: 'function',
+            origin: { via: 'function' },
+          })
+        // params only in scope when the cursor is inside the function
+        if (inRange(node, position))
+          for (const p of node.params)
+            collectPattern(p, (name) =>
+              add({ name, kind: 'parameter', origin: { via: 'param' } })
+            )
+        return
+      }
+      case 'FunctionExpression':
+      case 'ArrowFunctionExpression': {
+        if (inRange(node, position))
+          for (const p of node.params)
+            collectPattern(p, (name) =>
+              add({ name, kind: 'parameter', origin: { via: 'param' } })
+            )
+        return
+      }
+      case 'ImportDeclaration': {
+        const module = String(node.source?.value ?? '')
+        for (const spec of node.specifiers) {
+          // local name is spec.local.name for all specifier kinds
+          add({
+            name: spec.local.name,
+            kind: 'import',
+            origin: { via: 'import', module },
+          })
+        }
+        return
+      }
+    }
+  })
+
+  return [...byName.values()]
+}

package/llms.txt

@@ -8,6 +8,7 @@ This file is a navigation index for AI agents. It does not contain the docs them
 
 - [CLAUDE-TJS-SYNTAX.md](CLAUDE-TJS-SYNTAX.md) — TJS syntax reference. Critical: `function foo(x: 'default')` is NOT a TypeScript string-literal type. The colon value is an **example**; `'default'` widens to `string`. LLMs get this wrong constantly.
 - [CLAUDE.md](CLAUDE.md) — project overview, common commands, architecture, security model, and key APIs.
+- [PRINCIPLES.md](PRINCIPLES.md) — **non-negotiable language invariants**: options-off TJS ⊇ JS, and TJS ⊇ AJS. A richer layer may do *more* with the same source but must never make subset-legal code illegal (e.g. un-runnable signature tests are inconclusive, not errors). The opt-in unit is the **dialect**: `tjs(src, { dialect: 'js' })` preserves plain-JS semantics, `'tjs'` (default) is native; file tools map extension→dialect via `dialectForFilename`/`sourceKindForFilename` from `tjs-lang/lang`. TypeScript routes through `fromTS` (`tjs-lang/lang/from-ts`) so the lean lang bundle stays TS-free — the full `js | ts | tjs` routing recipe is in PRINCIPLES.md. A violation is a bug.
 
 ## Language guides
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tjs-lang",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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",
@@ -22,6 +22,25 @@
   "license": "Apache-2.0",
   "main": "./dist/index.js",
   "types": "./dist/src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "eval": [
+        "./dist/src/lang/eval.d.ts"
+      ],
+      "lang": [
+        "./dist/src/lang/transpiler.d.ts"
+      ],
+      "lang/from-ts": [
+        "./dist/src/lang/emitters/from-ts.d.ts"
+      ],
+      "vm": [
+        "./dist/src/vm/index.d.ts"
+      ],
+      "batteries": [
+        "./dist/src/batteries/index.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -142,6 +161,7 @@
   },
   "dependencies": {
     "acorn": "^8.15.0",
+    "acorn-loose": "^8.5.2",
     "acorn-walk": "^8.3.4",
     "tosijs-schema": "^1.3.0"
   }

package/src/batteries/audit.ts

@@ -190,9 +190,10 @@ async function checkEmbedding(
   }
 }
 
-// Tiny 1x1 red PNG as base64 for vision testing
+// 32x32 solid-red PNG (base64). NOT 1x1 — degenerate sizes are rejected by
+// real vision preprocessors (e.g. gemma: "Cannot handle this data type (1,1,1)").
 const TINY_TEST_IMAGE =
-  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8DwHwAFBQIAX8jx0gAAAABJRU5ErkJggg=='
+  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAMUlEQVR4nGO4o6FBU8QwasFoEI2motF8MFpUjJamo/XBaJU52qoYbReNNh01hkg+AACGobA9N+tfoAAAAABJRU5ErkJggg=='
 
 async function checkVision(baseUrl: string, modelId: string): Promise<boolean> {
   try {

package/src/cli/commands/check.ts

@@ -3,13 +3,14 @@
  */
 
 import { readFileSync } from 'fs'
-import { tjs } from '../../lang'
+import { tjs, dialectForFilename } from '../../lang'
 
 export async function check(file: string): Promise<void> {
   const source = readFileSync(file, 'utf-8')
 
   try {
-    const result = tjs(source)
+    // `.js`/`.mjs` ⇒ plain-JS semantics preserved; `.tjs` ⇒ native modes.
+    const result = tjs(source, { dialect: dialectForFilename(file) })
 
     // Report function info from types
     if (result.types && Object.keys(result.types).length > 0) {

package/src/cli/commands/emit.ts

@@ -21,7 +21,7 @@ import {
   existsSync,
 } from 'fs'
 import { join, basename, dirname, extname } from 'path'
-import { tjs } from '../../lang'
+import { tjs, dialectForFilename } from '../../lang'
 import { generateDocs } from '../../lang/docs'
 import { generateDTS } from '../../lang/emitters/dts'
 
@@ -84,9 +84,11 @@ async function emitFile(
   const filename = basename(inputPath)
 
   try {
-    // Use 'report' mode to get test results without throwing
+    // Use 'report' mode to get test results without throwing.
+    // `.js`/`.mjs` ⇒ plain-JS semantics preserved; `.tjs` ⇒ native modes.
     const result = tjs(source, {
       filename,
+      dialect: dialectForFilename(inputPath),
       debug: options.debug,
       runTests: 'report',
     })

package/src/cli/commands/run.ts

@@ -8,15 +8,19 @@ import { readFileSync } from 'fs'
 import { resolve } from 'path'
 import { preprocess } from '../../lang/parser'
 import { transpileToJS } from '../../lang/emitters/js'
+import { dialectForFilename } from '../../lang/dialect'
 import * as runtime from '../../lang/runtime'
 
 export async function run(file: string): Promise<void> {
   const absolutePath = resolve(file)
   const source = readFileSync(absolutePath, 'utf-8')
 
+  // `.js`/`.mjs` ⇒ plain-JS semantics preserved; `.tjs` ⇒ native modes.
+  const dialect = dialectForFilename(file)
+
   try {
     // Preprocess: transforms Type, Generic, Union declarations, runs tests
-    const preprocessed = preprocess(source)
+    const preprocessed = preprocess(source, { dialect })
 
     if (preprocessed.testErrors.length > 0) {
       console.error('Test failures:')
@@ -27,7 +31,7 @@ export async function run(file: string): Promise<void> {
     }
 
     // Transpile to JS
-    const result = transpileToJS(preprocessed.source)
+    const result = transpileToJS(preprocessed.source, { dialect })
 
     if (result.warnings && result.warnings.length > 0) {
       for (const warning of result.warnings) {

package/src/cli/commands/types.ts

@@ -3,12 +3,12 @@
  */
 
 import { readFileSync } from 'fs'
-import { tjs } from '../../lang'
+import { tjs, dialectForFilename } from '../../lang'
 
 export async function types(file: string): Promise<void> {
   const source = readFileSync(file, 'utf-8')
 
-  const result = tjs(source)
+  const result = tjs(source, { dialect: dialectForFilename(file) })
 
   // Output the type information as JSON
   const typeInfo = {

package/src/lang/codegen.test.ts

@@ -1543,8 +1543,11 @@ function map(arr: [''], counter = strLength): [0] { return arr.map(counter) }`)
         )
         const sig = testResults?.find((t) => t.isSignatureTest)
         expect(sig).toBeDefined()
+        // The module couldn't execute (runtime ReferenceError on `x`), so the
+        // test couldn't run → inconclusive, never a build-blocking failure.
         expect(sig?.passed).toBe(false)
-        expect(sig?.error).toContain('Module execution failed')
+        expect(sig?.inconclusive).toBe(true)
+        expect(sig?.error).toContain('could not be executed')
         // Critical: no line attribution → editor won't mark a misleading line
         expect(sig?.line).toBeUndefined()
       })

package/src/lang/core.ts

@@ -12,7 +12,7 @@ import type {
   FunctionSignature,
   TypeDescriptor,
 } from './types'
-import { parse, validateSingleFunction } from './parser'
+import { parse, extractFunctions } from './parser'
 import { transformFunction } from './emitters/ast'
 import {
   transpileToJS,
@@ -26,6 +26,7 @@ export {
   preprocess,
   extractTDoc,
   validateSingleFunction,
+  extractFunctions,
 } from './parser'
 export { transformFunction } from './emitters/ast'
 
@@ -47,14 +48,15 @@ export function transpile(
     vmTarget: true,
   })
 
-  const func = validateSingleFunction(program, options.filename)
+  const { entry, helpers } = extractFunctions(program, options.filename)
 
   const { ast, signature, warnings } = transformFunction(
-    func,
+    entry,
     originalSource,
     returnType,
     options,
-    requiredParams
+    requiredParams,
+    helpers.size > 0 ? helpers : undefined
   )
 
   return {

package/src/lang/dialect.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'bun:test'
+import { tjs } from './index'
+import { dialectForFilename, sourceKindForFilename } from './dialect'
+
+describe('source dialect', () => {
+  // A line of vanilla JS whose meaning TJS would otherwise change: structural
+  // `==` (→ Eq), honest truthiness (→ toBool), and `typeof` (→ TypeOf).
+  const JS = `function f(a, b) { if (a == b) { return typeof a } return null }`
+
+  const isMolested = (code: string) =>
+    code.includes('Eq(') || code.includes('toBool') || code.includes('TypeOf')
+
+  describe('dialect option', () => {
+    it("dialect: 'js' preserves plain-JS semantics (no rewrites)", () => {
+      expect(isMolested(tjs(JS, { dialect: 'js' }).code)).toBe(false)
+    })
+
+    it("dialect: 'tjs' applies native footgun-removal modes", () => {
+      expect(isMolested(tjs(JS, { dialect: 'tjs' }).code)).toBe(true)
+    })
+
+    it('a bare string still defaults to native TJS (backward compatible)', () => {
+      expect(isMolested(tjs(JS).code)).toBe(true)
+    })
+
+    it("dialect: 'js' is equivalent to the TjsCompat directive", () => {
+      const viaOption = tjs(JS, { dialect: 'js' }).code
+      const viaDirective = tjs(`TjsCompat\n${JS}`).code
+      // Both leave the comparison/typeof untouched.
+      expect(isMolested(viaOption)).toBe(false)
+      expect(isMolested(viaDirective)).toBe(false)
+    })
+  })
+
+  describe('dialectForFilename', () => {
+    it('maps JS extensions to the js dialect', () => {
+      for (const f of ['a.js', 'a.mjs', 'a.cjs', 'deep/b.JS']) {
+        expect(dialectForFilename(f)).toBe('js')
+      }
+    })
+
+    it('maps .tjs and unknown/TS extensions to the tjs dialect', () => {
+      // .ts is not a tjs() dialect — it routes through fromTS — so the dialect
+      // helper reports 'tjs'; use sourceKindForFilename to tell them apart.
+      for (const f of ['a.tjs', 'a.ts', 'a.mts', 'a.d.ts', 'noext']) {
+        expect(dialectForFilename(f)).toBe('tjs')
+      }
+    })
+  })
+
+  describe('sourceKindForFilename', () => {
+    it('classifies js / ts / tjs by extension', () => {
+      expect(sourceKindForFilename('x.js')).toBe('js')
+      expect(sourceKindForFilename('x.mjs')).toBe('js')
+      expect(sourceKindForFilename('x.cjs')).toBe('js')
+      expect(sourceKindForFilename('x.ts')).toBe('ts')
+      expect(sourceKindForFilename('x.mts')).toBe('ts')
+      expect(sourceKindForFilename('x.d.ts')).toBe('ts')
+      expect(sourceKindForFilename('x.tjs')).toBe('tjs')
+      expect(sourceKindForFilename('x')).toBe('tjs')
+    })
+  })
+})

package/src/lang/dialect.ts

@@ -0,0 +1,50 @@
+/**
+ * Dialect resolution for file-based tooling.
+ *
+ * The subset invariant (see PRINCIPLES.md) says plain JavaScript must transpile
+ * through TJS without changing meaning, while native `.tjs` gets the full
+ * footgun-removal feature set. The unit of opt-in is the *dialect* — and for a
+ * file, the dialect is its extension. This is the one canonical mapping that
+ * CLIs, bundler plugins, module loaders, and doc systems should all share so
+ * `.js` is never silently "improved" into different semantics.
+ */
+
+/** Source dialect understood by `tjs(src, { dialect })`. */
+export type Dialect = 'js' | 'tjs'
+
+/** How a file should be transpiled, based on its extension. */
+export type SourceKind = 'js' | 'ts' | 'tjs'
+
+const JS_EXT = /\.[mc]?js$/i // .js .mjs .cjs
+const TS_EXT = /\.[mc]?ts$/i // .ts .mts .cts  (excludes .d.ts — handled below)
+const TJS_EXT = /\.tjs$/i
+
+/**
+ * Classify a file by extension into the source kind that determines its
+ * transpile path:
+ *  - `'tjs'` → native TJS: `tjs(src)` (all modes ON — the better language)
+ *  - `'js'`  → plain JS:   `tjs(src, { dialect: 'js' })` (semantics preserved)
+ *  - `'ts'`  → TypeScript: route through `fromTS` (TS → TJS → JS)
+ *
+ * Unknown extensions default to `'tjs'` (the native language). `.d.ts` is
+ * treated as TypeScript.
+ */
+export function sourceKindForFilename(filename: string): SourceKind {
+  if (TJS_EXT.test(filename)) return 'tjs'
+  if (JS_EXT.test(filename)) return 'js'
+  if (TS_EXT.test(filename)) return 'ts'
+  return 'tjs'
+}
+
+/**
+ * Map a filename to the `dialect` option for `tjs()`. `.js`/`.mjs`/`.cjs` ⇒
+ * `'js'` (plain JavaScript, semantics preserved); everything else ⇒ `'tjs'`
+ * (native TJS).
+ *
+ * NOTE: TypeScript files are NOT a `tjs()` dialect — transpile them with
+ * `fromTS` first. Use {@link sourceKindForFilename} when you need to tell
+ * `.ts` apart from `.js`/`.tjs`.
+ */
+export function dialectForFilename(filename: string): Dialect {
+  return sourceKindForFilename(filename) === 'js' ? 'js' : 'tjs'
+}

package/src/lang/emitters/ast.ts

@@ -124,7 +124,8 @@ export function transformFunction(
   source: string,
   returnTypeAnnotation: string | undefined,
   options: TranspileOptions = {},
-  requiredParamsFromPreprocess?: Set<string>
+  requiredParamsFromPreprocess?: Set<string>,
+  helpers?: Map<string, FunctionDeclaration>
 ): {
   ast: BaseNode
   signature: FunctionSignature
@@ -175,6 +176,9 @@ export function transformFunction(
     source,
     filename: options.filename || '<source>',
     options,
+    helpers,
+    helperSteps: helpers ? new Map() : undefined,
+    helperTransforming: helpers ? new Set() : undefined,
   }
 
   // Transform function body
@@ -244,8 +248,21 @@ export function transformFunction(
   // Generate input schema for runtime validation
   const inputSchema = parametersToJsonSchema(signatureParams)
 
+  // Collect transitively-used helper bodies (transformed once) onto the root
+  // node. The VM installs these into ctx.helpers so callLocal can dispatch by
+  // name — call sites stay tiny and recursion is a runtime loop.
+  const helperBodies =
+    ctx.helperSteps && ctx.helperSteps.size > 0
+      ? Object.fromEntries(ctx.helperSteps)
+      : undefined
+
   return {
-    ast: { op: 'seq', steps, inputSchema },
+    ast: {
+      op: 'seq',
+      steps,
+      inputSchema,
+      ...(helperBodies && { helpers: helperBodies }),
+    },
     signature,
     warnings: ctx.warnings,
   }
@@ -1079,6 +1096,34 @@ function transformCallExpression(
     // This would be caught above, but just in case
   }
 
+  // Helper call? Emit callLocal referencing the helper by name. The body is
+  // transformed once and stored in ctx.helperSteps (collected onto the seq
+  // node), so call sites stay tiny and recursion is just a runtime loop.
+  if (ctx.helpers?.has(funcName)) {
+    const paramNames = ensureHelperTransformed(funcName, ctx, expr)
+    const argExprs = expr.arguments.map((arg) =>
+      expressionToValue(arg as Expression, ctx)
+    )
+    if (argExprs.length !== paramNames.length) {
+      throw new TranspileError(
+        `Helper '${funcName}' expects ${paramNames.length} argument(s), got ${argExprs.length}`,
+        getLocation(expr),
+        ctx.source,
+        ctx.filename
+      )
+    }
+    return {
+      step: {
+        op: 'callLocal',
+        name: funcName,
+        args: argExprs,
+        ...(resultVar && { result: resultVar }),
+        ...(resultVar && isConst && { resultConst: true }),
+      },
+      resultVar,
+    }
+  }
+
   // Check if it's a known atom
   // For now, we assume any function call is an atom call
   // The VM will validate at runtime
@@ -1097,6 +1142,89 @@ function transformCallExpression(
   }
 }
 
+/**
+ * Ensure a helper's body has been transformed once into `ctx.helperSteps`,
+ * returning its parameter names (for arity checking at the call site).
+ *
+ * Bodies are stored by name and called by reference at runtime, so recursion
+ * is fine: when a helper references itself (or a mutually-recursive sibling)
+ * the call site only needs the param names — the steps are filled in when the
+ * in-progress transform completes. The `helperTransforming` set just prevents
+ * re-entering a transform that's already underway.
+ */
+function ensureHelperTransformed(
+  name: string,
+  ctx: TransformContext,
+  callSite: CallExpression
+): string[] {
+  const fn = ctx.helpers!.get(name)!
+  // Accept plain identifiers (`x`) and example/default params (`x: 0` → `x = 0`
+  // after colon-shorthand desugaring). Destructuring isn't supported in v1.
+  // Helpers are arity-checked and called with explicit args, so the example/
+  // default is never applied — we only need the parameter name and position.
+  const paramNames: string[] = []
+  for (const param of fn.params) {
+    let id: Identifier | undefined
+    if (param.type === 'Identifier') {
+      id = param as Identifier
+    } else if (
+      param.type === 'AssignmentPattern' &&
+      (param as any).left?.type === 'Identifier'
+    ) {
+      id = (param as any).left as Identifier
+    }
+    if (!id) {
+      throw new TranspileError(
+        `Helper '${name}' parameters must be plain identifiers (optionally with an example value); destructuring is not supported`,
+        param.loc?.start ?? getLocation(callSite),
+        ctx.source,
+        ctx.filename
+      )
+    }
+    paramNames.push(id.name)
+  }
+
+  // Already transformed, or transform already underway (recursive reference):
+  // the call site only needs paramNames; the body is/will be in helperSteps.
+  if (ctx.helperSteps!.has(name) || ctx.helperTransforming!.has(name)) {
+    return paramNames
+  }
+
+  ctx.helperTransforming!.add(name)
+  try {
+    // Transform the helper body in a fresh inner context — isolated locals,
+    // params as the only known identifiers; helpers map is shared so it can
+    // call (and recurse into) other helpers.
+    const helperCtx: TransformContext = {
+      depth: 0,
+      locals: new Map(),
+      parameters: new Map(
+        paramNames.map((p) => [
+          p,
+          {
+            name: p,
+            type: { kind: 'any' as const },
+            required: true,
+          } as ParameterDescriptor,
+        ])
+      ),
+      atoms: ctx.atoms,
+      warnings: ctx.warnings,
+      source: ctx.source,
+      filename: ctx.filename,
+      options: ctx.options,
+      helpers: ctx.helpers,
+      helperSteps: ctx.helperSteps,
+      helperTransforming: ctx.helperTransforming,
+    }
+    const bodySteps = transformBlock(fn.body, helperCtx)
+    ctx.helperSteps!.set(name, { steps: bodySteps, paramNames })
+  } finally {
+    ctx.helperTransforming!.delete(name)
+  }
+  return paramNames
+}
+
 /**
  * Handle method calls like arr.map(), str.slice(), etc.
  */
@@ -1544,6 +1672,21 @@ function expressionToExprNode(
       // Handle global function calls (e.g., parseInt(x), parseFloat(x))
       if (call.callee.type === 'Identifier') {
         const funcName = (call.callee as Identifier).name
+
+        // Helper calls cannot be nested inside expressions — like template
+        // literals and complex calls, they must live at statement level so the
+        // expression sandbox stays call-free. Lift to a temp first.
+        if (ctx.helpers?.has(funcName)) {
+          throw new TranspileError(
+            `Helper '${funcName}' cannot be called inside an expression. ` +
+              `Assign its result to a variable first: ` +
+              `const result = ${funcName}(...); then use result.`,
+            getLocation(expr),
+            ctx.source,
+            ctx.filename
+          )
+        }
+
         return {
           $expr: 'call',
           callee: funcName,