c-next 0.2.16 → 0.2.17

package/src/transpiler/output/codegen/generators/declarationGenerators/ScopeGenerator.ts

@@ -26,6 +26,7 @@ import ArrayDimensionUtils from "./ArrayDimensionUtils";
 import QualifiedNameGenerator from "../../utils/QualifiedNameGenerator";
 import CodeGenState from "../../../../state/CodeGenState";
 import ScopeUtils from "../../../../../utils/ScopeUtils";
+import VariableModifierBuilder from "../../helpers/VariableModifierBuilder";
 
 /**
  * Generate initializer expression for a variable declaration.
@@ -38,10 +39,12 @@ function generateInitializer(
 ): string {
   if (varDecl.expression()) {
     // Issue #872: Set expectedType for MISRA 7.2 U suffix compliance
+    // Issue #992: withDeclarationInit suppresses compound literals at file scope (GCC 9-12 compat)
     const typeName = orchestrator.generateType(varDecl.type());
-    return CodeGenState.withExpectedType(
-      typeName,
-      () => ` = ${orchestrator.generateExpression(varDecl.expression()!)}`,
+    return CodeGenState.withExpectedType(typeName, () =>
+      CodeGenState.withDeclarationInit(
+        () => ` = ${orchestrator.generateExpression(varDecl.expression()!)}`,
+      ),
     );
   }
   // ADR-015: Zero initialization for uninitialized scope variables
@@ -204,12 +207,23 @@ function generateRegularVariable(
     orchestrator.markOpaqueScopeVariable(fullName);
   }
 
-  // Issue #282: Add 'const' modifier for const variables
+  // Issue #998: Use VariableModifierBuilder for consistent modifier handling
+  // This handles const, atomic, volatile, and validates mutual exclusion
+  // Scope variables are always at file scope (not in function body), no initializer for modifier purposes
+  const modifiers = VariableModifierBuilder.build(
+    varDecl,
+    false, // inFunctionBody - scope vars are file scope
+    false, // hasInitializer - doesn't affect volatile/atomic handling
+    false, // cppMode - doesn't affect volatile/atomic handling
+  );
+  // For scope variables: static for private, no modifier for public
+  // Then add volatile (from atomic or volatile keyword), then const
+  const staticPrefix = isPrivate ? "static " : "";
+  const volatilePrefix = modifiers.atomic || modifiers.volatile;
   const constPrefix = isConst ? "const " : "";
-  const prefix = isPrivate ? "static " : "";
 
   // Build declaration with all dimensions
-  let decl = `${prefix}${constPrefix}${type} ${fullName}`;
+  let decl = `${staticPrefix}${volatilePrefix}${constPrefix}${type} ${fullName}`;
   decl += ArrayDimensionUtils.generateArrayTypeDimension(
     arrayTypeCtx,
     orchestrator,
@@ -225,7 +239,12 @@ function generateRegularVariable(
 
   // Issue #948: Opaque types use NULL initialization instead of {0}
   // Issue #958: External typedef struct types also use NULL initialization
-  if (isOpaque || isExternalStruct) {
+  // Issue #996: ...but only for SCALAR handles, which are single pointers. An
+  // *array* of opaque handles needs a brace initializer ({0}), not a scalar
+  // NULL. Route arrays through generateInitializer, which uses
+  // getZeroInitializer(type, isArray) — the single source of truth for
+  // zero-initialization (ADR-015).
+  if ((isOpaque || isExternalStruct) && !isArray) {
     decl += " = NULL";
   } else {
     decl += generateInitializer(varDecl, isArray, orchestrator);

package/src/transpiler/output/codegen/generators/declarationGenerators/__tests__/ScopeGenerator.test.ts

@@ -126,6 +126,8 @@ function createMockVariableDecl(options: {
   name: string;
   type: string;
   isConst?: boolean;
+  isAtomic?: boolean;
+  isVolatile?: boolean;
   initialValue?: string;
   arrayDims?: string[];
   hasStringType?: boolean;
@@ -142,6 +144,10 @@ function createMockVariableDecl(options: {
         options.arrayTypeSize,
       ),
     constModifier: () => createMockConstModifier(options.isConst ?? false),
+    // Issue #998: atomic and volatile modifiers for scope variables
+    // Uses VariableModifierBuilder for consistent handling
+    atomicModifier: () => (options.isAtomic ? ({} as unknown) : null),
+    volatileModifier: () => (options.isVolatile ? ({} as unknown) : null),
     expression: () =>
       options.initialValue ? createMockExpression(options.initialValue) : null,
     arrayDimension: () =>
@@ -772,6 +778,86 @@ describe("ScopeGenerator", () => {
       expect(result.code).toContain("static Point Canvas_point = 0;");
       expect(result.code).not.toContain("Point*");
     });
+
+    it("generates atomic variable with volatile modifier (Issue #998)", () => {
+      const varDecl = createMockVariableDecl({
+        name: "counter",
+        type: "u32",
+        isAtomic: true,
+        initialValue: "0",
+      });
+      const member = createMockScopeMember({ variableDecl: varDecl });
+      const ctx = createMockScopeContext("ISR", [member]);
+      const input = createMockInput();
+      const state = createMockState();
+      const orchestrator = createMockOrchestrator();
+
+      const result = generateScope(ctx, input, state, orchestrator);
+
+      expect(result.code).toContain(
+        "static volatile uint32_t ISR_counter = 0;",
+      );
+    });
+
+    it("generates public atomic variable with volatile but without static (Issue #998)", () => {
+      const varDecl = createMockVariableDecl({
+        name: "flag",
+        type: "bool",
+        isAtomic: true,
+        initialValue: "false",
+      });
+      const member = createMockScopeMember({
+        visibility: "public",
+        variableDecl: varDecl,
+      });
+      const ctx = createMockScopeContext("Shared", [member]);
+      const input = createMockInput();
+      const state = createMockState();
+      const orchestrator = createMockOrchestrator();
+
+      const result = generateScope(ctx, input, state, orchestrator);
+
+      expect(result.code).toContain("volatile bool Shared_flag = false;");
+      expect(result.code).not.toContain("static volatile bool Shared_flag");
+    });
+
+    it("generates volatile-keyword variable with volatile modifier (Issue #998)", () => {
+      const varDecl = createMockVariableDecl({
+        name: "reg",
+        type: "u8",
+        isVolatile: true,
+        initialValue: "0",
+      });
+      const member = createMockScopeMember({ variableDecl: varDecl });
+      const ctx = createMockScopeContext("HW", [member]);
+      const input = createMockInput();
+      const state = createMockState();
+      const orchestrator = createMockOrchestrator();
+
+      const result = generateScope(ctx, input, state, orchestrator);
+
+      expect(result.code).toContain("static volatile uint8_t HW_reg = 0;");
+    });
+
+    it("throws error when both atomic and volatile are specified (Issue #998)", () => {
+      const varDecl = createMockVariableDecl({
+        name: "bad",
+        type: "u8",
+        isAtomic: true,
+        isVolatile: true,
+        initialValue: "0",
+        startLine: 10,
+      });
+      const member = createMockScopeMember({ variableDecl: varDecl });
+      const ctx = createMockScopeContext("Test", [member]);
+      const input = createMockInput();
+      const state = createMockState();
+      const orchestrator = createMockOrchestrator();
+
+      expect(() => generateScope(ctx, input, state, orchestrator)).toThrow(
+        /Cannot use both 'atomic' and 'volatile' modifiers/,
+      );
+    });
   });
 
   // ========================================================================

package/src/transpiler/output/codegen/generators/expressions/BinaryExprGenerator.ts

@@ -18,6 +18,7 @@ import IGeneratorInput from "../IGeneratorInput";
 import IGeneratorState from "../IGeneratorState";
 import IOrchestrator from "../IOrchestrator";
 import BinaryExprUtils from "./BinaryExprUtils";
+import CodeGenState from "../../../../state/CodeGenState";
 
 /**
  * Generator context passed to child generators.
@@ -116,6 +117,7 @@ const generateAndExpr = (
  * ADR-001: = becomes == in C
  * ADR-017: Enum type safety validation
  * ADR-045: String comparison via strcmp()
+ * Issue #1032: Clear expectedType for comparison operands
  */
 const generateEqualityExpr = (
   node: Parser.EqualityExpressionContext,
@@ -151,18 +153,14 @@ const generateEqualityExpr = (
       // Generate strcmp for string comparison - needs string.h
       effects.push({ type: "include", header: "string" });
 
-      const leftResult = generateRelationalExpr(
-        exprs[0],
-        input,
-        state,
-        orchestrator,
-      );
-      const rightResult = generateRelationalExpr(
-        exprs[1],
-        input,
-        state,
-        orchestrator,
-      );
+      // Issue #1032: Clear expectedType for equality comparisons.
+      // Use CodeGenState.withoutExpectedType() to clear the global state that
+      // generators read via getState(). The passed state is not used for
+      // expectedType lookup - generators read from CodeGenState directly.
+      const [leftResult, rightResult] = CodeGenState.withoutExpectedType(() => [
+        generateRelationalExpr(exprs[0], input, state, orchestrator),
+        generateRelationalExpr(exprs[1], input, state, orchestrator),
+      ]);
       effects.push(...leftResult.effects, ...rightResult.effects);
 
       const fullText = node.getText();
@@ -183,18 +181,29 @@ const generateEqualityExpr = (
   // Issue #152: Extract operators in order from parse tree children
   // ADR-001: C-Next uses = for equality, transpile to ==
   const operators = orchestrator.getOperatorsFromChildren(node);
-  return accumulateBinaryExprs(
-    exprs,
-    operators,
-    "=",
-    generateRelationalExpr,
-    { input, state, orchestrator },
-    BinaryExprUtils.mapEqualityOperator,
+
+  // Issue #1032: Clear expectedType for equality comparisons.
+  // The U suffix for MISRA 7.2 compliance applies to assignments, not comparisons.
+  // Use CodeGenState.withoutExpectedType() to clear the global state that
+  // generators read via getState(). The passed state is not used for
+  // expectedType lookup - generators read from CodeGenState directly.
+  return CodeGenState.withoutExpectedType(() =>
+    accumulateBinaryExprs(
+      exprs,
+      operators,
+      "=",
+      generateRelationalExpr,
+      { input, state, orchestrator },
+      BinaryExprUtils.mapEqualityOperator,
+    ),
   );
 };
 
 /**
  * Generate C code for a relational expression.
+ * Issue #1032: Clear expectedType for comparison operands - MISRA 7.2 suffix
+ * should not apply to comparisons, only to assignments. This prevents
+ * `i32 < 0` from becoming `signedIdx < 0U` which changes comparison semantics.
  */
 const generateRelationalExpr = (
   node: Parser.RelationalExpressionContext,
@@ -210,11 +219,21 @@ const generateRelationalExpr = (
 
   // Issue #152: Extract operators in order from parse tree children
   const operators = orchestrator.getOperatorsFromChildren(node);
-  return accumulateBinaryExprs(exprs, operators, "<", generateBitwiseOrExpr, {
-    input,
-    state,
-    orchestrator,
-  });
+
+  // Issue #1032: Clear expectedType for relational comparisons.
+  // The U suffix for MISRA 7.2 compliance applies to assignments, not comparisons.
+  // Comparing `i32 < 0` should NOT generate `signedIdx < 0U` because that
+  // changes semantics due to C's integer promotion rules.
+  // Use CodeGenState.withoutExpectedType() to clear the global state that
+  // generators read via getState(). The passed state is not used for
+  // expectedType lookup - generators read from CodeGenState directly.
+  return CodeGenState.withoutExpectedType(() =>
+    accumulateBinaryExprs(exprs, operators, "<", generateBitwiseOrExpr, {
+      input,
+      state,
+      orchestrator,
+    }),
+  );
 };
 
 /**

package/src/transpiler/output/codegen/generators/expressions/CallExprGenerator.ts

@@ -166,7 +166,8 @@ const _generateCFunctionArg = (
   }
 
   // Issue #948: Check if argument is an opaque scope variable (already a pointer)
-  const isOpaqueScopeVar = CodeGenState.isOpaqueScopeVariable(argCode);
+  // Issue #996: ...including an element of an opaque-handle array (arr[i])
+  const isOpaqueScopeVar = CodeGenState.isOpaqueScopeVariableAccess(argCode);
 
   // Add & if argument needs address-of to match parameter type.
   // Issue #322: struct types passed to pointer params.
@@ -284,50 +285,54 @@ const generateFunctionCall = (
   // Get function signature once for all arguments
   const sig = input.functionSignatures.get(funcExpr);
 
-  const args = argExprs
-    .map((e, idx) => {
-      // Get parameter type info from local signature or cross-file SymbolTable
-      const resolved = CallExprUtils.resolveTargetParam(
-        sig,
-        idx,
-        funcExpr,
-        input.symbolTable,
-      );
-      const targetParam = resolved.param;
-
-      // C/C++ function: use pass-by-value semantics
-      if (!isCNextFunc) {
-        return _generateCFunctionArg(e, targetParam, input, orchestrator);
-      }
-
-      // C-Next function: check if target parameter should be passed by value
-      if (
-        _shouldPassByValue(
-          funcExpr,
+  // Issue #992: Clear inDeclarationInit for function call arguments — struct
+  // initializers inside function args need compound literals, not plain designated initializers.
+  const args = CodeGenState.withoutDeclarationInit(() =>
+    argExprs
+      .map((e, idx) => {
+        // Get parameter type info from local signature or cross-file SymbolTable
+        const resolved = CallExprUtils.resolveTargetParam(
+          sig,
           idx,
-          targetParam,
-          resolved.isCrossFile,
-          orchestrator,
-        )
-      ) {
-        // Issue #872: Set expectedType for MISRA 7.2 compliance, but suppress bare enum resolution
-        const argCode = CodeGenState.withExpectedType(
-          targetParam?.baseType,
-          () => orchestrator.generateExpression(e),
-          true, // suppressEnumResolution
-        );
-        return wrapWithCppEnumCast(
-          argCode,
-          e,
-          targetParam?.baseType,
-          orchestrator,
+          funcExpr,
+          input.symbolTable,
         );
-      }
-
-      // Target parameter is pass-by-reference: use & logic
-      return orchestrator.generateFunctionArg(e, targetParam?.baseType);
-    })
-    .join(", ");
+        const targetParam = resolved.param;
+
+        // C/C++ function: use pass-by-value semantics
+        if (!isCNextFunc) {
+          return _generateCFunctionArg(e, targetParam, input, orchestrator);
+        }
+
+        // C-Next function: check if target parameter should be passed by value
+        if (
+          _shouldPassByValue(
+            funcExpr,
+            idx,
+            targetParam,
+            resolved.isCrossFile,
+            orchestrator,
+          )
+        ) {
+          // Issue #872: Set expectedType for MISRA 7.2 compliance, but suppress bare enum resolution
+          const argCode = CodeGenState.withExpectedType(
+            targetParam?.baseType,
+            () => orchestrator.generateExpression(e),
+            true, // suppressEnumResolution
+          );
+          return wrapWithCppEnumCast(
+            argCode,
+            e,
+            targetParam?.baseType,
+            orchestrator,
+          );
+        }
+
+        // Target parameter is pass-by-reference: use & logic
+        return orchestrator.generateFunctionArg(e, targetParam?.baseType);
+      })
+      .join(", "),
+  );
 
   return { code: `${funcExpr}(${args})`, effects };
 };

package/src/transpiler/output/codegen/generators/expressions/ExpressionGenerator.ts

@@ -15,6 +15,7 @@ import TGeneratorEffect from "../TGeneratorEffect";
 import IGeneratorInput from "../IGeneratorInput";
 import IGeneratorState from "../IGeneratorState";
 import IOrchestrator from "../IOrchestrator";
+import CodeGenState from "../../../../state/CodeGenState";
 
 /**
  * Generate C code for an expression (entry point).
@@ -74,9 +75,15 @@ const generateTernaryExpr = (
   orchestrator.validateTernaryConditionNoFunctionCall(condition);
 
   // Generate C output - parentheses already present from grammar
+  // Issue #992: Clear inDeclarationInit in ternary arms — struct initializers
+  // inside ternary branches need compound literals, not plain designated initializers.
   const condCode = orchestrator.generateOrExpr(condition);
-  const trueCode = orchestrator.generateOrExpr(trueExpr);
-  const falseCode = orchestrator.generateOrExpr(falseExpr);
+  const trueCode = CodeGenState.withoutDeclarationInit(() =>
+    orchestrator.generateOrExpr(trueExpr),
+  );
+  const falseCode = CodeGenState.withoutDeclarationInit(() =>
+    orchestrator.generateOrExpr(falseExpr),
+  );
 
   return { code: `(${condCode}) ? ${trueCode} : ${falseCode}`, effects };
 };

package/src/transpiler/output/codegen/generators/expressions/__tests__/CallExprGenerator.test.ts

@@ -1477,4 +1477,48 @@ describe("CallExprGenerator", () => {
       expect(result.code).toBe("use_handle(my_handle)");
     });
   });
+
+  describe("inDeclarationInit clearing (Issue #992)", () => {
+    it("clears inDeclarationInit during function argument generation", () => {
+      CodeGenState.inDeclarationInit = true;
+
+      const argExprs = [createMockExpressionContext("myArg")];
+      const argCtx = createMockArgListContext(argExprs);
+      const input = createMockInput();
+      const state = createMockState();
+
+      let flagDuringArg = true;
+      const orchestrator = createMockOrchestrator({
+        isCNextFunction: vi.fn(() => false),
+        generateExpression: vi.fn((ctx: Parser.ExpressionContext) => {
+          flagDuringArg = CodeGenState.inDeclarationInit;
+          return ctx.getText();
+        }),
+      });
+
+      generateFunctionCall("myFunc", argCtx, input, state, orchestrator);
+
+      expect(flagDuringArg).toBe(false);
+      expect(CodeGenState.inDeclarationInit).toBe(true);
+    });
+
+    it("restores inDeclarationInit after argument generation", () => {
+      CodeGenState.inDeclarationInit = true;
+
+      const argExprs = [
+        createMockExpressionContext("a"),
+        createMockExpressionContext("b"),
+      ];
+      const argCtx = createMockArgListContext(argExprs);
+      const input = createMockInput();
+      const state = createMockState();
+      const orchestrator = createMockOrchestrator({
+        isCNextFunction: vi.fn(() => false),
+      });
+
+      generateFunctionCall("myFunc", argCtx, input, state, orchestrator);
+
+      expect(CodeGenState.inDeclarationInit).toBe(true);
+    });
+  });
 });

package/src/transpiler/output/codegen/generators/expressions/__tests__/ExpressionGenerator.test.ts

@@ -1,9 +1,10 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach } from "vitest";
 import expressionGenerators from "../ExpressionGenerator";
 import IGeneratorInput from "../../IGeneratorInput";
 import IGeneratorState from "../../IGeneratorState";
 import IOrchestrator from "../../IOrchestrator";
 import * as Parser from "../../../../../logic/parser/grammar/CNextParser";
+import CodeGenState from "../../../../../state/CodeGenState";
 
 // ========================================================================
 // Test Helpers
@@ -455,6 +456,86 @@ describe("ExpressionGenerator", () => {
       });
     });
 
+    describe("inDeclarationInit clearing (Issue #992)", () => {
+      beforeEach(() => {
+        CodeGenState.reset();
+      });
+
+      it("clears inDeclarationInit in ternary true and false arms", () => {
+        CodeGenState.inDeclarationInit = true;
+
+        const condition = createMockOrExpr("x > 0");
+        const trueExpr = createMockOrExpr("a");
+        const falseExpr = createMockOrExpr("b");
+        const ctx = createMockTernaryContext([condition, trueExpr, falseExpr]);
+
+        const input = createMockInput();
+        const state = createMockState();
+
+        const flagDuringTrue: boolean[] = [];
+        const flagDuringFalse: boolean[] = [];
+
+        const orchestrator = createMockOrchestrator();
+        let callCount = 0;
+        (
+          orchestrator.generateOrExpr as ReturnType<typeof vi.fn>
+        ).mockImplementation((ctx: Parser.OrExpressionContext) => {
+          callCount++;
+          if (callCount === 2) {
+            flagDuringTrue.push(CodeGenState.inDeclarationInit);
+          } else if (callCount === 3) {
+            flagDuringFalse.push(CodeGenState.inDeclarationInit);
+          }
+          return ctx.getText();
+        });
+
+        expressionGenerators.generateTernaryExpr(
+          ctx,
+          input,
+          state,
+          orchestrator,
+        );
+
+        expect(flagDuringTrue).toEqual([false]);
+        expect(flagDuringFalse).toEqual([false]);
+        expect(CodeGenState.inDeclarationInit).toBe(true);
+      });
+
+      it("does not affect condition generation", () => {
+        CodeGenState.inDeclarationInit = true;
+
+        const condition = createMockOrExpr("x > 0");
+        const trueExpr = createMockOrExpr("a");
+        const falseExpr = createMockOrExpr("b");
+        const ctx = createMockTernaryContext([condition, trueExpr, falseExpr]);
+
+        const input = createMockInput();
+        const state = createMockState();
+
+        let flagDuringCondition = false;
+        const orchestrator = createMockOrchestrator();
+        let callCount = 0;
+        (
+          orchestrator.generateOrExpr as ReturnType<typeof vi.fn>
+        ).mockImplementation((ctx: Parser.OrExpressionContext) => {
+          callCount++;
+          if (callCount === 1) {
+            flagDuringCondition = CodeGenState.inDeclarationInit;
+          }
+          return ctx.getText();
+        });
+
+        expressionGenerators.generateTernaryExpr(
+          ctx,
+          input,
+          state,
+          orchestrator,
+        );
+
+        expect(flagDuringCondition).toBe(true);
+      });
+    });
+
     describe("effects", () => {
       it("returns empty effects array for non-ternary", () => {
         const orExpr = createMockOrExpr("value");

package/src/transpiler/output/codegen/helpers/ParameterInputAdapter.ts

@@ -60,6 +60,13 @@ interface IFromASTDeps {
    * When the C typedef has `const T*`, this preserves const on the generated param.
    */
   forceConst?: boolean;
+
+  /**
+   * Issue #995: Check if a type is an opaque handle (incomplete struct typedef).
+   * Opaque handles should not get auto-const because they must be passed to
+   * C APIs that expect non-const pointers.
+   */
+  isOpaqueType?: (typeName: string) => boolean;
 }
 
 /**
@@ -142,6 +149,8 @@ class ParameterInputAdapter {
     const isKnownPrimitive = !!deps.typeMap[typeName];
     // Issue #958: C-header typedef struct types need pointer semantics
     const isTypedefStruct = deps.isTypedefStructType(typeName);
+    // Issue #995: Detect opaque handles — rule applied in ParameterSignatureBuilder
+    const isOpaque = deps.isOpaqueType?.(typeName) ?? false;
     // Issue #895: Don't add auto-const for callback-compatible functions
     // because it would change the signature and break typedef compatibility
     const isAutoConst =
@@ -171,6 +180,8 @@ class ParameterInputAdapter {
         deps.forcePassByReference || isTypedefStruct || undefined,
       // Issue #895: Preserve const from callback typedef signature
       forceConst: deps.forceConst,
+      // Issue #995: Pass through opaque handle detection — rule applied in builder
+      isOpaqueHandle: isOpaque || undefined,
     };
   }
 
@@ -236,6 +247,8 @@ class ParameterInputAdapter {
       isPassByReference: isCallbackPointer ? true : !deps.isPassByValue,
       forcePointerSyntax: isCallbackPointer || undefined,
       forceConst: param.isCallbackConst || undefined,
+      // Issue #995: Pass through opaque handle detection — rule applied in builder
+      isOpaqueHandle: param.isOpaqueHandle || undefined,
     };
   }
 
@@ -296,14 +309,15 @@ class ParameterInputAdapter {
       }
     }
 
-    const isAutoConst = !deps.isModified && !isConst;
-
+    // ADR-006: Arrays are pass-by-reference and mutable by default.
+    // Never apply auto-const to arrays - only explicit const from source code.
+    // Auto-const would break compatibility with C APIs expecting mutable pointers.
     return {
       name,
       baseType: typeName,
       mappedType,
       isConst,
-      isAutoConst,
+      isAutoConst: false,
       isArray: true,
       arrayDimensions: dims,
       isCallback: false,

package/src/transpiler/output/codegen/helpers/ParameterSignatureBuilder.ts

@@ -47,6 +47,11 @@ class ParameterSignatureBuilder {
       return this._buildStringParam(param);
     }
 
+    // Issue #995: Opaque handles are always pass-by-reference with pointer syntax
+    if (param.isOpaqueHandle) {
+      return this._buildRefParam(param, refSuffix);
+    }
+
     // Known struct or known primitive: pass by reference
     if (param.isPassByReference) {
       return this._buildRefParam(param, refSuffix);
@@ -103,18 +108,21 @@ class ParameterSignatureBuilder {
   /**
    * Build pass-by-reference parameter signature.
    * C mode: const Point* p
-   * C++ mode: const Point& p (unless forcePointerSyntax)
+   * C++ mode: const Point& p (unless forcePointerSyntax or isOpaqueHandle)
    *
    * Issue #895: When forcePointerSyntax is set, always use pointer syntax
    * because C callback typedefs expect pointers, not C++ references.
+   * Issue #995: Opaque handles must use pointer syntax because C APIs
+   * expect pointers to incomplete struct types (e.g., widget_t*).
    */
   private static _buildRefParam(
     param: IParameterInput,
     refSuffix: string,
   ): string {
     const constPrefix = this._getConstPrefix(param);
-    // Issue #895: Override refSuffix for callback-compatible functions
-    const actualSuffix = param.forcePointerSyntax ? "*" : refSuffix;
+    // Issue #895/#995: Override refSuffix for callback-compatible or opaque handle params
+    const actualSuffix =
+      param.forcePointerSyntax || param.isOpaqueHandle ? "*" : refSuffix;
     return `${constPrefix}${param.mappedType}${actualSuffix} ${param.name}`;
   }
 
@@ -130,10 +138,15 @@ class ParameterSignatureBuilder {
    * Get const prefix combining explicit const, auto-const, and forced const.
    * Priority: forceConst > isConst > isAutoConst
    * Issue #895: forceConst preserves const from callback typedef signature.
+   * Issue #995: Opaque handles suppress auto-const (they must be passed to
+   * C APIs that expect non-const pointers).
    */
   private static _getConstPrefix(param: IParameterInput): string {
+    // Issue #995: Opaque handles never get auto-const — they're passed to C APIs
+    // expecting mutable pointers (e.g., LVGL's lv_obj_t)
+    const effectiveAutoConst = param.isOpaqueHandle ? false : param.isAutoConst;
     // Any source of const results in "const " prefix
-    if (param.forceConst || param.isConst || param.isAutoConst) {
+    if (param.forceConst || param.isConst || effectiveAutoConst) {
       return "const ";
     }
     return "";