@brew-lang/sdk 0.0.0-stage → 0.3.0-alpha

package/build/transpiler.js

@@ -0,0 +1,2025 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsdocTagText = jsdocTagText;
+exports.transpile = transpile;
+/**
+ * Brew Compiler — TypeScript to Skript
+ *
+ * Parses TypeScript with the official TypeScript parser by using the
+ * `ts.createSourceFile` API function, and then emits Skript code by walking
+ * the AST.
+ *
+ * The transpiler keeps a registry of declared types (interfaces / classes /
+ * functions) and a stack of lexical scopes, so that every identifier is
+ * resolved to a unique Skript variable key and a compile-time type. A type
+ * dispatcher then picks the right Skript representation per type:
+ *
+ * - types deriving from `NBTCompound`  -> SkBee `nbt compound` values,
+ *   indexed with `tag "name" of {_x}` syntax
+ * - types deriving from `JavaObject`   -> skript-Reflect syntax,
+ *   i.e. `{_player}.getLocation()`
+ * - everything else deriving from
+ *   `object` (including `object` and object literals) -> Skript list
+ *   variables, indexed with `{_x}::key`
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ts = __importStar(require("typescript"));
+// ---------------------------------------------------------------------------
+// Type mapping: TS types -> Skript types
+// ---------------------------------------------------------------------------
+const TYPE_MAP = {
+    // TS primitives and `object` keep their TS (lowercase) spelling
+    number: "number",
+    string: "text",
+    boolean: "boolean",
+    // `object` values cross function boundaries as an NBT compound: a single
+    // value (keyed lists lose their indices across calls, SkriptLang#811)
+    // carried by local variables only — global variables would not be usable
+    // inside async sections.
+    object: "nbt compound",
+    any: "object",
+    // `Function` holds a lambda (section) value; Skript's catch-all type
+    Function: "object",
+    // Skript domain types are PascalCase in the TS API...
+    Player: "player",
+    World: "world",
+    ItemType: "item type",
+    Location: "location",
+    Vector: "vector",
+    Timespan: "timespan",
+    // ...with lowercase aliases still accepted
+    player: "player",
+    world: "world",
+    itemtype: "item type",
+    location: "location",
+    vector: "vector",
+    timespan: "timespan",
+};
+/** Base types that decide a type's Skript representation. */
+const NBT_BASES = new Set(["nbtcompound", "compound"]);
+// "object": mirrored classes extend the java.lang.Object interface from
+// the @brew-types language packs
+const JAVA_BASES = new Set(["javaobject", "java", "object"]);
+/** Last dotted segment of a type name: org.bukkit.entity.Player -> Player
+ * (the registry keys declared types by their simple class name, so qualified
+ * Java-path references resolve to them). */
+function lastSegment(typeName) {
+    const i = typeName.lastIndexOf(".");
+    return i === -1 ? typeName : typeName.slice(i + 1);
+}
+// ---------------------------------------------------------------------------
+// Type registry: interfaces, classes and function signatures in the file
+// ---------------------------------------------------------------------------
+class TypeRegistry {
+    types = new Map();
+    /** Function name -> signature (param type texts + return type text). */
+    signatures = new Map();
+    /**
+     * `@ffi <pattern>` over an ambient `declare const X: T;`: the pattern
+     * substitutes for every use of X, like a macro. Declares without a
+     * pattern stay type-level.
+     */
+    macros = new Map();
+    /**
+     * `@ffi <pattern>` over an interface property: the pattern emits the
+     * property's native syntax instead of the default access. %this% is the
+     * receiver, %key% the property name, and %value% (setter form) the
+     * assigned value; %1%/%2%/%3% are aliases.
+     */
+    memberPatterns = new Map();
+    /**
+     * `@macro` functions: TypeScript macros, C/C++ #define-style — never
+     * emitted as functions; every call site expands the macro's body inline
+     * with its arguments bound to locals.
+     */
+    macroDecls = new Map();
+    /** Java class locations of the types used as Java objects in the script. */
+    usedClasslocs = new Set();
+    /** Collect declarations from a source file (case is preserved). */
+    collect(sf) {
+        for (const stmt of sf.statements) {
+            if (ts.isInterfaceDeclaration(stmt) || ts.isClassDeclaration(stmt)) {
+                const name = stmt.name?.text;
+                if (!name)
+                    continue;
+                const locTag = ts.getJSDocTags(stmt).find((t) => t.tagName.text === "classloc");
+                const classloc = locTag && typeof locTag.comment === "string"
+                    ? locTag.comment.trim() : undefined;
+                const info = {
+                    bases: (stmt.heritageClauses ?? []).flatMap((c) => c.types.map((t) => t.expression.getText())),
+                    members: new Map(),
+                    hasMethods: false,
+                    classloc,
+                };
+                for (const m of stmt.members) {
+                    if (ts.isPropertySignature(m) || ts.isPropertyDeclaration(m)) {
+                        if (ts.isIdentifier(m.name)) {
+                            info.members.set(m.name.text, m.type?.getText() ?? "any");
+                            // an @ffi pattern over the property: native get/set syntax
+                            const ptag = jsdocTagText(ts.getJSDocTags(m), ["ffi", "skript"]);
+                            if (ptag) {
+                                if (!this.memberPatterns.has(name))
+                                    this.memberPatterns.set(name, new Map());
+                                this.memberPatterns.get(name).set(m.name.text, ptag);
+                            }
+                        }
+                    }
+                    else if (ts.isMethodSignature(m) || ts.isMethodDeclaration(m) ||
+                        ts.isConstructSignatureDeclaration(m) || ts.isIndexSignatureDeclaration(m) ||
+                        ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) {
+                        info.hasMethods = true;
+                        if (ts.isGetAccessorDeclaration(m) && ts.isIdentifier(m.name)) {
+                            info.members.set(m.name.text, m.type?.getText() ?? "any");
+                        }
+                        else if (ts.isSetAccessorDeclaration(m) && ts.isIdentifier(m.name)) {
+                            info.members.set(m.name.text, m.parameters[0].type?.getText() ?? "any");
+                        }
+                        else if ((ts.isMethodSignature(m) || ts.isMethodDeclaration(m)) && ts.isIdentifier(m.name)) {
+                            // class methods (declare class members, incl. static ones) type
+                            // their accesses too, e.g. the result of a static call
+                            info.members.set(m.name.text, m.type?.getText() ?? "any");
+                        }
+                    }
+                }
+                this.types.set(name, info);
+            }
+            if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+                // `/** @ffi <pattern> */` maps an ambient stub onto a native
+                // Skript syntax instead of a function call: %1%, %2%, ... in the
+                // pattern are the call arguments, e.g.
+                //   /** @ffi broadcast %1% */ declare function broadcast(msg: string)
+                // turns `broadcast(m)` into the effect `broadcast {_m}`.
+                const pattern = jsdocTagText(ts.getJSDocTags(stmt), ["ffi", "skript"]);
+                // a `@macro` function is never emitted: its body expands inline at
+                // every call site. `@inline` generates the same macro from the
+                // function, but the function itself IS emitted — so value-position
+                // calls of statement-bodied inlines fall back to a real call.
+                if (stmt.body &&
+                    (jsdocTagText(ts.getJSDocTags(stmt), ["macro"]) !== undefined ||
+                        jsdocTagText(ts.getJSDocTags(stmt), ["inline"]) !== undefined)) {
+                    this.macroDecls.set(stmt.name.text, stmt);
+                }
+                this.signatures.set(stmt.name.text, {
+                    params: stmt.parameters.map((p) => p.type?.getText() ?? ""),
+                    ret: stmt.type?.getText() ?? "",
+                    pattern,
+                });
+            }
+            // Ambient `declare const X: T;` with an @ffi tag: a const macro whose
+            // pattern substitutes for every use of X.
+            if (ts.isVariableStatement(stmt)) {
+                for (const d of stmt.declarationList.declarations) {
+                    if (!ts.isIdentifier(d.name))
+                        continue;
+                    const ambient = (ts.getCombinedModifierFlags(d) & ts.ModifierFlags.Ambient) !== 0;
+                    if (!ambient)
+                        continue;
+                    const tag = jsdocTagText(ts.getJSDocTags(stmt), ["ffi", "skript"]);
+                    if (tag) {
+                        this.macros.set(d.name.text, {
+                            pattern: tag,
+                            type: d.type?.getText() ?? "",
+                        });
+                    }
+                }
+            }
+            // Type aliases: resolve to the aliased text.
+            if (ts.isTypeAliasDeclaration(stmt)) {
+                this.types.set(stmt.name.text, {
+                    bases: [],
+                    members: new Map(),
+                    hasMethods: false,
+                    alias: stmt.type.getText(),
+                });
+            }
+        }
+    }
+    /**
+     * Resolve relative imports and register the declarations of the imported
+     * modules (interfaces, type aliases, and declare-function signatures,
+     * including their @ffi patterns). This is how the TS API modules in
+     * src/api are consumed: scripts `import { broadcast } from ".../api"` and
+     * the transpiler picks up the mappings. Imported declarations override
+     * same-named local ones. Imported files are only PARSED, never type-checked.
+     */
+    collectImports(sf, importBase, visited = new Set()) {
+        for (const stmt of sf.statements) {
+            // follow both imports and index-style re-exports (`export * from "./x"`)
+            if (!ts.isImportDeclaration(stmt) &&
+                !(ts.isExportDeclaration(stmt) && stmt.moduleSpecifier))
+                continue;
+            const spec = stmt.moduleSpecifier.text;
+            if (!spec.startsWith(".")) {
+                // @brew-types/* language packs resolve through node_modules (walking
+                // up from the importing file, like node); other bare specifiers are
+                // left to the editor/runtime and not followed
+                if (spec.startsWith("@brew-types/")) {
+                    const pkgFile = TypeRegistry.resolveBrewSpec(spec, importBase);
+                    if (pkgFile && !visited.has(pkgFile)) {
+                        visited.add(pkgFile);
+                        const sub = ts.createSourceFile(pkgFile, fs.readFileSync(pkgFile, "utf8"), ts.ScriptTarget.Latest, true);
+                        this.collect(sub);
+                        this.collectImports(sub, path.dirname(pkgFile), visited);
+                    }
+                }
+                continue;
+            }
+            const target = spec.replace(/\.js$/, "");
+            const candidates = [
+                path.join(importBase, target + ".ts"),
+                path.join(importBase, target, "index.ts"),
+            ];
+            const file = candidates.find((c) => fs.existsSync(c));
+            if (!file || visited.has(file))
+                continue;
+            visited.add(file);
+            const sub = ts.createSourceFile(file, fs.readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+            this.collect(sub);
+            this.collectImports(sub, path.dirname(file), visited);
+        }
+    }
+    /** Resolve an @brew-types/... specifier to a file inside a node_modules
+     * dir at or above fromDir (the file itself or its index, .ts or .d.ts). */
+    static resolveBrewSpec(spec, fromDir) {
+        let dir = path.resolve(fromDir);
+        for (;;) {
+            const base = path.join(dir, "node_modules", spec);
+            for (const cand of [
+                base + ".ts", base + ".d.ts",
+                path.join(base, "index.ts"), path.join(base, "index.d.ts"),
+            ]) {
+                if (fs.existsSync(cand))
+                    return cand;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return null;
+            dir = parent;
+        }
+    }
+    /** Resolve a type name to its Skript representation category. */
+    category(typeText, depth = 0) {
+        // qualified names (org.bukkit.entity.Player) bind the declared class
+        let raw = lastSegment(typeText.trim());
+        if (!raw || raw === "void" || raw === "undefined" || raw === "null")
+            return "plain";
+        // async functions are annotated Promise<T>; the returned value is T
+        const promise = /^Promise<(.+)>$/.exec(raw);
+        if (promise)
+            return this.category(promise[1], depth + 1);
+        raw = lastSegment(raw); // strip any qualifier the unwrap revealed
+        if (raw.endsWith("[]"))
+            return "plain"; // Skript plural/list values
+        const lower = raw.toLowerCase();
+        if (["number", "string", "boolean", "text", "bigint", "symbol"].includes(lower))
+            return "plain";
+        if (raw === "object" || lower === "any")
+            return "list";
+        const info = this.types.get(raw);
+        if (info) {
+            if (info.alias !== undefined)
+                return this.category(info.alias, depth + 1);
+            if (NBT_BASES.has(lower))
+                return "nbt";
+            if (JAVA_BASES.has(lower))
+                return "java";
+            if (info.hasMethods && depth < 16)
+                return "java";
+            // Declared data types default to list representation unless a base
+            // says otherwise.
+            for (const base of info.bases) {
+                if (NBT_BASES.has(base.toLowerCase()))
+                    return "nbt";
+                if (JAVA_BASES.has(base.toLowerCase()))
+                    return "java";
+                if (this.types.has(base)) {
+                    const cat = this.category(base, depth + 1);
+                    if (cat !== "list" || this.types.get(base).hasMethods)
+                        return cat;
+                }
+            }
+            return "list";
+        }
+        if (NBT_BASES.has(lower))
+            return "nbt";
+        if (JAVA_BASES.has(lower))
+            return "java";
+        // `Function`-typed values hold sections: opaque single values
+        if (lower === "function")
+            return "plain";
+        // Unknown types (e.g. native Skript types like `player`) index like lists.
+        return "list";
+    }
+    /** Type text of a named member of a declared type, if known. */
+    memberType(typeText, member) {
+        const info = this.types.get(lastSegment(typeText.trim()));
+        if (!info || !info.members.has(member))
+            return null;
+        return info.members.get(member);
+    }
+    /**
+     * Mark a type as used as a Java object, collecting its @classloc for the
+     * skript-Reflect `import:` section.
+     */
+    markJava(typeName) {
+        const info = this.types.get(lastSegment(typeName.trim()));
+        if (info?.classloc)
+            this.usedClasslocs.add(info.classloc);
+    }
+}
+class Scope {
+    vars = new Map();
+}
+class ScopeStack {
+    obfuscate;
+    scopes = [new Scope()];
+    usedKeys = new Set();
+    counter = 0;
+    /** When true, locals get short generated keys ({_o1}, {_o2}, ...) instead
+     *  of their source names. Safe: Skript locals are call-scoped, so keys
+     *  can be reused across functions. */
+    constructor(obfuscate = false) {
+        this.obfuscate = obfuscate;
+    }
+    push() { this.scopes.push(new Scope()); }
+    pop() { this.scopes.pop(); }
+    /** Next short local key for obfuscated builds. */
+    nextKey() {
+        return `_o${(++this.counter).toString(36)}`;
+    }
+    /** Bind a name in the innermost scope under a unique Skript key. */
+    declare(name, typeText, category, isList = false) {
+        const key = this.obfuscate ? this.nextKey() : this.uniqueKey(`_${name}`);
+        return this.bind(name, key, typeText, category, isList);
+    }
+    uniqueKey(base) {
+        let key = base;
+        let n = 2;
+        while (this.usedKeys.has(key))
+            key = `${base}_${n++}`;
+        return key;
+    }
+    /** Bind a name in the innermost scope under the given key. */
+    bind(name, key, typeText, category, isList = false) {
+        this.usedKeys.add(key);
+        const info = { name, key, typeText, category, isList };
+        this.scopes[this.scopes.length - 1].vars.set(name, info);
+        return info;
+    }
+    /** Bind a name that keeps an externally chosen key (function parameters). */
+    declareWithKey(name, key, typeText, category, isList = false) {
+        return this.bind(name, key, typeText, category, isList);
+    }
+    /**
+     * Bind an undeclared name as a globalThis property: like JavaScript,
+     * assigning to a name no `let`/`const` declared creates a global —
+     * {globalThis::<name>} in Skript. Global names stay readable across
+     * triggers, so they are never obfuscated or suffixed.
+     */
+    declareGlobal(name, typeText, category, isList = false) {
+        const info = this.bind(name, `globalThis::${name}`, typeText, category, isList);
+        info.global = true;
+        return info;
+    }
+    /** Look a name up from the innermost scope outwards. */
+    lookup(name) {
+        for (let i = this.scopes.length - 1; i >= 0; i--) {
+            const v = this.scopes[i].vars.get(name);
+            if (v)
+                return v;
+        }
+        return undefined;
+    }
+}
+/**
+ * Runtime helper emitted (once) into scripts that read NBT tags. SkBee's
+ * typed getters return null when the requested type doesn't match the tag's
+ * actual type (NBTApi.getTag), so this reads the tag's runtime type first
+ * and uses the matching getter. */
+/**
+ * Deterministic per-file id (FNV-1a of the source, base36): the same file
+ * always obfuscates to the same names, and two different files never share
+ * function names — like ES6 module-scoped symbols.
+ */
+function fileKey(source) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < source.length; i++) {
+        h ^= source.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+const TS2SK_TAG_HELPER = [
+    "function brew_tag(c: nbt compound, k: text) :: object:",
+    "\tset {_t} to tag type of tag \"%{_k}%\" of {_c}",
+    "\tif \"%{_t}%\" is \"byte tag\":",
+    "\t\treturn byte tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"short tag\":",
+    "\t\treturn short tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"int tag\":",
+    "\t\treturn int tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"long tag\":",
+    "\t\treturn long tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"float tag\":",
+    "\t\treturn float tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"double tag\":",
+    "\t\treturn double tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"boolean tag\":",
+    "\t\treturn boolean tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"string tag\":",
+    "\t\treturn string tag \"%{_k}%\" of {_c}",
+    "\telse if \"%{_t}%\" is \"compound tag\":",
+    "\t\treturn compound tag \"%{_k}%\" of {_c}",
+    "\tstop",
+    "",
+];
+/**
+ * The comment of the first matching JSDoc tag. `@ffi` is the native-syntax
+ * annotation (the original name `@skript` still works); `@macro` marks a
+ * TypeScript macro (a C/C++ #define-style inline expansion).
+ */
+function jsdocTagText(tags, names) {
+    for (const t of tags) {
+        if (names.includes(t.tagName.text)) {
+            // a bare tag (no comment, e.g. `/** @macro */`) is present with ""
+            return typeof t.comment === "string" ? t.comment.trim() : "";
+        }
+    }
+    return undefined;
+}
+function skriptType(node, reg) {
+    if (!node)
+        return "object";
+    if (ts.isUnionTypeNode(node)) {
+        // `T | undefined` -> keep base type (Skript params are effectively optional)
+        const nonNull = node.types.find((t) => t.getText() !== "undefined" && t.getText() !== "null");
+        if (nonNull)
+            return skriptType(nonNull, reg);
+    }
+    const raw = node.getText();
+    // Arrays map to Skript's plural list types: player[] -> players
+    if (raw.endsWith("[]")) {
+        const elem = raw.slice(0, -2).toLowerCase();
+        if (elem === "object" || elem === "any")
+            return "objects";
+        return `${skriptTypeNodeText(raw.slice(0, -2), reg)}s`;
+    }
+    return skriptTypeNodeText(raw, reg);
+}
+function skriptTypeNodeText(raw, reg) {
+    // async functions are annotated Promise<T>; the function itself returns T
+    raw = raw.replace(/^Promise<(.+)>$/, "$1");
+    const mapped = TYPE_MAP[raw] ?? TYPE_MAP[raw.toLowerCase()] ?? raw;
+    const cat = reg.category(raw);
+    if (cat === "nbt")
+        return "nbt compound";
+    if (cat === "java") {
+        reg.markJava(raw);
+        return "javaobject";
+    }
+    return mapped;
+}
+// ---------------------------------------------------------------------------
+// Transpiler: expression/statement emission with the type dispatcher
+// ---------------------------------------------------------------------------
+class Transpiler {
+    lines = [];
+    indent = 0;
+    /** Statements that must be emitted before the next emitted line. */
+    /** Statements that must be emitted before the next emitted line. The
+     *  indentation is baked in at push time: pending lines can outlive the
+     *  statement that created them (e.g. at the end of a trigger body) and must
+     *  not be re-indented at whatever depth they finally flush. */
+    pending = [];
+    push(line) {
+        this.pending.push("\t".repeat(this.indent) + line);
+    }
+    /** Like push(), but `delta` indentation levels deeper (loop bodies). */
+    pushAt(delta, line) {
+        this.pending.push("\t".repeat(this.indent + delta) + line);
+    }
+    reg = new TypeRegistry();
+    /** Category of the return type of the function currently being emitted. */
+    currentRetCat = "plain";
+    /** True while emitting a function declared to return `object`. */
+    currentRetIsObject = false;
+    /**
+     * True while emitting a named function body: Skript functions cannot
+     * contain delays, so `await` is a compile error there (triggers and
+     * lambda/section bodies can await).
+     */
+    inFunction = false;
+    /**
+     * True once the current trigger or section body emitted an async run
+     * (`run section ... async`): Skript forbids `return` after a delay, so
+     * a later return is a compile error — the result belongs in a global.
+     */
+    sectionAwaited = false;
+    /**
+     * True while emitting the top-level `on load:` init trigger: top-level
+     * `let`/`const` declarations bind as globalThis globals, so triggers
+     * (and other scripts) can read them later.
+     */
+    topLevelInit = false;
+    /** Emits the brew_tag runtime helper when any NBT read occurs. */
+    usedTagHelper = false;
+    scopes = new ScopeStack(false);
+    tempCounter = 0;
+    /** Obfuscate local variables and locally-defined function names. */
+    obfuscate = false;
+    /** Local function renames for obfuscated builds (source name -> output). */
+    fnMap = new Map();
+    constructor(sf, opts) {
+        this.obfuscate = !!opts?.obfuscate;
+        this.scopes = new ScopeStack(this.obfuscate);
+        this.reg.collect(sf);
+        // imported API modules register AFTER the local declarations (they win)
+        if (opts?.importBase)
+            this.reg.collectImports(sf, opts.importBase);
+    }
+    // -- emitter helpers ------------------------------------------------------
+    emit(line) {
+        this.flushPending();
+        this.lines.push("\t".repeat(this.indent) + line);
+    }
+    flushPending() {
+        for (const l of this.pending)
+            this.lines.push(l);
+        this.pending = [];
+    }
+    body(stmts) {
+        for (const s of stmts)
+            this.statement(s);
+    }
+    indented(stmts) {
+        this.indent++;
+        this.body(stmts);
+        this.indent--;
+    }
+    // -- type helpers ---------------------------------------------------------
+    /** Skript variable reference for an identifier bound in scope. */
+    ref(v) {
+        return v.isList ? `{${v.key}::*}` : `{${v.key}}`;
+    }
+    /** Static type of an expression, when it can be determined. */
+    typeOfExpr(node) {
+        if (ts.isIdentifier(node)) {
+            const v = this.scopes.lookup(node.text);
+            if (v)
+                return v.typeText;
+            // an ambient @ffi const carries its declared type for dispatch
+            return this.reg.macros.get(node.text)?.type ?? "";
+        }
+        if (ts.isNumericLiteral(node))
+            return "number";
+        if (ts.isStringLiteral(node))
+            return "string";
+        if (node.kind === ts.SyntaxKind.TrueKeyword || node.kind === ts.SyntaxKind.FalseKeyword)
+            return "boolean";
+        if (ts.isPropertyAccessExpression(node)) {
+            const recExpr = node.expression;
+            // a mirrored class used as receiver (static access) contributes its own
+            // members to the type of the access
+            const rec = ts.isIdentifier(recExpr) && this.staticClassOf(recExpr.text)
+                ? recExpr.text
+                : this.typeOfExpr(recExpr);
+            return this.reg.memberType(rec, node.name.text) ?? "";
+        }
+        if (ts.isAwaitExpression(node))
+            return this.typeOfExpr(node.expression);
+        if (ts.isCallExpression(node)) {
+            if (ts.isIdentifier(node.expression)) {
+                if (this.callableOf(node.expression.text))
+                    return "";
+                return this.reg.signatures.get(node.expression.text)?.ret ?? "";
+            }
+            if (ts.isPropertyAccessExpression(node.expression)) {
+                const recExpr = node.expression.expression;
+                // static call on a mirrored class: the receiver's members type it
+                const rec = ts.isIdentifier(recExpr) && this.staticClassOf(recExpr.text)
+                    ? recExpr.text
+                    : this.typeOfExpr(recExpr);
+                return this.reg.memberType(rec, node.expression.name.text) ?? "";
+            }
+        }
+        if (ts.isObjectLiteralExpression(node))
+            return "object";
+        if (ts.isNewExpression(node))
+            return node.expression.getText();
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken)
+            return "number";
+        return "";
+    }
+    /** Category of an expression's value. */
+    categoryOfExpr(node) {
+        return this.reg.category(this.typeOfExpr(node));
+    }
+    /**
+     * If `name` refers to a mirrored class/interface with a @classloc and is
+     * not shadowed by a local variable or macro, return its registry entry —
+     * the receiver of a static call/field access (BukkitAdapter.worldIdentifier(w)).
+     */
+    staticClassOf(name) {
+        if (this.scopes.lookup(name) || this.reg.macros.has(name))
+            return undefined;
+        const info = this.reg.types.get(name);
+        return info?.classloc ? info : undefined;
+    }
+    /** True for calls to functions declared to return `object` (carrier ids). */
+    isObjCall(node) {
+        return ts.isCallExpression(node) && ts.isIdentifier(node.expression) &&
+            (this.reg.signatures.get(node.expression.text)?.ret ?? "").toLowerCase() === "object";
+    }
+    /** List form of a variable reference: {_x} -> {_x::*}. */
+    listForm(e) {
+        return e.replace(/^\{(_\w+|globalThis::\w+)\}$/, "{$1::*}");
+    }
+    /**
+     * The variable a call runs as a section, if the name is callable: a lambda
+     * or a `Function`-typed value (e.g. a parameter) holds a section object.
+     */
+    callableOf(name) {
+        const v = this.scopes.lookup(name);
+        if (!v)
+            return undefined;
+        return v.lambda || v.typeText.toLowerCase() === "function" ? v : undefined;
+    }
+    /**
+     * Whether a call on a callable variable runs async: awaited calls always
+     * do; lambdas default to their own `async` modifier, `Function` values
+     * (whose section came from elsewhere) run sync unless awaited.
+     */
+    callRunsAsync(v, awaited) {
+        return awaited || (v.lambda?.async ?? false);
+    }
+    /**
+     * Emit a lambda as a skript-reflect section:
+     *
+     *   create new section with {_a}, {_b} stored in {_f}:
+     *     ...body...
+     *
+     * The parameters bind to their own locals ({_a}); locals declared before
+     * the creation stay readable inside the section body (skript-reflect
+     * sections document this), which is how closures capture.
+     */
+    emitLambdaSection(arrow, key) {
+        this.scopes.push();
+        const prevInFunction = this.inFunction;
+        const prevAwaited = this.sectionAwaited;
+        this.inFunction = false; // sections may await even inside functions
+        this.sectionAwaited = false;
+        const params = arrow.parameters.map((p) => {
+            const t = p.type?.getText() ?? "";
+            const info = this.scopes.declare(p.name.getText(), t, this.reg.category(t));
+            return `{${info.key}}`;
+        });
+        const withArgs = params.length ? ` with ${params.join(", ")}` : "";
+        this.emit(`create new section${withArgs} stored in {${key}}:`);
+        this.indent++;
+        const prevObject = this.currentRetIsObject;
+        const prevCat = this.currentRetCat;
+        this.currentRetIsObject = false;
+        this.currentRetCat = arrow.type ? this.reg.category(arrow.type.getText()) : "plain";
+        if (arrow.body.kind === ts.SyntaxKind.Block) {
+            this.body(arrow.body.statements);
+        }
+        else {
+            // expression body: (a, b) => a + b
+            this.emit(`return ${this.expr(arrow.body)}`);
+        }
+        this.currentRetIsObject = prevObject;
+        this.currentRetCat = prevCat;
+        this.inFunction = prevInFunction;
+        this.sectionAwaited = prevAwaited;
+        this.indent--;
+        this.scopes.pop();
+    }
+    /**
+     * Emit `run section {_f} ... with args and store result in {_r}` for a
+     * lambda (or `Function`-typed value) call in expression position,
+     * returning the result's reference. Async sections only produce output
+     * when waited for, so async calls append `and wait` — that is what TS
+     * `await` maps onto.
+     */
+    emitLambdaRun(call, async) {
+        const v = this.callableOf(call.expression.getText());
+        const args = this.listString(call.arguments);
+        if (async)
+            this.sectionAwaited = true;
+        const tmp = `_ts_l${++this.tempCounter}`;
+        const withArgs = args ? ` with ${args}` : "";
+        const wait = async ? " and wait" : "";
+        this.push(`run section {${v.key}} ${async ? "async " : ""}${withArgs} and store result in {${tmp}}${wait}`
+            .replace(/\s+/g, " ").trim());
+        return `{${tmp}}`;
+    }
+    /**
+     * Store an object-returning call's result and read it into the target.
+     * The result is an NBT compound carrying the object (its keys ride in the
+     * brew:keys string list tag): compounds are single values, so they cross
+     * function boundaries and stay in local variables — global variables
+     * would not be usable inside async sections.
+     */
+    readObjectCall(call, targetKey, toNbt) {
+        const tmp = this.tempExpr(this.expr(call));
+        if (toNbt) {
+            this.emit(`set {${targetKey}} to {${tmp}}`);
+            return;
+        }
+        this.emit(`clear {${targetKey}::*}`);
+        this.convert(tmp, "nbt", "list", targetKey);
+    }
+    /** SkBee tag kind for a value type, used in `set <kind> tag ...`. */
+    /** SkBee nbt tag type for a value of the given TS type. Valid types:
+     *  byte, short, int, long, float, double, string, compound, and the list
+     *  variants — SkBee 3.4.1+ requires an explicit type when setting. */
+    nbtTagKind(typeText) {
+        const cat = this.reg.category(typeText);
+        switch (cat) {
+            case "nbt": return "compound";
+            case "java": return "string";
+        }
+        const lower = typeText.toLowerCase();
+        if (lower === "string")
+            return "string";
+        if (lower === "boolean")
+            return "byte";
+        if (lower === "number")
+            return "double";
+        if (typeText.endsWith("[]"))
+            return "compound list";
+        // unknown value types: string tags hold anything (stringified)
+        return "string";
+    }
+    // -- expressions ----------------------------------------------------------
+    expr(node) {
+        if (ts.isIdentifier(node)) {
+            const v = this.scopes.lookup(node.text);
+            if (v)
+                return this.ref(v);
+            // an ambient @ffi const: its pattern substitutes for the name
+            const macro = this.reg.macros.get(node.text);
+            if (macro)
+                return macro.pattern;
+            // undeclared names are globalThis properties (JS semantics)
+            return `{globalThis::${node.text}}`;
+        }
+        if (ts.isNumericLiteral(node))
+            return node.text;
+        if (ts.isStringLiteral(node))
+            return `"${node.text}"`;
+        if (node.kind === ts.SyntaxKind.TrueKeyword)
+            return "true";
+        if (node.kind === ts.SyntaxKind.FalseKeyword)
+            return "false";
+        if (node.kind === ts.SyntaxKind.NullKeyword)
+            return "<none>";
+        // Template strings: literal % is escaped as %%, expressions embed as %expr%.
+        if (ts.isTemplateExpression(node)) {
+            const chunkOf = (lit) => (lit.rawText ?? lit.text ?? "").replace(/%/g, "%%");
+            let text = chunkOf(node.head);
+            for (const span of node.templateSpans) {
+                let e = this.expr(span.expression);
+                if (e.includes('"')) {
+                    // Skript cannot nest quotes inside %...% interpolation (e.g.
+                    // `string tag "x" of {_n}`); hoist the expression into a temp
+                    // variable and interpolate that instead
+                    const t = `_ts_t${++this.tempCounter}`;
+                    this.push(`set {${t}} to ${e}`);
+                    e = `{${t}}`;
+                }
+                text += `%${e}%`;
+                text += chunkOf(span.literal);
+            }
+            return `"${text}"`;
+        }
+        if (ts.isBinaryExpression(node)) {
+            const l = this.expr(node.left);
+            const r = this.expr(node.right);
+            switch (node.operatorToken.kind) {
+                case ts.SyntaxKind.EqualsToken:
+                case ts.SyntaxKind.PlusEqualsToken:
+                case ts.SyntaxKind.MinusEqualsToken:
+                    throw new Error("Assignments must be statements, not expressions (at: " + node.getText() + ")");
+                // Parenthesize the operands: Skript otherwise glues the `and`/`or`
+                // into the left comparison's value list, e.g.
+                // `{_x} is greater than 100 and {_y} isn't 0` fails to parse.
+                case ts.SyntaxKind.AmpersandAmpersandToken: return `(${l}) and (${r})`;
+                case ts.SyntaxKind.BarBarToken: return `(${l}) or (${r})`;
+                case ts.SyntaxKind.EqualsEqualsEqualsToken:
+                case ts.SyntaxKind.EqualsEqualsToken: return `${l} is ${r}`;
+                case ts.SyntaxKind.ExclamationEqualsEqualsToken:
+                case ts.SyntaxKind.ExclamationEqualsToken: return `${l} isn't ${r}`;
+                case ts.SyntaxKind.GreaterThanToken: return `${l} is greater than ${r}`;
+                case ts.SyntaxKind.GreaterThanEqualsToken: return `${l} is greater than or equal to ${r}`;
+                case ts.SyntaxKind.LessThanToken: return `${l} is less than ${r}`;
+                case ts.SyntaxKind.LessThanEqualsToken: return `${l} is less than or equal to ${r}`;
+                case ts.SyntaxKind.PlusToken: return `${l} + ${r}`;
+                case ts.SyntaxKind.MinusToken: return `${l} - ${r}`;
+                case ts.SyntaxKind.AsteriskToken: return `${l} * ${r}`;
+                case ts.SyntaxKind.SlashToken: return `${l} / ${r}`;
+                case ts.SyntaxKind.PercentToken: return `mod(${l}, ${r})`;
+                default:
+                    throw new Error("Unsupported binary operator: " + node.operatorToken.getText());
+            }
+        }
+        if (ts.isPrefixUnaryExpression(node)) {
+            if (node.operator === ts.SyntaxKind.ExclamationToken)
+                return `not ${this.expr(node.operand)}`;
+            if (node.operator === ts.SyntaxKind.MinusToken)
+                return `-1 * ${this.expr(node.operand)}`;
+        }
+        if (ts.isParenthesizedExpression(node))
+            return `(${this.expr(node.expression)})`;
+        // await someLambda(...): the section runs async and the result is waited
+        // for (skript-reflect sections)
+        if (ts.isAwaitExpression(node)) {
+            if (this.inFunction) {
+                throw new Error("await cannot be used inside a function body — Skript functions cannot wait. " +
+                    "Move the await to the caller or use a lambda (at: " + node.getText() + ")");
+            }
+            const inner = node.expression;
+            if (ts.isCallExpression(inner) && ts.isIdentifier(inner.expression) &&
+                this.callableOf(inner.expression.text)) {
+                return this.emitLambdaRun(inner, true);
+            }
+            throw new Error("await is only supported on lambda calls (at: " + node.getText() + ")");
+        }
+        // Ternary: Skript has no conditional expression, so hoist an if/else
+        // that writes the branches into a temp. Unlike JS, both branches are
+        // evaluated eagerly (hoisted-if tradeoff).
+        if (ts.isConditionalExpression(node)) {
+            const cond = this.condition(node.condition);
+            const a = this.expr(node.whenTrue);
+            const b = this.expr(node.whenFalse);
+            const t = `_ts_t${++this.tempCounter}`;
+            this.push(`if ${cond}:`);
+            this.pushAt(1, `set {${t}} to ${a}`);
+            this.push("else:");
+            this.pushAt(1, `set {${t}} to ${b}`);
+            return `{${t}}`;
+        }
+        // Math.* / Object.* builtins -> native Skript expressions
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) &&
+            ts.isIdentifier(node.expression.expression)) {
+            const recv = node.expression.expression.text;
+            const m = node.expression.name.text;
+            const args = node.arguments.map((a) => this.expr(a));
+            if (recv === "Math") {
+                switch (m) {
+                    case "min":
+                    case "max":
+                    case "abs":
+                    case "floor":
+                    case "ceil":
+                    case "round":
+                    case "sqrt":
+                        return `${m}(${args.join(", ")})`;
+                    case "pow":
+                        if (args.length !== 2)
+                            throw new Error("Math.pow takes 2 arguments");
+                        return `${args[0]} ^ ${args[1]}`;
+                    case "random":
+                        return `random integer between ${args[0] ?? "0"} and ${args[1] ?? "1"}`;
+                    default:
+                        throw new Error(`Unsupported Math builtin: Math.${m}`);
+                }
+            }
+            if (recv === "Object") {
+                const arg = node.arguments[0];
+                if (arg && m === "keys") {
+                    const cat = this.categoryOfExpr(arg);
+                    if (cat === "nbt") {
+                        // the NBT carrier rides its keys in the brew:keys string list tag
+                        return `string list tag "brew:keys" of ${this.expr(arg)}`;
+                    }
+                    return `indices of ${this.listForm(this.expr(arg))}`;
+                }
+                if (arg && m === "values") {
+                    if (this.categoryOfExpr(arg) === "nbt") {
+                        throw new Error("Object.values is not supported on nbt compounds — use Object.keys " +
+                            "and index access instead (at: " + node.getText() + ")");
+                    }
+                    return this.listForm(this.expr(arg));
+                }
+                throw new Error(`Unsupported Object builtin: Object.${m}`);
+            }
+        }
+        // Function call -> Skript function call
+        if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
+            // lambda (section) call: shadows plain functions
+            const callable = this.callableOf(node.expression.text);
+            if (callable) {
+                return this.emitLambdaRun(node, this.callRunsAsync(callable, false));
+            }
+            // a @macro call: the body expands inline (#define-style)
+            if (this.reg.macroDecls.has(node.expression.text)) {
+                return this.emitMacroCall(node, false) ?? "<none>";
+            }
+            const fnName = this.fnMap.get(node.expression.text) ?? node.expression.text;
+            const sig = this.reg.signatures.get(node.expression.text);
+            if (sig?.pattern) {
+                // Native syntax mapping: %1%, %2%, ... -> the call arguments.
+                // Text-typed params take a quoted text so variables resolve at
+                // runtime (`"%{_name}%" parsed as player`); literals are already
+                // quoted by the expression emitter.
+                return sig.pattern.replace(/%(\d+)%/g, (_, n) => {
+                    const arg = node.arguments[Number(n) - 1];
+                    if (!arg)
+                        return "<none>";
+                    const e = this.expr(arg);
+                    const param = sig.params[Number(n) - 1] ?? "";
+                    if (param.toLowerCase() === "string" &&
+                        !ts.isStringLiteral(arg) && !ts.isTemplateExpression(arg)) {
+                        return `"%${e}%"`;
+                    }
+                    return e;
+                });
+            }
+            const types = node.arguments.map((_, i) => this.paramType(fnName, i));
+            return `${fnName}(${this.listString(node.arguments, types)})`;
+        }
+        // Object literal -> Skript list variable (keyed lists, see below).
+        if (ts.isObjectLiteralExpression(node)) {
+            return this.emitObjectLiteral(node, null);
+        }
+        // `new Compound({...})` -> NBT compound (SkBee).
+        if (ts.isNewExpression(node) && node.expression.getText() === "Compound") {
+            const arg = node.arguments?.[0];
+            if (arg && ts.isObjectLiteralExpression(arg))
+                return this.nbtFromLiteral(arg);
+            return `nbt compound from "{}"`;
+        }
+        // Property access / method calls, dispatched on the receiver's type.
+        if (ts.isPropertyAccessExpression(node)) {
+            return this.propertyAccess(node, "read");
+        }
+        // Method call on a typed receiver: player.getLocation()
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            // static call on a mirrored class: BukkitAdapter.worldIdentifier(w) ->
+            // class "xyz...BukkitAdapter".worldIdentifier({_w})  (skript-Reflect)
+            const recvExpr = node.expression.expression;
+            if (ts.isIdentifier(recvExpr)) {
+                const cls = this.staticClassOf(recvExpr.text);
+                if (cls) {
+                    this.reg.markJava(recvExpr.text); // classloc into the import: section
+                    return `class "${cls.classloc}".${node.expression.name.text}(${this.listString(node.arguments)})`;
+                }
+            }
+            const recCat = this.categoryOfExpr(node.expression.expression);
+            if (recCat === "java") {
+                return `${this.propertyAccess(node.expression, "call")}(${this.listString(node.arguments)})`;
+            }
+            return `${this.propertyAccess(node.expression, "read")}(${this.listString(node.arguments)})`;
+        }
+        throw new Error("Unsupported expression: " + node.getText());
+    }
+    /**
+     * Convert an expression between the object representations:
+     * - list <-> nbt: keys <-> tag names (SkBee tag expressions)
+     * - java values cannot be converted automatically (they only cross over
+     *   through their own methods) and pass through unchanged
+     * Helper lines are pushed to pending; the returned expression is ready to
+     * be used where the target representation is expected.
+     */
+    /**
+     * Returns null when the conversion wrote the result DIRECTLY into the
+     * target (nbt -> list with an assignKey), in which case the caller must
+     * not emit a `set` — a list copy would flatten the indices
+     * (SkriptLang#3127).
+     */
+    convert(e, from, to, assignKey) {
+        if (from === to || from === "plain" || to === "plain" || from === "java" || to === "java") {
+            return e;
+        }
+        // expressions (function calls, arithmetic) are evaluated once into a temp
+        const hoist = /^\{[^{}]+\}$/.test(e) ? e : this.tempExpr(e);
+        if (from === "list" && to === "nbt") {
+            // SkBee needs an explicit tag type per value (3.4.1+), so branch on the
+            // runtime type; the keys ride along in a string list tag so the list
+            // can be reconstructed on the other side of the boundary.
+            const n = ++this.tempCounter;
+            const c = `_ts_c${n}`;
+            const ki = `_ts_k${n}`;
+            const ks = `_ts_kl${n}`;
+            this.push(`set {${c}} to nbt compound from "{}"`);
+            // loop the list form ({_x} -> {_x::*}) so the values iterate
+            const list = hoist.replace(/^\{(_\w+)\}$/, "{$1::*}");
+            this.push(`loop ${list}:`);
+            // The key is hoisted into a variable and every dynamic tag name goes
+            // through a quoted interpolated string — the only form proven to
+            // behave at runtime in all of Skript's expression slots. Byte tags
+            // hold integers, so booleans are stored as 1/0 like Minecraft NBT.
+            this.pushAt(1, `set {${ki}} to loop-index`);
+            this.pushAt(1, `if loop-value is a number:`);
+            this.pushAt(2, `set double tag "%{${ki}}%" of {${c}} to loop-value`);
+            this.pushAt(1, `else if loop-value is true:`);
+            this.pushAt(2, `set byte tag "%{${ki}}%" of {${c}} to 1`);
+            this.pushAt(1, `else if loop-value is false:`);
+            this.pushAt(2, `set byte tag "%{${ki}}%" of {${c}} to 0`);
+            this.pushAt(1, `else if loop-value is a nbt compound:`);
+            this.pushAt(2, `set compound tag "%{${ki}}%" of {${c}} to loop-value`);
+            this.pushAt(1, `else:`);
+            this.pushAt(2, `set string tag "%{${ki}}%" of {${c}} to "%loop-value%"`);
+            this.pushAt(1, `add {${ki}} to {${ks}::*}`);
+            this.push(`set string list tag "brew:keys" of {${c}} to {${ks}::*}`);
+            return `{${c}}`;
+        }
+        // nbt -> list: re-zip via the embedded keys list tag. SkBee's typed
+        // getters return null when the requested type doesn't match the tag's
+        // actual type (NBTApi.getTag), so first read the tag's runtime type and
+        // then use the matching getter. With an assignKey the entries are
+        // written DIRECTLY into the target — copying a list variable loses its
+        // indices (SkriptLang#3127).
+        const target = assignKey ?? `_ts_l${++this.tempCounter}`;
+        const k = `_ts_k${++this.tempCounter}`;
+        this.usedTagHelper = true;
+        this.push(`loop string list tag "brew:keys" of ${hoist}:`);
+        this.pushAt(1, `set {${k}} to loop-value`);
+        this.pushAt(1, `set {${target}::%{${k}}%} to brew_tag(${hoist}, {${k}})`);
+        return assignKey ? null : `{${target}::*}`;
+    }
+    /** Store an expression in a fresh temp variable, returning its reference. */
+    tempExpr(e) {
+        const t = `_ts_x${++this.tempCounter}`;
+        this.push(`set {${t}} to ${e}`);
+        return `{${t}}`;
+    }
+    /** Declared TS type text of argument `i` of the named function, if known. */
+    paramType(fnName, i) {
+        const sig = this.reg.signatures.get(fnName);
+        if (!sig || i >= sig.params.length)
+            return undefined;
+        return sig.params[i];
+    }
+    /**
+     * Comma-joined Skript list from expression nodes. When more than one
+     * element is joined, every non-atomic element is wrapped in parentheses so
+     * Skript doesn't glue multi-word expressions to their neighbours, e.g.
+     * `set {_v::*} to (keyed {_k::*} from {_t::*}), 3`.
+     */
+    listString(nodes, paramTypes) {
+        const parts = nodes.map((n, i) => {
+            const e = this.expr(n);
+            const to = paramTypes?.[i];
+            if (to && to.toLowerCase() === "object") {
+                // object param: the callee receives an NBT compound carrying the
+                // object. A call that already returns an object IS one (passthrough);
+                // anything else is packed from its keyed-list form.
+                if (this.isObjCall(n))
+                    return e;
+                const list = ts.isObjectLiteralExpression(n)
+                    ? this.emitObjectLiteral(n, null)
+                    : this.listForm(e);
+                return this.convert(list, "list", "nbt") ?? e;
+            }
+            const cat = to ? this.reg.category(to) : undefined;
+            return cat && cat !== this.categoryOfExpr(n)
+                ? this.convert(e, this.categoryOfExpr(n), cat) ?? e
+                : e;
+        });
+        if (parts.length < 2)
+            return parts.join(", ");
+        return parts.map((e, i) => (this.isAtomic(nodes[i]) ? e : `(${e})`)).join(", ");
+    }
+    /** True when an expression is safe unparenthesized inside a comma list. */
+    isAtomic(node) {
+        if (ts.isStringLiteral(node) || ts.isNumericLiteral(node) ||
+            ts.isIdentifier(node) || ts.isTemplateExpression(node) ||
+            ts.isParenthesizedExpression(node) || ts.isCallExpression(node) ||
+            node.kind === ts.SyntaxKind.TrueKeyword ||
+            node.kind === ts.SyntaxKind.FalseKeyword ||
+            node.kind === ts.SyntaxKind.NullKeyword) {
+            return true;
+        }
+        if (ts.isPropertyAccessExpression(node)) {
+            // {_x::k} and {_p}.field are atomic; `tag "k" of {_x}` is not
+            return this.categoryOfExpr(node.expression) !== "nbt";
+        }
+        return false;
+    }
+    /**
+     * Emit an object literal as a Skript keyed list:
+     *
+     *   set {_ts_k<N>::*} to "k1", "k2", ...
+     *   set {_ts_v<N>::*} to v1, v2, ...
+     *   loop {_ts_k<N>::*}:
+     *     set {<target>::%loop-value%} to {_ts_v<N>::%loop-index%}
+     *
+     * When `assignTo` is given (e.g. declaring variable `thing`), the entries
+     * are written directly into `{_thing::*}`, creating `{_thing::k1} = v1`, ...
+     */
+    emitObjectLiteral(node, assignTo) {
+        const n = ++this.tempCounter;
+        const k = `_ts_k${n}`;
+        const v = `_ts_v${n}`;
+        const pairs = node.properties.filter(ts.isPropertyAssignment);
+        // Empty literal: no keyed construction needed (and the plain `set to `
+        // would emit a line ending early); an empty list is just `clear`.
+        if (pairs.length === 0) {
+            const target = assignTo ?? `_ts_e${n}`;
+            this.push(`clear {${target}::*}`);
+            return `{${target}::*}`;
+        }
+        const keys = pairs.map((p) => `"${p.name.getText().replace(/^["']|["']$/g, "")}"`);
+        const vals = this.listString(pairs.map((p) => p.initializer));
+        this.push(`set {${k}::*} to ${keys.join(", ")}`);
+        this.push(`set {${v}::*} to ${vals}`);
+        // Skript has no "keyed zip" expression: build the keyed list by looping
+        // the keys and pulling the value at the matching index.
+        //   loop {_k::*}:
+        //     set {_target::%loop-value%} to {_v::%loop-index%}
+        const target = assignTo ?? `_ts_o${++this.tempCounter}`;
+        this.push(`loop {${k}::*}:`);
+        this.pushAt(1, `set {${target}::%loop-value%} to {${v}::%loop-index%}`);
+        return `{${target}::*}`;
+    }
+    /**
+     * SNBT pairs of an object literal, e.g. `a: 1, b: %{_x}%, c: {inner: 2}`.
+     * Nested object literals become nested SNBT compounds.
+     */
+    nbtPairs(node) {
+        const pairs = node.properties.filter(ts.isPropertyAssignment).map((p) => {
+            const key = p.name.getText().replace(/^["']|["']$/g, "");
+            if (ts.isObjectLiteralExpression(p.initializer)) {
+                return `${key}: {${this.nbtPairs(p.initializer)}}`;
+            }
+            const val = this.expr(p.initializer);
+            // literals embed raw (SNBT knows numbers, booleans and quoted strings);
+            // every other value is an expression and embeds as %expression%.
+            // The whole SNBT goes inside a Skript string literal, so quotes in
+            // string values must be doubled (""), like any other Skript string.
+            // String-typed expressions get SNBT quotes too, so values with spaces
+            // survive: `""%{_name}%""` -> `name: "the name"`.
+            const literalRaw = ts.isNumericLiteral(p.initializer) || ts.isStringLiteral(p.initializer) ||
+                p.initializer.kind === ts.SyntaxKind.TrueKeyword ||
+                p.initializer.kind === ts.SyntaxKind.FalseKeyword;
+            const raw = literalRaw
+                ? val.replace(/"/g, '""')
+                : this.typeOfExpr(p.initializer).toLowerCase() === "string"
+                    ? `""%${val}%""`
+                    : `%${val}%`;
+            return `${key}: ${raw}`;
+        });
+        return pairs.join(", ");
+    }
+    /** Keys of an object literal (used for the brew:keys tag). */
+    objectLiteralKeys(node) {
+        return node.properties
+            .filter(ts.isPropertyAssignment)
+            .map((p) => p.name.getText().replace(/^["']|["']$/g, ""));
+    }
+    /** `nbt compound from "..."` from an object literal (SkBee). */
+    nbtFromLiteral(node) {
+        return `nbt compound from "{${this.nbtPairs(node)}}"`;
+    }
+    /**
+     * Property access, dispatched on the receiver's type category:
+     * - nbt:   `tag "name" of {_x}` (SkBee)
+     * - java:  `{_x}.name` (skript-Reflect)
+     * - list:  `{_x::name}` (Skript list index)
+     */
+    /**
+     * Expand a `@macro` call inline, C/C++ #define-style: the macro's body
+     * is never a function — each call site evaluates the arguments (into
+     * locals, once), binds the parameters, and emits the body statements plus
+     * the trailing `return` expression as the call's value.
+     *
+     * Statement-bodied macros can only be called in statement position (the
+     * statements emit in place); a macro whose body is a bare `return` works
+     * in expression position too.
+     */
+    emitMacroCall(call, statement) {
+        const decl = this.reg.macroDecls.get(call.expression.getText());
+        const body = decl.body.statements;
+        const last = body[body.length - 1];
+        const returns = last && ts.isReturnStatement(last);
+        const stmts = returns ? body.slice(0, -1) : body;
+        if (stmts.length > 0 && !statement) {
+            // an @inline function keeps its Skript function: a statement-bodied
+            // inline can still be called for its value
+            if (jsdocTagText(ts.getJSDocTags(decl), ["inline"]) !== undefined) {
+                const name = call.expression.getText();
+                const fnName = this.fnMap.get(name) ?? name;
+                const sig = this.reg.signatures.get(name);
+                return `${fnName}(${this.listString(call.arguments, sig?.params)})`;
+            }
+            throw new Error("this macro has statements before its return, so it can only be called as a " +
+                "statement, not as a value (at: " + call.getText().slice(0, 60) + ")");
+        }
+        // arguments are evaluated in the caller's scope, hoisted into locals
+        const argRefs = [];
+        for (const a of call.arguments) {
+            const e = this.expr(a);
+            const tmp = `_ts_m${++this.tempCounter}`;
+            this.push(`set {${tmp}} to ${e}`);
+            argRefs.push(tmp);
+        }
+        this.scopes.push();
+        decl.parameters.forEach((p, i) => {
+            const t = p.type?.getText() ?? "";
+            this.scopes.declareWithKey(p.name.getText(), argRefs[i] ?? `ts_m${++this.tempCounter}`, t, this.reg.category(t));
+        });
+        if (statement)
+            this.body(stmts);
+        const value = statement || !returns || !last.expression
+            ? null
+            : this.expr(last.expression);
+        this.scopes.pop();
+        return value;
+    }
+    /**
+     * The @ffi pattern of a property access, if the receiver's declared
+     * type annotates that member: native get/set syntax for NBT, Java
+     * objects, lists — anything.
+     */
+    memberPattern(receiverExpr, member) {
+        const type = this.typeOfExpr(receiverExpr);
+        return type ? (this.reg.memberPatterns.get(type)?.get(member) ?? null) : null;
+    }
+    /**
+     * Substitute a property's @skript pattern: %this% is the receiver
+     * (also %1%), %key% the property name (%2%), and %value% the assigned
+     * value (%3%) — the setter form.
+     */
+    applyMemberPattern(pattern, receiver, member, value) {
+        return pattern
+            .replace(/%this%|%1%/g, receiver)
+            .replace(/%key%|%2%/g, member)
+            .replace(/%value%|%3%/g, value ?? "<none>");
+    }
+    propertyAccess(node, mode) {
+        // static field read on a mirrored class: Messages.RENDER_IN_PROGRESS ->
+        // class "xyz...Messages".RENDER_IN_PROGRESS  (skript-Reflect)
+        if (ts.isIdentifier(node.expression)) {
+            const cls = this.staticClassOf(node.expression.text);
+            if (cls) {
+                this.reg.markJava(node.expression.text);
+                return `class "${cls.classloc}".${node.name.text}`;
+            }
+        }
+        const receiver = this.expr(node.expression);
+        const member = node.name.text;
+        const cat = this.categoryOfExpr(node.expression);
+        // a @skript pattern on the property replaces the default access form
+        const pattern = this.memberPattern(node.expression, member);
+        if (pattern) {
+            if (pattern.includes("%value%") || pattern.includes("%3%")) {
+                throw new Error("the property is set-only: its @skript pattern is a setter form " +
+                    "(it contains %value%) and cannot be read (at: " + node.getText().slice(0, 60) + ")");
+            }
+            return this.applyMemberPattern(pattern, receiver, member);
+        }
+        switch (cat) {
+            case "nbt":
+                // typed getters return null on type mismatch (NBTApi.getTag), so
+                // reads go through the runtime helper that matches the tag's type
+                this.usedTagHelper = true;
+                return `brew_tag(${receiver}, "${member}")`;
+            case "java":
+                return `${receiver}.${member}`;
+            default:
+                return this.indexRef(node.expression, member, receiver);
+        }
+    }
+    /**
+     * Skript list index of a member: `{_x::name}`. The index belongs INSIDE the
+     * variable braces — `{_x}::name` is invalid Skript. For non-variable
+     * receivers (e.g. call results) fall back to `{...}::name`, which is the
+     * best we can do without an intermediate variable.
+     */
+    indexRef(receiverExpr, member, receiver) {
+        const rec = receiver ?? this.expr(receiverExpr);
+        const m = /^\{(_\w+|globalThis::\w+)\}$/.exec(rec);
+        return m ? `{${m[1]}::${member}}` : `${rec}::${member}`;
+    }
+    /**
+     * Skript cannot combine two conditions with and/or (the `and`/`or` glue
+     * into value lists), so complex conditions are evaluated into a boolean
+     * flag first, one single-condition line at a time:
+     *
+     *   set {_ts_bN} to false
+     *   if {_p::y} is greater than 100:
+     *     set {_ts_bN} to true
+     *   ...
+     *   if {_ts_bN} is true:  (or: isn't true)
+     */
+    isLogicalCond(e) {
+        if (ts.isParenthesizedExpression(e))
+            return this.isLogicalCond(e.expression);
+        if (ts.isPrefixUnaryExpression(e))
+            return e.operator === ts.SyntaxKind.ExclamationToken && this.isLogicalCond(e.operand);
+        if (ts.isBinaryExpression(e)) {
+            const k = e.operatorToken.kind;
+            if (k === ts.SyntaxKind.AmpersandAmpersandToken || k === ts.SyntaxKind.BarBarToken)
+                return true;
+        }
+        return false;
+    }
+    /** Skript condition text for a single (non-logical) TS condition. */
+    condition(e) {
+        if (ts.isParenthesizedExpression(e))
+            return this.condition(e.expression);
+        if (ts.isPrefixUnaryExpression(e) && e.operator === ts.SyntaxKind.ExclamationToken) {
+            return this.invertedCondition(e.operand);
+        }
+        // bare values need explicit truthiness: booleans test against `true`,
+        // everything else (numbers, texts, optional args bound by Skript)
+        // tests for being set — JS truthiness maps to "has a value"
+        if (ts.isIdentifier(e))
+            return this.truthiness(e);
+        return this.expr(e);
+    }
+    /** `x` as a condition: `{_x} is true` for booleans, `{_x} is set` else. */
+    truthiness(e, invert = false) {
+        const ref = this.expr(e);
+        const op = invert ? "isn't" : "is";
+        const t = (ts.isIdentifier(e) ? this.typeOfExpr(e) : "").toLowerCase();
+        return t === "boolean" ? `${ref} ${op} true` : `${ref} ${op} set`;
+    }
+    /** The negation of a single TS condition. */
+    invertedCondition(e) {
+        e = ts.isParenthesizedExpression(e) ? e.expression : e;
+        if (ts.isPrefixUnaryExpression(e) && e.operator === ts.SyntaxKind.ExclamationToken) {
+            return this.condition(e.operand); // !!x == x
+        }
+        if (ts.isBinaryExpression(e)) {
+            const l = this.expr(e.left);
+            const r = this.expr(e.right);
+            switch (e.operatorToken.kind) {
+                case ts.SyntaxKind.EqualsEqualsEqualsToken:
+                case ts.SyntaxKind.EqualsEqualsToken: return `${l} isn't ${r}`;
+                case ts.SyntaxKind.ExclamationEqualsEqualsToken:
+                case ts.SyntaxKind.ExclamationEqualsToken: return `${l} is ${r}`;
+                case ts.SyntaxKind.GreaterThanToken: return `${l} is less than or equal to ${r}`;
+                case ts.SyntaxKind.GreaterThanEqualsToken: return `${l} is less than ${r}`;
+                case ts.SyntaxKind.LessThanToken: return `${l} is greater than or equal to ${r}`;
+                case ts.SyntaxKind.LessThanEqualsToken: return `${l} is greater than ${r}`;
+            }
+        }
+        if (ts.isIdentifier(e))
+            return this.truthiness(e, true);
+        throw new Error("Cannot negate this condition: " + e.getText());
+    }
+    /**
+     * Evaluate an arbitrary TS condition into a fresh boolean flag. Returns the
+     * flag's key; the flag is set to true iff the condition holds.
+     */
+    emitCondFlag(e) {
+        e = ts.isParenthesizedExpression(e) ? e.expression : e;
+        const flag = (n = ++this.tempCounter) => `_ts_b${n}`;
+        if (ts.isPrefixUnaryExpression(e) && e.operator === ts.SyntaxKind.ExclamationToken && this.isLogicalCond(e.operand)) {
+            // !(A && B) -> evaluate A&&B, then invert
+            const inner = this.emitCondFlag(e.operand);
+            const f = flag();
+            this.push(`set {${f}} to false`);
+            this.push(`if {${inner}} isn't true:`);
+            this.pushAt(1, `set {${f}} to true`);
+            return f;
+        }
+        if (ts.isPrefixUnaryExpression(e) && e.operator === ts.SyntaxKind.ExclamationToken) {
+            const f = flag();
+            this.push(`set {${f}} to false`);
+            this.push(`if ${this.invertedCondition(e.operand)}:`);
+            this.pushAt(1, `set {${f}} to true`);
+            return f;
+        }
+        if (ts.isBinaryExpression(e) && e.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+            const a = this.emitCondFlag(e.left);
+            const b = this.emitCondFlag(e.right);
+            const f = flag();
+            this.push(`set {${f}} to false`);
+            this.push(`if {${a}} is true:`);
+            this.pushAt(1, `if {${b}} is true:`);
+            this.pushAt(2, `set {${f}} to true`);
+            return f;
+        }
+        if (ts.isBinaryExpression(e) && e.operatorToken.kind === ts.SyntaxKind.BarBarToken) {
+            const a = this.emitCondFlag(e.left);
+            const b = this.emitCondFlag(e.right);
+            const f = flag();
+            this.push(`set {${f}} to false`);
+            this.push(`if {${a}} is true:`);
+            this.pushAt(1, `set {${f}} to true`);
+            this.push(`if {${b}} is true:`);
+            this.pushAt(1, `set {${f}} to true`);
+            return f;
+        }
+        // simple condition, evaluated directly
+        const f = flag();
+        this.push(`set {${f}} to false`);
+        this.push(`if ${this.condition(e)}:`);
+        this.pushAt(1, `set {${f}} to true`);
+        return f;
+    }
+    /** Emit an `if`/`else if` line for a TS condition (flag machinery when logical). */
+    emitConditionLine(prefix, e) {
+        if (this.isLogicalCond(e)) {
+            const f = this.emitCondFlag(e);
+            this.emit(`${prefix} {${f}} is true:`);
+        }
+        else {
+            this.emit(`${prefix} ${this.condition(e)}:`);
+        }
+    }
+    // -- statements -----------------------------------------------------------
+    statement(stmt) {
+        if (ts.isBlock(stmt)) {
+            this.scopes.push();
+            this.body(stmt.statements);
+            this.scopes.pop();
+            return;
+        }
+        // let / const / var -> set {_name} to ...
+        if (ts.isVariableStatement(stmt)) {
+            for (const d of stmt.declarationList.declarations) {
+                if (!ts.isIdentifier(d.name))
+                    throw new Error("Destructuring is not supported yet");
+                const name = d.name.text;
+                // lambda -> skript-reflect section: `create new section with {_a},
+                // {_b} stored in {_f}:` (locals from before the creation stay
+                // readable inside the section)
+                // top-level declarations bind as globalThis globals: the init
+                // trigger runs before every user trigger, and its bindings must
+                // stay readable from them (like a module's exports)
+                const declare = this.topLevelInit
+                    ? (n, t, c, l = false) => this.scopes.declareGlobal(n, t, c, l)
+                    : (n, t, c, l = false) => this.scopes.declare(n, t, c, l);
+                if (d.initializer && ts.isArrowFunction(d.initializer)) {
+                    const arrow = d.initializer;
+                    const info = declare(name, "", "plain", false);
+                    info.lambda = {
+                        async: !!arrow.modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword),
+                    };
+                    this.emitLambdaSection(arrow, info.key);
+                    continue;
+                }
+                const typeText = d.type?.getText() ?? this.typeOfExpr(d.initializer);
+                const cat = this.reg.category(typeText);
+                if (cat === "java")
+                    this.reg.markJava(typeText);
+                const info = declare(name, typeText, cat, (d.type?.getText() ?? "").endsWith("[]"));
+                const init = d.initializer;
+                if (ts.isObjectLiteralExpression(init) && cat === "nbt") {
+                    // NBT-typed literal: build an actual nbt compound (SkBee SNBT)
+                    this.emit(`set {${info.key}} to ${this.nbtFromLiteral(init)}`);
+                }
+                else if (ts.isObjectLiteralExpression(init) && cat === "list") {
+                    this.emitObjectLiteral(init, info.key);
+                }
+                else if (ts.isObjectLiteralExpression(init)) {
+                    this.emit(`set {${info.key}} to ${this.expr(init)}`);
+                }
+                else if (this.isObjCall(init)) {
+                    // object-returning call: its NBT compound result is read straight
+                    // into the target
+                    this.readObjectCall(init, info.key, cat === "nbt");
+                }
+                else {
+                    const from = this.categoryOfExpr(init);
+                    const e = this.expr(init);
+                    if (from === "list" && cat !== "nbt") {
+                        // list values are copied key by key: a plain `set {x::*} to {y::*}`
+                        // loses the indices (SkriptLang#3127)
+                        this.push(`loop ${this.listForm(e)}:`);
+                        this.pushAt(1, `set {${info.key}::%loop-index%} to loop-value`);
+                    }
+                    else {
+                        const conv = this.convert(e, from, cat, info.key);
+                        // conv === null: the conversion wrote directly into {key::...}
+                        if (conv !== null)
+                            this.emit(`set ${this.ref(info)} to ${conv}`);
+                    }
+                }
+            }
+            return;
+        }
+        if (ts.isExpressionStatement(stmt)) {
+            const e = stmt.expression;
+            // x++ / x-- (and ++x / --x) -> add/remove 1
+            if ((ts.isPostfixUnaryExpression(e) || ts.isPrefixUnaryExpression(e)) &&
+                (e.operator === ts.SyntaxKind.PlusPlusToken ||
+                    e.operator === ts.SyntaxKind.MinusMinusToken)) {
+                const target = this.expr(e.operand);
+                this.emit(e.operator === ts.SyntaxKind.PlusPlusToken
+                    ? `add 1 to ${target}`
+                    : `remove 1 from ${target}`);
+                return;
+            }
+            if (ts.isBinaryExpression(e)) {
+                const kind = e.operatorToken.kind;
+                if (kind === ts.SyntaxKind.EqualsToken) {
+                    this.emitAssignment(e);
+                    return;
+                }
+                if (kind === ts.SyntaxKind.PlusEqualsToken) {
+                    this.emit(`add ${this.expr(e.right)} to ${this.expr(e.left)}`);
+                    return;
+                }
+                if (kind === ts.SyntaxKind.MinusEqualsToken) {
+                    this.emit(`remove ${this.expr(e.right)} from ${this.expr(e.left)}`);
+                    return;
+                }
+                if (kind === ts.SyntaxKind.AsteriskEqualsToken || kind === ts.SyntaxKind.SlashEqualsToken) {
+                    const op = kind === ts.SyntaxKind.AsteriskEqualsToken ? "*" : "/";
+                    this.emit(`set ${this.expr(e.left)} to ${this.expr(e.left)} ${op} ${this.expr(e.right)}`);
+                    return;
+                }
+            }
+            // a @macro statement call: the body expands inline
+            if (ts.isCallExpression(e) && ts.isIdentifier(e.expression) &&
+                this.reg.macroDecls.has(e.expression.text)) {
+                this.emitMacroCall(e, true);
+                return;
+            }
+            // lambda (section) call as a statement: run without storing a result.
+            // An awaited async call waits; without await it is fire-and-forget.
+            {
+                const target = ts.isAwaitExpression(e) ? e.expression : e;
+                const awaited = ts.isAwaitExpression(e);
+                if (ts.isCallExpression(target) && ts.isIdentifier(target.expression)) {
+                    const callable = this.callableOf(target.expression.text);
+                    if (callable) {
+                        const async = this.callRunsAsync(callable, awaited);
+                        const args = this.listString(target.arguments);
+                        if (async)
+                            this.sectionAwaited = true;
+                        const wait = async ? " and wait" : "";
+                        const withArgs = args ? ` with ${args}` : "";
+                        this.emit(`run section {${callable.key}} ${async ? "async " : ""}${withArgs}${wait}`
+                            .replace(/\s+/g, " ").trim());
+                        return;
+                    }
+                }
+            }
+            this.emit(this.expr(e));
+            return;
+        }
+        // if / else if / else
+        if (ts.isIfStatement(stmt)) {
+            this.scopes.push();
+            this.emitConditionLine("if", stmt.expression);
+            this.indented([stmt.thenStatement]);
+            let cur = stmt;
+            while (cur.elseStatement) {
+                const els = cur.elseStatement;
+                if (ts.isIfStatement(els)) {
+                    this.emitConditionLine("else if", els.expression);
+                    this.indented([els.thenStatement]);
+                    cur = els;
+                }
+                else {
+                    this.emit("else:");
+                    this.indented([els]);
+                    this.scopes.pop();
+                    return;
+                }
+            }
+            this.scopes.pop();
+            return;
+        }
+        if (ts.isWhileStatement(stmt)) {
+            this.scopes.push();
+            if (this.isLogicalCond(stmt.expression)) {
+                // logical conditions must be re-evaluated every iteration: wrap the
+                // loop and exit early when the flag ends up false
+                this.emit("while 1 is 1:");
+                this.indent++;
+                const f = this.emitCondFlag(stmt.expression);
+                this.emit(`if {${f}} isn't true:`);
+                this.indent++;
+                this.emit("exit loop");
+                this.indent--;
+                this.body([stmt.statement]);
+                this.indent--;
+            }
+            else {
+                this.emit(`while ${this.condition(stmt.expression)}:`);
+                this.indented([stmt.statement]);
+            }
+            this.scopes.pop();
+            return;
+        }
+        // for..of -> loop
+        if (ts.isForOfStatement(stmt)) {
+            const decl = stmt.initializer.declarations[0];
+            const item = decl.name.text;
+            this.scopes.push();
+            // element type: the annotation, else T[] of the iterated expression
+            const iterType = this.typeOfExpr(stmt.expression);
+            const typeText = decl.type?.getText() ??
+                (iterType.endsWith("[]") ? iterType.slice(0, -2) : "");
+            const info = this.scopes.declare(item, typeText, this.reg.category(typeText));
+            this.emit(`loop ${this.expr(stmt.expression)}:`);
+            this.indent++;
+            this.emit(`set ${this.ref(info)} to loop-value`);
+            this.body([stmt.statement]);
+            this.indent--;
+            this.scopes.pop();
+            return;
+        }
+        if (ts.isReturnStatement(stmt)) {
+            // Skript forbids returning after a delay: the guard covers both a
+            // return that follows an earlier async run AND `return await ...`
+            // (the await sits inside the return expression itself)
+            const containsAwait = (n) => ts.isAwaitExpression(n) || n.getChildren().some(containsAwait);
+            if (stmt.expression && !this.inFunction &&
+                (this.sectionAwaited || containsAwait(stmt.expression))) {
+                throw new Error("a value cannot be returned after a delay (Skript forbids return after async runs) — " +
+                    "store it in a global instead and read it later (assign to an undeclared name, e.g. " +
+                    "`result = value`, which maps to {globalThis::result}) (at: " +
+                    stmt.getText().slice(0, 60) + ")");
+            }
+            if (stmt.expression && this.currentRetIsObject) {
+                // object return: pack the keyed list into an NBT compound and return
+                // it. A call that already returns an object IS one and passes
+                // straight through.
+                if (this.isObjCall(stmt.expression)) {
+                    this.emit(`return ${this.expr(stmt.expression)}`);
+                    return;
+                }
+                const list = ts.isObjectLiteralExpression(stmt.expression)
+                    ? this.emitObjectLiteral(stmt.expression, null)
+                    : this.expr(stmt.expression);
+                const conv = this.convert(this.listForm(list), "list", "nbt");
+                this.emit(`return ${conv ?? list}`);
+                return;
+            }
+            if (stmt.expression && ts.isObjectLiteralExpression(stmt.expression)) {
+                const out = this.emitObjectLiteral(stmt.expression, null);
+                this.emit(`return ${this.convert(out, "list", this.currentRetCat)}`);
+                return;
+            }
+            if (stmt.expression) {
+                const e = this.expr(stmt.expression);
+                const conv = this.convert(e, this.categoryOfExpr(stmt.expression), this.currentRetCat);
+                this.emit(`return ${conv ?? e}`);
+            }
+            else {
+                this.emit("stop");
+            }
+            return;
+        }
+        if (ts.isBreakStatement(stmt)) {
+            this.emit("exit loop");
+            return;
+        }
+        if (ts.isContinueStatement(stmt)) {
+            this.emit("# continue (unsupported)");
+            return;
+        }
+        throw new Error("Unsupported statement: " + stmt.getText().slice(0, 60));
+    }
+    /** Skript type name for a TS type node, using this registry. */
+    skriptType(node) {
+        return skriptType(node, this.reg);
+    }
+    /** Emit a Skript `function` declaration. */
+    emitFunction(f) {
+        this.scopes.push();
+        this.bindParams(f); // keys first: the signature names come from the scope
+        const params = f.parameters.map((p) => {
+            const v = this.scopes.lookup(p.name.getText());
+            // Skript names parameters WITHOUT the underscore: `f(o: text)` binds
+            // {_o} in the body
+            return `${v.key.replace(/^_/, "")}: ${skriptType(p.type, this.reg)}`;
+        });
+        // `void` (and a missing annotation) means no Skript return type
+        const retText = f.type?.getText() ?? "";
+        const isVoid = retText.toLowerCase() === "void";
+        const ret = f.type && !isVoid ? ` :: ${skriptType(f.type, this.reg)}:` : ":";
+        // `object` returns travel as an NBT compound (see TYPE_MAP); everything
+        // else converts to its Skript representation as usual
+        this.currentRetIsObject = retText.toLowerCase() === "object";
+        this.currentRetCat = this.currentRetIsObject || isVoid || !f.type
+            ? this.currentRetIsObject ? "list" : "plain"
+            : this.reg.category(retText);
+        const outName = this.fnMap.get(f.name.text) ?? f.name.text;
+        this.emit(`function ${outName}(${params.join(", ")})${ret}`);
+        this.indent++;
+        const prevInFunction = this.inFunction;
+        this.inFunction = true;
+        this.emitObjectParamPrologue(f);
+        this.body(f.body?.statements ?? []);
+        this.inFunction = prevInFunction;
+        this.indent--;
+        this.scopes.pop();
+        this.currentRetIsObject = false;
+    }
+    /**
+     * Emit the top-level `on load:` init trigger: the statements run in
+     * source order, and their `let`/`const` declarations bind as
+     * globalThis globals so every later trigger can read them.
+     */
+    emitTopLevel(stmts) {
+        this.scopes.push();
+        this.emit("on load:");
+        this.indent++;
+        this.sectionAwaited = false;
+        this.topLevelInit = true;
+        this.body(stmts);
+        this.topLevelInit = false;
+        this.indent--;
+        this.scopes.pop();
+    }
+    /** Emit a `on <event>:` trigger from a /** @on ... *\/ function. */
+    emitEvent(event, decl) {
+        this.currentRetCat = "plain";
+        this.sectionAwaited = false; // each trigger starts fresh
+        this.scopes.push();
+        this.bindParams(decl);
+        this.emit(`on ${event}:`);
+        this.indent++;
+        for (const p of decl.parameters) {
+            const v = this.scopes.lookup(p.name.getText());
+            const t = skriptType(p.type, this.reg).toLowerCase();
+            const binding = v.isList
+                ? "<none> # TODO: bind list event param"
+                : t === "player"
+                    ? "player"
+                    : t === "world"
+                        ? "world"
+                        : "<none>";
+            this.emit(`set ${this.ref(v)} to ${binding}`);
+        }
+        this.body(decl.body?.statements ?? []);
+        this.indent--;
+        this.scopes.pop();
+    }
+    /** Emit a `command /name <args>:` block from a /** @command ... *\/ function.
+     * Skript binds each declared argument to {_name} inside the trigger, so
+     * the params need no binding lines — the body compiles as usual. */
+    emitCommand(name, decl) {
+        this.currentRetCat = "plain";
+        this.sectionAwaited = false;
+        this.scopes.push();
+        this.bindParams(decl);
+        const tags = ts.getJSDocTags(decl);
+        const opt = (tag) => {
+            const v = jsdocTagText(tags, [tag]);
+            return v !== undefined ? v : null;
+        };
+        const args = decl.parameters.map((p) => {
+            const t = p.type ? skriptType(p.type, this.reg) : "text";
+            const spec = `<${p.name.getText()}: ${t}>`;
+            return p.questionToken ? `[${spec}]` : spec;
+        }).join(" ");
+        const path = name.replace(/^\//, "");
+        this.emit(`command /${path}${args ? " " + args : ""}:`);
+        this.indent++;
+        const permission = opt("permission");
+        if (permission)
+            this.emit(`permission: ${permission}`);
+        const usage = opt("usage");
+        if (usage)
+            this.emit(`usage: ${usage}`);
+        const aliases = opt("aliases");
+        if (aliases)
+            this.emit(`aliases: ${aliases}`);
+        this.emit("trigger:");
+        this.indent++;
+        this.body(decl.body?.statements ?? []);
+        this.indent--;
+        this.indent--;
+        this.scopes.pop();
+    }
+    /** Bind function parameters as scope entries ({_name}, or {_oN} when
+     *  obfuscating). */
+    bindParams(f) {
+        for (const p of f.parameters) {
+            const typeText = p.type?.getText() ?? "";
+            const isList = typeText.endsWith("[]");
+            const cat = this.reg.category(typeText);
+            const key = this.obfuscate ? this.scopes.nextKey() : `_${p.name.getText()}`;
+            this.scopes.declareWithKey(p.name.getText(), key, typeText, cat, isList);
+        }
+    }
+    /**
+     * Prologue for functions with `object` parameters: the caller passed an
+     * NBT compound, so re-zip it into the local keyed list. Body code then
+     * reads {_p::key} as usual.
+     */
+    emitObjectParamPrologue(f) {
+        for (const p of f.parameters) {
+            if ((p.type?.getText() ?? "").toLowerCase() !== "object")
+                continue;
+            const name = p.name.getText();
+            this.emit(`clear {_${name}::*}`);
+            this.convert(`{_${name}}`, "nbt", "list", `_${name}`);
+        }
+    }
+    /** `x.y = v`, dispatched on x's type. */
+    emitAssignment(e) {
+        const left = e.left;
+        if (ts.isIdentifier(left)) {
+            let v = this.scopes.lookup(left.text);
+            // assigning to a name no let/const declared creates a global, like
+            // JavaScript: {globalThis::<name>} (see ScopeStack.declareGlobal)
+            if (!v) {
+                const typeText = this.typeOfExpr(e.right);
+                v = this.scopes.declareGlobal(left.text, typeText, this.reg.category(typeText), typeText.endsWith("[]"));
+            }
+            const key = this.ref(v);
+            const rhs = e.right;
+            if (ts.isObjectLiteralExpression(rhs) && (!v || v.category === "list" || v.category === "nbt")) {
+                if (v && v.category === "nbt") {
+                    this.emit(`set {${v.key}} to ${this.nbtFromLiteral(rhs)}`);
+                }
+                else {
+                    this.emitObjectLiteral(rhs, v ? v.key : `_${left.text}`);
+                }
+                return;
+            }
+            const targetKey = v?.key ?? `_${left.text}`;
+            if (this.isObjCall(rhs)) {
+                // object-returning call: read its NBT compound result into the
+                // target (see declarations)
+                this.readObjectCall(rhs, targetKey, (v?.category ?? "list") === "nbt");
+                return;
+            }
+            const value = this.expr(rhs);
+            const from = this.categoryOfExpr(rhs);
+            const to = v?.category ?? "plain";
+            if (from === "list" && to !== "nbt") {
+                // keyed copy (list assignment flattens indices, SkriptLang#3127)
+                this.push(`loop ${this.listForm(value)}:`);
+                this.pushAt(1, `set {${targetKey}::%loop-index%} to loop-value`);
+                return;
+            }
+            const conv = this.convert(value, from, to, targetKey);
+            if (conv !== null)
+                this.emit(`set ${key} to ${conv}`);
+            return;
+        }
+        if (ts.isPropertyAccessExpression(left)) {
+            const receiverCat = this.categoryOfExpr(left.expression);
+            const member = left.name.text;
+            const receiver = this.expr(left.expression);
+            const value = this.expr(e.right);
+            // a @skript pattern on the property: setter form. Without %value%
+            // the pattern is an expression and the value is assigned into it;
+            // with %value% the pattern is the full setter effect.
+            const pattern = this.memberPattern(left.expression, member);
+            if (pattern) {
+                const target = this.applyMemberPattern(pattern.replace(/set\s+/, ""), receiver, member, value);
+                if (/%value%|%3%/.test(pattern)) {
+                    this.emit(this.applyMemberPattern(pattern, receiver, member, value));
+                }
+                else {
+                    this.emit(`set ${target} to ${value}`);
+                }
+                return;
+            }
+            switch (receiverCat) {
+                case "nbt": {
+                    const kind = this.nbtTagKind(this.typeOfExpr(e.right));
+                    this.emit(`set ${kind} tag "${member}" of ${this.expr(left.expression)} to ${value}`);
+                    return;
+                }
+                case "java":
+                    this.emit(`set ${this.expr(left.expression)}.${member} to ${value}`);
+                    return;
+                default:
+                    this.emit(`set ${this.indexRef(left.expression, member)} to ${value}`);
+                    return;
+            }
+        }
+        this.emit(`set ${this.expr(left)} to ${this.expr(e.right)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Top level: functions + /** @on <event> */ triggers
+// ---------------------------------------------------------------------------
+function getEventName(decl) {
+    const tag = ts.getJSDocTags(decl).find((t) => t.tagName.text === "on");
+    if (tag && typeof tag.comment === "string")
+        return tag.comment.trim();
+    return null;
+}
+/** The name/path of a `/** @command /name *\/` function, else null. */
+function getCommandName(decl) {
+    const tag = ts.getJSDocTags(decl).find((t) => t.tagName.text === "command");
+    if (tag && typeof tag.comment === "string" && tag.comment.trim()) {
+        return tag.comment.trim();
+    }
+    return null;
+}
+function transpile(source, scriptName = "generated", opts) {
+    const sf = ts.createSourceFile(scriptName + ".ts", source, ts.ScriptTarget.Latest, true);
+    const t = new Transpiler(sf, opts);
+    const events = [];
+    const commands = [];
+    const funcs = [];
+    const topLevel = [];
+    for (const stmt of sf.statements) {
+        if (ts.isFunctionDeclaration(stmt)) {
+            // `declare function ...` = ambient declaration (native Skript/addon
+            // function): skip it, don't emit a Skript function.
+            if (!stmt.body)
+                continue;
+            // `@macro` functions are never emitted: they expand inline at each
+            // call site (the registry holds their bodies)
+            if (jsdocTagText(ts.getJSDocTags(stmt), ["macro"]) !== undefined)
+                continue;
+            const ev = getEventName(stmt);
+            const cmd = getCommandName(stmt);
+            if (cmd)
+                commands.push([cmd, stmt]);
+            else if (ev)
+                events.push([ev, stmt]);
+            else
+                funcs.push(stmt);
+        }
+        else if (ts.isInterfaceDeclaration(stmt) || ts.isClassDeclaration(stmt) ||
+            ts.isTypeAliasDeclaration(stmt) || ts.isImportDeclaration(stmt) ||
+            ts.isImportEqualsDeclaration(stmt) || ts.isExportDeclaration(stmt)) {
+            // Type-level declarations: consumed by the type registry, not emitted.
+            continue;
+        }
+        else if (ts.isVariableStatement(stmt) &&
+            stmt.declarationList.declarations.some((d) => (ts.getCombinedModifierFlags(d) & ts.ModifierFlags.Ambient) !== 0)) {
+            // ambient `declare const`: registered as a @skript macro, not emitted
+            continue;
+        }
+        else {
+            // any other top-level statement runs in the init trigger, in source
+            // order (see below)
+            topLevel.push(stmt);
+        }
+    }
+    // obfuscation: functions defined in this file get a per-file id + index,
+    // so same-named functions in different files never collide (like ES6
+    // module symbols) and the original names are hidden in the output
+    if (opts?.obfuscate) {
+        const key = fileKey(source);
+        funcs.forEach((f, i) => {
+            if (f.name)
+                t.fnMap.set(f.name.text, `${key}_f${i + 1}`);
+        });
+    }
+    // Skript functions first, then event triggers
+    for (const f of funcs) {
+        t.emitFunction(f);
+        t.emit("");
+    }
+    // Top-level statements run in their own `on load:` trigger, emitted first
+    // so it precedes every user trigger (same-event triggers run in document
+    // order): their top-level declarations bind as globalThis globals.
+    if (topLevel.length > 0) {
+        t.emitTopLevel(topLevel);
+        t.emit("");
+    }
+    for (const [event, decl] of events) {
+        t.emitEvent(event, decl);
+        t.emit("");
+    }
+    // commands last: like triggers, they are not callable functions
+    for (const [name, decl] of commands) {
+        t.emitCommand(name, decl);
+        t.emit("");
+    }
+    // NBT reads need the runtime tag helper (see TS2SK_TAG_HELPER)
+    if (t.usedTagHelper)
+        t.lines.unshift(...TS2SK_TAG_HELPER);
+    // skript-Reflect needs the Java classes imported at the top of the script
+    if (t.reg.usedClasslocs.size > 0) {
+        const imports = ["import:", ...[...t.reg.usedClasslocs].sort().map((l) => `\t${l}`), ""];
+        t.lines.unshift(...imports);
+    }
+    return t.lines.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}
+//# sourceMappingURL=transpiler.js.map