@typecad/cuttlefish 0.1.0-alpha.1

package/dist/emit/emitters/namespace-emitter.js

@@ -0,0 +1,324 @@
+import { emitCommentLines } from "../utils/index.js";
+import { appendSourceLine, appendRenderedStatement } from "./line-appender.js";
+import { createChildEmissionScope } from "../snprintf-helpers.js";
+import { escapeCppKeyword } from "../../utils/strings.js";
+import { isStringEnum } from "../../api/shared/index.js";
+import { resolveEnumValues, narrowestEnumUnderlying } from "../utils/cpp-helpers.js";
+export function emitNamespaces(ctx) {
+    const { program, strategy, reservedNames, mappedFunctions, topLevelScope, exprRenderer, statementRenderer } = ctx;
+    const normalizeCppTypeForTarget = (cppType) => strategy.normalizeCppType(cppType);
+    const renderExpression = (expr, calleeTransformer) => exprRenderer.render(expr, calleeTransformer);
+    const renderParameters = (params, forHeader = false) => statementRenderer.renderParameters(params, forHeader);
+    const renderTypedName = (cppType, name) => statementRenderer.renderTypedName(cppType, name);
+    for (const ns of program.namespaces) {
+        emitCommentLines(ns.leadingComments, "", (line) => appendSourceLine(ctx, line));
+        appendSourceLine(ctx, `namespace ${ns.name} {`);
+        appendSourceLine(ctx, "");
+        // Namespace enums
+        for (const enumDef of ns.enums) {
+            emitCommentLines(enumDef.leadingComments, "  ", (line) => appendSourceLine(ctx, line));
+            // String enum → inner namespace of constexpr const char* constants
+            // (see type-decl-emitter.ts / isStringEnum for rationale).
+            if (isStringEnum(enumDef)) {
+                appendSourceLine(ctx, `  namespace ${enumDef.name} {`);
+                for (const member of enumDef.members) {
+                    const memberName = ctx.reservedNames.has(member.name)
+                        ? `_${member.name}`
+                        : member.name;
+                    const renamed = strategy.renameEnumMember(enumDef.name, memberName);
+                    const escaped = String(member.value).replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+                    appendSourceLine(ctx, `    constexpr const char* ${renamed} = "${escaped}";`);
+                }
+                appendSourceLine(ctx, "  }");
+                emitCommentLines(enumDef.trailingComments, "  ", (line) => appendSourceLine(ctx, line));
+                appendSourceLine(ctx, "");
+                continue;
+            }
+            const enumKeyword = "enum class";
+            const underlyingType = narrowestEnumUnderlying(resolveEnumValues(enumDef.members), strategy.needsLargeEnumUnderlying());
+            appendSourceLine(ctx, `  ${enumKeyword} ${enumDef.name}${underlyingType} {`);
+            let autoValue = 0;
+            for (let i = 0; i < enumDef.members.length; i++) {
+                const member = enumDef.members[i];
+                let valueSuffix;
+                if (typeof member.value === "number") {
+                    valueSuffix = ` = ${member.value}`;
+                    autoValue = member.value + 1;
+                }
+                else if (typeof member.value === "string") {
+                    valueSuffix = ` = ${autoValue}`;
+                    autoValue++;
+                }
+                else {
+                    valueSuffix = "";
+                    autoValue++;
+                }
+                const commaSuffix = i < enumDef.members.length - 1 ? "," : "";
+                appendSourceLine(ctx, `    ${member.name}${valueSuffix}${commaSuffix}`);
+            }
+            appendSourceLine(ctx, "  };");
+            emitCommentLines(enumDef.trailingComments, "  ", (line) => appendSourceLine(ctx, line));
+            appendSourceLine(ctx, "");
+        }
+        // Namespace type aliases
+        for (const typeAlias of ns.typeAliases) {
+            emitCommentLines(typeAlias.leadingComments, "  ", (line) => appendSourceLine(ctx, line));
+            const cppType = normalizeCppTypeForTarget(typeAlias.cppType);
+            if (cppType !== "auto" && !strategy.shouldSkipTypeAlias(cppType)) {
+                appendSourceLine(ctx, `  using ${typeAlias.name} = ${cppType};`);
+                emitCommentLines(typeAlias.trailingComments, "  ", (line) => appendSourceLine(ctx, line));
+                appendSourceLine(ctx, "");
+            }
+        }
+        // Namespace constants
+        for (const constant of ns.constants) {
+            const constType = normalizeCppTypeForTarget(constant.cppType);
+            const isConst = constant.storage === "const" || constant.storage === undefined;
+            if (constType !== "auto") {
+                if (isConst) {
+                    appendSourceLine(ctx, `  const ${constType} ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+                else {
+                    appendSourceLine(ctx, `  ${constType} ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+            }
+            else {
+                if (isConst) {
+                    appendSourceLine(ctx, `  const auto ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+                else {
+                    appendSourceLine(ctx, `  auto ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+            }
+        }
+        if (ns.assignments) {
+            for (const assign of ns.assignments) {
+                appendSourceLine(ctx, `  ${assign.target} = ${renderExpression(assign.value, undefined)};`);
+            }
+        }
+        if (ns.constants.length > 0) {
+            appendSourceLine(ctx, "");
+        }
+        // Namespace classes
+        for (const classDef of ns.classes) {
+            emitCommentLines(classDef.leadingComments, "  ", (line) => appendSourceLine(ctx, line));
+            if (classDef.isAbstract) {
+                appendSourceLine(ctx, `  // Abstract class - contains pure virtual methods`);
+            }
+            appendSourceLine(ctx, `  class ${classDef.name} {`);
+            const publicFields = classDef.fields.filter(f => f.visibility === "public");
+            const privateFields = classDef.fields.filter(f => f.visibility === "private");
+            const protectedFields = classDef.fields.filter(f => f.visibility === "protected");
+            const publicMethods = classDef.methods.filter(m => m.visibility === "public");
+            const privateMethods = classDef.methods.filter(m => m.visibility === "private");
+            const protectedMethods = classDef.methods.filter(m => m.visibility === "protected");
+            const needsPublicSection = publicFields.length > 0 || publicMethods.length > 0 || classDef.constructor || ctx.callbackFunctions.length > 0;
+            if (needsPublicSection) {
+                appendSourceLine(ctx, "  public:");
+                if (ctx.callbackFunctions.length > 0) {
+                    for (const callback of ctx.callbackFunctions) {
+                        // Friend declaration must match the synthesized callback's actual
+                        // signature (void name() for ISRs, or R name(args) for typed
+                        // std::function-callback lambdas). See renderCallbackSignature in
+                        // function-emitter-impl.ts.
+                        const fret = callback.returnType && callback.returnType !== "void" ? callback.returnType : "void";
+                        const fparams = (callback.typedParams ?? []).map((p) => `${p.cppType} ${p.name}`).join(", ");
+                        appendSourceLine(ctx, `    friend ${fret} ${callback.name}(${fparams});`);
+                    }
+                    appendSourceLine(ctx, "");
+                }
+                if (classDef.constructor) {
+                    const ctorParams = renderParameters(classDef.constructor.parameters);
+                    appendSourceLine(ctx, `    ${classDef.name}(${ctorParams}) {`);
+                    const ctorScope = createChildEmissionScope(topLevelScope, classDef.constructor.parameters);
+                    for (const stmt of classDef.constructor.statements) {
+                        appendRenderedStatement(ctx, stmt, "      ", ctorScope);
+                    }
+                    appendSourceLine(ctx, "    }");
+                    appendSourceLine(ctx, "");
+                }
+                for (const field of publicFields) {
+                    const initSuffix = field.initializer ? ` = ${renderExpression(field.initializer, undefined)}` : "";
+                    const fieldType = strategy.overrideClassFieldType(field.name, normalizeCppTypeForTarget(field.cppType));
+                    // Mirror the method-render prefix (line ~159) and the top-level
+                    // class-emitter: a static field renders as `static inline` so a
+                    // static method's `Cls::field` access resolves. Without this, a
+                    // static field on a namespace-nested class silently dropped to an
+                    // instance field (namespace stress test Finding 2).
+                    const staticPrefix = field.isStatic ? "static inline " : "";
+                    appendSourceLine(ctx, `    ${staticPrefix}${renderTypedName(fieldType, field.name)}${initSuffix};`);
+                }
+                if (publicFields.length > 0)
+                    appendSourceLine(ctx, "");
+                for (const method of publicMethods) {
+                    const methodParams = renderParameters(method.parameters);
+                    const staticPrefix = method.isStatic ? "static " : "";
+                    const returnType = normalizeCppTypeForTarget(method.returnType);
+                    if (method.isAbstract) {
+                        appendSourceLine(ctx, `    virtual ${returnType} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams}) = 0;`);
+                        appendSourceLine(ctx, "");
+                        continue;
+                    }
+                    appendSourceLine(ctx, `    ${staticPrefix}${returnType} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams}) {`);
+                    const methodScope = createChildEmissionScope(topLevelScope, method.parameters);
+                    for (const stmt of method.statements) {
+                        appendRenderedStatement(ctx, stmt, "      ", methodScope);
+                    }
+                    appendSourceLine(ctx, "    }");
+                    appendSourceLine(ctx, "");
+                }
+            }
+            if (privateFields.length > 0 || privateMethods.length > 0) {
+                appendSourceLine(ctx, "  private:");
+                for (const field of privateFields) {
+                    const initSuffix = field.initializer ? ` = ${renderExpression(field.initializer, undefined)}` : "";
+                    const fieldType = strategy.overrideClassFieldType(field.name, normalizeCppTypeForTarget(field.cppType));
+                    // Mirror the method-render prefix (line ~159) and the top-level
+                    // class-emitter: a static field renders as `static inline` so a
+                    // static method's `Cls::field` access resolves. Without this, a
+                    // static field on a namespace-nested class silently dropped to an
+                    // instance field (namespace stress test Finding 2).
+                    const staticPrefix = field.isStatic ? "static inline " : "";
+                    appendSourceLine(ctx, `    ${staticPrefix}${renderTypedName(fieldType, field.name)}${initSuffix};`);
+                }
+                for (const method of privateMethods) {
+                    const methodParams = renderParameters(method.parameters);
+                    appendSourceLine(ctx, `    ${normalizeCppTypeForTarget(method.returnType)} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams}) {`);
+                    const methodScope = createChildEmissionScope(topLevelScope, method.parameters);
+                    for (const stmt of method.statements) {
+                        appendRenderedStatement(ctx, stmt, "      ", methodScope);
+                    }
+                    appendSourceLine(ctx, "    }");
+                }
+            }
+            if (protectedFields.length > 0 || protectedMethods.length > 0) {
+                appendSourceLine(ctx, "  protected:");
+                for (const field of protectedFields) {
+                    const initSuffix = field.initializer ? ` = ${renderExpression(field.initializer, undefined)}` : "";
+                    const fieldType = strategy.overrideClassFieldType(field.name, normalizeCppTypeForTarget(field.cppType));
+                    // Mirror the method-render prefix (line ~159) and the top-level
+                    // class-emitter: a static field renders as `static inline` so a
+                    // static method's `Cls::field` access resolves. Without this, a
+                    // static field on a namespace-nested class silently dropped to an
+                    // instance field (namespace stress test Finding 2).
+                    const staticPrefix = field.isStatic ? "static inline " : "";
+                    appendSourceLine(ctx, `    ${staticPrefix}${renderTypedName(fieldType, field.name)}${initSuffix};`);
+                }
+                for (const method of protectedMethods) {
+                    const methodParams = renderParameters(method.parameters);
+                    appendSourceLine(ctx, `    ${normalizeCppTypeForTarget(method.returnType)} ${escapeCppKeyword(method.name, reservedNames)}(${methodParams}) {`);
+                    const methodScope = createChildEmissionScope(topLevelScope, method.parameters);
+                    for (const stmt of method.statements) {
+                        appendRenderedStatement(ctx, stmt, "      ", methodScope);
+                    }
+                    appendSourceLine(ctx, "    }");
+                }
+            }
+            appendSourceLine(ctx, "  };");
+            emitCommentLines(classDef.trailingComments, "  ", (line) => appendSourceLine(ctx, line));
+            appendSourceLine(ctx, "");
+        }
+        // Namespace functions
+        for (const fn of ns.functions) {
+            const parameterList = renderParameters(fn.parameters);
+            emitCommentLines(fn.leadingComments, "  ", (line) => appendSourceLine(ctx, line));
+            if (fn.typeParameters && fn.typeParameters.length > 0) {
+                appendSourceLine(ctx, `  template<typename ${fn.typeParameters.join(", typename ")}>`);
+            }
+            appendSourceLine(ctx, `  ${normalizeCppTypeForTarget(fn.returnType)} ${fn.originalName}(${parameterList}) {`);
+            const namespaceFunctionScope = createChildEmissionScope(topLevelScope, fn.parameters);
+            for (const statement of fn.statements) {
+                appendRenderedStatement(ctx, statement, "    ", namespaceFunctionScope);
+            }
+            appendSourceLine(ctx, "  }");
+            emitCommentLines(fn.trailingComments, "  ", (line) => appendSourceLine(ctx, line));
+            appendSourceLine(ctx, "");
+        }
+        if (ns.children && ns.children.length > 0) {
+            emitNestedNamespaces(ctx, ns.children, "  ");
+        }
+        appendSourceLine(ctx, `} // namespace ${ns.name}`);
+        emitCommentLines(ns.trailingComments, "", (line) => appendSourceLine(ctx, line));
+        appendSourceLine(ctx, "");
+    }
+}
+function emitNestedNamespaces(ctx, namespaces, indent) {
+    const { strategy, reservedNames, topLevelScope, exprRenderer, statementRenderer } = ctx;
+    const normalizeCppTypeForTarget = (cppType) => strategy.normalizeCppType(cppType);
+    const renderExpression = (expr, calleeTransformer) => exprRenderer.render(expr, calleeTransformer);
+    const renderParameters = (params, forHeader = false) => statementRenderer.renderParameters(params, forHeader);
+    const renderTypedName = (cppType, name) => statementRenderer.renderTypedName(cppType, name);
+    for (const ns of namespaces) {
+        emitCommentLines(ns.leadingComments, indent, (line) => appendSourceLine(ctx, line));
+        appendSourceLine(ctx, `${indent}namespace ${ns.name} {`);
+        appendSourceLine(ctx, "");
+        for (const enumDef of ns.enums) {
+            emitCommentLines(enumDef.leadingComments, `${indent}  `, (line) => appendSourceLine(ctx, line));
+            const enumKeyword = "enum class";
+            const underlyingType = narrowestEnumUnderlying(resolveEnumValues(enumDef.members), strategy.needsLargeEnumUnderlying());
+            appendSourceLine(ctx, `${indent}  ${enumKeyword} ${enumDef.name}${underlyingType} {`);
+            let autoValue = 0;
+            for (let i = 0; i < enumDef.members.length; i++) {
+                const member = enumDef.members[i];
+                let valueSuffix;
+                if (typeof member.value === "number") {
+                    valueSuffix = ` = ${member.value}`;
+                    autoValue = member.value + 1;
+                }
+                else if (typeof member.value === "string") {
+                    valueSuffix = ` = ${autoValue}`;
+                    autoValue++;
+                }
+                else {
+                    valueSuffix = "";
+                    autoValue++;
+                }
+                const commaSuffix = i < enumDef.members.length - 1 ? "," : "";
+                appendSourceLine(ctx, `${indent}    ${member.name}${valueSuffix}${commaSuffix}`);
+            }
+            appendSourceLine(ctx, `${indent}  };`);
+            appendSourceLine(ctx, "");
+        }
+        for (const constant of ns.constants) {
+            const constType = normalizeCppTypeForTarget(constant.cppType);
+            const isConst = constant.storage === "const" || constant.storage === undefined;
+            if (constType !== "auto") {
+                if (isConst) {
+                    appendSourceLine(ctx, `${indent}  const ${constType} ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+                else {
+                    appendSourceLine(ctx, `${indent}  ${constType} ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+            }
+            else {
+                if (isConst) {
+                    appendSourceLine(ctx, `${indent}  const auto ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+                else {
+                    appendSourceLine(ctx, `${indent}  auto ${constant.name} = ${renderExpression(constant.value, undefined)};`);
+                }
+            }
+        }
+        if (ns.assignments) {
+            for (const assign of ns.assignments) {
+                appendSourceLine(ctx, `${indent}  ${assign.target} = ${renderExpression(assign.value, undefined)};`);
+            }
+        }
+        for (const fn of ns.functions) {
+            const parameterList = renderParameters(fn.parameters);
+            appendSourceLine(ctx, `${indent}  ${normalizeCppTypeForTarget(fn.returnType)} ${fn.originalName}(${parameterList}) {`);
+            const fnScope = createChildEmissionScope(topLevelScope, fn.parameters);
+            for (const statement of fn.statements) {
+                appendRenderedStatement(ctx, statement, `${indent}    `, fnScope);
+            }
+            appendSourceLine(ctx, `${indent}  }`);
+            appendSourceLine(ctx, "");
+        }
+        if (ns.children && ns.children.length > 0) {
+            emitNestedNamespaces(ctx, ns.children, `${indent}  `);
+        }
+        appendSourceLine(ctx, `${indent}} // namespace ${ns.name}`);
+        emitCommentLines(ns.trailingComments, indent, (line) => appendSourceLine(ctx, line));
+        appendSourceLine(ctx, "");
+    }
+}

package/dist/emit/emitters/output-finalizer.d.ts

@@ -0,0 +1,4 @@
+import type { GeneratedOutputs } from "../../types.js";
+import type { EmitterContext } from "./emitter-context.js";
+export declare function emitPreamble(ctx: EmitterContext): void;
+export declare function finalizeOutput(ctx: EmitterContext): GeneratedOutputs;

package/dist/emit/emitters/output-finalizer.js

@@ -0,0 +1,267 @@
+import path from "node:path";
+import { writeText } from "../../utils/fs.js";
+import { makeGeneratedMap, writeSourceMap } from "../../mapping/source-map.js";
+import { dedupe, hasConsoleCalls, resolveTranspiledModuleInclude } from "../utils/index.js";
+import { appendHeaderLine } from "./line-appender.js";
+/** Derives a unique C preprocessor guard name from a source file path. */
+function sanitizeGuardName(filePath) {
+    // Use the basename minus extension, uppercased, with non-alphanumeric
+    // characters replaced by underscores.
+    const base = filePath.replace(/^.*[\\/]/, "").replace(/\.[^.]+$/, "");
+    return base.replace(/[^a-zA-Z0-9]/g, "_").toUpperCase();
+}
+/** Extracts a C preprocessor guard from a polyfill definition string. */
+function polyfillDefinitionGuard(definition) {
+    // Match function names after 'inline', 'template<...>', or at start of line.
+    // Handles: "inline double __tc_random() { ... }"
+    //          "template<typename T> std::string __tc_join(...) { ... }"
+    //          "int __tc_setTimeout(...) { ... }"
+    //          "struct __tc_task_state { ... };"
+    const funcMatch = definition.match(/\b(__tc_\w+)\s*\(/);
+    if (funcMatch)
+        return `__TC_POLYFILL_${funcMatch[1].toUpperCase()}`;
+    const structMatch = definition.match(/\b(struct|class)\s+(\w+)/);
+    if (structMatch)
+        return `__TC_POLYFILL_${structMatch[2].toUpperCase()}`;
+    return null;
+}
+export function emitPreamble(ctx) {
+    const { strategy, effectiveEmitMode, program, shimLines, emittedPolyfills, asyncTaskClasses, includes, programAnalysis } = ctx;
+    for (const include of dedupe(includes)) {
+        appendSourceLineLocal(ctx, `#include ${include}`);
+    }
+    appendSourceLineLocal(ctx, "");
+    if (emittedPolyfills) {
+        if (emittedPolyfills.declarations.length > 0) {
+            for (const declaration of emittedPolyfills.declarations) {
+                appendSourceLineLocal(ctx, declaration);
+            }
+            appendSourceLineLocal(ctx, "");
+        }
+        if (emittedPolyfills.definitions.length > 0) {
+            if (effectiveEmitMode === "split") {
+                // Use per-definition guards based on function/struct names so that
+                // the same inline helper (e.g. __tc_random) is only defined once
+                // even when multiple headers are included by the same TU.
+                for (const definition of emittedPolyfills.definitions) {
+                    const guard = polyfillDefinitionGuard(definition);
+                    if (guard) {
+                        appendHeaderLine(ctx, `#ifndef ${guard}`);
+                        appendHeaderLine(ctx, `#define ${guard}`);
+                    }
+                    appendHeaderLine(ctx, definition.trimEnd());
+                    if (guard) {
+                        appendHeaderLine(ctx, `#endif // ${guard}`);
+                    }
+                }
+                appendHeaderLine(ctx, "");
+            }
+            else {
+                for (const definition of emittedPolyfills.definitions) {
+                    appendSourceLineLocal(ctx, definition.trimEnd());
+                    appendSourceLineLocal(ctx, "");
+                }
+            }
+        }
+    }
+    // Shim lines (CUTTLEFISH_UNDEFINED, nullish helpers) must come BEFORE
+    // async task classes — the async state machine references CUTTLEFISH_UNDEFINED
+    // for default timeout values (e.g. waitForRising with no timeout arg).
+    if (shimLines.length > 0) {
+        for (const line of shimLines) {
+            appendSourceLineLocal(ctx, line);
+        }
+        appendSourceLineLocal(ctx, "");
+    }
+    if (asyncTaskClasses.length > 0) {
+        for (const { classDef, instanceDecl } of asyncTaskClasses) {
+            for (const line of classDef.split("\n")) {
+                appendSourceLineLocal(ctx, line);
+            }
+            appendSourceLineLocal(ctx, "");
+            appendSourceLineLocal(ctx, instanceDecl);
+            appendSourceLineLocal(ctx, "");
+        }
+    }
+    if (strategy.needsVectorOverload() && hasConsoleCalls(program, strategy) && (programAnalysis.usesVectorTypes || programAnalysis.hasArrayInObjectLiteral)) {
+        appendSourceLineLocal(ctx, "template <typename T>");
+        appendSourceLineLocal(ctx, "std::ostream& operator<<(std::ostream& os, const std::vector<T>& values)");
+        appendSourceLineLocal(ctx, "{");
+        appendSourceLineLocal(ctx, '  os << "[";');
+        appendSourceLineLocal(ctx, "  for (size_t i = 0; i < values.size(); ++i)");
+        appendSourceLineLocal(ctx, "  {");
+        appendSourceLineLocal(ctx, "    if (i > 0)");
+        appendSourceLineLocal(ctx, "    {");
+        appendSourceLineLocal(ctx, '      os << ", ";');
+        appendSourceLineLocal(ctx, "    }");
+        appendSourceLineLocal(ctx, "    os << values[i];");
+        appendSourceLineLocal(ctx, "  }");
+        appendSourceLineLocal(ctx, '  os << "]";');
+        appendSourceLineLocal(ctx, "  return os;");
+        appendSourceLineLocal(ctx, "}");
+        appendSourceLineLocal(ctx, "");
+    }
+    if (programAnalysis.hasGenerators) {
+        appendSourceLineLocal(ctx, "#include <coroutine>");
+        appendSourceLineLocal(ctx, "#include <optional>");
+        appendSourceLineLocal(ctx, "");
+        appendSourceLineLocal(ctx, "template<typename T>");
+        appendSourceLineLocal(ctx, "struct __tc_Generator {");
+        appendSourceLineLocal(ctx, "  struct promise_type {");
+        appendSourceLineLocal(ctx, "    T current_value;");
+        appendSourceLineLocal(ctx, "    auto get_return_object() { return __tc_Generator{std::coroutine_handle<promise_type>::from_promise(*this)}; }");
+        appendSourceLineLocal(ctx, "    auto initial_suspend() { return std::suspend_always{}; }");
+        appendSourceLineLocal(ctx, "    auto final_suspend() noexcept { return std::suspend_always{}; }");
+        appendSourceLineLocal(ctx, "    auto yield_value(T value) { current_value = value; return std::suspend_always{}; }");
+        appendSourceLineLocal(ctx, "    void return_void() {}");
+        appendSourceLineLocal(ctx, "    void unhandled_exception() { throw; }");
+        appendSourceLineLocal(ctx, "  };");
+        appendSourceLineLocal(ctx, "  std::coroutine_handle<promise_type> handle;");
+        appendSourceLineLocal(ctx, "  __tc_Generator(std::coroutine_handle<promise_type> h) : handle(h) {}");
+        appendSourceLineLocal(ctx, "  ~__tc_Generator() { if (handle) handle.destroy(); }");
+        appendSourceLineLocal(ctx, "  __tc_Generator(const __tc_Generator&) = delete;");
+        appendSourceLineLocal(ctx, "  __tc_Generator(__tc_Generator&& other) noexcept : handle(other.handle) { other.handle = nullptr; }");
+        appendSourceLineLocal(ctx, "  bool next() { handle.resume(); return !handle.done(); }");
+        appendSourceLineLocal(ctx, "  T value() { return handle.promise().current_value; }");
+        appendSourceLineLocal(ctx, "  struct iterator {");
+        appendSourceLineLocal(ctx, "    std::coroutine_handle<promise_type> handle;");
+        appendSourceLineLocal(ctx, "    bool done;");
+        appendSourceLineLocal(ctx, "    iterator& operator++() { handle.resume(); done = handle.done(); return *this; }");
+        appendSourceLineLocal(ctx, "    T operator*() { return handle.promise().current_value; }");
+        appendSourceLineLocal(ctx, "    bool operator!=(const iterator& other) const { return done != other.done; }");
+        appendSourceLineLocal(ctx, "  };");
+        appendSourceLineLocal(ctx, "  iterator begin() { handle.resume(); return {handle, handle.done()}; }");
+        appendSourceLineLocal(ctx, "  iterator end() { return {handle, true}; }");
+        appendSourceLineLocal(ctx, "};");
+        appendSourceLineLocal(ctx, "");
+    }
+}
+export function finalizeOutput(ctx) {
+    const { program, strategy, options, effectiveEmitMode, isNpmPackage, baseName, includes, shimLines, emittedPolyfills } = ctx;
+    const outDir = options.outDir;
+    const sourceExtension = strategy.sourceExtension(ctx.isEntryFile, isNpmPackage);
+    const headerPath = path.join(outDir, `${baseName}.h`);
+    const sourcePath = path.join(outDir, `${baseName}.${sourceExtension}`);
+    let outputHeaderPath;
+    let outputHeaderMapPath;
+    if (effectiveEmitMode === "split") {
+        // Re-export includes to the header
+        const headerIncludes = [];
+        for (const reExport of program.reExports) {
+            const transpiledInclude = resolveTranspiledModuleInclude(reExport.moduleSpecifier, options.npmPackages, program.fileName);
+            if (transpiledInclude.isTranspiled) {
+                headerIncludes.push(transpiledInclude.include);
+                continue;
+            }
+            if (reExport.moduleSpecifier.startsWith(".")) {
+                let modulePath = reExport.moduleSpecifier;
+                modulePath = modulePath.replace(/\.js$/, "").replace(/\.mjs$/, "");
+                const segments = modulePath.split("/");
+                const baseName = segments[segments.length - 1] || segments[segments.length - 2];
+                const headerName = `${baseName}.h`;
+                headerIncludes.push(`"${headerName}"`);
+            }
+        }
+        const finalHeaderLines = [...ctx.headerLines];
+        const headerIncludeLines = dedupe([
+            ...includes,
+            ...headerIncludes,
+        ]);
+        if (headerIncludeLines.length > 0) {
+            const includeLines = headerIncludeLines.map((inc) => `#include ${inc}`);
+            finalHeaderLines.splice(1, 0, ...includeLines, "");
+        }
+        // Cross-module class forward declarations
+        if (options.crossModuleClasses && options.crossModuleClasses.size > 0) {
+            const localClasses = new Set(program.classes.map(cls => cls.name));
+            const importedSymbols = new Set();
+            for (const imp of program.imports) {
+                for (const sym of imp.namedImports) {
+                    importedSymbols.add(sym);
+                }
+            }
+            const forwardDecls = [];
+            for (const className of options.crossModuleClasses) {
+                if (!localClasses.has(className) && importedSymbols.has(className)) {
+                    forwardDecls.push(`class ${className};`);
+                }
+            }
+            if (forwardDecls.length > 0) {
+                let insertIdx = 1;
+                while (insertIdx < finalHeaderLines.length &&
+                    (finalHeaderLines[insertIdx].startsWith("#include") ||
+                        finalHeaderLines[insertIdx] === "")) {
+                    insertIdx++;
+                }
+                finalHeaderLines.splice(insertIdx, 0, ...forwardDecls, "");
+            }
+        }
+        // Non-entry split-file headers may contain inline class method bodies
+        // that emit cuttlefish_nullish(...) calls (from `??` lowering). The
+        // helper shim is appended to the .cpp source via appendHelpers above,
+        // but the .h header — which is #included by the entry .cpp and by other
+        // headers — also needs the shim, because the inline method bodies live
+        // in the header. The shim is wrapped in a single #ifndef guard so
+        // emitting it into every non-entry header is safe.
+        //
+        // To decide whether THIS header needs the shim, scan its already-emitted
+        // lines for an actual cuttlefish_nullish( call. The programAnalysis flag
+        // is unreliable here (it's computed per-file before emit, and class
+        // method bodies on abstract bases can produce cuttlefish_nullish calls
+        // the analysis didn't attribute). A post-emit text scan is exact.
+        if (!ctx.isEntryFile && shimLines.length > 0) {
+            const headerNeedsNullish = finalHeaderLines.some(l => l.includes('cuttlefish_nullish('));
+            if (headerNeedsNullish) {
+                let insertIdx = 1;
+                while (insertIdx < finalHeaderLines.length) {
+                    const l = finalHeaderLines[insertIdx].trim();
+                    // Skip blank lines, includes, comments, and forward declarations
+                    // (e.g. `class Foo;`) — these are all preamble.
+                    if (l === "" || l.startsWith("#include") || l.startsWith("//") || /^class\s+\w+\s*;$/.test(l)) {
+                        insertIdx++;
+                        continue;
+                    }
+                    break;
+                }
+                finalHeaderLines.splice(insertIdx, 0, ...shimLines, "");
+            }
+        }
+        writeText(headerPath, finalHeaderLines.join("\n").trimEnd() + "\n");
+        outputHeaderPath = headerPath;
+        if (options.emitMaps) {
+            outputHeaderMapPath = writeSourceMap(makeGeneratedMap(headerPath, program.fileName, ctx.headerMapEntries));
+        }
+    }
+    // Non-entry Arduino files: header-only
+    const sourceExtension2 = strategy.sourceExtension(ctx.isEntryFile, isNpmPackage);
+    if (sourceExtension2 === "h" && !isNpmPackage) {
+        ctx.sourceLines.unshift("#pragma once", "");
+    }
+    // NOTE: The file-wide `\b${varName}\.` → `${varName}->` text sweep that lived
+    // here has been REMOVED. The `->`/`.` decision for global pointer variables
+    // (including ISR-captured ones like `const btn = new Button()` accessed inside
+    // a hoisted callback) is now made structurally by ExpressionRenderer, which
+    // consults `globalPointerVarTypes` (threaded in from this context) in
+    // inferExpressionCppType. That decision runs per-IR-node with the resolved
+    // symbol/type, replacing the name-keyed regex that operated on joined output
+    // text and could not distinguish a global pointer variable from a same-named
+    // value field/member (the demo #15–#23 failure class).
+    writeText(sourcePath, ctx.sourceLines.join("\n").trimEnd() + "\n");
+    const outputSourceMapPath = options.emitMaps
+        ? writeSourceMap(makeGeneratedMap(sourcePath, program.fileName, ctx.sourceMapEntries))
+        : undefined;
+    const diagnostics = [...program.diagnostics, ...ctx.profileDiagnostics, ...ctx.emitDiagnostics];
+    diagnostics.push(...strategy.emitDiagnostics(options.emitMode));
+    return {
+        headerPath: outputHeaderPath,
+        sourcePath,
+        headerMapPath: outputHeaderMapPath,
+        sourceMapPath: outputSourceMapPath,
+        diagnostics,
+        asyncTaskNames: ctx.asyncTaskClasses.map(t => t.taskVarName),
+        usesTimers: ctx.usesTimers,
+    };
+}
+function appendSourceLineLocal(ctx, line) {
+    ctx.sourceLines.push(line);
+}

package/dist/emit/emitters/setup.d.ts

@@ -0,0 +1,3 @@
+import type { ProgramIR } from "../../api/index.js";
+import type { EmitterContext, EmitterOptions } from "./emitter-context.js";
+export declare function buildEmitterContext(program: ProgramIR, options: EmitterOptions): EmitterContext;