codama-renderers-dart 0.4.3 → 0.5.1

package/src/fragments/instructionPage.ts

@@ -7,16 +7,20 @@ import { visit } from "@codama/visitors-core";
 
 import type { Fragment } from "../utils/fragment.js";
 import {
-  emptyFragment,
   fragment,
   fragmentFromString,
   mergeFragments,
   use,
 } from "../utils/fragment.js";
 import type { RenderScope } from "../utils/options.js";
-import { camelCase, pascalCase } from "../utils/nameTransformers.js";
+import { camelCase } from "../utils/nameTransformers.js";
+import { getDiscriminatorValidationFragment } from "../utils/discriminators.js";
+import { getTopLevelDecoderFragment } from "../utils/exactDecoder.js";
+import {
+  getDartValueFragment,
+  isConstDartValueNode,
+} from "../utils/valueNodes.js";
 import { getDiscriminatorConstantsFragment } from "./discriminatorConstants.js";
-import { WELL_KNOWN_ADDRESSES } from "../utils/wellKnownAddresses.js";
 
 /**
  * Generate a full Dart file for an instruction.
@@ -31,19 +35,55 @@ export function getInstructionPageFragment(
   const parseFnName = scope.nameApi.instructionParseFunction(name);
 
   const accounts = node.accounts ?? [];
-  const args = (node.arguments ?? []).filter(
-    (arg) => !isDiscriminatorArg(arg, node),
-  );
   const allArgs = node.arguments ?? [];
+  const optionalAccountStrategy: string =
+    node.optionalAccountStrategy ?? "programId";
+  if (
+    optionalAccountStrategy !== "programId" &&
+    optionalAccountStrategy !== "omitted"
+  ) {
+    throw new Error(
+      `Unsupported optional account strategy on instruction "${node.name}": ${optionalAccountStrategy}`,
+    );
+  }
+  const args = allArgs.filter(
+    (arg) =>
+      !isDiscriminatorArg(arg, node) && !isOmittedDefaultArgument(arg),
+  );
 
   // Build the instruction data class
   const dataClassName = `${typeName}InstructionData`;
 
   // Visit each arg type once and collect manifests for reuse
-  const allArgManifests = allArgs.map((arg) => ({
+  const allArgManifests = (node.arguments ?? []).map((arg) => ({
     arg,
     manifest: visit(arg.type, scope.typeManifestVisitor),
   }));
+  const argDefaultValues = new Map(
+    allArgManifests.flatMap(({ arg, manifest }) => {
+      if (arg.defaultValue == null) return [];
+      const needsRenderedDefault =
+        isOmittedDefaultArgument(arg) ||
+        isDiscriminatorArg(arg, node) ||
+        arg.defaultValue.kind !== "accountBumpValueNode";
+      if (!needsRenderedDefault) return [];
+      return [
+        [
+          arg,
+          getDartValueFragment(arg.defaultValue, manifest.type.content),
+        ] as const,
+      ];
+    }),
+  );
+  for (const arg of allArgs.filter((candidate) =>
+    isDiscriminatorArg(candidate, node),
+  )) {
+    if (!argDefaultValues.has(arg)) {
+      throw new Error(
+        `Field discriminator "${arg.name}" on instruction "${node.name}" must reference a field with a default value.`,
+      );
+    }
+  }
 
   // Data fields (non-discriminator arguments)
   const dataFieldDecls = allArgManifests
@@ -56,20 +96,25 @@ export function getInstructionPageFragment(
   const dataCtorParams = allArgManifests
     .map(({ arg, manifest }) => {
       const fieldName = camelCase(arg.name as string);
+      if (isOmittedDefaultArgument(arg)) return "";
       if (isDiscriminatorArg(arg, node)) {
         return isConstDefaultValue(arg.defaultValue)
-          ? `    this.${fieldName} = ${getDiscriminatorDefault(arg, node)},`
+          ? `    this.${fieldName} = ${argDefaultValues.get(arg)!.content},`
           : `    ${manifest.type.content}? ${fieldName},`;
       }
       return `    required this.${fieldName},`;
     })
+    .filter(Boolean)
     .join("\n");
 
   const dataCtorInitializers = allArgManifests
     .map(({ arg }) => {
       const fieldName = camelCase(arg.name as string);
+      if (isOmittedDefaultArgument(arg)) {
+        return `      ${fieldName} = ${argDefaultValues.get(arg)!.content}`;
+      }
       if (isDiscriminatorArg(arg, node) && !isConstDefaultValue(arg.defaultValue)) {
-        return `      ${fieldName} = ${fieldName} ?? ${getDiscriminatorDefault(arg, node)}`;
+        return `      ${fieldName} = ${fieldName} ?? ${argDefaultValues.get(arg)!.content}`;
       }
       return null;
     })
@@ -90,13 +135,17 @@ export function getInstructionPageFragment(
     .join("\n");
 
   const toMapFields = allArgs
-    .map(
-      (arg) =>
-        `      '${arg.name as string}': value.${camelCase(arg.name as string)},`,
-    )
+    .map((arg) => {
+      const value =
+        isOmittedDefaultArgument(arg) || isDiscriminatorArg(arg, node)
+          ? argDefaultValues.get(arg)!.content
+          : `value.${camelCase(arg.name as string)}`;
+      return `      '${arg.name as string}': ${value},`;
+    })
     .join("\n");
 
   const fromMapFields = allArgManifests
+    .filter(({ arg }) => !isOmittedDefaultArgument(arg))
     .map(({ arg, manifest }) => {
       const typeStr = manifest.type.content;
       const isNullable = typeStr.endsWith("?");
@@ -105,7 +154,20 @@ export function getInstructionPageFragment(
     })
     .join("\n");
 
-  const dataCtorKeyword = dataCtorInitializers ? "" : "const ";
+  const dataCtorKeyword = allArgs.every(
+    (arg) =>
+      !isOmittedDefaultArgument(arg) ||
+      isConstDartValueNode(arg.defaultValue!),
+  ) && allArgs.every(
+    (arg) =>
+      !isDiscriminatorArg(arg, node) ||
+      isConstDefaultValue(arg.defaultValue),
+  )
+    ? "const "
+    : "";
+  const dataCtorSignature = dataCtorParams
+    ? `${dataCtorKeyword}${dataClassName}({\n${dataCtorParams}\n  })${dataCtorInitializers ? ` :\n${dataCtorInitializers}` : ""};`
+    : `${dataCtorKeyword}${dataClassName}()${dataCtorInitializers ? ` :\n${dataCtorInitializers}` : ""};`;
   const dataEncoderName = `get${typeName}InstructionDataEncoder`;
   const dataDecoderName = `get${typeName}InstructionDataDecoder`;
   const dataCodecName = `get${typeName}InstructionDataCodec`;
@@ -134,7 +196,11 @@ export function getInstructionPageFragment(
       const manifest = argManifestMap.get(arg)!;
       const fieldName = camelCase(arg.name as string);
       const typeStr = manifest.type.content;
-      const hasDefault = arg.defaultValue != null;
+      // Account bumps require asynchronous PDA derivation, so callers must
+      // provide them instead of relying on a synchronous generated default.
+      const hasDefault =
+        arg.defaultValue != null &&
+        arg.defaultValue.kind !== "accountBumpValueNode";
       if (hasDefault) {
         // Don't add `?` if the type is already nullable.
         const nullableType = typeStr.endsWith("?") ? typeStr : `${typeStr}?`;
@@ -151,7 +217,10 @@ export function getInstructionPageFragment(
       const role = getAccountRole(acc);
       const isOptional = acc.isOptional ?? false;
       if (isOptional) {
-        return `    if (${fieldName} != null) AccountMeta(address: ${fieldName}, role: ${role}),`;
+        if (optionalAccountStrategy === "omitted") {
+          return `    if (${fieldName} != null) AccountMeta(address: ${fieldName}, role: ${role}),`;
+        }
+        return `    if (${fieldName} != null) AccountMeta(address: ${fieldName}, role: ${role}) else AccountMeta(address: ${instrProgramParam}, role: AccountRole.readonly),`;
       }
       return `    AccountMeta(address: ${fieldName}, role: ${role}),`;
     })
@@ -161,17 +230,31 @@ export function getInstructionPageFragment(
   const dataConstruction = allArgs
     .map((arg) => {
       const fieldName = camelCase(arg.name as string);
-      if (isDiscriminatorArg(arg, node)) {
+      if (
+        isOmittedDefaultArgument(arg) ||
+        isDiscriminatorArg(arg, node)
+      ) {
         return ""; // Use default
       }
-      // Use 'arg_<name>' prefix to reference builder params without shadowing.
-      return `      ${fieldName}: ${fieldName}${arg.defaultValue != null ? ` ?? ${getDefaultValue(arg)}` : ""},`;
+      const skipDefault = arg.defaultValue?.kind === "accountBumpValueNode";
+      return `      ${fieldName}: ${fieldName}${arg.defaultValue != null && !skipDefault ? ` ?? ${argDefaultValues.get(arg)!.content}` : ""},`;
     })
     .filter(Boolean)
     .join("\n");
 
   // Discriminator
   const discFragment = getDiscriminatorConstantsFragment(node, scope);
+  const discriminatorValidation = getDiscriminatorValidationFragment(
+    node,
+    scope,
+  );
+  const topLevelDecoder = getTopLevelDecoderFragment({
+    typeName: dataClassName,
+    description: `${name} instruction decoder`,
+    discriminatorValidation,
+    fromMapFields,
+    requireExactConsumption: true,
+  });
 
   const parts: Fragment[] = [
     fragment`// Auto-generated. Do not edit.
@@ -199,9 +282,7 @@ ${use("AccountRole", "solanaInstructions")}`,
   parts.push(fragment`
 @immutable
 class ${fragmentFromString(dataClassName)} {
-  ${fragmentFromString(dataCtorKeyword)}${fragmentFromString(dataClassName)}({
-${fragmentFromString(dataCtorParams)}
-  })${fragmentFromString(dataCtorInitializers ? ` :\n${dataCtorInitializers}` : "")};
+  ${fragmentFromString(dataCtorSignature)}
 
 ${fragmentFromString(dataFieldDecls)}
 }`);
@@ -226,12 +307,7 @@ Decoder<${fragmentFromString(dataClassName)}> ${fragmentFromString(dataDecoderNa
 ${fragmentFromString(decFields)}
   ]);
 
-  return transformDecoder(
-    structDecoder,
-    (Map<String, Object?> map, Uint8List bytes, int offset) => ${fragmentFromString(dataClassName)}(
-${fragmentFromString(fromMapFields)}
-    ),
-  );
+${topLevelDecoder}
 }
 
 Codec<${fragmentFromString(dataClassName)}, ${fragmentFromString(dataClassName)}> ${fragmentFromString(dataCodecName)}() {
@@ -274,6 +350,9 @@ ${fragmentFromString(dataClassName)} ${fragmentFromString(parseFnName)}(Instruct
     result.imports.mergeWith(manifest.decoder.imports);
     result.imports.mergeWith(manifest.type.imports);
   }
+  for (const defaultValue of argDefaultValues.values()) {
+    result.imports.mergeWith(defaultValue.imports);
+  }
 
   return result;
 }
@@ -299,23 +378,6 @@ function isDiscriminatorArg(
   );
 }
 
-function getDiscriminatorDefault(
-  arg: InstructionArgumentNode,
-  _node: InstructionNode,
-): string {
-  if (arg.defaultValue) {
-    if (arg.defaultValue.kind === "numberValueNode") {
-      return String(arg.defaultValue.number);
-    }
-    if (arg.defaultValue.kind === "bytesValueNode") {
-      const data = arg.defaultValue.data as string;
-      const bytes = data.match(/.{1,2}/g)?.map((b) => parseInt(b, 16)) ?? [];
-      return `Uint8List.fromList([${bytes.join(", ")}])`;
-    }
-  }
-  return "0";
-}
-
 function isConstDefaultValue(defaultValue: InstructionArgumentNode["defaultValue"]): boolean {
   if (!defaultValue) return false;
   switch (defaultValue.kind) {
@@ -329,31 +391,6 @@ function isConstDefaultValue(defaultValue: InstructionArgumentNode["defaultValue
   }
 }
 
-function getDefaultValue(arg: InstructionArgumentNode): string {
-  if (!arg.defaultValue) return "null";
-  const dv = arg.defaultValue;
-  switch (dv.kind) {
-    case "numberValueNode":
-      return String(dv.number);
-    case "booleanValueNode":
-      return String(dv.boolean);
-    case "stringValueNode":
-      return `'${dv.string}'`;
-    case "publicKeyValueNode": {
-      const wellKnownName = WELL_KNOWN_ADDRESSES.get(dv.publicKey);
-      if (wellKnownName) {
-        use(wellKnownName, "solanaAddresses");
-        return wellKnownName;
-      }
-      return `Address('${dv.publicKey}')`;
-    }
-    case "noneValueNode":
-      return "null";
-    case "bytesValueNode": {
-      const bytes = dv.data.match(/.{1,2}/g)?.map((b) => parseInt(b, 16)) ?? [];
-      return `Uint8List.fromList([${bytes.join(", ")}])`;
-    }
-    default:
-      return "null";
-  }
+function isOmittedDefaultArgument(arg: InstructionArgumentNode): boolean {
+  return arg.defaultValue != null && arg.defaultValueStrategy === "omitted";
 }

package/src/fragments/programPage.ts

@@ -1,4 +1,10 @@
-import type { ProgramNode } from "@codama/nodes";
+import {
+  getAllInstructionsWithSubs,
+  type InstructionNode,
+  type ProgramNode,
+  type ValueNode,
+} from "@codama/nodes";
+import { visit } from "@codama/visitors-core";
 
 import type { Fragment } from "../utils/fragment.js";
 import {
@@ -67,19 +73,172 @@ ${fragmentFromString(accountVariants)}
 }`);
   }
 
-  // Instruction identifier enum
-  const instructions = node.instructions ?? [];
+  // Instruction identification and parsing helpers.
+  const instructions = getAllInstructionsWithSubs(node);
   if (instructions.length > 0) {
+    const programName = pascalCase(name);
+    const instructionEnum = `${programName}Instruction`;
     const instrVariants = instructions
       .map((instr) => `  ${camelCase(instr.name as string)},`)
       .join("\n");
 
     parts.push(fragment`
-/// Known instructions for the ${fragmentFromString(pascalCase(name))} program.
-enum ${fragmentFromString(pascalCase(name))}Instruction {
+/// Known instructions for the ${fragmentFromString(programName)} program.
+enum ${fragmentFromString(instructionEnum)} {
 ${fragmentFromString(instrVariants)}
 }`);
+
+    const identifiableInstructions = instructions
+      .map((instruction) => ({
+        instruction,
+        condition: getInstructionDiscriminatorCondition(instruction, scope),
+      }))
+      .filter(({ condition }) => condition !== null) as {
+        instruction: InstructionNode;
+        condition: Fragment;
+      }[];
+
+    if (identifiableInstructions.length > 0) {
+      const identifyBranches = identifiableInstructions.map(
+        ({ instruction, condition }) => fragment`  if (${condition}) {
+    return ${fragmentFromString(instructionEnum)}.${fragmentFromString(camelCase(instruction.name as string))};
+  }`,
+      );
+      const parsedBase = `Parsed${programName}Instruction`;
+      const parsedClasses = instructions.map((instruction) => {
+        const instructionName = pascalCase(instruction.name as string);
+        const variant = camelCase(instruction.name as string);
+        const parsedClass = `Parsed${instructionName}`;
+        const dataClass = `${instructionName}InstructionData`;
+        return fragment`/// A parsed ${fragmentFromString(instructionName)} instruction.
+final class ${fragmentFromString(parsedClass)} extends ${fragmentFromString(parsedBase)} {
+  const ${fragmentFromString(parsedClass)}({required this.data})
+      : super(${fragmentFromString(instructionEnum)}.${fragmentFromString(variant)});
+
+  final ${use(dataClass, "../instructions/instructions.dart")} data;
+}`;
+      });
+      const parseBranches = instructions.map((instruction) => {
+        const instructionName = pascalCase(instruction.name as string);
+        const variant = camelCase(instruction.name as string);
+        const parsedClass = `Parsed${instructionName}`;
+        const parseFunction = scope.nameApi.instructionParseFunction(
+          instruction.name as string,
+        );
+        return fragment`    ${fragmentFromString(instructionEnum)}.${fragmentFromString(variant)} => ${fragmentFromString(parsedClass)}(
+      data: ${use(parseFunction, "../instructions/instructions.dart")}(instruction),
+    ),`;
+      });
+
+      parts.push(fragment`
+/// Identifies the type of a ${fragmentFromString(programName)} instruction.
+${fragmentFromString(instructionEnum)} identify${fragmentFromString(programName)}Instruction(
+  ${use("Uint8List", "dartTypedData")} data,
+) {
+${mergeFragments(identifyBranches, (cs) => cs.join("\n"))}
+
+  throw ${use("SolanaError", "solanaErrors")}(
+    ${use("SolanaErrorCode", "solanaErrors")}.programClientsFailedToIdentifyInstruction,
+    {
+      'instructionData': data,
+      'programName': '${fragmentFromString(name)}',
+    },
+  );
+}
+
+/// A parsed instruction from the ${fragmentFromString(programName)} program.
+sealed class ${fragmentFromString(parsedBase)} {
+  const ${fragmentFromString(parsedBase)}(this.instructionType);
+
+  final ${fragmentFromString(instructionEnum)} instructionType;
+}
+
+${mergeFragments(parsedClasses, (cs) => cs.join("\n\n"))}
+
+/// Parses a ${fragmentFromString(programName)} instruction.
+${fragmentFromString(parsedBase)} parse${fragmentFromString(programName)}Instruction(
+  ${use("Instruction", "solanaInstructions")} instruction,
+) {
+  return switch (identify${fragmentFromString(programName)}Instruction(
+    instruction.data ?? Uint8List(0),
+  )) {
+${mergeFragments(parseBranches, (cs) => cs.join("\n"))}
+  };
+}`);
+    }
   }
 
   return mergeFragments(parts, (cs) => cs.join("\n"));
-}
+}
+
+function getInstructionDiscriminatorCondition(
+  instruction: InstructionNode,
+  scope: RenderScope,
+): Fragment | null {
+  const discriminators = instruction.discriminators ?? [];
+  if (discriminators.length === 0) return null;
+
+  const conditions = discriminators.map((discriminator): Fragment | null => {
+    switch (discriminator.kind) {
+      case "sizeDiscriminatorNode":
+        return fragment`data.length == ${discriminator.size}`;
+      case "constantDiscriminatorNode": {
+        const manifest = visit(
+          discriminator.constant.type,
+          scope.typeManifestVisitor,
+        );
+        const value = getValueFragment(
+          discriminator.constant.value,
+          manifest.type.content,
+        );
+        if (value === null) return null;
+        return fragment`${use("containsBytes", "solanaCodecsCore")}(data, ${manifest.encoder}.encode(${value}), ${discriminator.offset})`;
+      }
+      case "fieldDiscriminatorNode": {
+        const argument = (instruction.arguments ?? []).find(
+          (candidate) => candidate.name === discriminator.name,
+        );
+        if (argument?.defaultValue == null) return null;
+        const manifest = visit(argument.type, scope.typeManifestVisitor);
+        const value = getValueFragment(
+          argument.defaultValue,
+          manifest.type.content,
+        );
+        if (value === null) return null;
+        return fragment`${use("containsBytes", "solanaCodecsCore")}(data, ${manifest.encoder}.encode(${value}), ${discriminator.offset})`;
+      }
+    }
+  });
+
+  if (conditions.some((condition) => condition === null)) return null;
+  return mergeFragments(conditions as Fragment[], (cs) => cs.join(" && "));
+}
+
+function getValueFragment(
+  value:
+    | ValueNode
+    | NonNullable<
+        NonNullable<InstructionNode["arguments"]>[number]["defaultValue"]
+      >,
+  dartType?: string,
+): Fragment | null {
+  switch (value.kind) {
+    case "numberValueNode":
+      return fragmentFromString(
+        dartType === "BigInt"
+          ? `BigInt.from(${value.number})`
+          : String(value.number),
+      );
+    case "booleanValueNode":
+      return fragmentFromString(String(value.boolean));
+    case "stringValueNode":
+      return fragmentFromString(`'${value.string.replaceAll("'", "\\'")}'`);
+    case "bytesValueNode": {
+      const clean = value.data.replace(/^0x/, "");
+      const bytes = clean.match(/.{1,2}/g)?.map((byte) => parseInt(byte, 16)) ?? [];
+      return fragment`${use("Uint8List", "dartTypedData")}.fromList([${fragmentFromString(bytes.join(", "))}])`;
+    }
+    default:
+      return null;
+  }
+}

package/src/fragments/typePage.ts

@@ -1,4 +1,9 @@
-import type { DefinedTypeNode, StructFieldTypeNode, TypeNode } from "@codama/nodes";
+import type {
+  DefinedTypeNode,
+  EnumVariantTypeNode,
+  StructFieldTypeNode,
+  TypeNode,
+} from "@codama/nodes";
 import { resolveNestedTypeNode } from "@codama/nodes";
 import { visit } from "@codama/visitors-core";
 
@@ -30,13 +35,14 @@ export function getTypePageFragment(
 
   // Check what kind of type this is
   if (typeNode.kind === "enumTypeNode") {
-    const isScalar = typeNode.variants.every(
+    const variants = typeNode.variants ?? [];
+    const isScalar = variants.every(
       (v) => v.kind === "enumEmptyVariantTypeNode",
     );
     if (isScalar) {
-      return getScalarEnumPageFragment(node, scope);
+      return getScalarEnumPageFragment(node, variants, scope);
     }
-    return getDataEnumPageFragment(node, scope);
+    return getDataEnumPageFragment(node, variants, scope);
   }
 
   if (typeNode.kind === "structTypeNode") {
@@ -52,6 +58,7 @@ export function getTypePageFragment(
  */
 function getScalarEnumPageFragment(
   node: DefinedTypeNode,
+  enumVariants: EnumVariantTypeNode[],
   scope: RenderScope,
 ): Fragment {
   const name = node.name as string;
@@ -59,7 +66,7 @@ function getScalarEnumPageFragment(
   const enumNode = node.type;
   if (enumNode.kind !== "enumTypeNode") return emptyFragment();
 
-  const variants = enumNode.variants.map((v) => {
+  const variants = enumVariants.map((v) => {
     const variantName = scope.nameApi.enumVariant(v.name as string);
     return variantName;
   });
@@ -73,6 +80,18 @@ function getScalarEnumPageFragment(
   const resolvedSize = resolveNestedTypeNode(enumNode.size);
   const sizeType = resolvedSize.format ?? "u8";
   const sizeCodecName = getNumberCodecName(sizeType);
+  const isU64 = sizeType === "u64";
+  const encodedVariantIndex = isU64
+    ? "BigInt.from(value.index)"
+    : "value.index";
+  const decodedVariant = isU64
+    ? `(BigInt value, Uint8List bytes, int offset) {
+      if (value.isNegative || value >= BigInt.from(${typeName}.values.length)) {
+        throw RangeError('Invalid ${typeName} discriminator: ' + value.toString());
+      }
+      return ${typeName}.values[value.toInt()];
+    }`
+    : `(int value, Uint8List bytes, int offset) => ${typeName}.values[value]`;
 
   return fragment`// Auto-generated. Do not edit.
 // ignore_for_file: type=lint
@@ -94,14 +113,14 @@ ${fragmentFromString(variantLines)}
 Encoder<${fragmentFromString(typeName)}> ${fragmentFromString(encoderName)}() {
   return transformEncoder(
     get${fragmentFromString(sizeCodecName)}Encoder(),
-    (${fragmentFromString(typeName)} value) => value.index,
+    (${fragmentFromString(typeName)} value) => ${fragmentFromString(encodedVariantIndex)},
   );
 }
 
 Decoder<${fragmentFromString(typeName)}> ${fragmentFromString(decoderName)}() {
   return transformDecoder(
     get${fragmentFromString(sizeCodecName)}Decoder(),
-    (int value, Uint8List bytes, int offset) => ${fragmentFromString(typeName)}.values[value],
+    ${fragmentFromString(decodedVariant)},
   );
 }
 
@@ -115,6 +134,7 @@ Codec<${fragmentFromString(typeName)}, ${fragmentFromString(typeName)}> ${fragme
  */
 function getDataEnumPageFragment(
   node: DefinedTypeNode,
+  variants: EnumVariantTypeNode[],
   scope: RenderScope,
 ): Fragment {
   const name = node.name as string;
@@ -130,8 +150,9 @@ function getDataEnumPageFragment(
   // Collect all field type manifests from variants so we can merge their imports
   const allVariantManifests: { encoder: Fragment; decoder: Fragment; type: Fragment }[] = [];
 
-  for (let i = 0; i < enumNode.variants.length; i++) {
-    const variant = enumNode.variants[i];
+  for (let i = 0; i < variants.length; i++) {
+    const variant = variants[i];
+    const variantName = pascalCase(variant.name as string);
     const variantClassName = scope.nameApi.sealedClassVariant(
       name,
       variant.name as string,
@@ -149,7 +170,7 @@ function getDataEnumPageFragment(
   int get hashCode => runtimeType.hashCode;
 
   @override
-  String toString() => '${typeName}.${variantClassName}()';
+  String toString() => '${typeName}.${variantName}()';
 }`);
 
       encoderVariants.push(
@@ -162,7 +183,7 @@ function getDataEnumPageFragment(
       decodeCases.push(`case ${i}: return const ${variantClassName}();`);
     } else if (variant.kind === "enumStructVariantTypeNode") {
       const resolvedStruct = resolveNestedTypeNode(variant.struct);
-      const fields = resolvedStruct.fields;
+      const fields = resolvedStruct.fields ?? [];
 
       // Visit each field type once and collect manifests
       const fieldManifests = fields.map((f: StructFieldTypeNode) => ({
@@ -217,7 +238,7 @@ ${fieldDecls}
   int get hashCode => ${hashExpression};
 
   @override
-  String toString() => '${typeName}.${variantClassName}(${toStringFields})';
+  String toString() => '${typeName}.${variantName}(${toStringFields})';
 }`);
 
       const encFields = fieldManifests
@@ -270,7 +291,7 @@ ${fieldDecls}
       decodeCases.push(`case ${i}: return ${variantClassName}(${fromMapFields.replace(/\n/g, ' ').replace(/,$/, '')});`);
     } else if (variant.kind === "enumTupleVariantTypeNode") {
       const resolvedTuple = resolveNestedTypeNode(variant.tuple);
-      const items = resolvedTuple.items;
+      const items = resolvedTuple.items ?? [];
       if (items.length === 1) {
         const manifest = visit(items[0], scope.typeManifestVisitor);
         allVariantManifests.push(manifest);
@@ -288,7 +309,7 @@ ${fieldDecls}
   int get hashCode => value.hashCode;
 
   @override
-  String toString() => '${typeName}.${variantClassName}(\$value)';
+  String toString() => '${typeName}.${variantName}(\$value)';
 }`);
         encoderVariants.push(
           `(${i}, transformEncoder<${manifest.type.content}, Map<String, Object?>>(${manifest.encoder.content}, (Map<String, Object?> map) => map['value']! as ${manifest.type.content}))`,
@@ -383,7 +404,7 @@ function getStructPageFragment(
   const structNode = node.type;
   if (structNode.kind !== "structTypeNode") return emptyFragment();
 
-  const fields = structNode.fields;
+  const fields = structNode.fields ?? [];
 
   // Visit each field type once and collect manifests for reuse
   const fieldManifests = fields.map((f: StructFieldTypeNode) => ({

package/src/index.ts

@@ -3,6 +3,7 @@ export { getRenderMapVisitor } from "./visitors/getRenderMapVisitor.js";
 export { getTypeManifestVisitor } from "./visitors/getTypeManifestVisitor.js";
 export { DartImportMap, DART_EXTERNAL_PACKAGE_MAP } from "./utils/importMap.js";
 export { createDartNameApi } from "./utils/nameTransformers.js";
+export { normalizeRootNode } from "./utils/normalizeRootNode.js";
 export type { DartNameApi } from "./utils/nameTransformers.js";
 export type { RenderOptions, GetRenderMapOptions, RenderScope } from "./utils/options.js";
 export type { TypeManifest } from "./utils/typeManifest.js";