redscript-mc 2.0.0 → 2.1.0

package/src/cli.ts

@@ -9,10 +9,14 @@
  *   redscript version
  */
 
-import { compile, check } from './index'
+import { compile, checkWithWarnings } from './index'
 import { formatError } from './diagnostics'
+import { parseMcVersion, DEFAULT_MC_VERSION } from './types/mc-version'
 import { startRepl } from './repl'
 import { generateDts } from './builtins/metadata'
+import { FileCache } from './cache/index'
+import { DependencyGraph } from './cache/deps'
+import { compileIncremental } from './cache/incremental'
 import * as fs from 'fs'
 import * as path from 'path'
 import * as https from 'https'
@@ -49,6 +53,10 @@ Options:
   --namespace <ns>       Datapack namespace (default: derived from filename)
   --hot-reload <url>     After each successful compile, POST to <url>/reload
                          (use with redscript-testharness; e.g. http://localhost:25561)
+  --source-map           Generate .sourcemap.json files alongside .mcfunction output
+  --mc-version <ver>     Target Minecraft version (default: 1.21). Affects codegen features.
+                         e.g. --mc-version 1.20.2, --mc-version 1.19
+  --lenient              Treat type errors as warnings instead of blocking compilation
   -h, --help             Show this help message
 `)
 }
@@ -150,6 +158,9 @@ function parseArgs(args: string[]): {
   namespace?: string
   help?: boolean
   hotReload?: string
+  sourceMap?: boolean
+  mcVersionStr?: string
+  lenient?: boolean
 } {
   const result: ReturnType<typeof parseArgs> = {}
   let i = 0
@@ -169,6 +180,15 @@ function parseArgs(args: string[]): {
     } else if (arg === '--hot-reload') {
       result.hotReload = args[++i]
       i++
+    } else if (arg === '--source-map') {
+      result.sourceMap = true
+      i++
+    } else if (arg === '--mc-version') {
+      result.mcVersionStr = args[++i]
+      i++
+    } else if (arg === '--lenient') {
+      result.lenient = true
+      i++
     } else if (!result.command) {
       result.command = arg
       i++
@@ -193,6 +213,9 @@ function compileCommand(
   file: string,
   output: string,
   namespace: string,
+  sourceMap = false,
+  mcVersionStr?: string,
+  lenient = false,
 ): void {
   // Read source file
   if (!fs.existsSync(file)) {
@@ -200,10 +223,20 @@ function compileCommand(
     process.exit(1)
   }
 
+  let mcVersion = DEFAULT_MC_VERSION
+  if (mcVersionStr) {
+    try {
+      mcVersion = parseMcVersion(mcVersionStr)
+    } catch (e) {
+      console.error(`Error: ${(e as Error).message}`)
+      process.exit(1)
+    }
+  }
+
   const source = fs.readFileSync(file, 'utf-8')
 
   try {
-    const result = compile(source, { namespace, filePath: file })
+    const result = compile(source, { namespace, filePath: file, generateSourceMap: sourceMap, mcVersion, lenient })
 
     for (const w of result.warnings) {
       console.error(`Warning: ${w}`)
@@ -224,12 +257,12 @@ function compileCommand(
     console.log(`  Namespace: ${namespace}`)
     console.log(`  Files: ${result.files.length}`)
   } catch (err) {
-    console.error(formatError(err as Error, source))
+    console.error(formatError(err as Error, source, file))
     process.exit(1)
   }
 }
 
-function checkCommand(file: string): void {
+function checkCommand(file: string, namespace?: string): void {
   // Read source file
   if (!fs.existsSync(file)) {
     console.error(`Error: File not found: ${file}`)
@@ -238,13 +271,19 @@ function checkCommand(file: string): void {
 
   const source = fs.readFileSync(file, 'utf-8')
 
-  const error = check(source, 'redscript', file)
-  if (error) {
-    console.error(formatError(error, source))
+  const ns = namespace ?? deriveNamespace(file)
+  const result = checkWithWarnings(source, ns, file)
+
+  for (const w of result.warnings) {
+    console.error(`Warning: ${w}`)
+  }
+
+  if (result.error) {
+    console.error(formatError(result.error, source, file))
     process.exit(1)
   }
 
-  console.log(`✓ ${file} is valid`)
+  console.log(`✓ No errors found`)
 }
 
 async function hotReload(url: string): Promise<void> {
@@ -276,54 +315,55 @@ function watchCommand(dir: string, output: string, namespace?: string, hotReload
   console.log(`👁  Watching ${dir} for .mcrs file changes...`)
   console.log(`   Output: ${output}`)
   if (hotReloadUrl) console.log(`   Hot reload: ${hotReloadUrl}`)
+  console.log(`   Incremental compilation enabled`)
   console.log(`   Press Ctrl+C to stop\n`)
 
+  // Set up incremental compilation infrastructure
+  const cacheDir = path.join(dir, '.redscript-cache')
+  const cache = new FileCache(cacheDir)
+  cache.load()
+  const depGraph = new DependencyGraph()
+
   // Debounce timer
   let debounceTimer: NodeJS.Timeout | null = null
 
-  // Compile all .mcrs files in directory
-  async function compileAll(): Promise<void> {
+  // Compile all .mcrs files in directory (incrementally)
+  async function compileAllIncremental(): Promise<void> {
     const files = findRsFiles(dir)
     if (files.length === 0) {
       console.log(`⚠  No .mcrs files found in ${dir}`)
       return
     }
 
-    let hasErrors = false
-    for (const file of files) {
-      let source = ''
-      try {
-        source = fs.readFileSync(file, 'utf-8')
-        const ns = namespace ?? deriveNamespace(file)
-        const result = compile(source, { namespace: ns, filePath: file })
-        for (const w of result.warnings) {
-          console.error(`Warning: ${w}`)
-        }
-
-        // Create output directory
-        fs.mkdirSync(output, { recursive: true })
-
-        // Write all files
-        for (const dataFile of result.files) {
-          const filePath = path.join(output, dataFile.path)
-          const fileDir = path.dirname(filePath)
-          fs.mkdirSync(fileDir, { recursive: true })
-          fs.writeFileSync(filePath, dataFile.content)
-        }
-
-        const timestamp = new Date().toLocaleTimeString()
-        console.log(`✓ [${timestamp}] Compiled ${file} (${result.files.length} files)`)
-      } catch (err) {
-        hasErrors = true
-        const timestamp = new Date().toLocaleTimeString()
-        console.error(`✗ [${timestamp}] ${formatError(err as Error, source)}`)
+    const incResult = compileIncremental(files, cache, depGraph, {
+      namespace,
+      output,
+    })
+
+    const timestamp = new Date().toLocaleTimeString()
+
+    // Print warnings from recompiled files
+    for (const [file, compileResult] of incResult.results) {
+      for (const w of compileResult.warnings) {
+        console.error(`Warning: ${w}`)
       }
+      console.log(`✓ [${timestamp}] Compiled ${path.relative(dir, file)} (${compileResult.files.length} files)`)
     }
 
-    if (!hasErrors) {
-      if (hotReloadUrl) await hotReload(hotReloadUrl)
-      console.log('')
+    if (incResult.cached > 0) {
+      console.log(`  [${timestamp}] ${incResult.cached} file(s) unchanged (cached)`)
     }
+
+    // Print errors
+    for (const [file, errMsg] of incResult.errors) {
+      console.error(`✗ [${timestamp}] ${path.relative(dir, file)}: ${errMsg}`)
+    }
+
+    // Persist cache
+    cache.save()
+
+    if (incResult.errors.size === 0 && hotReloadUrl) await hotReload(hotReloadUrl)
+    console.log('')
   }
 
   // Find all .mcrs files recursively
@@ -333,7 +373,7 @@ function watchCommand(dir: string, output: string, namespace?: string, hotReload
 
     for (const entry of entries) {
       const fullPath = path.join(directory, entry.name)
-      if (entry.isDirectory()) {
+      if (entry.isDirectory() && entry.name !== '.redscript-cache') {
         results.push(...findRsFiles(fullPath))
       } else if (entry.isFile() && entry.name.endsWith('.mcrs')) {
         results.push(fullPath)
@@ -344,7 +384,7 @@ function watchCommand(dir: string, output: string, namespace?: string, hotReload
   }
 
   // Initial compile
-  void compileAll()
+  void compileAllIncremental()
 
   // Watch for changes
   fs.watch(dir, { recursive: true }, (eventType, filename) => {
@@ -355,7 +395,7 @@ function watchCommand(dir: string, output: string, namespace?: string, hotReload
       }
       debounceTimer = setTimeout(() => {
         console.log(`📝 Change detected: ${filename}`)
-        void compileAll()
+        void compileAllIncremental()
       }, 100)
     }
   })
@@ -392,6 +432,9 @@ async function main(): Promise<void> {
         parsed.file,
         output,
         namespace,
+        parsed.sourceMap,
+        parsed.mcVersionStr,
+        parsed.lenient,
       )
       }
       break
@@ -416,7 +459,7 @@ async function main(): Promise<void> {
         printUsage()
         process.exit(1)
       }
-      checkCommand(parsed.file)
+      checkCommand(parsed.file, parsed.namespace)
       break
 
     case 'fmt':

package/src/compile.ts

@@ -13,8 +13,8 @@ import { DiagnosticError } from './diagnostics'
 // Re-export v2 compile
 // ---------------------------------------------------------------------------
 
-export { compile, CompileOptions, CompileResult } from '../src2/emit/compile'
-export type { DatapackFile } from '../src2/emit/index'
+export { compile, CompileOptions, CompileResult } from './emit/compile'
+export type { DatapackFile } from './emit/index'
 
 // ---------------------------------------------------------------------------
 // Source Range / Preprocessing

package/src/diagnostics/index.ts

@@ -161,26 +161,23 @@ export function parseErrorMessage(
   return new DiagnosticError(kind, rawMessage, { file: filePath, line: 1, col: 1 }, sourceLines)
 }
 
-export function formatError(error: Error | DiagnosticError, source?: string): string {
+export function formatError(error: Error | DiagnosticError, source?: string, filePath?: string): string {
   if (error instanceof DiagnosticError) {
     const sourceLines = source?.split('\n') ?? error.sourceLines ?? []
     const { file, line, col } = error.location
-    const locationPart = file
-      ? ` in ${file} at line ${line}, col ${col}`
-      : ` at line ${line}, col ${col}`
-    const lines = [`Error${locationPart}:`]
+    const fileStr = file ?? filePath ?? '<input>'
+    const header = `${fileStr}:${line}:${col}: error: ${error.message}`
     const pointerLines = formatSourcePointer(sourceLines, line, col)
-    if (pointerLines.length > 0) {
-      lines.push(...pointerLines)
+    if (pointerLines.length === 0) {
+      return header
     }
-    lines.push(error.message)
-    return lines.join('\n')
+    return [header, ...pointerLines].join('\n')
   }
 
   if (!source) {
     return error.message
   }
 
-  const parsed = parseErrorMessage('ParseError', error.message, source.split('\n'))
-  return formatError(parsed, source)
+  const parsed = parseErrorMessage('ParseError', error.message, source.split('\n'), filePath)
+  return formatError(parsed, source, filePath)
 }

package/src/emit/compile.ts

@@ -0,0 +1,177 @@
+/**
+ * Top-level compile function for the v2 pipeline.
+ *
+ * Pipeline: source → Lexer → Parser → TypeCheck → HIR → MIR → optimize → LIR → emit
+ */
+
+import { Lexer } from '../lexer'
+import { Parser } from '../parser'
+import { preprocessSourceWithMetadata } from '../compile'
+import { DiagnosticError, parseErrorMessage } from '../diagnostics'
+import { lowerToHIR } from '../hir/lower'
+import { monomorphize } from '../hir/monomorphize'
+import { lowerToMIR } from '../mir/lower'
+import { optimizeModule } from '../optimizer/pipeline'
+import { lowerToLIR } from '../lir/lower'
+import { lirOptimizeModule } from '../optimizer/lir/pipeline'
+import { emit, type DatapackFile } from './index'
+import { coroutineTransform, type CoroutineInfo } from '../optimizer/coroutine'
+import { analyzeBudget } from '../lir/budget'
+import { McVersion, DEFAULT_MC_VERSION } from '../types/mc-version'
+import { TypeChecker } from '../typechecker'
+
+export interface CompileOptions {
+  namespace?: string
+  filePath?: string
+  /** v1 compat: inline library sources (treated as `module library;` imports) */
+  librarySources?: string[]
+  /** When true, generate .sourcemap.json files alongside .mcfunction output */
+  generateSourceMap?: boolean
+  /** Target Minecraft version (default: 1.21). Affects which MC features are used. */
+  mcVersion?: McVersion
+  /**
+   * When true, type errors are reported as warnings instead of blocking compilation.
+   * Use for gradual migration or testing with existing codebases that have type errors.
+   */
+  lenient?: boolean
+}
+
+export interface CompileResult {
+  files: DatapackFile[]
+  warnings: string[]
+  /** Always true — v1 compat shim (compile() throws on error) */
+  readonly success: true
+}
+
+export function compile(source: string, options: CompileOptions = {}): CompileResult {
+  const { namespace = 'redscript', filePath, generateSourceMap = false, mcVersion = DEFAULT_MC_VERSION, lenient = false } = options
+  const warnings: string[] = []
+
+  // Preprocess: resolve import directives, merge imported sources
+  const preprocessed = preprocessSourceWithMetadata(source, { filePath })
+  const processedSource = preprocessed.source
+
+  // Stage 1: Lex + Parse → AST
+  const lexer = new Lexer(processedSource)
+  const tokens = lexer.tokenize()
+  const parser = new Parser(tokens, processedSource, filePath)
+  const ast = parser.parse(namespace)
+
+  // Merge library imports (files with `module library;`) into AST
+  for (const li of preprocessed.libraryImports ?? []) {
+    const libPreprocessed = preprocessSourceWithMetadata(li.source, { filePath: li.filePath })
+    const libTokens = new Lexer(libPreprocessed.source, li.filePath).tokenize()
+    const libAst = new Parser(libTokens, libPreprocessed.source, li.filePath).parse(namespace)
+    for (const fn of libAst.declarations) fn.isLibraryFn = true
+    ast.declarations.push(...libAst.declarations)
+    ast.structs.push(...libAst.structs)
+    ast.implBlocks.push(...libAst.implBlocks)
+    ast.enums.push(...libAst.enums)
+    ast.consts.push(...libAst.consts)
+    ast.globals.push(...libAst.globals)
+  }
+
+  // Merge librarySources (v1 compat: inline library strings) before HIR
+  if (options.librarySources) {
+    for (const libSrc of options.librarySources) {
+      const libTokens = new Lexer(libSrc).tokenize()
+      const libAst = new Parser(libTokens, libSrc).parse(namespace)
+      for (const fn of libAst.declarations) fn.isLibraryFn = true
+      ast.declarations.push(...libAst.declarations)
+      ast.structs.push(...libAst.structs)
+      ast.implBlocks.push(...libAst.implBlocks)
+      ast.enums.push(...libAst.enums)
+      ast.consts.push(...libAst.consts)
+      ast.globals.push(...libAst.globals)
+    }
+  }
+
+  // Stage 1b: Type checking
+  // Run TypeChecker on the merged AST. In error-mode (default), throw on first type error.
+  // In lenient mode, demote type errors to warnings.
+  {
+    const checker = new TypeChecker(processedSource, filePath)
+    const typeErrors = checker.check(ast)
+    if (typeErrors.length > 0) {
+      if (lenient) {
+        for (const e of typeErrors) {
+          warnings.push(`[TypeError] line ${e.location.line}, col ${e.location.col}: ${e.message}`)
+        }
+      } else {
+        throw typeErrors[0]
+      }
+    }
+  }
+
+  // Stage 2–7: lower, optimize, emit
+  // Wrap non-DiagnosticError from later stages so CLI always gets structured errors.
+  try {
+    // Stage 2: AST → HIR
+    const hirRaw = lowerToHIR(ast)
+
+    // Stage 2b: Monomorphize generic functions
+    const hir = monomorphize(hirRaw)
+
+    // Extract @tick, @load, @coroutine, and @schedule functions from HIR (before decorator info is lost)
+    const tickFunctions: string[] = []
+    const loadFunctions: string[] = []
+    const coroutineInfos: CoroutineInfo[] = []
+    const scheduleFunctions: Array<{ name: string; ticks: number }> = []
+    for (const fn of hir.functions) {
+      for (const dec of fn.decorators) {
+        if (dec.name === 'tick') tickFunctions.push(fn.name)
+        if (dec.name === 'load') loadFunctions.push(fn.name)
+        if (dec.name === 'coroutine') {
+          coroutineInfos.push({
+            fnName: fn.name,
+            batch: dec.args?.batch ?? 10,
+            onDone: dec.args?.onDone,
+          })
+        }
+        if (dec.name === 'schedule') {
+          scheduleFunctions.push({ name: fn.name, ticks: dec.args?.ticks ?? 1 })
+        }
+      }
+    }
+
+    // Stage 3: HIR → MIR
+    const mir = lowerToMIR(hir, filePath)
+
+    // Stage 4: MIR optimization
+    const mirOpt = optimizeModule(mir)
+
+    // Stage 4b: Coroutine transform (opt-in, only for @coroutine functions)
+    const coroResult = coroutineTransform(mirOpt, coroutineInfos)
+    const mirFinal = coroResult.module
+    tickFunctions.push(...coroResult.generatedTickFunctions)
+
+    // Stage 5: MIR → LIR
+    const lir = lowerToLIR(mirFinal)
+
+    // Stage 6: LIR optimization
+    const lirOpt = lirOptimizeModule(lir)
+
+    // Static tick budget analysis
+    const coroutineNames = new Set(coroutineInfos.map(c => c.fnName))
+    const budgetDiags = analyzeBudget(lirOpt, coroutineNames)
+    for (const diag of budgetDiags) {
+      if (diag.level === 'error') {
+        throw new DiagnosticError(
+          'LoweringError',
+          diag.message,
+          { line: 1, col: 1, file: filePath },
+        )
+      }
+      warnings.push(diag.message)
+    }
+
+    // Stage 7: LIR → .mcfunction
+    const files = emit(lirOpt, { namespace, tickFunctions, loadFunctions, scheduleFunctions, generateSourceMap, mcVersion })
+
+    return { files, warnings, success: true as const }
+  } catch (err) {
+    if (err instanceof DiagnosticError) throw err
+    const sourceLines = processedSource.split('\n')
+    throw parseErrorMessage('LoweringError', (err as Error).message, sourceLines, filePath)
+  }
+}

package/{src2 → src}/emit/index.ts

@@ -6,6 +6,8 @@
  */
 
 import type { LIRModule, LIRFunction, LIRInstr, Slot, CmpOp, ExecuteSubcmd } from '../lir/types'
+import { SourceMapBuilder, serializeSourceMap, sourceMapPath } from './sourcemap'
+import { McVersion, DEFAULT_MC_VERSION } from '../types/mc-version'
 
 export interface DatapackFile {
   path: string
@@ -16,6 +18,11 @@ export interface EmitOptions {
   namespace: string
   tickFunctions?: string[]
   loadFunctions?: string[]
+  scheduleFunctions?: Array<{ name: string; ticks: number }>
+  /** When true, generate a .sourcemap.json sidecar file for each .mcfunction */
+  generateSourceMap?: boolean
+  /** Target Minecraft version; controls which MC features are used in codegen */
+  mcVersion?: McVersion
 }
 
 // ---------------------------------------------------------------------------
@@ -26,7 +33,10 @@ export function emit(module: LIRModule, options: EmitOptions): DatapackFile[] {
   const { namespace } = options
   const tickFns = options.tickFunctions ?? []
   const loadFns = options.loadFunctions ?? []
+  const scheduleFns = options.scheduleFunctions ?? []
   const objective = module.objective
+  const genSourceMap = options.generateSourceMap ?? false
+  const mcVersion = options.mcVersion ?? DEFAULT_MC_VERSION
   const files: DatapackFile[] = []
 
   // pack.mcmeta
@@ -46,9 +56,27 @@ export function emit(module: LIRModule, options: EmitOptions): DatapackFile[] {
 
   // Each LIR function → .mcfunction file
   for (const fn of module.functions) {
-    const lines = emitFunction(fn, namespace, objective)
     const fnPath = fnNameToPath(fn.name, namespace)
-    files.push({ path: fnPath, content: lines.join('\n') + '\n' })
+    if (genSourceMap) {
+      const builder = new SourceMapBuilder(fnPath)
+      const lines = emitFunctionWithSourceMap(fn, namespace, objective, builder, mcVersion)
+      files.push({ path: fnPath, content: lines.join('\n') + '\n' })
+      const map = builder.build()
+      if (map) {
+        files.push({ path: sourceMapPath(fnPath), content: serializeSourceMap(map) })
+      }
+    } else {
+      const lines = emitFunction(fn, namespace, objective, mcVersion)
+      files.push({ path: fnPath, content: lines.join('\n') + '\n' })
+    }
+  }
+
+  // @schedule wrapper functions: _schedule_xxx → schedule function ns:xxx Nt
+  for (const { name, ticks } of scheduleFns) {
+    files.push({
+      path: `data/${namespace}/function/_schedule_${name}.mcfunction`,
+      content: `schedule function ${namespace}:${name} ${ticks}t\n`,
+    })
   }
 
   // Tag files for tick/load
@@ -76,10 +104,25 @@ export function emit(module: LIRModule, options: EmitOptions): DatapackFile[] {
 // Function emission
 // ---------------------------------------------------------------------------
 
-function emitFunction(fn: LIRFunction, namespace: string, objective: string): string[] {
+function emitFunction(fn: LIRFunction, namespace: string, objective: string, mcVersion: McVersion): string[] {
+  const lines: string[] = []
+  for (const instr of fn.instructions) {
+    lines.push(emitInstr(instr, namespace, objective, mcVersion))
+  }
+  return lines
+}
+
+function emitFunctionWithSourceMap(
+  fn: LIRFunction,
+  namespace: string,
+  objective: string,
+  builder: SourceMapBuilder,
+  mcVersion: McVersion,
+): string[] {
   const lines: string[] = []
   for (const instr of fn.instructions) {
-    lines.push(emitInstr(instr, namespace, objective))
+    lines.push(emitInstr(instr, namespace, objective, mcVersion))
+    builder.addLine(instr.sourceLoc)
   }
   return lines
 }
@@ -94,7 +137,7 @@ function fnNameToPath(name: string, namespace: string): string {
 // Instruction emission
 // ---------------------------------------------------------------------------
 
-function emitInstr(instr: LIRInstr, ns: string, obj: string): string {
+function emitInstr(instr: LIRInstr, ns: string, obj: string, mcVersion: McVersion): string {
   switch (instr.kind) {
     case 'score_set':
       return `scoreboard players set ${slot(instr.dst)} ${instr.value}`
@@ -127,7 +170,7 @@ function emitInstr(instr: LIRInstr, ns: string, obj: string): string {
       return `scoreboard players operation ${slot(instr.a)} >< ${slot(instr.b)}`
 
     case 'store_cmd_to_score':
-      return `execute store result score ${slot(instr.dst)} run ${emitInstr(instr.cmd, ns, obj)}`
+      return `execute store result score ${slot(instr.dst)} run ${emitInstr(instr.cmd, ns, obj, mcVersion)}`
 
     case 'store_score_to_nbt':
       return `execute store result storage ${instr.ns} ${instr.path} ${instr.type} ${instr.scale} run scoreboard players get ${slot(instr.src)}`
@@ -145,7 +188,11 @@ function emitInstr(instr: LIRInstr, ns: string, obj: string): string {
       return `function ${instr.fn}`
 
     case 'call_macro':
-      return `function ${instr.fn} with storage ${instr.storage}`
+      if (mcVersion >= McVersion.v1_20_2) {
+        return `function ${instr.fn} with storage ${instr.storage}`
+      }
+      // Pre-1.20.2: macros not supported; call function directly (args in storage are ignored)
+      return `function ${instr.fn}`
 
     case 'call_if_matches':
       return `execute if score ${slot(instr.slot)} matches ${instr.range} run function ${instr.fn}`
@@ -168,7 +215,13 @@ function emitInstr(instr: LIRInstr, ns: string, obj: string): string {
       return `scoreboard players operation $ret ${instr.slot.obj} = ${slot(instr.slot)}`
 
     case 'macro_line':
-      return `$${instr.template}`
+      if (mcVersion >= McVersion.v1_20_2) {
+        return `$${instr.template}`
+      }
+      // Pre-1.20.2: function macros not available. Emit as a plain command with
+      // $(param) placeholders replaced by storage reads via data get (best-effort
+      // compat for string/id params; numeric coords will not be dynamic).
+      return macroLineCompat(instr.template)
 
     case 'raw':
       return instr.cmd
@@ -194,6 +247,17 @@ function cmpToMC(op: CmpOp): string {
   }
 }
 
+/**
+ * Pre-1.20.2 compat: emit a macro template as a plain command.
+ * $(param) placeholders are replaced with `storage rs:macro_args <param>` data-get
+ * expressions for string/id values, or left as literal "0" for coordinates.
+ * This is best-effort — dynamic numeric positions cannot be truly emulated.
+ */
+function macroLineCompat(template: string): string {
+  // Replace $(param) with data-get-style substitution marker
+  return template.replace(/\$\((\w+)\)/g, (_m, p) => `{storage:rs:macro_args,path:${p}}`)
+}
+
 function emitSubcmd(sub: ExecuteSubcmd): string {
   switch (sub.kind) {
     case 'as':